AGENTS.md Configuration

Capabilities

• code_generation: enabled
• code_review: enabled
• documentation: enabled

Constraints

• tech_stack: ["React", "TypeScript"]
• security: "no sensitive data processing"

[个人项目][团队协作]

### 2. 分层配置策略
根据项目复杂度实施分层配置：
- **基础层**：定义通用技术栈和安全规则
- **模块层**：为不同功能模块设置专项规则
- **场景层**：针对开发/测试/生产环境定制行为

### 3. 验证与迭代
通过以下步骤验证配置效果：
1. 运行`npx agents-validator`检查配置文件合法性
2. 使用AI生成典型功能代码，对比配置预期
3. 收集团队反馈并优化规则

## 三、场景落地：不同规模项目的配置实践

### 个人项目快速配置模板
```markdown
# AGENTS.md for Personal Project
## Capabilities
- code_completion: enabled
- refactoring: enabled

## Constraints
- style_guide: "airbnb"
- file_structure: "feature-based"

[个人项目]

团队协作增强模板

# AGENTS.md for Team Collaboration
## Capabilities
- code_review: enabled
- test_generation: enabled
- documentation: enabled

## TeamKnowledge
- coding_standards: "docs/standards.md"
- architecture_decisions: "docs/adr/"

## Workflow
- commit_message_format: "type(scope): description"

[团队协作]

企业级项目完整模板

# AGENTS.md for Enterprise Project
## Capabilities
- security_scanning: enabled
- performance_analysis: enabled
- compliance_check: enabled

## Constraints
- regulatory_compliance: ["GDPR", "SOC2"]
- performance_baseline: "docs/performance.md"

## Environments
- development:
  - code_generation: enabled
- production:
  - code_generation: restricted

[企业级]

四、问题解决：AGENTS.md配置故障排除指南

症状：配置不生效

原因：

• 文件位置错误（未放在项目根目录）
• 配置语法不符合JSON Schema规范
• AI工具版本不支持AGENTS.md

解决方案：

1. 验证文件路径：ls -la AGENTS.md
2. 使用JSON Schema验证工具检查语法
3. 升级开发工具至最新版本

症状：AI生成代码仍不符合规范

原因：

• 规则定义过于模糊
• 未针对特定框架设置专项规则
• 缺少示例代码参考

解决方案：

1. 细化约束条件，如将"React"改为"React 18+, functional components only"
2. 添加框架特定规则："react_hooks": "must follow exhaustive-deps rule"
3. 引用示例代码："examples": "src/examples/"

症状：团队成员配置不一致

原因：

• 配置文件未纳入版本控制
• 本地修改未同步到团队
• 缺少配置更新通知机制

解决方案：

1. 将AGENTS.md添加到Git跟踪：git add AGENTS.md
2. 设置配置变更审查流程
3. 在README中添加配置更新日志

五、高级实践：AGENTS.md配置的持续优化

JSON Schema规范应用

AGENTS.md支持JSON Schema验证，通过以下配置确保格式正确性：

{
  "$schema": "https://agents-md.org/schema/v1",
  "capabilities": {
    "type": "array",
    "items": {
      "type": "string",
      "enum": ["code_generation", "code_review", "documentation"]
    }
  }
}

工具解析差异处理

不同AI工具对AGENTS.md的解析存在差异：

• Copilot：优先读取Capabilities部分
• Cursor：支持环境变量动态配置
• Devin：强调TeamKnowledge部分的知识库引用

建议创建工具适配层：

## ToolSpecific
- copilot:
  - priority: ["Capabilities", "Constraints"]
- cursor:
  - priority: ["Environments", "Workflow"]