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

新增四层信息架构： - 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>
2026-05-25 16:49:36 +08:00
parent 5dfc382c55
commit 4184a6d0b5
65 changed files with 1642 additions and 582 deletions
@@ -0,0 +1,323 @@
+# ErrLens 使用手册
+
+> 适用对象：人类负责人、Arch AI、Dev AI、QA AI
+
+---
+
+## 目录
+
+- [人类篇：我怎么管项目](#人类篇我怎么管项目)
+- [AI 篇：我怎么干活](#ai-篇我怎么干活)
+  - [Arch AI](#arch-ai-架构师)
+  - [Dev AI](#dev-ai-开发者)
+  - [QA AI](#qa-ai-测试者)
+- [场景篇](#场景篇)
+  - [日常推进](#场景一日常推进)
+  - [换电脑/换模型](#场景二换电脑换模型)
+  - [阶段切换](#场景三阶段切换)
+  - [Bug 修复循环](#场景四bug-修复循环)
+  - [产出分享内容](#场景五产出分享内容)
+- [速查表](#速查表)
+
+---
+
+## 人类篇：我怎么管项目
+
+### 第一次进来
+
+```
+1. 打开 DASHBOARD.md（根目录，30 秒读完）
+   → 了解：现在在哪个阶段、进度如何、有什么阻塞
+2. 打开 ROADMAP.md（想看更多细节时）
+   → 看：任务看板、谁在干什么、什么被卡住了
+3. 打开 docs/使用手册.md（就是本文档）
+   → 了解：怎么跟 AI 协作
+```
+
+### 日常工作
+
+| 你想干嘛 | 去哪个文件 | 干什么 |
+|----------|-----------|--------|
+| 看看进度 | `DASHBOARD.md` | 一眼看到阶段和阻塞 |
+| 看谁在干什么 | `ROADMAP.md` → 任务看板 | 看 DOING 列 |
+| 看某个任务详情 | `review/active/{任务ID}/task.md` | 任务描述 |
+| 看测试结果 | `reports/` | QA AI 生成的报告 |
+| 看为什么这样设计 | `.ai/knowledge/decisions.md` | 架构决策记录 |
+| 找可分享的内容 | `docs/share/` | 对外文章 |
+
+### 你做决策的时机
+
+1. **阶段开始** — 审阅 Arch AI 的 PRD 和架构设计，签字后 Dev AI 才能开工
+2. **阶段结束** — 审阅 completion.md 和测试报告，签字后进入下一阶段
+3. **任务验收** — QA AI 通过后，你最终确认任务完成
+4. **升级裁决** — 当 Bug 修复 3 轮还没搞定（ROADMAP.md 会标红），需要你来拍板
+
+### 你不需要懂的东西
+
+- `projects/*/src/` — 代码，交给 Dev AI
+- `projects/*/tests/` — 测试代码，交给 QA AI
+- `.ai/config/` — AI 配置文件，Arch AI 维护
+- 成品出来后你直接用，感受告诉我就行
+
+---
+
+## AI 篇：我怎么干活
+
+### 核心原则
+
+```
+每次会话只读 3 个文件：
+  1. .ai/roles/{你的角色}/card.md    ← 我是谁（不变）
+  2. .ai/roles/{你的角色}/today.md   ← 今天干嘛（会变）
+  3. ROADMAP.md 或 具体任务文件        ← 按需
+
+不要从头遍历项目。用链接按需加载。
+```
+
+---
+
+### Arch AI（架构师）
+
+#### 进来第一件事
+
+```
+读 .ai/roles/arch/card.md   → 身份、权限、当前阶段
+读 .ai/roles/arch/today.md  → 今天要干什么
+读 ROADMAP.md               → 全局进度、阻塞项
+```
+
+#### 日常工作
+
+| 做什么 | 怎么做 | 产出 |
+|--------|--------|------|
+| 写 PRD | 读 `docs/share/00_项目缘起.md`（了解背景）→ 写 `docs/01_产品需求/PRD.md` | PRD.md |
+| 设计架构 | 用 `.ai/prompts/architecture/architecture-design.md` 模板 | `docs/02_系统架构/` |
+| 评估技术 | 用 `.ai/prompts/architecture/technical-evaluation.md` 模板 | 技术评估文档 |
+| 分配任务 | 更新各角色 `queue.md` 和 `today.md`，同步 `ROADMAP.md` | 任务分配完成 |
+| 定义验收标准 | 写 `review/active/{任务ID}/acceptance.md` | 验收标准 |
+| 评估变更影响 | 写 `review/active/{任务ID}/impact.md` | 影响评估 |
+| 记录决策 | 在 `.ai/knowledge/decisions.md` 新增 ADR | 决策记录 |
+| 记录模式 | 同样的做法出现 3 次，写入 `.ai/knowledge/patterns.md` | 模式沉淀 |
+
+#### 完成工作后
+
+```
+1. 更新 today.md（标记完成，添加下一个任务）
+2. 更新 ROADMAP.md（如有任务状态变化）
+3. 写 .ai/knowledge/journal/{日期}.md（简要记录今天做了什么）
+```
+
+#### 阶段切换（重要）
+
+```
+1. 检查 completion.md 全部打勾
+2. 更新 ROADMAP.md 阶段进度
+3. 更新所有 .ai/roles/{*}/card.md 的当前阶段
+4. 更新 .ai/phases/INDEX.md
+5. 写 docs/share/phase-NN/阶段复盘_*.md（对外分享）
+6. 通知人类签字
+```
+
+---
+
+### Dev AI（开发者）
+
+#### 进来第一件事
+
+```
+读 .ai/roles/dev/card.md   → 身份、权限、当前阶段
+读 .ai/roles/dev/today.md  → 今天要干什么、领哪个任务
+```
+
+#### 领取任务
+
+```
+1. 看 today.md 的"待领取"列
+2. 选一个无阻塞的任务
+3. 读 review/active/{任务ID}/task.md       → 理解任务
+4. 读 review/active/{任务ID}/acceptance.md  → 看验收标准
+5. 读 review/active/{任务ID}/impact.md      → 了解影响范围
+6. 开始写代码
+```
+
+#### 写代码时
+
+| 需要什么 | 去哪里 |
+|----------|--------|
+| 代码风格 | `.ai/prompts/coding/code-style.md` |
+| 文档模板 | `.ai/prompts/coding/doc-template.md` |
+| 阶段架构 | `.ai/phases/phase-01-foundation/architecture.md` |
+| 共享工具 | `shared/utils/` |
+
+#### 完成代码后
+
+```
+1. 写/更新项目文档（projects/{项目}/docs/）
+2. 更新 today.md（标记完成）
+3. 通知 QA AI（更新 ROADMAP.md 任务状态为 REVIEW）
+4. 写 .ai/knowledge/journal/{日期}.md（简要记录）
+```
+
+#### 修 Bug
+
+```
+1. 读 review/active/{任务ID}/feedback/round{N}.md   → 看 QA 的反馈
+2. 只修反馈中列出的 Bug，不改其他东西
+3. 修完后通知 QA AI 复查（不重写 acceptance/impact）
+```
+
+---
+
+### QA AI（测试者）
+
+#### 进来第一件事
+
+```
+读 .ai/roles/qa/card.md   → 身份、权限
+读 .ai/roles/qa/today.md  → 今天有什么要测的
+读 ROADMAP.md             → 看 REVIEW 列有没有新任务
+```
+
+#### 开始测试
+
+```
+1. 确认 ROADMAP.md 中有 REVIEW 状态的任务
+2. 读 review/active/{任务ID}/task.md         → 理解任务
+3. 读 review/active/{任务ID}/acceptance.md    → 确认验收标准
+4. 读 review/active/{任务ID}/impact.md        → 确定回归测试范围
+5. 在 projects/{项目}/tests/ 编写测试
+6. 执行测试
+7. 生成报告到 reports/
+8. 写反馈到 review/active/{任务ID}/feedback/round{N}.md
+```
+
+#### Bug 报告规则
+
+| 级别 | 定义 | 行动 |
+|------|------|------|
+| BLOCKER | 功能完全不可用 | Dev AI 必须立即修复 |
+| HIGH | 核心功能有严重问题 | Dev AI 必须修复 |
+| MEDIUM | 边缘场景问题 | Dev AI 应修复 |
+| LOW | 建议优化 | Dev AI 可选修复 |
+
+用 `.ai/prompts/testing/bug-report.md` 模板。
+
+#### 修复循环
+
+```
+Round 1: 初始测试 → 写 feedback/round1.md
+Round 2: 复查修复 → 写 feedback/round2.md
+Round 3: 最终复查 → 写 feedback/round3.md
+  仍有 BLOCKER/HIGH → ⚠️ 升级给人类
+```
+
+---
+
+## 场景篇
+
+### 场景一：日常推进
+
+**人类**：
+1. 早上打开 `DASHBOARD.md` 看一眼
+2. 打开 `ROADMAP.md` 看阻塞项
+3. 该干嘛干嘛，有问题 AI 会标红
+
+**AI**：
+1. 读 card.md + today.md
+2. 按 today.md 的任务清单推进
+3. 完成一个标记一个
+4. 每天写一行 journal
+
+### 场景二：换电脑/换模型
+
+**换电脑**：用 `resume-context` Skill → 自动加载 DASHBOARD + ROADMAP + 当前阶段上下文
+
+**换模型**（比如从 DeepSeek 换成 Claude）：用 `switch-model` Skill → 指定角色 → 自动加载角色工作台
+
+**手动恢复**：
+```
+1. 读 DASHBOARD.md → 知道现在在哪
+2. 读 .ai/roles/{你的角色}/card.md → 知道你是谁
+3. 读 .ai/roles/{你的角色}/today.md → 知道该干嘛
+```
+
+### 场景三：阶段切换
+
+```
+Phase 1 完成 → Phase 2 启动：
+
+1. Arch AI 检查 completion.md 全部打勾
+2. Arch AI 写阶段复盘到 docs/share/phase-01/
+3. 人类签字确认
+4. Arch AI 更新：
+   ├── ROADMAP.md（阶段进度条）
+   ├── .ai/phases/INDEX.md（状态改为 DONE/ACTIVE）
+   ├── .ai/roles/*/card.md（当前阶段字段）
+   └── .ai/roles/*/today.md（新阶段首批任务）
+5. 新阶段启动，所有 AI 从新 today.md 开始
+```
+
+### 场景四：Bug 修复循环
+
+```
+Dev AI 提交代码
+  → QA AI 测试
+    → 有 Bug? 
+      ├── 是 → feedback/round1.md
+      │        → Dev AI 修复
+      │          → QA AI 复查
+      │            → 还有 Bug?
+      │              ├── 是 → feedback/round2.md
+      │              │        → Dev AI 修复
+      │              │          → QA AI 复查
+      │              │            → 还有 Bug?
+      │              │              ├── 是(BLOCKER/HIGH) → ⚠️ 升级人类
+      │              │              └── 否 → ✅ DONE
+      │              └── 否 → ✅ DONE
+      └── 否 → ✅ DONE
+```
+
+### 场景五：产出分享内容
+
+```
+条件：阶段完成或重要决策产生
+执行者：Arch AI
+
+1. 从 .ai/knowledge/decisions.md 选一个决策
+2. 用 docs/share/templates/决策故事模板.md 写故事版
+3. 从 .ai/phases/*/completion.md 提取阶段总结
+4. 用 docs/share/templates/阶段复盘模板.md 写复盘
+5. 放到 docs/share/phase-NN/
+6. 更新 docs/share/README.md 的状态
+
+原则：不是重写，是"翻译"——加背景、加思考、去掉内部细节
+```
+
+---
+
+## 速查表
+
+### 我想知道...
+
+| 问题 | 答案在哪 |
+|------|----------|
+| 项目总进度 | `DASHBOARD.md` |
+| 谁在干什么 | `ROADMAP.md` 看板 |
+| 这个任务怎么做 | `review/active/{ID}/task.md` |
+| 这个设计为什么这样 | `.ai/knowledge/decisions.md` |
+| AI 有什么权限 | `AGENTS.md`（权威）或 `.ai/roles/{role}/card.md`（摘要） |
+| 代码怎么写才规范 | `.ai/prompts/coding/code-style.md` |
+| 测试怎么报告 Bug | `.ai/prompts/testing/bug-report.md` |
+| 架构设计怎么出 | `.ai/prompts/architecture/architecture-design.md` |
+| 现在是什么阶段 | `DASHBOARD.md` 或 `.ai/phases/phase-01-foundation/goal.md` |
+| 踩过什么坑 | `.ai/knowledge/lessons.md` |
+| 今天做了什么 | `.ai/knowledge/journal/{日期}.md` |
+| 能对外发什么 | `docs/share/` |
+| 怎么装开发环境 | `ENVIRONMENT.md` |
+| 新加入一个 AI 怎么上手 | 读本文档 + 读对应角色的 card.md + today.md |
+
+---
+
+## 维护者
+
+Arch AI。本文档随架构演变同步更新。