tupingr
4184a6d0b5
新增四层信息架构： - 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>
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。本文档随架构演变同步更新。
|