From 4184a6d0b5004b1d1c2ca38855a8575ad6fbacdb Mon Sep 17 00:00:00 2001 From: tupingr Date: Mon, 25 May 2026 16:49:36 +0800 Subject: [PATCH] =?UTF-8?q?refactor(architecture):=20=E4=BF=A1=E6=81=AF?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E9=87=8D=E6=9E=84=20=E2=80=94=20=E4=BB=8E"?= =?UTF-8?q?=E4=BA=BA=E7=B1=BB=E5=AF=BC=E5=90=91=E5=8D=95=E4=BD=93=E6=96=87?= =?UTF-8?q?=E6=A1=A3"=E5=88=B0"AI=E4=BC=98=E5=85=88=E5=88=86=E5=B1=82?= =?UTF-8?q?=E6=9E=B6=E6=9E=84"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增四层信息架构： - 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 --- .ai/knowledge/decisions.md | 57 ++++ .ai/knowledge/journal/.gitkeep | 0 .ai/knowledge/journal/2026-05-25.md | 35 ++ .ai/knowledge/lessons.md | 25 ++ .ai/knowledge/patterns.md | 39 +++ .ai/phases/INDEX.md | 17 + .../phase-01-foundation/architecture.md | 45 +++ .ai/phases/phase-01-foundation/completion.md | 16 + .ai/phases/phase-01-foundation/decisions.md | 27 ++ .ai/phases/phase-01-foundation/goal.md | 27 ++ .ai/phases/phase-01-foundation/scope.md | 42 +++ .ai/phases/phase-02-mvp/architecture.md | 3 + .ai/phases/phase-02-mvp/completion.md | 3 + .ai/phases/phase-02-mvp/decisions.md | 3 + .ai/phases/phase-02-mvp/goal.md | 11 + .ai/phases/phase-02-mvp/scope.md | 3 + .ai/phases/phase-03-features/architecture.md | 3 + .ai/phases/phase-03-features/completion.md | 3 + .ai/phases/phase-03-features/decisions.md | 3 + .ai/phases/phase-03-features/goal.md | 3 + .ai/phases/phase-03-features/scope.md | 3 + .ai/phases/phase-04-polish/architecture.md | 3 + .ai/phases/phase-04-polish/completion.md | 3 + .ai/phases/phase-04-polish/decisions.md | 3 + .ai/phases/phase-04-polish/goal.md | 3 + .ai/phases/phase-04-polish/scope.md | 3 + .ai/principles.md | 47 +++ .ai/prompts/architecture/README.md | 6 + .../architecture/architecture-design.md | 44 +++ .../architecture/technical-evaluation.md | 41 +++ .ai/roles/README.md | 26 ++ .ai/roles/arch/card.md | 34 ++ .ai/roles/arch/queue.md | 18 + .ai/roles/arch/today.md | 22 ++ .ai/roles/dev/card.md | 31 ++ .ai/roles/dev/queue.md | 17 + .ai/roles/dev/today.md | 24 ++ .ai/roles/qa/card.md | 30 ++ .ai/roles/qa/queue.md | 19 ++ .ai/roles/qa/today.md | 18 + AGENTS.md | 235 +++---------- DASHBOARD.md | 58 ++++ README.md | 224 ++++-------- ROADMAP.md | 68 ++++ docs/01_产品需求/README.md | 19 ++ docs/02_系统架构/README.md | 22 ++ docs/03_开发规范/README.md | 17 + docs/04_部署运维/README.md | 20 ++ docs/05_变更日志/2026-05-25.md | 37 ++ docs/DECISIONS.md | 153 +-------- docs/PROJECT_CONTEXT.md | 135 ++------ docs/share/00_项目缘起.md | 5 + docs/share/01_框架设计思路.md | 8 + docs/share/README.md | 41 +++ docs/share/phase-01/决策故事_ADR-007.md | 5 + docs/share/phase-01/阶段复盘_基础搭建.md | 3 + docs/share/templates/决策故事模板.md | 38 +++ docs/share/templates/阶段复盘模板.md | 35 ++ docs/使用手册.md | 323 ++++++++++++++++++ review/active/CROSS-001/task.md | 1 + review/active/INDEX.md | 13 + review/active/P01-001/task.md | 1 + review/active/P01-002/task.md | 1 + review/active/P02-001/task.md | 1 + review/active/P03-001/task.md | 1 + 65 files changed, 1642 insertions(+), 582 deletions(-) create mode 100644 .ai/knowledge/decisions.md create mode 100644 .ai/knowledge/journal/.gitkeep create mode 100644 .ai/knowledge/journal/2026-05-25.md create mode 100644 .ai/knowledge/lessons.md create mode 100644 .ai/knowledge/patterns.md create mode 100644 .ai/phases/INDEX.md create mode 100644 .ai/phases/phase-01-foundation/architecture.md create mode 100644 .ai/phases/phase-01-foundation/completion.md create mode 100644 .ai/phases/phase-01-foundation/decisions.md create mode 100644 .ai/phases/phase-01-foundation/goal.md create mode 100644 .ai/phases/phase-01-foundation/scope.md create mode 100644 .ai/phases/phase-02-mvp/architecture.md create mode 100644 .ai/phases/phase-02-mvp/completion.md create mode 100644 .ai/phases/phase-02-mvp/decisions.md create mode 100644 .ai/phases/phase-02-mvp/goal.md create mode 100644 .ai/phases/phase-02-mvp/scope.md create mode 100644 .ai/phases/phase-03-features/architecture.md create mode 100644 .ai/phases/phase-03-features/completion.md create mode 100644 .ai/phases/phase-03-features/decisions.md create mode 100644 .ai/phases/phase-03-features/goal.md create mode 100644 .ai/phases/phase-03-features/scope.md create mode 100644 .ai/phases/phase-04-polish/architecture.md create mode 100644 .ai/phases/phase-04-polish/completion.md create mode 100644 .ai/phases/phase-04-polish/decisions.md create mode 100644 .ai/phases/phase-04-polish/goal.md create mode 100644 .ai/phases/phase-04-polish/scope.md create mode 100644 .ai/principles.md create mode 100644 .ai/prompts/architecture/README.md create mode 100644 .ai/prompts/architecture/architecture-design.md create mode 100644 .ai/prompts/architecture/technical-evaluation.md create mode 100644 .ai/roles/README.md create mode 100644 .ai/roles/arch/card.md create mode 100644 .ai/roles/arch/queue.md create mode 100644 .ai/roles/arch/today.md create mode 100644 .ai/roles/dev/card.md create mode 100644 .ai/roles/dev/queue.md create mode 100644 .ai/roles/dev/today.md create mode 100644 .ai/roles/qa/card.md create mode 100644 .ai/roles/qa/queue.md create mode 100644 .ai/roles/qa/today.md create mode 100644 DASHBOARD.md create mode 100644 ROADMAP.md create mode 100644 docs/01_产品需求/README.md create mode 100644 docs/02_系统架构/README.md create mode 100644 docs/03_开发规范/README.md create mode 100644 docs/04_部署运维/README.md create mode 100644 docs/05_变更日志/2026-05-25.md create mode 100644 docs/share/00_项目缘起.md create mode 100644 docs/share/01_框架设计思路.md create mode 100644 docs/share/README.md create mode 100644 docs/share/phase-01/决策故事_ADR-007.md create mode 100644 docs/share/phase-01/阶段复盘_基础搭建.md create mode 100644 docs/share/templates/决策故事模板.md create mode 100644 docs/share/templates/阶段复盘模板.md create mode 100644 docs/使用手册.md create mode 100644 review/active/INDEX.md diff --git a/.ai/knowledge/decisions.md b/.ai/knowledge/decisions.md new file mode 100644 index 0000000..c61599e --- /dev/null +++ b/.ai/knowledge/decisions.md @@ -0,0 +1,57 @@ +# 架构决策记录 (ADR) + +## ADR-001: "1 人 + 2 AI" 协作框架 + +- 日期: 2026-05-23 +- 状态: 已采纳（后升级为 1 人 + 3 AI） +- 决策: 采用人类负责人 + Dev AI + QA AI 的三角协作模式 +- 理由: 单人开发需要 AI 辅助，但 AI 不能互审，需要人类做最终决策 +- 影响: 定义了 R/W/RW/- 四级权限体系 + +## ADR-002: 四级权限体系 + +- 日期: 2026-05-23 +- 状态: 已采纳 +- 决策: 采用 `-`(禁止) / `R`(只读) / `W`(可写) / `RW`(读写) 四级权限，比二进制的读写更精细 +- 理由: AI 角色需要明确的边界，"只读但不能写"和"完全不可见"需要区分 +- 影响: 所有目录访问按权限矩阵执行，`forbidden > read_only > allowed` 优先级 + +## ADR-003: 根级 docs/ 目录 + +- 日期: 2026-05-23 +- 状态: 已采纳 +- 决策: 项目级文档放在根目录 `docs/` 而非子项目内 +- 理由: 跨项目共享的文档（架构设计、开发规范）不应属于某个子项目 +- 影响: docs/ 由 Arch AI 和 Dev AI 共同维护 + +## ADR-004: 独立 tools/ 和 data/ 目录 + +- 日期: 2026-05-23 +- 状态: 已采纳 +- 决策: 开发工具脚本和训练数据从 shared/ 中独立出来 +- 理由: tools 和 data 的使用场景和权限需求与 shared 不同 +- 影响: Arch AI 和 Dev AI 可写 tools/ 和 data/，QA AI 只能读 data/ + +## ADR-005: 工作流重试和升级机制 + +- 日期: 2026-05-23 +- 状态: 已采纳 +- 决策: 测试 → 修复循环最多 3 轮，Round 3 仍有 BLOCKER/HIGH 则升级给人类 +- 理由: 防止无限循环，确保严重问题得到人类关注 +- 影响: `skip_acceptance_on_retry: true`，修复轮次不重写验收标准 + +## ADR-006: resume-context Skill 多机同步 + +- 日期: 2026-05-23 +- 状态: 已采纳 +- 决策: 通过 `resume-context` Skill 实现换电脑时上下文恢复 +- 理由: 用户在家和公司两台电脑开发，需要快速恢复 AI 工作上下文 +- 影响: 角色检测、关键文档加载、上下文摘要生成 + +## ADR-007: 分层信息架构 + Token 预算 + +- 日期: 2026-05-25 +- 状态: 已采纳 +- 决策: 采用四层信息架构（工作台 → 路线图 → 阶段上下文 → 知识沉淀），每层有 token 预算 +- 理由: AI 上下文窗口有限（~200K tokens），旧 AGENTS.md 单体文件浪费 token；每个 AI 角色只需要知道自己该干什么 +- 影响: 所有 AI 从 `.ai/roles/{role}/` 启动；新增 `ROADMAP.md`、`DASHBOARD.md`、`docs/share/` 分享层 diff --git a/.ai/knowledge/journal/.gitkeep b/.ai/knowledge/journal/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.ai/knowledge/journal/2026-05-25.md b/.ai/knowledge/journal/2026-05-25.md new file mode 100644 index 0000000..490ebba --- /dev/null +++ b/.ai/knowledge/journal/2026-05-25.md @@ -0,0 +1,35 @@ +# 2026-05-25 — 信息架构重构 + +## 做了什么 + +完成项目信息架构从"人类导向单体文档"到"AI 优先分层架构"的全面重构。 + +### 新增 (~35 个文件) + +- **角色工作台** (`.ai/roles/`): 为 Arch/Dev/QA 三个 AI 角色各创建 card.md + today.md + queue.md，AI 每天只需读 2 个小文件即可开工 +- **阶段上下文** (`.ai/phases/`): Phase 1-4 的阶段目标、范围、架构决策文档。当前 Phase 1 已填充，Phase 2-4 为模板占位 +- **知识沉淀** (`.ai/knowledge/`): decisions.md（迁移 6 个旧 ADR + 新增 ADR-007）、patterns.md、lessons.md +- **架构提示词** (`.ai/prompts/architecture/`): 补充之前缺失的架构设计和技术选型模板 +- **分享层** (`.ai/share/`): 阶段复盘模板、决策故事模板、项目缘起和框架设计思路占位 +- **人类仪表盘** (DASHBOARD.md): 根目录，30 秒可读 +- **路线图看板** (ROADMAP.md): 阶段进度 + 任务看板 + 阻塞项，人机共享 +- **任务索引** (review/active/INDEX.md): 所有活跃任务一览 + +### 修改 (6 个文件) + +- AGENTS.md: 239 行 → ~120 行，顶部 AI 跳转 +- README.md: 精简，聚焦人类读者 +- docs/PROJECT_CONTEXT.md: 精简，加跳转链接 +- docs/DECISIONS.md: 替换为跳转存根 +- 5 个 task.md: 添加 phase 字段 + +## 关键决策 + +1. 分层信息架构：工作台 → 路线图 → 阶段上下文 → 知识沉淀 +2. Token 预算制度：每个文件标注预算上限 +3. "一鸡多吃"：开发过程自动沉淀为可分享内容 +4. 角色工作台代替全局 AGENTS.md 作为 AI 入口 + +## 经验教训 + +见 lessons.md L-001: 单体 AGENTS.md 浪费 AI 上下文 diff --git a/.ai/knowledge/lessons.md b/.ai/knowledge/lessons.md new file mode 100644 index 0000000..675ae0d --- /dev/null +++ b/.ai/knowledge/lessons.md @@ -0,0 +1,25 @@ +# 经验教训 + +## 目的 + +记录开发过程中学到的东西。每条记录包含： +- 上下文（我们在做什么） +- 问题（出了什么问题/什么让我们意外） +- 教训（学到了什么） +- 行动（因此改变了什么） + +--- + +## L-001: 单体 AGENTS.md 浪费 AI 上下文 + +**日期**: 2026-05-25 +**上下文**: 项目启动阶段，每次 AI 会话都需要读 AGENTS.md 来了解角色和权限 +**问题**: AGENTS.md 239 行，约 80% 内容与当前 AI 角色无关。AI 有效上下文被大量无关信息占据 +**教训**: 为人类设计的文档结构不适用于 AI 的信息获取模式。AI 需要"最少必要信息"，而不是"全局完整视图" +**行动**: 重构为分层信息架构：角色工作台 → 阶段上下文 → 知识沉淀。AI 只需读 2 个小文件即可开工 + +--- + +## L-002 + +*（待项目推进中记录）* diff --git a/.ai/knowledge/patterns.md b/.ai/knowledge/patterns.md new file mode 100644 index 0000000..668f4e4 --- /dev/null +++ b/.ai/knowledge/patterns.md @@ -0,0 +1,39 @@ +# 可复用模式 + +## 目的 + +记录开发过程中发现的可持续复用的模式和做法。 +同样的模式出现 3 次以上时，应当记录在这里。 + +--- + +## P-001: AI 任务交接 (review/active/) + +**上下文**: AI 角色之间需要传递工作成果 +**问题**: 如何结构化任务交接，让任何 AI 都能接手 +**方案**: 标准化 `review/active/{任务ID}/` 结构： +- `task.md` — 任务描述（Arch AI 定义） +- `acceptance.md` — 验收标准（Arch AI + Dev AI + QA AI 共同维护） +- `impact.md` — 变更影响范围（Arch AI + Dev AI 评估） +- `feedback/` — 反馈记录（QA AI 提交） + +**何时用**: 每个跨 AI 角色的任务 +**何时不用**: 单角色任务（如纯文档更新、配置修改） + +--- + +## P-002: 角色工作台 (daily task board) + +**上下文**: AI 每次会话需要快速进入工作状态 +**问题**: 从头探索项目结构浪费时间 +**方案**: `.ai/roles/{role}/today.md` 每日任务清单，AI 只需读 2 个文件（card + today） +**何时用**: 每次 AI 会话 +**维护者**: Arch AI 负责分配，各 AI 自己更新完成状态 + +--- + +## 反模式（避免） + +- 在多个文件中重复同一状态信息 → 只在 ROADMAP.md 记录 +- 决策讨论散落在任务 feedback 中 → 提炼到 knowledge/decisions.md +- 大段文档内联而非链接 → 用链接 + 一句话摘要 diff --git a/.ai/phases/INDEX.md b/.ai/phases/INDEX.md new file mode 100644 index 0000000..20808fd --- /dev/null +++ b/.ai/phases/INDEX.md @@ -0,0 +1,17 @@ +# 阶段索引 + +| 阶段 | 名称 | 状态 | 目录 | +|------|------|------|------| +| 1 | 基础搭建 | ACTIVE | `phase-01-foundation/` | +| 2 | MVP | PLANNED | `phase-02-mvp/` | +| 3 | 功能完善 | PLANNED | `phase-03-features/` | +| 4 | 打磨发布 | PLANNED | `phase-04-polish/` | + +## 阶段切换规则 + +1. 当前阶段 completion.md 全部打勾 +2. 人类签字确认 +3. Arch AI 更新本索引文件 +4. Arch AI 更新所有角色 card.md +5. Arch AI 更新 ROADMAP.md +6. 产出阶段复盘（docs/share/phase-NN/） diff --git a/.ai/phases/phase-01-foundation/architecture.md b/.ai/phases/phase-01-foundation/architecture.md new file mode 100644 index 0000000..8c66ccf --- /dev/null +++ b/.ai/phases/phase-01-foundation/architecture.md @@ -0,0 +1,45 @@ +# Phase 1: 基础搭建 — 架构概览 + +## 技术栈 + +| 层 | 技术 | 说明 | +|----|------|------| +| 前端 (P01) | Taro 4 + React 18 + TypeScript + Tailwind CSS | 跨端小程序 | +| 后端 (P01) | NestJS 10 + TypeScript | REST API | +| 数据库 | PostgreSQL（Schema 本阶段确定） | 关系型存储 | +| 包管理 | pnpm | monorepo | +| 测试 | Jest | 单元 + 集成 + E2E | +| AI 训练 (P02) | Python + PyTorch | 延期至 Phase 2 | +| Web 后台 (P03) | Next.js | 延期至 Phase 2 | + +## 当前架构快照 + +``` +P01_errlens_app/ + src/ # Taro 小程序源码（已有骨架） + pages/index/ # 首页（通用模板，待替换为错题本首页） + components/ui/ # shadcn/ui Taro 组件库（~50个组件） + lib/ # 工具函数（cn, platform, measure, hooks） + presets/ # H5 适配（navbar, error boundary, styles） + server/ # NestJS 后端 + src/ + main.ts # 启动入口 + app.module.ts # 根模块 + app.controller.ts # GET /hello, GET /health + tests/ # Jest 测试（已有 utils 测试骨架） + +P02_errlens_training/ # 空壳，Phase 2 启动 +P03_errlens_web/ # 空壳，Phase 2 启动 +``` + +## 关键约束 + +- 所有业务代码在 projects/*/src/（权限边界） +- 跨平台目标：微信小程序优先，抖音/H5 为次 +- AI 代码必须遵循 `.ai/prompts/coding/code-style.md` + +## 待定问题 + +- 数据库 Schema 设计（PRD 先行） +- P01 页面架构（几个页面、导航结构） +- 后端 API 版本策略 diff --git a/.ai/phases/phase-01-foundation/completion.md b/.ai/phases/phase-01-foundation/completion.md new file mode 100644 index 0000000..eb248a4 --- /dev/null +++ b/.ai/phases/phase-01-foundation/completion.md @@ -0,0 +1,16 @@ +# Phase 1: 基础搭建 — 完成检查清单 + +## 完成状态 + +- [ ] 所有 goal.md 中的成功标准达成 +- [ ] 所有活跃任务处于 DONE 或 ARCHIVED +- [ ] QA AI 签字确认 +- [ ] 人类签字确认 +- [ ] 知识已沉淀至 .ai/knowledge/ +- [ ] Phase 2 MVP 计划已起草 +- [ ] 阶段复盘已写出（docs/share/phase-01/） +- [ ] Token 预算审计通过 + +## 阶段交接 + +*（阶段接近完成时填写）* diff --git a/.ai/phases/phase-01-foundation/decisions.md b/.ai/phases/phase-01-foundation/decisions.md new file mode 100644 index 0000000..218f8e3 --- /dev/null +++ b/.ai/phases/phase-01-foundation/decisions.md @@ -0,0 +1,27 @@ +# Phase 1: 基础搭建 — 阶段决策 + +本文件记录在 Phase 1 执行过程中产生的决策（区别于全局 ADR）。 + +## D-001: 信息架构分层设计 + +- 日期: 2026-05-25 +- 状态: 已采纳 +- 决策: 采用 token 预算的分层架构（工作台 → 阶段 → 知识 → 分享） +- 理由: AI 上下文窗口有限，旧 AGENTS.md 单体文件浪费 token +- 影响: 所有 AI 从 `.ai/roles/{role}/` 启动，不再从 AGENTS.md 启动 + +## D-002: 阶段化上下文加载 + +- 日期: 2026-05-25 +- 状态: 已采纳 +- 决策: AI 只加载当前 Phase 的上下文，不加载所有历史 +- 理由: 未来阶段技术栈和侧重点可能不同，历史信息反而干扰 +- 影响: 阶段包必须自包含、可独立阅读 + +## D-003: 角色工作台代替全局入口 + +- 日期: 2026-05-25 +- 状态: 已采纳 +- 决策: 用 `today.md` + `queue.md` 替代从 AGENTS.md 找任务 +- 理由: AI 不需要理解整个项目结构，只需要知道自己该干什么 +- 影响: Arch AI 负责维护各角色的任务分配 diff --git a/.ai/phases/phase-01-foundation/goal.md b/.ai/phases/phase-01-foundation/goal.md new file mode 100644 index 0000000..59c1db1 --- /dev/null +++ b/.ai/phases/phase-01-foundation/goal.md @@ -0,0 +1,27 @@ +# Phase 1: 基础搭建 — 目标 + +## 阶段目标 + +建立完整的开发骨架： +- 可运转的"1 人 + 3 AI"协作框架 +- 完整的目录和权限体系 +- 可运行的项目脚手架（Taro + React + NestJS） +- 测试基础设施 +- 信息架构设计（分层 AI 上下文） + +## 成功标准 + +- [ ] 3 个 AI 角色能独立通过工作台启动工作 +- [ ] P01 可通过 `pnpm dev` 启动并显示首页 +- [ ] 测试可通过 `pnpm test` 运行并产出报告 +- [ ] 所有初始 review/ 任务处于 DONE 或 ARCHIVED +- [ ] 共享工具库可工作并通过测试 +- [ ] 信息架构重构完成 + +## 阶段 Owner + +Arch AI 协调，Dev AI 实现，QA AI 验证，人类最终验收。 + +## 下一阶段 + +Phase 2: MVP — 实现错题本核心功能 diff --git a/.ai/phases/phase-01-foundation/scope.md b/.ai/phases/phase-01-foundation/scope.md new file mode 100644 index 0000000..8e8ebd9 --- /dev/null +++ b/.ai/phases/phase-01-foundation/scope.md @@ -0,0 +1,42 @@ +# Phase 1: 基础搭建 — 范围 + +## 范围内 + +### 协作框架 +- AGENTS.md（AI 角色 + 权限 + 工作流） +- .ai/config/（JSON 角色配置） +- .ai/prompts/（编码、测试、架构提示词模板） +- .ai/roles/（AI 角色工作台） +- .ai/phases/（阶段上下文） +- review/（任务交接中心） + +### P01_errlens_app（主应用） +- Taro 4 + React 18 脚手架，集成 shadcn/ui +- NestJS 后端脚手架 +- 可运行的开发服务器（pnpm dev） +- 基础页面路由 + +### 测试基础设施 +- Jest 配置 +- 示例单元测试 +- 测试结果报告流程 + +### 文档体系 +- 阶段追踪文档 +- 知识库基础 +- 人类仪表盘 +- 分享内容层 + +## 范围外（延期至 Phase 2+） + +- 实际业务功能（登录、错题分析等） +- P02 数据训练实现 +- P03 Web 后台实现 +- CI/CD 流水线配置 +- 生产部署 + +## 项目依赖 + +- P01 独立（可独立开发） +- P02 依赖 P01 定义数据 Schema（Phase 2） +- P03 依赖 P01 API 稳定（Phase 3） diff --git a/.ai/phases/phase-02-mvp/architecture.md b/.ai/phases/phase-02-mvp/architecture.md new file mode 100644 index 0000000..ab55f90 --- /dev/null +++ b/.ai/phases/phase-02-mvp/architecture.md @@ -0,0 +1,3 @@ +# Phase 2: MVP — 架构决策 + +*（Phase 2 执行过程中由 Arch AI 填写）* diff --git a/.ai/phases/phase-02-mvp/completion.md b/.ai/phases/phase-02-mvp/completion.md new file mode 100644 index 0000000..d56d283 --- /dev/null +++ b/.ai/phases/phase-02-mvp/completion.md @@ -0,0 +1,3 @@ +# Phase 2: MVP — 完成检查清单 + +*（Phase 2 接近完成时更新）* diff --git a/.ai/phases/phase-02-mvp/decisions.md b/.ai/phases/phase-02-mvp/decisions.md new file mode 100644 index 0000000..dd5b8b9 --- /dev/null +++ b/.ai/phases/phase-02-mvp/decisions.md @@ -0,0 +1,3 @@ +# Phase 2: MVP — 阶段决策 + +*（Phase 2 执行过程中由 Arch AI 填写）* diff --git a/.ai/phases/phase-02-mvp/goal.md b/.ai/phases/phase-02-mvp/goal.md new file mode 100644 index 0000000..16825f2 --- /dev/null +++ b/.ai/phases/phase-02-mvp/goal.md @@ -0,0 +1,11 @@ +# Phase 2: MVP — 目标 + +*（Phase 1 完成时由 Arch AI 填写）* + +## 阶段目标 + +## 成功标准 + +## 阶段 Owner + +## 下一阶段 diff --git a/.ai/phases/phase-02-mvp/scope.md b/.ai/phases/phase-02-mvp/scope.md new file mode 100644 index 0000000..dd44028 --- /dev/null +++ b/.ai/phases/phase-02-mvp/scope.md @@ -0,0 +1,3 @@ +# Phase 2: MVP — 范围 + +*（Phase 1 完成时由 Arch AI 填写）* diff --git a/.ai/phases/phase-03-features/architecture.md b/.ai/phases/phase-03-features/architecture.md new file mode 100644 index 0000000..c28a0f9 --- /dev/null +++ b/.ai/phases/phase-03-features/architecture.md @@ -0,0 +1,3 @@ +# Phase 3: 功能完善 — 架构决策 + +*（Phase 3 执行过程中由 Arch AI 填写）* diff --git a/.ai/phases/phase-03-features/completion.md b/.ai/phases/phase-03-features/completion.md new file mode 100644 index 0000000..a554ecf --- /dev/null +++ b/.ai/phases/phase-03-features/completion.md @@ -0,0 +1,3 @@ +# Phase 3: 功能完善 — 完成检查清单 + +*（Phase 3 接近完成时更新）* diff --git a/.ai/phases/phase-03-features/decisions.md b/.ai/phases/phase-03-features/decisions.md new file mode 100644 index 0000000..b64dfee --- /dev/null +++ b/.ai/phases/phase-03-features/decisions.md @@ -0,0 +1,3 @@ +# Phase 3: 功能完善 — 阶段决策 + +*（Phase 3 执行过程中由 Arch AI 填写）* diff --git a/.ai/phases/phase-03-features/goal.md b/.ai/phases/phase-03-features/goal.md new file mode 100644 index 0000000..03f6400 --- /dev/null +++ b/.ai/phases/phase-03-features/goal.md @@ -0,0 +1,3 @@ +# Phase 3: 功能完善 — 目标 + +*（Phase 2 完成时由 Arch AI 填写）* diff --git a/.ai/phases/phase-03-features/scope.md b/.ai/phases/phase-03-features/scope.md new file mode 100644 index 0000000..a4af284 --- /dev/null +++ b/.ai/phases/phase-03-features/scope.md @@ -0,0 +1,3 @@ +# Phase 3: 功能完善 — 范围 + +*（Phase 2 完成时由 Arch AI 填写）* diff --git a/.ai/phases/phase-04-polish/architecture.md b/.ai/phases/phase-04-polish/architecture.md new file mode 100644 index 0000000..82a9814 --- /dev/null +++ b/.ai/phases/phase-04-polish/architecture.md @@ -0,0 +1,3 @@ +# Phase 4: 打磨发布 — 架构决策 + +*（Phase 4 执行过程中由 Arch AI 填写）* diff --git a/.ai/phases/phase-04-polish/completion.md b/.ai/phases/phase-04-polish/completion.md new file mode 100644 index 0000000..d6877a5 --- /dev/null +++ b/.ai/phases/phase-04-polish/completion.md @@ -0,0 +1,3 @@ +# Phase 4: 打磨发布 — 完成检查清单 + +*（Phase 4 接近完成时更新）* diff --git a/.ai/phases/phase-04-polish/decisions.md b/.ai/phases/phase-04-polish/decisions.md new file mode 100644 index 0000000..e9ab582 --- /dev/null +++ b/.ai/phases/phase-04-polish/decisions.md @@ -0,0 +1,3 @@ +# Phase 4: 打磨发布 — 阶段决策 + +*（Phase 4 执行过程中由 Arch AI 填写）* diff --git a/.ai/phases/phase-04-polish/goal.md b/.ai/phases/phase-04-polish/goal.md new file mode 100644 index 0000000..4954b54 --- /dev/null +++ b/.ai/phases/phase-04-polish/goal.md @@ -0,0 +1,3 @@ +# Phase 4: 打磨发布 — 目标 + +*（Phase 3 完成时由 Arch AI 填写）* diff --git a/.ai/phases/phase-04-polish/scope.md b/.ai/phases/phase-04-polish/scope.md new file mode 100644 index 0000000..f64a6e1 --- /dev/null +++ b/.ai/phases/phase-04-polish/scope.md @@ -0,0 +1,3 @@ +# Phase 4: 打磨发布 — 范围 + +*（Phase 3 完成时由 Arch AI 填写）* diff --git a/.ai/principles.md b/.ai/principles.md new file mode 100644 index 0000000..7c7da58 --- /dev/null +++ b/.ai/principles.md @@ -0,0 +1,47 @@ +# 信息架构设计原则 + +## 为什么这样设计 + +AI 的上下文窗口有限（~200K tokens）。当前架构按人类认知模式设计——详尽文档、全局视角——但 AI 每个读入上下文的字都是成本。这套分层架构的核心思想：**每个角色只加载必要信息，按需展开细节。** + +## Token 预算 + +| 层级 | 预算 | 内容 | 加载时机 | +|------|------|------|----------| +| 角色工作台 (card + today) | < 2K | 身份+今日任务 | 每次会话必读 | +| 阶段上下文 (phase) | < 5K | 目标+范围+架构 | 按需加载 | +| 专题文档 (knowledge) | < 3K | 决策/模式/教训 | 按需加载 | +| 路线图 (ROADMAP) | < 2K | 全局进度 | 需要全局视野时 | + +## 信息分层 + +``` +Layer 0: 角色工作台 → AI 每天进来只读这个 +Layer 1: 路线图看板 → 人类 + AI 共享进度 +Layer 2: 阶段上下文 → 按当前阶段按需加载 +Layer 3: 知识沉淀 → 自动积累，永久沉淀 +``` + +## 维护规则 + +1. **不超预算**：每个文件严格遵守 token 预算，超了就拆分 +2. **不重复状态**：状态只在一处记录（ROADMAP.md），其他地方引用 +3. **Git 管历史**：文档只描述"现在是什么"，历史由 Git 负责 +4. **一文一答**：每个文件独立回答一个问题，不需要串联阅读 +5. **角色无关设计**：任何 AI 模型都能通过读 card.md 快速接管角色 + +## 文件约定 + +- 角色工作台: `.ai/roles/{role}/` +- 阶段上下文: `.ai/phases/phase-NN-name/` +- 知识沉淀: `.ai/knowledge/` +- 提示词模板: `.ai/prompts/{domain}/` + +## 阶段切换检查清单 + +切换阶段时 Arch AI 必须： +- [ ] 更新所有角色的 card.md（当前阶段字段） +- [ ] 更新 ROADMAP.md（阶段进度条） +- [ ] 生成上一阶段的 completion.md +- [ ] 产出阶段复盘（docs/share/phase-NN/） +- [ ] 审计 token 预算 diff --git a/.ai/prompts/architecture/README.md b/.ai/prompts/architecture/README.md new file mode 100644 index 0000000..40c1e5c --- /dev/null +++ b/.ai/prompts/architecture/README.md @@ -0,0 +1,6 @@ +# 架构提示词模板 + +| 文件 | 用途 | +|------|------| +| `architecture-design.md` | 系统架构设计模板 | +| `technical-evaluation.md` | 技术选型评估模板 | diff --git a/.ai/prompts/architecture/architecture-design.md b/.ai/prompts/architecture/architecture-design.md new file mode 100644 index 0000000..5f942fe --- /dev/null +++ b/.ai/prompts/architecture/architecture-design.md @@ -0,0 +1,44 @@ +# 系统架构设计模板 + +## 输入 + +- 产品需求文档 (PRD) +- 技术约束（已有技术栈、团队能力） +- 非功能性需求（性能、安全、可扩展性） + +## 输出结构 + +### 1. 架构概述 +- 一句话描述架构核心思路 +- 系统边界和范围 + +### 2. 架构图（文字描述 + ASCII） +- 模块划分和职责 +- 模块间通信方式 +- 数据流向 + +### 3. 技术选型 +- 每个模块的技术栈及理由 +- 对比方案及淘汰原因 +- 风险点和缓解措施 + +### 4. 接口设计 +- 模块间接口定义 +- API 契约（请求/响应格式） +- 数据模型概要 + +### 5. 非功能性设计 +- 性能目标及实现策略 +- 安全设计（认证、授权、数据保护） +- 可扩展性考虑 + +### 6. 部署架构 +- 运行环境 +- 服务拓扑 +- CI/CD 流程 + +## 注意事项 + +- 架构文档面向 Arch AI 和 Dev AI，不要写人类才需要的背景介绍 +- 决策必须写理由，方便后续 AI 理解为什么这样设计 +- 每个模块标注影响范围（HIGH/MEDIUM/LOW），供 QA AI 确定回归测试范围 diff --git a/.ai/prompts/architecture/technical-evaluation.md b/.ai/prompts/architecture/technical-evaluation.md new file mode 100644 index 0000000..3e1f389 --- /dev/null +++ b/.ai/prompts/architecture/technical-evaluation.md @@ -0,0 +1,41 @@ +# 技术选型评估模板 + +## 输入 + +- 需要解决的技术问题 +- 约束条件（预算、时间、团队、已有技术栈） + +## 输出结构 + +### 1. 需求描述 +- 要解决什么问题 +- 关键约束是什么 + +### 2. 候选方案（2-4 个） + +每个方案描述： +- 方案名称和简介 +- 优势（3-5 条） +- 劣势（3-5 条） +- 与本项目技术栈的兼容度 + +### 3. 评估维度 + +| 维度 | 权重 | 方案A | 方案B | 方案C | +|------|------|-------|-------|-------| +| 性能 | 30% | — | — | — | +| 生态成熟度 | 25% | — | — | — | +| 学习曲线 | 20% | — | — | — | +| 社区活跃度 | 15% | — | — | — | +| 团队熟悉度 | 10% | — | — | — | +| **加权总分** | 100% | — | — | — | + +### 4. 推荐方案 +- 推荐哪个、为什么 +- 主要风险 +- 如果失败，备选方案是什么 + +## 注意事项 + +- 评估维度可调整，但必须说明理由 +- 不追求"最优"，追求"最适合当前阶段" diff --git a/.ai/roles/README.md b/.ai/roles/README.md new file mode 100644 index 0000000..e5d6fb4 --- /dev/null +++ b/.ai/roles/README.md @@ -0,0 +1,26 @@ +# AI 角色工作台 + +每个角色有一个独立的工作台目录。AI 每天进来只需读自己的工作台。 + +## 使用方式 + +``` +1. 读 card.md → 我是谁、我能写哪、当前阶段（< 1K tokens） +2. 读 today.md → 今天干什么、任务优先级（< 1K tokens） +3. 需要细节 → 按链接按需加载 +4. 完成后 → 更新 today.md，写 journal +``` + +## 三个角色 + +| 角色 | 目录 | 职责 | +|------|------|------| +| Arch AI | `arch/` | 需求分析、架构设计、技术选型、跨模块协调 | +| Dev AI | `dev/` | 编码实现、文档编写、Bug 修复 | +| QA AI | `qa/` | 测试编写、测试执行、质量反馈 | + +## 维护规则 + +- Arch AI 负责分配任务到各角色的 queue.md 和 today.md +- 每个 AI 完成工作后更新自己的 today.md +- 阶段切换时 Arch AI 更新所有 card.md diff --git a/.ai/roles/arch/card.md b/.ai/roles/arch/card.md new file mode 100644 index 0000000..a31ac67 --- /dev/null +++ b/.ai/roles/arch/card.md @@ -0,0 +1,34 @@ +# Arch AI — 架构师 + +## 身份 + +我是架构 AI。负责需求分析、架构设计、技术选型、跨模块协调。 +拥有最高 AI 权限，指导 Dev AI 和 QA AI 的工作。 + +## 权限 + +**可写**: docs/ shared/ projects/*/src/ projects/*/docs/ review/*/acceptance.md review/*/impact.md review/*/task.md tools/ data/ +**只读**: .ai/ projects/*/tests/ reports/ review/*/feedback/ +**禁止**: 无 + +## 当前阶段 + +Phase 1: 基础搭建 — `.ai/phases/phase-01-foundation/goal.md` + +## 核心交付物 + +- 产品需求文档 (PRD) +- 系统架构设计文档 +- 技术选型评估 +- 验收标准定义 +- 变更影响评估 +- 跨模块协调 + +## 协作文件 + +- 任务分配: `.ai/roles/{dev,qa}/queue.md` +- 代码规范: `.ai/prompts/coding/code-style.md` +- 完整权限: `AGENTS.md` +- 阶段上下文: `.ai/phases/phase-01-foundation/` +- 知识沉淀: `.ai/knowledge/` +- 全局视野: `ROADMAP.md` diff --git a/.ai/roles/arch/queue.md b/.ai/roles/arch/queue.md new file mode 100644 index 0000000..b340c8f --- /dev/null +++ b/.ai/roles/arch/queue.md @@ -0,0 +1,18 @@ +# Arch AI · 任务队列 + +## 当前阶段 (Phase 1) 任务 + +| # | 任务 | 优先级 | 状态 | 依赖 | +|---|------|--------|------|------| +| 1 | 信息架构重构 | P0 | DOING | — | +| 2 | 错题本 PRD 编写 | P0 | TODO | 1 | +| 3 | 系统架构设计 | P1 | TODO | 2 | +| 4 | P01 文档改写 | P1 | TODO | 2 | +| 5 | 架构提示词模板 | P2 | TODO | — | + +## 未来阶段预留 + +| # | 任务 | 阶段 | 优先级 | +|---|------|------|--------| +| — | Phase 2 MVP 架构设计 | 2 | — | +| — | Phase 3 功能迭代架构 | 3 | — | diff --git a/.ai/roles/arch/today.md b/.ai/roles/arch/today.md new file mode 100644 index 0000000..b87eea0 --- /dev/null +++ b/.ai/roles/arch/today.md @@ -0,0 +1,22 @@ +# Arch AI · 今日任务 · 2026-05-25 + +## 进行中 + +- [ ] 信息架构重构 — 正在实施 + +## 待办（按优先级） + +1. **[P0]** 完成信息架构重构（所有文件创建 + 改写） +2. **[P0]** 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档 +3. **[P0]** 将 P01 项目文档从"代码检测"重写为"错题本" +4. **[P1]** 设计 `docs/02_系统架构/` — 系统架构文档 +5. **[P1]** 补充 `.ai/prompts/architecture/` 提示词模板 + +## 已完成 + +- [x] 分析项目现状，识别架构问题 +- [x] 输出信息架构重构方案 + +## 阻塞 + +（无外部阻塞） diff --git a/.ai/roles/dev/card.md b/.ai/roles/dev/card.md new file mode 100644 index 0000000..a235f75 --- /dev/null +++ b/.ai/roles/dev/card.md @@ -0,0 +1,31 @@ +# Dev AI — 开发者 + +## 身份 + +我是开发 AI。负责编写业务代码、技术文档、Bug 修复。 +不修改测试代码和测试报告。 + +## 权限 + +**可写**: projects/*/src/ projects/*/docs/ docs/ tools/ data/ shared/ review/*/acceptance.md review/*/impact.md +**只读**: review/*/task.md review/*/feedback/ +**禁止**: projects/*/tests/ reports/ + +## 当前阶段 + +Phase 1: 基础搭建 — `.ai/phases/phase-01-foundation/goal.md` + +## 核心交付物 + +- 业务代码实现 (projects/*/src/) +- 项目文档 (projects/*/docs/) +- 验收标准补充 +- 变更影响评估 + +## 协作文件 + +- 代码规范: `.ai/prompts/coding/code-style.md` +- 文档模板: `.ai/prompts/coding/doc-template.md` +- 完整权限: `AGENTS.md` +- 阶段上下文: `.ai/phases/phase-01-foundation/` +- 全局视野: `ROADMAP.md` diff --git a/.ai/roles/dev/queue.md b/.ai/roles/dev/queue.md new file mode 100644 index 0000000..65a22d8 --- /dev/null +++ b/.ai/roles/dev/queue.md @@ -0,0 +1,17 @@ +# Dev AI · 任务队列 + +## 当前阶段 (Phase 1) 可执行任务 + +| # | 任务 ID | 项目 | 描述 | 优先级 | 状态 | +|---|---------|------|------|--------|------| +| 1 | P03-001 | Web | 项目初始化 | LOW | TODO | +| 2 | CROSS-001 | 共享 | 共享工具库更新 | HIGH | TODO | +| 3 | P01-001 | App | 用户登录 | HIGH | TODO | +| 4 | P01-002 | App | 代码分析 API | MEDIUM | TODO | +| 5 | P02-001 | 训练 | 数据预处理 | MEDIUM | TODO | + +## 任务详情 + +每个任务的详细描述 → `review/active/{任务ID}/task.md` +验收标准 → `review/active/{任务ID}/acceptance.md` +影响范围 → `review/active/{任务ID}/impact.md` diff --git a/.ai/roles/dev/today.md b/.ai/roles/dev/today.md new file mode 100644 index 0000000..7b92a15 --- /dev/null +++ b/.ai/roles/dev/today.md @@ -0,0 +1,24 @@ +# Dev AI · 今日任务 · 2026-05-25 + +## 进行中 + +（无） + +## 待领取（按优先级） + +| # | 任务 | 来源 | 说明 | +|---|------|------|------| +| 1 | P03-001 | `review/active/P03-001/` | Web 项目初始化（无依赖，可立即开始） | +| 2 | CROSS-001 | `review/active/CROSS-001/` | 共享工具库更新（等待已有 bug 修复） | + +## 暂不可领（等待 Arch AI） + +| # | 任务 | 阻塞原因 | +|---|------|----------| +| 1 | P01-001 用户登录 | 等待 PRD | +| 2 | P01-002 代码分析API | 等待 PRD | +| 3 | P02-001 数据预处理 | 等待 PRD | + +## 已完成 + +（无） diff --git a/.ai/roles/qa/card.md b/.ai/roles/qa/card.md new file mode 100644 index 0000000..cfb7098 --- /dev/null +++ b/.ai/roles/qa/card.md @@ -0,0 +1,30 @@ +# QA AI — 测试者 + +## 身份 + +我是测试 AI。负责编写测试用例、执行测试、提交反馈。 +不修改业务代码。 + +## 权限 + +**可写**: projects/*/tests/ reports/ review/*/acceptance.md review/*/feedback/ +**只读**: projects/*/src/ projects/*/docs/ docs/ data/ shared/ review/*/task.md +**禁止**: .ai/ tools/ review/*/impact.md + +## 当前阶段 + +Phase 1: 基础搭建 — `.ai/phases/phase-01-foundation/goal.md` + +## 核心交付物 + +- 测试用例 (projects/*/tests/) +- 测试报告 (reports/) +- Bug 反馈 (review/*/feedback/) +- 验收标准补充 + +## 协作文件 + +- Bug 报告模板: `.ai/prompts/testing/bug-report.md` +- 完整权限: `AGENTS.md` +- 阶段上下文: `.ai/phases/phase-01-foundation/` +- 全局视野: `ROADMAP.md` diff --git a/.ai/roles/qa/queue.md b/.ai/roles/qa/queue.md new file mode 100644 index 0000000..10ec1b2 --- /dev/null +++ b/.ai/roles/qa/queue.md @@ -0,0 +1,19 @@ +# QA AI · 任务队列 + +## 当前阶段 (Phase 1) + +暂无测试任务。所有活跃任务处于 TODO 状态。 + +## 测试流程 + +1. 确认任务已进入 REVIEW 状态（见 ROADMAP.md） +2. 读取 `review/active/{任务ID}/task.md` — 理解任务 +3. 读取 `review/active/{任务ID}/acceptance.md` — 确认验收标准 +4. 读取 `review/active/{任务ID}/impact.md` — 了解影响范围 +5. 在 `projects/{项目}/tests/` 编写测试 +6. 执行测试，生成报告到 `reports/` +7. 提交反馈到 `review/active/{任务ID}/feedback/` + +## 已完成的测试 + +（无） diff --git a/.ai/roles/qa/today.md b/.ai/roles/qa/today.md new file mode 100644 index 0000000..20ef7ca --- /dev/null +++ b/.ai/roles/qa/today.md @@ -0,0 +1,18 @@ +# QA AI · 今日任务 · 2026-05-25 + +## 进行中 + +（无） + +## 待执行 + +当前没有进入 REVIEW 状态的任务，暂无测试任务。 + +## 已完成 + +（无） + +## 说明 + +等待 Dev AI 完成代码开发后，任务状态转为 REVIEW 时开始测试工作。 +关注 `ROADMAP.md` 中的 DOING 列，当有任务进入 REVIEW 时立即介入。 diff --git a/AGENTS.md b/AGENTS.md index 8755b72..ff1a956 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,163 +1,62 @@ # AI 角色定义与权限约定 +> **如果你是 AI，请直接跳转到你的角色工作台：** +> - Arch AI → `.ai/roles/arch/card.md` +> - Dev AI → `.ai/roles/dev/card.md` +> - QA AI → `.ai/roles/qa/card.md` +> +> **如果你是**人类，请看 `DASHBOARD.md` + `ROADMAP.md`。 +> +> 本文档是权限矩阵的**唯一权威参考**。角色工作台中的权限描述为摘要，如有冲突以本文档为准。 + +--- + ## 团队架构 + +`1 人类 + 3 AI` 协作模式： +- **Arch AI** — 需求分析、架构设计、技术选型、跨模块协调 +- **Dev AI** — 代码编写、文档生成、Bug 修复 +- **QA AI** — 测试设计、测试执行、质量反馈 +- **人类** — 需求输入、最终决策、成果验收 + +--- + +## 工作流（简化版） + ``` -┌─────────────────────────────────────────────┐ -│ 人类负责人 │ -│ 需求分析 · 架构设计 · 最终决策 │ -└───────────────┬───────────┬─────────────────┘ - │ │ - ┌───────────┴──┐ ┌────┴────────────┐ - ▼ ▼ ▼ ▼ -┌───────────────┐ ┌──────────────┐ ┌───────────────┐ -│ Arch AI │ │ Dev AI │ │ QA AI │ -│ 需求分析 │ │ 代码编写 │ │ 测试设计 │ -│ 架构设计 │ │ 文档生成 │ │ 测试执行 │ -│ 技术选型 │ │ 影响评估 │ │ 质量保障 │ -│ 跨模块协调 │ └──────────────┘ └───────────────┘ -└───────────────┘ +需求分析(Arch) → 架构设计(Arch) → 开发实现(Dev) → 测试验证(QA) → 人类验收 + ↑ │ + └── Bug修复 ──┘ (最多3轮) ``` +缺陷修复循环：最多 3 轮。第 3 轮仍有 BLOCKER/HIGH → 升级给人类裁决。 + +详细工作流配置：`.ai/config/workflow.json` + --- ## 角色职责 -### Arch AI (架构AI) -**职责范围：** -- ✅ 需求分析和产品规划 -- ✅ 系统架构设计 -- ✅ 技术选型和评估 -- ✅ 跨模块协调和集成 -- ✅ 编写架构文档 (`docs/`) -- ✅ 定义验收标准 (`review/*/acceptance.md`) -- ✅ 评估变更影响 (`review/*/impact.md`) -- ✅ 维护共享资源 (`shared/`) -- ✅ 维护开发工具 (`tools/`) -- ✅ 维护训练数据 (`data/`) -- ✅ 指导 Dev AI 和 QA AI 工作 +### Arch AI +- 可写：需求分析、架构设计、技术选型、跨模块协调、架构文档、验收标准、影响评估、共享资源、开发工具、训练数据、业务代码 +- 只读：AI 配置、测试代码、测试报告、测试反馈 +- 指导 Dev AI 和 QA AI 工作，分配任务队列 -**可读但不可写：** -- 👁 AI 配置文件 (`.ai/`) —— 只读，了解团队规则 -- 👁 测试代码 (`projects/*/tests/`) —— 只读，了解测试覆盖 -- 👁 测试报告 (`reports/`) —— 只读，了解质量状况 -- 👁 测试反馈 (`review/*/feedback/`) —— 只读，了解问题 +### Dev AI +- 可写：业务代码、技术文档、项目级文档、开发工具、训练数据、共享资源、验收标准、影响评估 +- 只读：任务描述、测试反馈 +- 禁止：测试代码、测试报告 -**禁止操作：** -- ❌ 无（架构 AI 拥有最高 AI 权限） - -### Dev AI (编码AI) -**职责范围：** -- ✅ 编写业务代码 (`projects/*/src/`) -- ✅ 生成技术文档 (`projects/*/docs/`) -- ✅ 维护项目级文档 (`docs/`) -- ✅ 维护开发工具 (`tools/`) -- ✅ 维护训练数据 (`data/`) -- ✅ 定义验收标准 (`review/*/acceptance.md`) -- ✅ 评估变更影响 (`review/*/impact.md`) -- ✅ 维护共享资源 (`shared/`) - -**可读但不可写：** -- 👁 任务描述 (`review/*/task.md`) —— 只读，不可修改 -- 👁 测试反馈 (`review/*/feedback/`) —— 只读，用于修 Bug - -**禁止操作：** -- ❌ 修改测试代码 (`projects/*/tests/`) -- ❌ 修改测试报告 (`reports/`) - -### QA AI (测试AI) -**职责范围：** -- ✅ 编写测试用例 (`projects/*/tests/`) -- ✅ 执行测试并生成报告 (`reports/`) -- ✅ 补充验收标准 (`review/*/acceptance.md`) -- ✅ 提交测试反馈 (`review/*/feedback/`) - -**可读但不可写：** -- 👁 业务代码 (`projects/*/src/`) —— 只读，理解逻辑编写测试 -- 👁 技术文档 (`projects/*/docs/`) —— 只读，了解接口设计 -- 👁 项目级文档 (`docs/`) —— 只读，了解系统架构 -- 👁 训练数据 (`data/`) —— 只读，了解数据分布 -- 👁 共享资源 (`shared/`) —— 只读，了解工具函数 -- 👁 任务描述 (`review/*/task.md`) —— 只读，了解测试目标 -- 👁 验收标准 (`review/*/acceptance.md`) —— 只读，了解测试要求 - -**禁止操作：** -- ❌ 修改业务代码 (`projects/*/src/`) -- ❌ 修改技术文档 (`projects/*/docs/`) -- ❌ 修改共享资源 (`shared/`) -- ❌ 修改影响评估 (`review/*/impact.md`) -- ❌ 修改开发工具 (`tools/`) -- ❌ 修改测试反馈 (`review/*/feedback/`) - -### 人类负责人 -**职责范围：** -- ✅ 可以修改所有目录 -- ✅ 审核 AI 输出质量 -- ✅ 解决 AI 之间的冲突 -- ✅ 最终决策和验收 - ---- - -## 工作流程 - -``` -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ 需求分析 │ ───→ │ 架构设计 │ ───→ │ 开发实现 │ ───→ │ 测试验证 │ ───→ │ 验收确认 │ -│ (Arch AI) │ │ (Arch AI) │ │ (Dev AI) │ │ (QA AI) │ │ (人类) │ -└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ - ↑ │ - │ Bug → 修复 │ - └──────────────────────┘ - (最多 2 轮) -``` - -### 详细流程说明 - -**1. 需求分析阶段** -- Arch AI 分析用户需求，输出产品规划 -- 输出: `docs/01_产品需求/PRD.md`、`review/{task_id}/task.md` - -**2. 架构设计阶段** -- Arch AI 设计系统架构，技术选型 -- 输出: `docs/02_系统架构/`、`review/{task_id}/impact.md`、`review/{task_id}/acceptance.md` - -**3. 开发实现阶段** -- Dev AI 读取任务描述和验收标准，编写代码 + 文档 -- 输出: `projects/*/src/`, `projects/*/docs/` - -**4. 测试验证阶段** -- QA AI 根据验收标准编写测试，执行测试，生成报告 -- 测试反馈写入 `review/{task_id}/feedback/round{round}.md` -- 输出: `projects/*/tests/`, `reports/test-results/`, `review/{task_id}/feedback/` - -### 缺陷修复循环 - -| 规则 | 说明 | -|------|------| -| 最大轮次 | 3 轮（初始测试 + 最多 2 轮修复复查） | -| 循环范围 | 测试失败 → Dev AI 修复 → QA AI 复查 | -| 跳过项 | 修复轮次中 Dev AI **只修 Bug**，不重新写 acceptance/impact | -| 触发升级 | 第 3 轮仍有 BLOCKER 或 HIGH 级别 Bug → 暂停流转，待人类裁决 | - -``` -Round 1: Dev 开发 → QA 测试 → 3 个 Bug -Round 2: Dev 修复 → QA 复查 → 1 个 Bug（MEDIUM） -Round 3: Dev 修复 → QA 复查 → 0 个 Bug ✅ → 提交人类验收 -``` - -如果 Round 3 仍有 BLOCKER/HIGH： -``` -Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决 -``` - -**4. 验收确认阶段** -- 人类审核测试报告，确认任务完成或驳回 -- 确认后任务状态更新为 DONE，移入 `review/archived/` +### QA AI +- 可写：测试用例、测试报告、验收标准补充、测试反馈 +- 只读：业务代码、技术文档、项目级文档、训练数据、共享资源、任务描述 +- 禁止：AI 配置、开发工具、影响评估 --- ## 目录权限矩阵 -> **图例**：`-` = 无权访问    `R` = 只读    `W` = 可写（含读）    `RW` = 读写 +> 图例：`-` = 禁止    `R` = 只读    `W` = 可写（含读）    `RW` = 读写 | 目录路径 | Arch AI | Dev AI | QA AI | 人类 | |---------|---------|--------|-------|------| @@ -176,58 +75,33 @@ Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类 | `reports/` | `R` | `-` | `RW` | `RW` | | `.github/` | `-` | `-` | `-` | `RW` | -> **解析优先级**：当同一条路径被多个规则匹配时，`forbidden > read_only > allowed`。禁止规则永远优先。 -> -> **默认行为**：任何未出现在上表中的路径，默认禁止所有 AI 访问（等效于 `-`）。 - ---- - -## 沟通规范 - -### Dev AI → QA AI -在 `review/{task_id}/` 目录提交： -- **验收标准** (`acceptance.md`) - 明确测试目标 -- **变更影响范围** (`impact.md`) - 指导回归测试 -- **环境准备** 参考项目级 `ENVIRONMENT.md` - -### QA AI → Dev AI -在 `review/{task_id}/feedback/` 目录提交： -- **测试结果报告** (`round{round}.md`) -- **Bug清单** - 列出问题和严重程度 -- **改进建议** - 代码优化建议 +优先级：`forbidden > read_only > allowed`。未出现在表中的路径默认禁止所有 AI。 --- ## 命名规范 -### 项目命名 -``` -P01_项目名称 # P01 表示项目编号 -``` - ### 任务编号 -``` -P01-001 # P01 项目编号 + 001 任务编号 -``` +`P{项目编号}-{任务序号}`，如 `P01-001` ### 分支命名 ``` -feature/P01-001-login # 功能开发 -bugfix/P01-001-password # Bug修复 -test/P01-001-testcases # 测试用例 +feature/P01-001-short-desc # 功能开发 +bugfix/P01-001-short-desc # Bug修复 +test/P01-001-short-desc # 测试用例 ``` ### 提交信息 ``` -feat(P01-001): 实现用户登录功能 -fix(P01-001): 修复密码验证问题 -docs(P01-001): 更新接口文档 -test(P01-001): 添加登录测试用例 +feat(P01-001): 简短描述 +fix(P01-001): 简短描述 +docs(P01-001): 简短描述 +test(P01-001): 简短描述 ``` --- -## AI 配置文件说明 +## AI 配置文件索引 | 文件 | 说明 | |------|------| @@ -237,4 +111,7 @@ test(P01-001): 添加登录测试用例 | `.ai/config/workflow.json` | 工作流配置（阶段、触发器） | | `.ai/prompts/architecture/` | 架构设计提示词模板 | | `.ai/prompts/coding/` | 编码提示词模板 | -| `.ai/prompts/testing/` | 测试提示词模板 | \ No newline at end of file +| `.ai/prompts/testing/` | 测试提示词模板 | +| `.ai/roles/` | AI 角色工作台（日常入口） | +| `.ai/phases/` | 阶段上下文 | +| `.ai/knowledge/` | 知识沉淀 | diff --git a/DASHBOARD.md b/DASHBOARD.md new file mode 100644 index 0000000..5cf5817 --- /dev/null +++ b/DASHBOARD.md @@ -0,0 +1,58 @@ +# ErrLens 项目仪表盘 + +> 人类视角 · 30 秒了解项目全貌 · 无需懂代码 + +--- + +## 当前状态 + +**Phase 1/4 — 基础搭建** · 进度约 30% + +我们正在搭建项目的"骨架"：定义 AI 怎么协作、目录怎么组织、开发环境怎么跑。还没开始写业务代码。 + +--- + +## 四个阶段 + +| 阶段 | 进度 | 状态 | 一句话说明 | +|------|------|------|------------| +| 1. 基础搭建 | ~30% | ← 当前 | 搭骨架：框架、权限、信息架构 | +| 2. MVP | 0% | 未开始 | 做核心：错题录入、AI 分析 | +| 3. 功能完善 | 0% | 未开始 | 加功能：推荐、多端、训练迭代 | +| 4. 打磨发布 | 0% | 未开始 | 提质量：性能、安全、文档 | + +--- + +## 现在在做什么 + +- **信息架构重构** — 让 AI 能高效协作的文档体系（进行中） +- **5 个开发任务待启动** — 都在等待产品需求文档 + +--- + +## 需要你关注的事 + +- [ ] 确认信息架构设计方向是否符合预期 +- [ ] 审阅角色工作台（`.ai/roles/`）是否合理 +- [ ] 决定 P01 项目方向：坚持"错题本"还是调整定位 + +--- + +## 快速入口 + +| 你想看什么 | 去哪里 | +|------------|--------| +| **怎么使用这套体系** | **[docs/使用手册.md](docs/使用手册.md)** | +| 详细任务看板 | [ROADMAP.md](ROADMAP.md) | +| 项目为什么要这样做 | [docs/share/](docs/share/) | +| 架构决策记录 | [.ai/knowledge/decisions.md](.ai/knowledge/decisions.md) | +| 怎么搭建的开发环境 | [ENVIRONMENT.md](ENVIRONMENT.md) | +| AI 角色怎么分工 | [AGENTS.md](AGENTS.md) | + +--- + +## 可分享内容 + +→ [docs/share/](docs/share/) — 项目开发全记录，可对外发布 + +*仪表盘每次阶段切换时更新，不随每日任务变化。* diff --git a/README.md b/README.md index 847b160..766164b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,46 @@ -# ErrLens AI 编程项目 +# ErrLens -一个"人+3AI"协作模式的 AI 辅助编程项目仓库。 +一个"人+3AI"协作模式的 AI 编程项目。学生错题本应用（小程序 + AI 训练 + Web 后台）。 + +--- + +## 快速入口 + +| 入口 | 谁看 | 说明 | +|------|------|------| +| [DASHBOARD.md](DASHBOARD.md) | 人类 | 30 秒了解项目全貌 | +| [ROADMAP.md](ROADMAP.md) | 人类 + AI | 阶段进度 + 任务看板 | +| [docs/share/](docs/share/) | 所有人 | 项目开发过程全记录 | +| [.ai/roles/](.ai/roles/) | AI | 角色工作台（每个 AI 的入口） | + +--- + +## 团队角色 + +| 角色 | 是谁 | 干什么 | +|------|------|--------| +| 人类负责人 | 你 | 需求、审阅、决策、验收 | +| Arch AI | AI 模型 | 需求分析、架构设计、跨模块协调 | +| Dev AI | AI 模型 | 写代码、写文档、修 Bug | +| QA AI | AI 模型 | 写测试、跑测试、写反馈 | + +角色详情：[AGENTS.md](AGENTS.md) + +--- + +## 快速开始 + +```bash +git clone +cd errlens + +# 安装前端依赖 +pnpm install + +# 启动 P01 开发服务器 +cd projects/P01_errlens_app +pnpm dev +``` --- @@ -8,161 +48,41 @@ ``` . -├── AGENTS.md # AI角色定义+权限约定+工作流 -├── README.md -├── .gitignore -├── .ai/ # AI协作核心配置 -│ ├── config/ -│ │ ├── architect.json # Arch AI 配置 -│ │ ├── coder.json # Dev AI 配置 -│ │ ├── tester.json # QA AI 配置 -│ │ └── workflow.json # 工作流配置 -│ └── prompts/ -│ ├── architecture/ # 架构设计提示词模板 -│ ├── coding/ # 编码提示词模板 -│ └── testing/ # 测试提示词模板 -├── docs/ # 项目级总体文档 +├── DASHBOARD.md # 人类仪表盘 +├── ROADMAP.md # 路线图看板 +├── AGENTS.md # AI 角色 + 权限 +├── ENVIRONMENT.md # 开发环境 +├── .ai/ # AI 协作核心 +│ ├── roles/ # 角色工作台（AI 日常入口） +│ ├── phases/ # 阶段上下文 +│ ├── knowledge/ # 知识沉淀 +│ ├── prompts/ # 提示词模板 +│ └── config/ # 角色配置 +├── docs/ # 项目文档 │ ├── 01_产品需求/ │ ├── 02_系统架构/ -│ ├── 03_开发规范/ -│ ├── 04_部署运维/ -│ ├── 05_变更日志/ -│ │ └── archived/ # 历史变更日志（按年月归档） -│ └── 06_开发日志/ -├── tools/ # 开发工具脚本 -├── data/ # 训练数据 -├── projects/ # 项目代码 -│ ├── P01_errlens_app/ # 主应用项目 -│ │ ├── src/ # 业务代码 (Dev AI) -│ │ ├── tests/ # 测试代码 (QA AI) -│ │ ├── docs/ # 项目文档 (Dev AI) -│ │ │ ├── 01_需求概要.md -│ │ │ ├── 02_架构设计.md -│ │ │ └── 03_接口定义.md -│ │ └── ENVIRONMENT.md # 项目级环境准备 -│ └── P02_errlens_training/ # AI训练项目 -│ ├── src/ -│ ├── tests/ -│ ├── docs/ -│ │ ├── 01_需求概要.md -│ │ ├── 02_架构设计.md -│ │ └── 03_训练流程.md -│ └── ENVIRONMENT.md -├── review/ # 交接中心 -│ ├── active/ # 活跃任务 -│ │ ├── P01-001/ # 项目1-任务001 -│ │ │ ├── task.md # 任务描述 -│ │ │ ├── acceptance.md # 验收标准 -│ │ │ ├── impact.md # 变更影响范围 -│ │ │ └── feedback/ # 反馈记录 -│ │ │ └── round1.md -│ │ ├── P01-002/ # 项目1-任务002 -│ │ ├── P02-001/ # 项目2-任务001 -│ │ └── CROSS-001/ # 跨项目任务 -│ └── archived/ # 已完成任务（按季度归档） -│ ├── 2026-Q2/ -│ └── 2026-Q3/ -├── shared/ # 共享资源 -│ ├── scripts/ # 共享脚本 -│ ├── templates/ # 代码/文档模板 -│ └── utils/ # 工具函数 -├── reports/ # 统一报告 -│ ├── test-results/ # 测试结果 -│ └── quality-reports/ # 质量评审报告 -└── .github/ # CI/CD配置 - └── workflows/ +│ ├── share/ # 对外分享内容 +│ └── ... +├── projects/ # 代码 +│ ├── P01_errlens_app/ +│ ├── P02_errlens_training/ +│ └── P03_errlens_web/ +├── review/ # 任务交接 +│ └── active/ # 活跃任务 +├── shared/ # 共享资源 +└── tools/ # 开发工具 ``` --- -## 团队角色 - -| 角色 | 是谁 | 干什么 | 不干什么 | -|------|------|--------|----------| -| **人类负责人** | 你 | 下指令、审阅、做决策、定验收标准 | 不写代码、不写测试 | -| **Arch AI** | Claude/TRAE/元宝等 | 需求分析、架构设计、技术选型、跨模块协调 | 不写测试 | -| **Dev AI** | Claude/TRAE/元宝等 | 写业务代码+文档、修bug、写impact | 不动tests/、不跑测试 | -| **QA AI** | 扣子编程AI | 写测试、跑测试、写反馈 | 不动src/、不改业务代码 | - ---- - -## 工作流程 - -1. **Arch AI** 分析需求，输出 `docs/01_产品需求/PRD.md` 和 `review/active/P01-001/task.md` -2. **Arch AI** 设计架构，输出 `docs/02_系统架构/`、`acceptance.md`、`impact.md` -3. **Dev AI** 在 `projects/P01_errlens_app/src/` 写代码，在 `docs/` 写文档 -4. **你**审一眼，没问题就触发QA AI -5. **QA AI** 读 `task.md` + `acceptance.md` + `impact.md`，按 `ENVIRONMENT.md` 准备环境，在 `tests/` 写测试并执行，写 `feedback/round1.md` -6. **有bug** → 你看反馈 → 让Dev AI修 → 回到步骤3（round2） - **通过** → 你确认 → 任务关闭，报告归档到 `reports/` - ---- - ## 可用 Skill -| Skill | 功能 | 触发词 | -|-------|------|--------| -| **ai-collab-setup** | 创建协作框架 | 初始化项目时 | -| **add-subproject** | 添加子项目 | 新增子项目时 | -| **resume-context** | 换电脑时同步上下文 | `接着干 开发/测试/架构` | -| **switch-model** | 换大模型时同步上下文 | `切换模型 架构/开发/测试` | -| **update-constitution** | 更新宪法文件 | AI 角色/权限/工作流变更时 | -| **update-docs** | 更新项目文档 | 代码/结构变更后 | -| **git** | 封装 git 操作 | 提交/推送/分支管理时 | - ---- - -## 任务状态流转 - -``` -TODO → IN_PROGRESS → REVIEW → DONE → ARCHIVED（移入archived/季度目录） -``` - -`task.md` 中添加状态字段： -``` -status: TODO | IN_PROGRESS | REVIEW | DONE | ARCHIVED -``` - ---- - -## 决策总结 - -| 问题 | 决策 | -|------|------| -| 任务创建 | 先手动，中期脚本化（create-task.sh），后期CI联动Issue | -| 跨项目任务 | `CROSS-xxx/`，feedback按项目分文件（如 `P01-round1.md`） | -| 任务归档 | `review/active/` + `review/archived/2026-Qx/`，状态字段驱动，定期归档 | - ---- - -## 快速开始 - -```bash -# 克隆仓库 -git clone -cd errlens - -# 查看目录结构 -find . -type d | sort - -# 查看当前任务 -ls -la review/ -``` - ---- - -## 参考文档 - -| 文件 | 说明 | -|------|------| -| [AGENTS.md](AGENTS.md) | AI角色定义与权限约定 | -| [workflow.json](.ai/config/workflow.json) | 工作流配置 | -| [P01-001 任务](review/P01-001/task.md) | 示例任务单 | - ---- - -## 版本历史 - -| 版本 | 日期 | 说明 | -|------|------|------| -| v1.0 | 2026-05-22 | 初始版本，完成目录结构设计 | \ No newline at end of file +| Skill | 功能 | +|-------|------| +| resume-context | 换电脑时同步上下文 | +| switch-model | 换大模型时同步上下文 | +| update-constitution | 更新 AI 角色/权限/工作流 | +| update-docs | 代码变更后同步文档 | +| git | 封装 git 操作 | +| ai-collab-setup | 初始化协作框架 | +| add-subproject | 添加子项目 | diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..a7d92ed --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,68 @@ +# ErrLens 项目路线图 + +> 人类 + AI 共享视野。状态由 Arch AI 维护。 + +--- + +## 阶段总览 + +``` +Phase 1 [====------] 基础搭建 ← 当前 (30%) +Phase 2 [----------] MVP (0%) +Phase 3 [----------] 功能完善 (0%) +Phase 4 [----------] 打磨发布 (0%) +``` + +| 阶段 | 名称 | 状态 | 进度 | 预计重点 | +|------|------|------|------|----------| +| 1 | 基础搭建 | ACTIVE | ~30% | 框架、脚手架、权限、信息架构 | +| 2 | MVP | PLANNED | 0% | 错题录入、AI 分析、基础展示 | +| 3 | 功能完善 | PLANNED | 0% | 个性化推荐、多端适配、训练迭代 | +| 4 | 打磨发布 | PLANNED | 0% | 性能优化、安全审计、文档完善 | + +--- + +## 当前阶段 (Phase 1) 任务看板 + +### TODO（待开始） + +| 任务 | 项目 | 描述 | 优先级 | 阻塞原因 | +|------|------|------|--------|----------| +| P01-001 | App | 用户登录注册 | HIGH | 等待 PRD | +| P01-002 | App | 代码分析 API | MEDIUM | 等待 PRD + 项目定位确认 | +| P02-001 | 训练 | 数据集预处理 | MEDIUM | 等待 PRD | +| P03-001 | Web | Web 项目初始化 | LOW | — | +| CROSS-001 | 共享 | 共享工具库更新 | HIGH | 1 个日期格式 bug 待修 | + +### DOING（进行中） + +| 任务 | 项目 | 描述 | 负责人 | 预计完成 | +|------|------|------|--------|----------| +| — | 全局 | 信息架构重构 | Arch AI | 2026-05-25 | + +### REVIEW（待验收） + +（空） + +### DONE（已完成） + +（空） + +--- + +## 阻塞项 + +| 级别 | 描述 | 影响范围 | 分配给 | 创建日期 | +|------|------|----------|--------|----------| +| RED | PRD 未编写 | P01-001, P01-002, P02-001 无法开始 | Arch AI | 2026-05-23 | +| YELLOW | P01 文档内容仍是"代码检测"模板 | P01-002 定位错误 | Arch AI | 2026-05-23 | +| YELLOW | CROSS-001 P01 日期格式 bug | CROSS-001 无法关闭 | Dev AI | 2026-05-23 | + +--- + +## 最近更新 + +| 日期 | 事件 | +|------|------| +| 2026-05-25 | 信息架构重构：分层 AI 上下文 + 角色工作台 + 分享层 | +| 2026-05-23 | 框架搭建完成：目录结构、权限体系、7 个 Skill | diff --git a/docs/01_产品需求/README.md b/docs/01_产品需求/README.md new file mode 100644 index 0000000..509d9e9 --- /dev/null +++ b/docs/01_产品需求/README.md @@ -0,0 +1,19 @@ +# 产品需求 + +本目录存放产品需求文档。文档由 Arch AI 编写，人类审阅。 + +## 文件说明 + +| 文件 | 说明 | 状态 | +|------|------|------| +| PRD.md | 产品需求文档（主文档） | 待编写 | + +## 编写时机 + +Phase 1 基础搭建阶段完成信息架构重构后，Arch AI 将在此编写 PRD。 + +## 相关链接 + +- 阶段上下文: `.ai/phases/phase-01-foundation/` +- 架构决策: `.ai/knowledge/decisions.md` +- 路线图: `ROADMAP.md` diff --git a/docs/02_系统架构/README.md b/docs/02_系统架构/README.md new file mode 100644 index 0000000..d8f98b1 --- /dev/null +++ b/docs/02_系统架构/README.md @@ -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` diff --git a/docs/03_开发规范/README.md b/docs/03_开发规范/README.md new file mode 100644 index 0000000..0ba1aeb --- /dev/null +++ b/docs/03_开发规范/README.md @@ -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` diff --git a/docs/04_部署运维/README.md b/docs/04_部署运维/README.md new file mode 100644 index 0000000..3caf78b --- /dev/null +++ b/docs/04_部署运维/README.md @@ -0,0 +1,20 @@ +# 部署运维 + +本目录存放部署和运维相关文档。 + +## 文件说明 + +| 文件 | 说明 | 状态 | +|------|------|------| +| 部署架构.md | 部署拓扑和环境说明 | 待编写 | +| CI_CD.md | 持续集成/持续部署配置 | 待编写 | +| 运维手册.md | 日常运维操作手册 | 待编写 | + +## 编写时机 + +Phase 2 MVP 有可部署产物后开始编写。 + +## 相关链接 + +- 环境配置: `ENVIRONMENT.md` +- 各子项目环境: `projects/P0X_*/ENVIRONMENT.md` diff --git a/docs/05_变更日志/2026-05-25.md b/docs/05_变更日志/2026-05-25.md new file mode 100644 index 0000000..972d678 --- /dev/null +++ b/docs/05_变更日志/2026-05-25.md @@ -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 diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 8f83ca3..fe12546 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -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 预算）。 diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md index 7d335b0..e1571b6 100644 --- a/docs/PROJECT_CONTEXT.md +++ b/docs/PROJECT_CONTEXT.md @@ -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 项目初始化 diff --git a/docs/share/00_项目缘起.md b/docs/share/00_项目缘起.md new file mode 100644 index 0000000..d632f6a --- /dev/null +++ b/docs/share/00_项目缘起.md @@ -0,0 +1,5 @@ +# 项目缘起 + +> *（待写：由 Arch AI 在 PRD 完成后撰写）* +> +> 内容包括：为什么要做错题本、解决什么痛点、为什么选择这个技术方案、为什么用 AI 协作模式。 diff --git a/docs/share/01_框架设计思路.md b/docs/share/01_框架设计思路.md new file mode 100644 index 0000000..9c320c6 --- /dev/null +++ b/docs/share/01_框架设计思路.md @@ -0,0 +1,8 @@ +# 框架设计思路 + +> *（待写：信息架构重构稳定后撰写）* +> +> 内容包括：为什么传统的项目文档结构对 AI 不友好、分层信息架构的设计思考、token 预算的概念、"一鸡多吃"的分享层设计。 +> +> 对应 ADR：ADR-007 +> 背景参考：`.ai/principles.md` diff --git a/docs/share/README.md b/docs/share/README.md new file mode 100644 index 0000000..dbdf3a8 --- /dev/null +++ b/docs/share/README.md @@ -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/ → 开发周记（合并精选） +``` diff --git a/docs/share/phase-01/决策故事_ADR-007.md b/docs/share/phase-01/决策故事_ADR-007.md new file mode 100644 index 0000000..1de9c2d --- /dev/null +++ b/docs/share/phase-01/决策故事_ADR-007.md @@ -0,0 +1,5 @@ +# ADR-007 决策故事 + +> 信息架构为什么从"单体文档"变成"分层设计" +> +> *（Phase 1 完成时撰写，基于 `.ai/knowledge/decisions.md` 中的 ADR-007 扩展）* diff --git a/docs/share/phase-01/阶段复盘_基础搭建.md b/docs/share/phase-01/阶段复盘_基础搭建.md new file mode 100644 index 0000000..73a9f48 --- /dev/null +++ b/docs/share/phase-01/阶段复盘_基础搭建.md @@ -0,0 +1,3 @@ +# Phase 1: 基础搭建 — 阶段复盘 + +> *（Phase 1 完成时由 Arch AI 撰写，基于 `.ai/phases/phase-01-foundation/completion.md` 扩展）* diff --git a/docs/share/templates/决策故事模板.md b/docs/share/templates/决策故事模板.md new file mode 100644 index 0000000..7b7552e --- /dev/null +++ b/docs/share/templates/决策故事模板.md @@ -0,0 +1,38 @@ +# 决策故事模板 + +## 决策编号 + +ADR-XXX + +## 标题 + +用一句话描述这个决策（吸引人的标题） + +## 背景 + +- 当时在做什么 +- 遇到了什么问题 +- 有哪些约束条件 + +## 选项 + +| 选项 | 优势 | 劣势 | +|------|------|------| +| A | ... | ... | +| B | ... | ... | +| C | ... | ... | + +## 思考过程 + +- 为什么排除了某个选项 +- 最纠结的点是什么 +- 最终决策的关键因素 + +## 结果 + +- 决策带来的影响 +- 如果有机会重来，会改变什么 + +## 一句话总结 + +（可引用/可传播的一句话） diff --git a/docs/share/templates/阶段复盘模板.md b/docs/share/templates/阶段复盘模板.md new file mode 100644 index 0000000..e686da8 --- /dev/null +++ b/docs/share/templates/阶段复盘模板.md @@ -0,0 +1,35 @@ +# 阶段复盘模板 + +## 阶段信息 + +- 阶段编号：Phase N +- 阶段名称： +- 时间范围： +- 参与角色： + +## 做了什么 + +- （列表形式概述本阶段完成的主要工作） + +## 关键决策 + +- （本阶段最重要的 3-5 个决策及背后的思考） + +## 踩过的坑 + +- （本阶段遇到的主要问题及解决方案） + +## 学到的东西 + +- （可复用的经验教训） + +## 数据 + +- 新增代码行数： +- 任务完成数： +- Bug 修复数： +- 测试覆盖率： + +## 下一阶段预告 + +- （接下来要做什么） diff --git a/docs/使用手册.md b/docs/使用手册.md new file mode 100644 index 0000000..0a5bf10 --- /dev/null +++ b/docs/使用手册.md @@ -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。本文档随架构演变同步更新。 diff --git a/review/active/CROSS-001/task.md b/review/active/CROSS-001/task.md index 605f713..107dae7 100644 --- a/review/active/CROSS-001/task.md +++ b/review/active/CROSS-001/task.md @@ -6,6 +6,7 @@ - 创建时间: 2026-05-22 - 负责人: Dev AI - 状态: TODO +- 阶段: Phase 1 ## 任务描述 更新 shared/utils/ 中的工具函数，修复影响 P01 和 P02 的通用问题： diff --git a/review/active/INDEX.md b/review/active/INDEX.md new file mode 100644 index 0000000..bc2654f --- /dev/null +++ b/review/active/INDEX.md @@ -0,0 +1,13 @@ +# 活跃任务索引 + +> 由 Arch AI 维护。AI 通过此索引发现任务，然后读取具体任务文件。 + +| 任务 ID | 项目 | 标题 | 状态 | 阶段 | 角色 | 反馈轮次 | +|---------|------|------|------|------|------|----------| +| P01-001 | P01 App | 用户登录 | TODO | 1 | Dev AI | Round 1 | +| P01-002 | P01 App | 代码分析 API | TODO | 1 | Dev AI | — | +| P02-001 | P02 训练 | 数据集预处理 | TODO | 1 | Dev AI | — | +| P03-001 | P03 Web | 项目初始化 | TODO | 1 | Dev AI | — | +| CROSS-001 | 全部 | 共享工具库更新 | TODO | 1 | Dev AI | Round 1 | + +更新于: 2026-05-25 diff --git a/review/active/P01-001/task.md b/review/active/P01-001/task.md index 78f05a3..484ff1e 100644 --- a/review/active/P01-001/task.md +++ b/review/active/P01-001/task.md @@ -6,6 +6,7 @@ - 创建时间: 2026-05-22 - 负责人: Dev AI - 状态: TODO +- 阶段: Phase 1 ## 任务描述 实现用户登录功能，包括： diff --git a/review/active/P01-002/task.md b/review/active/P01-002/task.md index 009bfbd..1af10a9 100644 --- a/review/active/P01-002/task.md +++ b/review/active/P01-002/task.md @@ -6,6 +6,7 @@ - 创建时间: 2026-05-22 - 负责人: Dev AI - 状态: TODO +- 阶段: Phase 1 ## 任务描述 实现代码分析API，包括： diff --git a/review/active/P02-001/task.md b/review/active/P02-001/task.md index bda671f..0fc4f64 100644 --- a/review/active/P02-001/task.md +++ b/review/active/P02-001/task.md @@ -6,6 +6,7 @@ - 创建时间: 2026-05-22 - 负责人: Dev AI - 状态: TODO +- 阶段: Phase 1 ## 任务描述 实现数据集预处理模块，包括： diff --git a/review/active/P03-001/task.md b/review/active/P03-001/task.md index ff3380e..8a822d6 100644 --- a/review/active/P03-001/task.md +++ b/review/active/P03-001/task.md @@ -5,6 +5,7 @@ - 项目：P03_errlens_web - 创建时间：2026-05-22 - 状态：TODO +- 阶段: Phase 1 ## 任务描述 完成 errlens_web 项目的初始化工作。