ai_soc_sw/docs/使用手册.md

ErrLens 使用手册

适用对象：人类负责人、Arch AI、Dev AI、QA AI

---

目录

• 人类篇：我怎么管项目
• AI 篇：我怎么干活
  • Arch AI
  • Dev AI
  • QA AI
• 场景篇
  • 日常推进
  • 换电脑/换模型
  • 阶段切换
  • 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。本文档随架构演变同步更新。