ai_soc_sw/AGENTS.md

AI 角色定义与权限约定

团队架构

┌─────────────────────────────────────────────┐
│              人类负责人                      │
│      需求分析 · 架构设计 · 最终决策          │
└───────────────────┬─────────────────────────┘
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
┌───────────────┐       ┌───────────────┐
│    Dev AI     │       │    QA AI      │
│ 代码编写      │       │ 测试设计      │
│ 文档生成      │       │ 测试执行      │
│ 影响评估      │       │ 质量保障      │
└───────────────┘       └───────────────┘

---

角色职责

Dev AI (编码AI)

职责范围：

• ✅ 编写业务代码 (projects/*/src/)
• ✅ 生成技术文档 (projects/*/docs/)
• ✅ 定义验收标准 (review/*/acceptance.md)
• ✅ 评估变更影响 (review/*/impact.md)
• ✅ 维护共享资源 (shared/)

禁止操作：

• ❌ 修改测试代码 (projects/*/tests/)
• ❌ 修改测试报告 (reports/)
• ❌ 提交测试反馈 (review/*/feedback/)

QA AI (测试AI)

职责范围：

• ✅ 编写测试用例 (projects/*/tests/)
• ✅ 执行测试并生成报告 (reports/)
• ✅ 补充验收标准 (review/*/acceptance.md)
• ✅ 提交测试反馈 (review/*/feedback/)

禁止操作：

• ❌ 修改业务代码 (projects/*/src/)
• ❌ 修改技术文档 (projects/*/docs/)
• ❌ 修改共享资源 (shared/)
• ❌ 修改任务描述和影响评估

人类负责人

职责范围：

• ✅ 可以修改所有目录
• ✅ 审核 AI 输出质量
• ✅ 解决 AI 之间的冲突
• ✅ 最终决策和验收

---

工作流程

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  需求分析   │ ──→ │  开发实现   │ ──→ │  影响评估   │
│   (人类)    │     │  (Dev AI)   │     │  (Dev AI)   │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ 验收标准    │ ──→ │  测试设计   │ ──→ │  测试执行   │
│ (Dev AI)    │     │  (QA AI)    │     │  (QA AI)    │
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
┌─────────────┐     ┌─────────────┐
│  反馈提交   │ ──→ │  验收确认   │
│  (QA AI)    │     │   (人类)    │
└─────────────┘     └─────────────┘

详细流程说明

1. 需求分析阶段

• 人类负责人创建任务单
• 输出: review/{task_id}/task.md

2. 开发实现阶段

• Dev AI 根据任务描述编写代码
• 输出: projects/*/src/, projects/*/docs/

3. 影响评估阶段

• Dev AI 分析变更影响范围
• 输出: review/{task_id}/impact.md

4. 验收标准定义

• Dev AI 定义验收标准
• QA AI 可补充测试要点
• 输出: review/{task_id}/acceptance.md

5. 测试设计阶段

• QA AI 根据验收标准编写测试用例
• 输出: projects/*/tests/

6. 测试执行阶段

• QA AI 执行测试并生成报告
• 输出: reports/test-results/, reports/quality-reports/

7. 反馈提交阶段

• QA AI 提交测试反馈
• 输出: review/{task_id}/feedback/round{round}.md

8. 验收确认阶段

• 人类负责人审核测试结果
• 确认任务完成或返回修改

---

目录权限矩阵

目录路径	Dev AI	QA AI	人类
.ai/	❌	❌	✅
shared/	✅	❌	✅
projects/*/src/	✅	❌	✅
projects/*/tests/	❌	✅	✅
projects/*/docs/	✅	❌	✅
review/*/task.md	❌	❌	✅
review/*/acceptance.md	✅	✅	✅
review/*/impact.md	✅	❌	✅
review/*/feedback/	❌	✅	✅
reports/	❌	✅	✅
.github/	❌	❌	✅

---

沟通规范

Dev AI → QA AI

在 review/{task_id}/ 目录提交：

• 验收标准 (acceptance.md) - 明确测试目标
• 变更影响范围 (impact.md) - 指导回归测试
• 环境准备 参考项目级 ENVIRONMENT.md

QA AI → Dev AI

在 review/{task_id}/feedback/ 目录提交：

• 测试结果报告 (round{round}.md)
• Bug清单 - 列出问题和严重程度
• 改进建议 - 代码优化建议

---

命名规范

项目命名

P01_项目名称        # P01 表示项目编号

任务编号

P01-001            # P01 项目编号 + 001 任务编号

分支命名

feature/P01-001-login    # 功能开发
bugfix/P01-001-password  # Bug修复
test/P01-001-testcases   # 测试用例

提交信息

feat(P01-001): 实现用户登录功能
fix(P01-001): 修复密码验证问题
docs(P01-001): 更新接口文档
test(P01-001): 添加登录测试用例

---

AI 配置文件说明

文件	说明
.ai/config/coder.json	Dev AI 配置（权限、职责）
.ai/config/tester.json	QA AI 配置（权限、职责）
.ai/config/workflow.json	工作流配置（阶段、触发器）
.ai/prompts/coding/	编码提示词模板
.ai/prompts/testing/	测试提示词模板