hwd32/ai_soc_sw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(architecture): 信息架构重构 — 从"人类导向单体文档"到"AI优先分层架构"

Browse Source 
新增四层信息架构：
- Layer 0: 角色工作台 (.ai/roles/) — AI 每天只需读2个小文件
- Layer 1: 路线图看板 (ROADMAP.md) — 人机共享进度
- Layer 2: 阶段上下文 (.ai/phases/) — 按当前阶段加载
- Layer 3: 知识沉淀 (.ai/knowledge/) — 决策/模式/教训自动积累

新增：
- DASHBOARD.md — 人类仪表盘（30秒了解全貌）
- ROADMAP.md — 任务看板+阻塞追踪
- docs/share/ — 对外分享内容层（一鸡多吃）
- docs/使用手册.md — 人+AI使用手册
- .ai/prompts/architecture/ — 补充缺失的架构提示词
- .ai/principles.md — 信息架构设计原则
- review/active/INDEX.md — 任务索引

修改：
- AGENTS.md: 239行→117行，顶部AI跳转
- README.md: 精简聚焦人类读者
- PROJECT_CONTEXT.md: 精简+分层说明
- DECISIONS.md: 替换为跳转存根
- 5个task.md: 添加phase字段

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
tupingr
2026-05-25 16:49:36 +08:00
parent 5dfc382c55
commit 4184a6d0b5
65 changed files with 1642 additions and 582 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+56 -179
View File
@@ -1,163 +1,62 @@
# AI 角色定义与权限约定
> **如果你是 AI，请直接跳转到你的角色工作台：**
> - Arch AI → `.ai/roles/arch/card.md`
> - Dev AI → `.ai/roles/dev/card.md`
> - QA AI → `.ai/roles/qa/card.md`
>
> **如果你是**人类，请看 `DASHBOARD.md` + `ROADMAP.md`。
>
> 本文档是权限矩阵的**唯一权威参考**。角色工作台中的权限描述为摘要，如有冲突以本文档为准。
---
## 团队架构
`1 人类 + 3 AI` 协作模式：
- **Arch AI** — 需求分析、架构设计、技术选型、跨模块协调
- **Dev AI** — 代码编写、文档生成、Bug 修复
- **QA AI** — 测试设计、测试执行、质量反馈
- **人类** — 需求输入、最终决策、成果验收
---
## 工作流（简化版）
```
┌─────────────────────────────────────────────┐
│ 人类负责人 │
│ 需求分析 · 架构设计 · 最终决策 │
└───────────────┬───────────┬─────────────────┘
│ │
┌───────────┴──┐ ┌────┴────────────┐
▼ ▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌───────────────┐
│ Arch AI │ │ Dev AI │ │ QA AI │
│ 需求分析 │ │ 代码编写 │ │ 测试设计 │
│ 架构设计 │ │ 文档生成 │ │ 测试执行 │
│ 技术选型 │ │ 影响评估 │ │ 质量保障 │
│ 跨模块协调 │ └──────────────┘ └───────────────┘
└───────────────┘
需求分析(Arch) → 架构设计(Arch) → 开发实现(Dev) → 测试验证(QA) → 人类验收
↑ │
└── Bug修复 ──┘ (最多3轮)
```
缺陷修复循环：最多 3 轮。第 3 轮仍有 BLOCKER/HIGH → 升级给人类裁决。
详细工作流配置：`.ai/config/workflow.json`
---
## 角色职责
### Arch AI (架构AI)
**职责范围：**
- ✅ 需求分析和产品规划
- ✅ 系统架构设计
- ✅ 技术选型和评估
- ✅ 跨模块协调和集成
- ✅ 编写架构文档 (`docs/`)
- ✅ 定义验收标准 (`review/*/acceptance.md`)
- ✅ 评估变更影响 (`review/*/impact.md`)
- ✅ 维护共享资源 (`shared/`)
- ✅ 维护开发工具 (`tools/`)
- ✅ 维护训练数据 (`data/`)
- ✅ 指导 Dev AI 和 QA AI 工作
### Arch AI
- 可写：需求分析、架构设计、技术选型、跨模块协调、架构文档、验收标准、影响评估、共享资源、开发工具、训练数据、业务代码
- 只读：AI 配置、测试代码、测试报告、测试反馈
- 指导 Dev AI 和 QA AI 工作，分配任务队列
**可读但不可写：**
- 👁 AI 配置文件 (`.ai/`) —— 只读，了解团队规则
- 👁 测试代码 (`projects/*/tests/`) —— 只读，了解测试覆盖
- 👁 测试报告 (`reports/`) —— 只读，了解质量状况
- 👁 测试反馈 (`review/*/feedback/`) —— 只读，了解问题
### Dev AI
- 可写：业务代码、技术文档、项目级文档、开发工具、训练数据、共享资源、验收标准、影响评估
- 只读：任务描述、测试反馈
- 禁止：测试代码、测试报告
**禁止操作：**
- ❌ 无（架构 AI 拥有最高 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/`)
**可读但不可写：**
- 👁 业务代码 (`projects/*/src/`) —— 只读，理解逻辑编写测试
- 👁 技术文档 (`projects/*/docs/`) —— 只读，了解接口设计
- 👁 项目级文档 (`docs/`) —— 只读，了解系统架构
- 👁 训练数据 (`data/`) —— 只读，了解数据分布
- 👁 共享资源 (`shared/`) —— 只读，了解工具函数
- 👁 任务描述 (`review/*/task.md`) —— 只读，了解测试目标
- 👁 验收标准 (`review/*/acceptance.md`) —— 只读，了解测试要求
**禁止操作：**
- ❌ 修改业务代码 (`projects/*/src/`)
- ❌ 修改技术文档 (`projects/*/docs/`)
- ❌ 修改共享资源 (`shared/`)
- ❌ 修改影响评估 (`review/*/impact.md`)
- ❌ 修改开发工具 (`tools/`)
- ❌ 修改测试反馈 (`review/*/feedback/`)
### 人类负责人
**职责范围：**
- ✅ 可以修改所有目录
- ✅ 审核 AI 输出质量
- ✅ 解决 AI 之间的冲突
- ✅ 最终决策和验收
---
## 工作流程
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 需求分析 │ ───→ │ 架构设计 │ ───→ │ 开发实现 │ ───→ │ 测试验证 │ ───→ │ 验收确认 │
│ (Arch AI) │ │ (Arch AI) │ │ (Dev AI) │ │ (QA AI) │ │ (人类) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
↑ │
│ Bug → 修复 │
└──────────────────────┘
(最多 2 轮)
```
### 详细流程说明
**1. 需求分析阶段**
- Arch AI 分析用户需求，输出产品规划
- 输出: `docs/01_产品需求/PRD.md`、`review/{task_id}/task.md`
**2. 架构设计阶段**
- Arch AI 设计系统架构，技术选型
- 输出: `docs/02_系统架构/`、`review/{task_id}/impact.md`、`review/{task_id}/acceptance.md`
**3. 开发实现阶段**
- Dev AI 读取任务描述和验收标准，编写代码 + 文档
- 输出: `projects/*/src/`, `projects/*/docs/`
**4. 测试验证阶段**
- 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/`
### QA AI
- 可写：测试用例、测试报告、验收标准补充、测试反馈
- 只读：业务代码、技术文档、项目级文档、训练数据、共享资源、任务描述
- 禁止：AI 配置、开发工具、影响评估
---
## 目录权限矩阵
> **图例**：`-` = 无权访问 &nbsp;&nbsp; `R` = 只读 &nbsp;&nbsp; `W` = 可写（含读） &nbsp;&nbsp; `RW` = 读写
> 图例：`-` = 禁止 &nbsp;&nbsp; `R` = 只读 &nbsp;&nbsp; `W` = 可写（含读） &nbsp;&nbsp; `RW` = 读写
| 目录路径 | Arch AI | Dev AI | QA AI | 人类 |
|---------|---------|--------|-------|------|
@@ -176,58 +75,33 @@ Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类
| `reports/` | `R` | `-` | `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清单** - 列出问题和严重程度
- **改进建议** - 代码优化建议
优先级：`forbidden > read_only > allowed`。未出现在表中的路径默认禁止所有 AI。
---
## 命名规范
### 项目命名
```
P01_项目名称 # P01 表示项目编号
```
### 任务编号
```
P01-001 # P01 项目编号 + 001 任务编号
```
`P{项目编号}-{任务序号}`，如 `P01-001`
### 分支命名
```
feature/P01-001-login # 功能开发
bugfix/P01-001-password # Bug修复
test/P01-001-testcases # 测试用例
feature/P01-001-short-desc # 功能开发
bugfix/P01-001-short-desc # Bug修复
test/P01-001-short-desc # 测试用例
```
### 提交信息
```
feat(P01-001): 实现用户登录功能
fix(P01-001): 修复密码验证问题
docs(P01-001): 更新接口文档
test(P01-001): 添加登录测试用例
feat(P01-001): 简短描述
fix(P01-001): 简短描述
docs(P01-001): 简短描述
test(P01-001): 简短描述
```
---
## AI 配置文件说明
## AI 配置文件索引
| 文件 | 说明 |
|------|------|
@@ -237,4 +111,7 @@ test(P01-001): 添加登录测试用例
| `.ai/config/workflow.json` | 工作流配置（阶段、触发器） |
| `.ai/prompts/architecture/` | 架构设计提示词模板 |
| `.ai/prompts/coding/` | 编码提示词模板 |
| `.ai/prompts/testing/` | 测试提示词模板 |
| `.ai/prompts/testing/` | 测试提示词模板 |
| `.ai/roles/` | AI 角色工作台（日常入口） |
| `.ai/phases/` | 阶段上下文 |
| `.ai/knowledge/` | 知识沉淀 |