tupingr
456cda909b
- docs/ 项目级总体文档（产品需求、系统架构、开发规范、部署运维、变更日志） - tools/ 开发工具脚本 - data/ 训练数据 - AGENTS.md 权限矩阵新增三个目录的权限定义 - coder.json Dev AI 新增 docs/、tools/、data/ 可写路径 - tester.json QA AI 新增 docs/、data/ 只读路径，tools/ 禁止路径 - ai-collab-setup/SKILL.md 目录结构同步更新到 v2.1
206 lines
7.2 KiB
Markdown
206 lines
7.2 KiB
Markdown
# AI 角色定义与权限约定
|
||
|
||
## 团队架构
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 人类负责人 │
|
||
│ 需求分析 · 架构设计 · 最终决策 │
|
||
└───────────────────┬─────────────────────────┘
|
||
│
|
||
┌───────────┴───────────┐
|
||
▼ ▼
|
||
┌───────────────┐ ┌───────────────┐
|
||
│ Dev AI │ │ QA AI │
|
||
│ 代码编写 │ │ 测试设计 │
|
||
│ 文档生成 │ │ 测试执行 │
|
||
│ 影响评估 │ │ 质量保障 │
|
||
└───────────────┘ └───────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 角色职责
|
||
|
||
### Dev AI (编码AI)
|
||
**职责范围：**
|
||
- ✅ 编写业务代码 (`projects/*/src/`)
|
||
- ✅ 生成技术文档 (`projects/*/docs/`)
|
||
- ✅ 维护项目级文档 (`docs/`)
|
||
- ✅ 维护开发工具 (`tools/`)
|
||
- ✅ 维护训练数据 (`data/`)
|
||
- ✅ 定义验收标准 (`review/*/acceptance.md`)
|
||
- ✅ 评估变更影响 (`review/*/impact.md`)
|
||
- ✅ 维护共享资源 (`shared/`)
|
||
|
||
**可读但不可写：**
|
||
- 👁 任务描述 (`review/*/task.md`) —— 只读，不可修改
|
||
- 👁 测试反馈 (`review/*/feedback/`) —— 只读，用于修 Bug
|
||
|
||
**禁止操作：**
|
||
- ❌ 修改测试代码 (`projects/*/tests/`)
|
||
- ❌ 修改测试报告 (`reports/`)
|
||
|
||
### QA AI (测试AI)
|
||
**职责范围：**
|
||
- ✅ 编写测试用例 (`projects/*/tests/`)
|
||
- ✅ 执行测试并生成报告 (`reports/`)
|
||
- ✅ 补充验收标准 (`review/*/acceptance.md`)
|
||
- ✅ 提交测试反馈 (`review/*/feedback/`)
|
||
|
||
**可读但不可写：**
|
||
- 👁 任务描述 (`review/*/task.md`) —— 只读，了解测试目标
|
||
- 👁 项目级文档 (`docs/`) —— 只读，了解系统架构
|
||
- 👁 训练数据 (`data/`) —— 只读，了解数据分布
|
||
|
||
**禁止操作：**
|
||
- ❌ 修改业务代码 (`projects/*/src/`)
|
||
- ❌ 修改技术文档 (`projects/*/docs/`)
|
||
- ❌ 修改共享资源 (`shared/`)
|
||
- ❌ 修改影响评估 (`review/*/impact.md`)
|
||
- ❌ 修改开发工具 (`tools/`)
|
||
|
||
### 人类负责人
|
||
**职责范围：**
|
||
- ✅ 可以修改所有目录
|
||
- ✅ 审核 AI 输出质量
|
||
- ✅ 解决 AI 之间的冲突
|
||
- ✅ 最终决策和验收
|
||
|
||
---
|
||
|
||
## 工作流程
|
||
|
||
```
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ 需求分析 │ ───→ │ 开发实现 │ ───→ │ 测试验证 │ ───→ │ 验收确认 │
|
||
│ (人类) │ │ (Dev AI) │ │ (QA AI) │ │ (人类) │
|
||
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
|
||
↑ │
|
||
│ Bug → 修复 │
|
||
└──────────────────────┘
|
||
(最多 2 轮)
|
||
```
|
||
|
||
### 详细流程说明
|
||
|
||
**1. 需求分析阶段**
|
||
- 人类负责人创建任务单
|
||
- 输出: `review/{task_id}/task.md`
|
||
|
||
**2. 开发实现阶段**
|
||
- Dev AI 读取任务描述，编写代码 + 文档
|
||
- 同时输出验收标准和变更影响范围
|
||
- 输出: `projects/*/src/`, `projects/*/docs/`, `review/{task_id}/impact.md`, `review/{task_id}/acceptance.md`
|
||
|
||
**3. 测试验证阶段**
|
||
- QA AI 根据验收标准编写测试，执行测试，生成报告
|
||
- 测试反馈写入 `review/{task_id}/feedback/round{round}.md`
|
||
- 输出: `projects/*/tests/`, `reports/test-results/`, `review/{task_id}/feedback/`
|
||
|
||
### 缺陷修复循环
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| 最大轮次 | 3 轮（初始测试 + 最多 2 轮修复复查） |
|
||
| 循环范围 | 测试失败 → Dev AI 修复 → QA AI 复查 |
|
||
| 跳过项 | 修复轮次中 Dev AI **只修 Bug**，不重新写 acceptance/impact |
|
||
| 触发升级 | 第 3 轮仍有 BLOCKER 或 HIGH 级别 Bug → 暂停流转，待人类裁决 |
|
||
|
||
```
|
||
Round 1: Dev 开发 → QA 测试 → 3 个 Bug
|
||
Round 2: Dev 修复 → QA 复查 → 1 个 Bug（MEDIUM）
|
||
Round 3: Dev 修复 → QA 复查 → 0 个 Bug ✅ → 提交人类验收
|
||
```
|
||
|
||
如果 Round 3 仍有 BLOCKER/HIGH：
|
||
```
|
||
Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决
|
||
```
|
||
|
||
**4. 验收确认阶段**
|
||
- 人类审核测试报告，确认任务完成或驳回
|
||
- 确认后任务状态更新为 DONE，移入 `review/archived/`
|
||
|
||
---
|
||
|
||
## 目录权限矩阵
|
||
|
||
> **图例**：`-` = 无权访问 `R` = 只读 `W` = 可写（含读） `RW` = 读写
|
||
|
||
| 目录路径 | Dev AI | QA AI | 人类 |
|
||
|---------|--------|-------|------|
|
||
| `.ai/` | `-` | `-` | `RW` |
|
||
| `docs/` | `RW` | `R` | `RW` |
|
||
| `tools/` | `RW` | `-` | `RW` |
|
||
| `data/` | `RW` | `R` | `RW` |
|
||
| `shared/` | `RW` | `-` | `RW` |
|
||
| `projects/*/src/` | `RW` | `-` | `RW` |
|
||
| `projects/*/tests/` | `-` | `RW` | `RW` |
|
||
| `projects/*/docs/` | `RW` | `-` | `RW` |
|
||
| `review/*/task.md` | `R` | `R` | `RW` |
|
||
| `review/*/acceptance.md` | `RW` | `RW` | `RW` |
|
||
| `review/*/impact.md` | `RW` | `-` | `RW` |
|
||
| `review/*/feedback/` | `R` | `RW` | `RW` |
|
||
| `reports/` | `-` | `RW` | `RW` |
|
||
| `.github/` | `-` | `-` | `RW` |
|
||
|
||
> **解析优先级**：当同一条路径被多个规则匹配时，`forbidden > read_only > allowed`。禁止规则永远优先。
|
||
>
|
||
> **默认行为**：任何未出现在上表中的路径，默认禁止所有 AI 访问（等效于 `-`）。
|
||
|
||
---
|
||
|
||
## 沟通规范
|
||
|
||
### 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/` | 测试提示词模板 | |