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