hwd32/ai_soc_sw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
新增四层信息架构：
- 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>
This commit is contained in:
tupingr
2026-05-25 16:49:36 +08:00
parent 5dfc382c55
commit 4184a6d0b5
65 changed files with 1642 additions and 582 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01_产品需求/README.md
+19
View File
@@ -0,0 +1,19 @@
# 产品需求
本目录存放产品需求文档。文档由 Arch AI 编写，人类审阅。
## 文件说明
| 文件 | 说明 | 状态 |
|------|------|------|
| PRD.md | 产品需求文档（主文档） | 待编写 |
## 编写时机
Phase 1 基础搭建阶段完成信息架构重构后，Arch AI 将在此编写 PRD。
## 相关链接
- 阶段上下文: `.ai/phases/phase-01-foundation/`
- 架构决策: `.ai/knowledge/decisions.md`
- 路线图: `ROADMAP.md`
docs/02_系统架构/README.md
+22
View File
@@ -0,0 +1,22 @@
# 系统架构
本目录存放系统架构设计文档。文档由 Arch AI 编写。
## 文件说明
| 文件 | 说明 | 状态 |
|------|------|------|
| 总体架构.md | 系统总体架构设计 | 待编写 |
| 技术选型.md | 技术选型评估 | 待编写 |
| 模块设计.md | 主要模块设计 | 待编写 |
| 数据模型.md | 数据库 Schema 设计 | 待编写 |
## 编写时机
PRD 完成，进入架构设计阶段后开始编写。
## 相关链接
- 架构提示词模板: `.ai/prompts/architecture/`
- 架构决策: `.ai/knowledge/decisions.md`
- 阶段架构快照: `.ai/phases/phase-01-foundation/architecture.md`
docs/03_开发规范/README.md
+17
View File
@@ -0,0 +1,17 @@
# 开发规范
本目录存放项目开发规范文档。
## 文件说明
| 文件 | 说明 | 状态 |
|------|------|------|
| 编码规范.md | 代码风格和命名规范 | 已有 `.ai/prompts/coding/code-style.md` |
| 提交规范.md | Git 提交信息规范 | 已有 `AGENTS.md` 提交信息部分 |
| 文档规范.md | 文档编写规范 | 待编写 |
## 相关链接
- AI 代码规范: `.ai/prompts/coding/code-style.md`
- 文档模板: `.ai/prompts/coding/doc-template.md`
- 信息架构原则: `.ai/principles.md`
docs/04_部署运维/README.md
+20
View File
@@ -0,0 +1,20 @@
# 部署运维
本目录存放部署和运维相关文档。
## 文件说明
| 文件 | 说明 | 状态 |
|------|------|------|
| 部署架构.md | 部署拓扑和环境说明 | 待编写 |
| CI_CD.md | 持续集成/持续部署配置 | 待编写 |
| 运维手册.md | 日常运维操作手册 | 待编写 |
## 编写时机
Phase 2 MVP 有可部署产物后开始编写。
## 相关链接
- 环境配置: `ENVIRONMENT.md`
- 各子项目环境: `projects/P0X_*/ENVIRONMENT.md`
docs/05_变更日志/2026-05-25.md
+37
View File
@@ -0,0 +1,37 @@
# 2026-05-25 — 信息架构重构
## 概述
将项目信息架构从"人类导向单体文档"重构为"AI 优先分层架构"。
## 新增
- `.ai/roles/` — AI 角色工作台（Arch/Dev/QA 各含 card + today + queue）
- `.ai/phases/` — 阶段上下文（Phase 1-4，含 goal/scope/architecture/decisions/completion）
- `.ai/knowledge/` — 知识沉淀（decisions、patterns、lessons、journal）
- `.ai/prompts/architecture/` — 架构提示词模板（architecture-design、technical-evaluation）
- `.ai/principles.md` — 信息架构设计原则
- `ROADMAP.md` — 项目路线图看板（根目录）
- `DASHBOARD.md` — 人类仪表盘（根目录）
- `docs/share/` — 对外分享内容层
- `review/active/INDEX.md` — 活跃任务索引
- `docs/01-04/README.md` — 各文档目录说明
## 修改
- `AGENTS.md` — 压缩至 ~120 行，顶部添加 AI 角色工作台跳转
- `README.md` — 精简，聚焦人类读者，加入 DASHBOARD/ROADMAP/share 链接
- `docs/PROJECT_CONTEXT.md` — 精简，添加分层架构说明和跳转
- `docs/DECISIONS.md` — 替换为跳转存根（内容迁移至 .ai/knowledge/decisions.md）
- `review/active/*/task.md` — 5 个任务均添加 `阶段: Phase 1` 字段
## 决策
- ADR-007: 分层信息架构 + Token 预算制度
- D-001: 信息架构分层设计
- D-002: 阶段化上下文加载
- D-003: 角色工作台代替全局入口
## 维护者
Arch AI
docs/DECISIONS.md
+2 -151
View File
@@ -1,154 +1,5 @@
# 架构决策记录 (ADR)
## 什么是 ADR？
ADR 已迁移至 [.ai/knowledge/decisions.md](../.ai/knowledge/decisions.md)。
ADR（Architecture Decision Record）记录项目中重要的架构决策及其原因。当新成员（或 AI）加入时，可以通过 ADR 快速理解"为什么这么做"。
## 决策记录
### ADR-001: 采用"1 人 + 2AI"协作框架
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
项目需要高效开发，但团队只有 1 人。利用 AI 辅助编程可以大幅提升效率。
**决策**:
采用 1 个负责人 + 2 个 AI（Dev AI 编码 + QA AI 测试）的协作模式。
**后果**:
- ✅ 开发效率大幅提升
- ✅ 代码质量有保障（独立测试 AI）
- ⚠️ 需要维护权限体系和协作流程
- ⚠️ 人类需要审阅 AI 输出
---
### ADR-002: 采用 R/W/RW/- 四态权限体系
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
初始框架使用简单的 allowed/forbidden 二元权限，无法满足"只读"场景。
**决策**:
采用四态权限：`-`（无权）、`R`（只读）、`W`（可写）、`RW`（读写）。
**后果**:
- ✅ 更细粒度的权限控制
- ✅ 明确只读路径（如 task.md、feedback/）
- ⚠️ 权限矩阵更复杂，需要维护
---
### ADR-003: 项目级文档放在根目录 docs/
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
项目级文档（产品需求、架构设计等）不属于任何子项目，需要独立存放。
**决策**:
在根目录创建 `docs/` 目录，而非 `projects/P00_DOCS/`。
**后果**:
- ✅ 语义清晰，业界标准
- ✅ 路径简短
- ⚠️ 需要在权限矩阵中单独定义
---
### ADR-004: 新增 tools/ 和 data/ 目录
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
开发工具脚本和训练数据需要独立管理，不应混入项目代码。
**决策**:
在根目录创建 `tools/`（开发工具）和 `data/`（训练数据）。
**权限**:
- `tools/`: Dev AI 可写，QA AI 禁止
- `data/`: Dev AI 可写，QA AI 只读
**后果**:
- ✅ 职责分离，便于管理
- ✅ 训练数据独立于代码
- ⚠️ 需要维护数据版本
---
### ADR-005: 工作流增加 retry 和 escalation 机制
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
线性工作流无法处理测试失败的情况。
**决策**:
- 增加 retry 机制：最多 3 轮测试修复循环
- 增加 escalation 机制：第 3 轮仍有 BLOCKER/HIGH 时升级给人类
**后果**:
- ✅ 自动处理常见 Bug 修复
- ✅ 严重问题及时升级
- ⚠️ 需要维护修复轮次计数
---
### ADR-006: 创建 resume-context Skill 解决多电脑同步
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
用户在家和单位两台电脑间切换，需要快速恢复开发上下文。
**决策**:
- 创建 `resume-context` Skill
- 创建 `docs/PROJECT_CONTEXT.md` 项目上下文
- 创建 `docs/06_开发日志/` 按日期记录讨论
**后果**:
- ✅ 换电脑后快速恢复上下文
- ✅ 新 AI 对话可以读取背景
- ⚠️ 需要维护文档更新
---
## 决策模板
```markdown
### ADR-XXX: 决策标题
**日期**: YYYY-MM-DD
**状态**: 考虑中 / 已采纳 / 已废弃
**决策者**: XXX
**背景**:
[为什么需要做这个决策]
**决策**:
[具体决定是什么]
**后果**:
- ✅ 好处
- ⚠️ 需要注意的点
```
---
**最后更新**: 2026-05-23
**维护者**: 人类负责人 + Dev AI
该文件包含全部 7 条 ADR（含 ADR-007: 分层信息架构 + Token 预算）。
docs/PROJECT_CONTEXT.md
+35 -100
View File
@@ -1,117 +1,52 @@
# 项目上下文 - ErrLens 错题本
# 项目上下文
## 项目愿景
## 项目概述
打造跨平台的学生错题本应用，配套 Web 管理后台和数据训练算法，形成"数据采集 → AI 分析 → 个性化推荐"的数据飞轮。
ErrLens 是一个学生错题本应用。核心概念是"数据飞轮"：收集错题 → AI 分析 → 个性化推荐。
包含三个子项目：
- **P01_errlens_app** — 跨平台小程序（Taro + React + NestJS）
- **P02_errlens_training** — AI 训练算法（Python + PyTorch）
- **P03_errlens_web** — Web 管理后台（Next.js）
## 当前阶段
**框架搭建阶段**（2026-05-23 完成）
Phase 1: 基础搭建。完成协作框架和项目脚手架。
已完成：
- ✅ "1 人 + 3AI（Arch AI + Dev AI + QA AI）"协作框架
- ✅ 完整目录结构和权限体系（R/W/RW/- 四态）
- ✅ AI 配置文件（architect.json、coder.json、tester.json、workflow.json）
- ✅ 提示词模板（architecture/、coding/、testing/）
- ✅ Skill 工具（7 个）
- ✅ 项目级文档目录（docs/、tools/、data/）
待启动：
- ⏳ P01_errlens_app 小程序开发
- ⏳ P02_errlens_training 数据训练算法
- ⏳ P03_errlens_web Web 管理后台
→ 当前进度和任务看板：[ROADMAP.md](../ROADMAP.md)
→ 人类视角仪表盘：[DASHBOARD.md](../DASHBOARD.md)
## 技术栈
| 层级 | 技术选型 | 说明 |
|------|---------|------|
| 小程序 | Taro + React + TypeScript | 跨平台（微信优先，预留支付宝/抖音） |
| Web 管理 | Next.js + React + TypeScript | SSR，便于 SEO 和性能 |
| 后端 | NestJS + TypeScript | 统一语言，便于维护 |
| 数据库 | PostgreSQL | 关系型数据，支持复杂查询 |
| AI 训练 | Python + PyTorch | 错题分析和推荐算法 |
| 包管理 | pnpm | 快速、节省磁盘空间 |
| 协作框架 | 1 人 + 2AI | Dev AI（编码）+ QA AI（测试） |
| 层 | 技术 |
|----|------|
| 前端 (P01) | Taro 4 + React 18 + TypeScript + Tailwind CSS |
| 后端 (P01) | NestJS 10 + TypeScript |
| 数据库 | PostgreSQL |
| Web (P03) | Next.js（Phase 2 启动） |
| AI (P02) | Python + PyTorch（Phase 2 启动） |
| 包管理 | pnpm monorepo |
| 测试 | Jest |
## 团队架构
## 团队
```
人类负责人（唯一决策者）
├── Dev AI（编码 AI）- 编写代码、文档、影响评估
└── QA AI（测试 AI）- 编写测试、执行测试、质量保障
```
"1 人类 + 3 AI" 协作模式。详见 [AGENTS.md](../AGENTS.md)。
详细权限见 [AGENTS.md](../AGENTS.md)
## 信息架构
## 关键决策
项目采用分层信息架构，针对 AI 上下文窗口优化：
- AI 入口：`.ai/roles/{role}/card.md` + `today.md`（< 2K tokens）
- 阶段上下文：`.ai/phases/phase-NN/`（< 5K tokens）
- 知识沉淀：`.ai/knowledge/`（自动积累）
- 设计原则：`.ai/principles.md`
| 决策 | 原因 | 日期 |
|------|------|------|
| 采用 R/W/RW/- 四态权限体系 | 比二元权限更灵活，明确只读路径 | 2026-05-23 |
| 项目级文档放在根目录 docs/ | 不属于任何子项目，业界标准做法 | 2026-05-23 |
| 新增 tools/ 和 data/ 目录 | 开发工具和训练数据需要独立管理 | 2026-05-23 |
| 创建 resume-context Skill | 解决多电脑切换时的上下文同步问题 | 2026-05-23 |
| 工作流增加 retry 机制 | 允许最多 3 轮测试修复循环 | 2026-05-23 |
| 工作流增加 escalation 机制 | 第 3 轮仍有严重 Bug 时升级给人类 | 2026-05-23 |
| 新增 Arch AI 角色 | 需求分析和架构设计需要专门的 AI 角色 | 2026-05-23 |
| 创建 7 个 Skill 工具 | 标准化常用操作，减少重复劳动 | 2026-05-23 |
| switch-model 必须指定角色 | 不同角色检查不同内容，避免信息过载 | 2026-05-23 |
| switch-model git 检查优先 | 确保在安全环境下加载上下文 | 2026-05-23 |
## 架构决策
## 待解决问题
→ [.ai/knowledge/decisions.md](../.ai/knowledge/decisions.md)
1. **Web 管理后台具体功能** - 尚未确定，需要简化设计，保持可扩展性
2. **数据来源** - 用户有一些数据但不够，需要数据飞轮思维
3. **跨平台优先级** - 目前主要是微信，但框架上要考虑跨平台
4. **AI 训练算法细节** - 错题分析和推荐算法的具体实现方案
## 关键待办
## 下一步计划
1. [ ] 完成产品需求文档（PRD）
2. [ ] 完成系统架构设计
3. [ ] 启动 P01_errlens_app 小程序开发
4. [ ] 设计数据采集方案
5. [ ] 规划 Web 管理后台功能
## 项目结构
```
errlens/
├── docs/ # 项目级总体文档
│ ├── 01_产品需求/
│ ├── 02_系统架构/
│ ├── 03_开发规范/
│ ├── 04_部署运维/
│ ├── 05_变更日志/
│ │ └── archived/ # 历史变更日志（按年月归档）
│ └── 06_开发日志/
├── tools/ # 开发工具脚本
├── data/ # 训练数据
├── projects/ # 子项目
│ ├── P01_errlens_app/ # 错题本小程序
│ ├── P02_errlens_training/# 数据训练算法
│ └── P03_errlens_web/ # Web 管理后台
├── review/ # 任务交接中心
├── reports/ # 测试/质量报告
├── shared/ # 共享资源
└── .ai/ # AI 协作配置
```
## 开发环境
- **操作系统**: Windows / macOS / Linux（跨平台开发）
- **IDE**: Trae CN
- **Node.js**: >= 20.x
- **包管理器**: pnpm >= 9.0.0
- **Python**: >= 3.10（AI 训练）
## 同步机制
- **代码同步**: Git（远程仓库：GitCode）
- **上下文同步**: `docs/PROJECT_CONTEXT.md` + `docs/06_开发日志/`
- **恢复上下文**: 使用 `resume-context` Skill
---
**最后更新**: 2026-05-23
**维护者**: 人类负责人 + Dev AI
- [ ] 编写错题本 PRD
- [ ] 设计系统架构文档
- [ ] 将 P01 文档从"代码检测"改写为"错题本"
- [ ] 启动 P03 Web 项目初始化
docs/share/00_项目缘起.md
+5
View File
@@ -0,0 +1,5 @@
# 项目缘起
> *（待写：由 Arch AI 在 PRD 完成后撰写）*
>
> 内容包括：为什么要做错题本、解决什么痛点、为什么选择这个技术方案、为什么用 AI 协作模式。
docs/share/01_框架设计思路.md
+8
View File
@@ -0,0 +1,8 @@
# 框架设计思路
> *（待写：信息架构重构稳定后撰写）*
>
> 内容包括：为什么传统的项目文档结构对 AI 不友好、分层信息架构的设计思考、token 预算的概念、"一鸡多吃"的分享层设计。
>
> 对应 ADR：ADR-007
> 背景参考：`.ai/principles.md`
docs/share/README.md
+41
View File
@@ -0,0 +1,41 @@
# 分享内容
这里记录 ErrLens 从零到一的完整开发过程。每一个决策、每一次踩坑、每一个阶段性成果，都会沉淀到这里。
**目标读者**：对 AI 辅助编程感兴趣的人、想做类似项目的人、未来的自己。
---
## 内容目录
| 文件 | 说明 | 状态 |
|------|------|------|
| [00_项目缘起.md](00_项目缘起.md) | 为什么要做这个项目 | 待写 |
| [01_框架设计思路.md](01_框架设计思路.md) | 信息架构为什么这样设计 | 待写 |
## 按阶段
| 阶段 | 复盘 | 决策故事 | 状态 |
|------|------|----------|------|
| Phase 1: 基础搭建 | [阶段复盘](phase-01/阶段复盘_基础搭建.md) | [ADR-007 故事](phase-01/决策故事_ADR-007.md) | 待写 |
| Phase 2: MVP | — | — | 未开始 |
---
## 分享原则
1. **不是做完再写**：开发过程中自动积累，阶段结束时翻译为对外语言
2. **去掉内部细节**：不暴露 API 密钥、服务器地址、个人信息
3. **加上思考过程**：不只说"做了什么"，更要说"为什么这么选"
4. **可独立阅读**：每篇文章自成一体，不需要读其他文章才能理解
## 内容来源
```
开发过程中的产出 → 对外分享内容
─────────────────────────────────────────────
.ai/knowledge/decisions.md → 决策故事（加背景、加思考）
.ai/phases/*/completion.md → 阶段复盘（扩展为文章）
.ai/knowledge/lessons.md → 踩坑记录（精选）
.ai/knowledge/journal/ → 开发周记（合并精选）
```
docs/share/phase-01/决策故事_ADR-007.md
+5
View File
@@ -0,0 +1,5 @@
# ADR-007 决策故事
> 信息架构为什么从"单体文档"变成"分层设计"
>
> *（Phase 1 完成时撰写，基于 `.ai/knowledge/decisions.md` 中的 ADR-007 扩展）*
docs/share/phase-01/阶段复盘_基础搭建.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 1: 基础搭建 — 阶段复盘
> *（Phase 1 完成时由 Arch AI 撰写，基于 `.ai/phases/phase-01-foundation/completion.md` 扩展）*
docs/share/templates/决策故事模板.md
+38
View File
@@ -0,0 +1,38 @@
# 决策故事模板
## 决策编号
ADR-XXX
## 标题
用一句话描述这个决策（吸引人的标题）
## 背景
- 当时在做什么
- 遇到了什么问题
- 有哪些约束条件
## 选项
| 选项 | 优势 | 劣势 |
|------|------|------|
| A | ... | ... |
| B | ... | ... |
| C | ... | ... |
## 思考过程
- 为什么排除了某个选项
- 最纠结的点是什么
- 最终决策的关键因素
## 结果
- 决策带来的影响
- 如果有机会重来，会改变什么
## 一句话总结
（可引用/可传播的一句话）
docs/share/templates/阶段复盘模板.md
+35
View File
@@ -0,0 +1,35 @@
# 阶段复盘模板
## 阶段信息
- 阶段编号：Phase N
- 阶段名称：
- 时间范围：
- 参与角色：
## 做了什么
- （列表形式概述本阶段完成的主要工作）
## 关键决策
- （本阶段最重要的 3-5 个决策及背后的思考）
## 踩过的坑
- （本阶段遇到的主要问题及解决方案）
## 学到的东西
- （可复用的经验教训）
## 数据
- 新增代码行数：
- 任务完成数：
- Bug 修复数：
- 测试覆盖率：
## 下一阶段预告
- （接下来要做什么）
docs/使用手册.md
+323
View File
@@ -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。本文档随架构演变同步更新。