# 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。本文档随架构演变同步更新。