refactor(architecture): 信息架构重构 — 从"人类导向单体文档"到"AI优先分层架构"
新增四层信息架构： - 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
@@ -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/` 分享层
|
||||
@@ -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 上下文
|
||||
@@ -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
|
||||
|
||||
*（待项目推进中记录）*
|
||||
@@ -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
|
||||
- 大段文档内联而非链接 → 用链接 + 一句话摘要
|
||||
@@ -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/）
|
||||
@@ -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 版本策略
|
||||
@@ -0,0 +1,16 @@
|
||||
# Phase 1: 基础搭建 — 完成检查清单
|
||||
|
||||
## 完成状态
|
||||
|
||||
- [ ] 所有 goal.md 中的成功标准达成
|
||||
- [ ] 所有活跃任务处于 DONE 或 ARCHIVED
|
||||
- [ ] QA AI 签字确认
|
||||
- [ ] 人类签字确认
|
||||
- [ ] 知识已沉淀至 .ai/knowledge/
|
||||
- [ ] Phase 2 MVP 计划已起草
|
||||
- [ ] 阶段复盘已写出（docs/share/phase-01/）
|
||||
- [ ] Token 预算审计通过
|
||||
|
||||
## 阶段交接
|
||||
|
||||
*（阶段接近完成时填写）*
|
||||
@@ -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 负责维护各角色的任务分配
|
||||
@@ -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 — 实现错题本核心功能
|
||||
@@ -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）
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 2: MVP — 架构决策
|
||||
|
||||
*（Phase 2 执行过程中由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 2: MVP — 完成检查清单
|
||||
|
||||
*（Phase 2 接近完成时更新）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 2: MVP — 阶段决策
|
||||
|
||||
*（Phase 2 执行过程中由 Arch AI 填写）*
|
||||
@@ -0,0 +1,11 @@
|
||||
# Phase 2: MVP — 目标
|
||||
|
||||
*（Phase 1 完成时由 Arch AI 填写）*
|
||||
|
||||
## 阶段目标
|
||||
|
||||
## 成功标准
|
||||
|
||||
## 阶段 Owner
|
||||
|
||||
## 下一阶段
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 2: MVP — 范围
|
||||
|
||||
*（Phase 1 完成时由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 3: 功能完善 — 架构决策
|
||||
|
||||
*（Phase 3 执行过程中由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 3: 功能完善 — 完成检查清单
|
||||
|
||||
*（Phase 3 接近完成时更新）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 3: 功能完善 — 阶段决策
|
||||
|
||||
*（Phase 3 执行过程中由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 3: 功能完善 — 目标
|
||||
|
||||
*（Phase 2 完成时由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 3: 功能完善 — 范围
|
||||
|
||||
*（Phase 2 完成时由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 4: 打磨发布 — 架构决策
|
||||
|
||||
*（Phase 4 执行过程中由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 4: 打磨发布 — 完成检查清单
|
||||
|
||||
*（Phase 4 接近完成时更新）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 4: 打磨发布 — 阶段决策
|
||||
|
||||
*（Phase 4 执行过程中由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 4: 打磨发布 — 目标
|
||||
|
||||
*（Phase 3 完成时由 Arch AI 填写）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 4: 打磨发布 — 范围
|
||||
|
||||
*（Phase 3 完成时由 Arch AI 填写）*
|
||||
@@ -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 预算
|
||||
@@ -0,0 +1,6 @@
|
||||
# 架构提示词模板
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `architecture-design.md` | 系统架构设计模板 |
|
||||
| `technical-evaluation.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 确定回归测试范围
|
||||
@@ -0,0 +1,41 @@
|
||||
# 技术选型评估模板
|
||||
|
||||
## 输入
|
||||
|
||||
- 需要解决的技术问题
|
||||
- 约束条件（预算、时间、团队、已有技术栈）
|
||||
|
||||
## 输出结构
|
||||
|
||||
### 1. 需求描述
|
||||
- 要解决什么问题
|
||||
- 关键约束是什么
|
||||
|
||||
### 2. 候选方案（2-4 个）
|
||||
|
||||
每个方案描述：
|
||||
- 方案名称和简介
|
||||
- 优势（3-5 条）
|
||||
- 劣势（3-5 条）
|
||||
- 与本项目技术栈的兼容度
|
||||
|
||||
### 3. 评估维度
|
||||
|
||||
| 维度 | 权重 | 方案A | 方案B | 方案C |
|
||||
|------|------|-------|-------|-------|
|
||||
| 性能 | 30% | — | — | — |
|
||||
| 生态成熟度 | 25% | — | — | — |
|
||||
| 学习曲线 | 20% | — | — | — |
|
||||
| 社区活跃度 | 15% | — | — | — |
|
||||
| 团队熟悉度 | 10% | — | — | — |
|
||||
| **加权总分** | 100% | — | — | — |
|
||||
|
||||
### 4. 推荐方案
|
||||
- 推荐哪个、为什么
|
||||
- 主要风险
|
||||
- 如果失败，备选方案是什么
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 评估维度可调整，但必须说明理由
|
||||
- 不追求"最优"，追求"最适合当前阶段"
|
||||
@@ -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
|
||||
@@ -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`
|
||||
@@ -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 | — |
|
||||
@@ -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] 输出信息架构重构方案
|
||||
|
||||
## 阻塞
|
||||
|
||||
（无外部阻塞）
|
||||
@@ -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`
|
||||
@@ -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`
|
||||
@@ -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 |
|
||||
|
||||
## 已完成
|
||||
|
||||
（无）
|
||||
@@ -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`
|
||||
@@ -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/`
|
||||
|
||||
## 已完成的测试
|
||||
|
||||
（无）
|
||||
@@ -0,0 +1,18 @@
|
||||
# QA AI · 今日任务 · 2026-05-25
|
||||
|
||||
## 进行中
|
||||
|
||||
（无）
|
||||
|
||||
## 待执行
|
||||
|
||||
当前没有进入 REVIEW 状态的任务，暂无测试任务。
|
||||
|
||||
## 已完成
|
||||
|
||||
（无）
|
||||
|
||||
## 说明
|
||||
|
||||
等待 Dev AI 完成代码开发后，任务状态转为 REVIEW 时开始测试工作。
|
||||
关注 `ROADMAP.md` 中的 DOING 列，当有任务进入 REVIEW 时立即介入。
|
||||
@@ -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/` | 测试提示词模板 |
|
||||
| `.ai/prompts/testing/` | 测试提示词模板 |
|
||||
| `.ai/roles/` | AI 角色工作台（日常入口） |
|
||||
| `.ai/phases/` | 阶段上下文 |
|
||||
| `.ai/knowledge/` | 知识沉淀 |
|
||||
|
||||
@@ -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/) — 项目开发全记录，可对外发布
|
||||
|
||||
*仪表盘每次阶段切换时更新，不随每日任务变化。*
|
||||
@@ -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 <repository-url>
|
||||
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 <repository-url>
|
||||
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 | 初始版本，完成目录结构设计 |
|
||||
| Skill | 功能 |
|
||||
|-------|------|
|
||||
| resume-context | 换电脑时同步上下文 |
|
||||
| switch-model | 换大模型时同步上下文 |
|
||||
| update-constitution | 更新 AI 角色/权限/工作流 |
|
||||
| update-docs | 代码变更后同步文档 |
|
||||
| git | 封装 git 操作 |
|
||||
| ai-collab-setup | 初始化协作框架 |
|
||||
| add-subproject | 添加子项目 |
|
||||
|
||||
+68
@@ -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 |
|
||||
@@ -0,0 +1,19 @@
|
||||
# 产品需求
|
||||
|
||||
本目录存放产品需求文档。文档由 Arch AI 编写，人类审阅。
|
||||
|
||||
## 文件说明
|
||||
|
||||
| 文件 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| PRD.md | 产品需求文档（主文档） | 待编写 |
|
||||
|
||||
## 编写时机
|
||||
|
||||
Phase 1 基础搭建阶段完成信息架构重构后，Arch AI 将在此编写 PRD。
|
||||
|
||||
## 相关链接
|
||||
|
||||
- 阶段上下文: `.ai/phases/phase-01-foundation/`
|
||||
- 架构决策: `.ai/knowledge/decisions.md`
|
||||
- 路线图: `ROADMAP.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`
|
||||
@@ -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`
|
||||
@@ -0,0 +1,20 @@
|
||||
# 部署运维
|
||||
|
||||
本目录存放部署和运维相关文档。
|
||||
|
||||
## 文件说明
|
||||
|
||||
| 文件 | 说明 | 状态 |
|
||||
|------|------|------|
|
||||
| 部署架构.md | 部署拓扑和环境说明 | 待编写 |
|
||||
| CI_CD.md | 持续集成/持续部署配置 | 待编写 |
|
||||
| 运维手册.md | 日常运维操作手册 | 待编写 |
|
||||
|
||||
## 编写时机
|
||||
|
||||
Phase 2 MVP 有可部署产物后开始编写。
|
||||
|
||||
## 相关链接
|
||||
|
||||
- 环境配置: `ENVIRONMENT.md`
|
||||
- 各子项目环境: `projects/P0X_*/ENVIRONMENT.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
|
||||
+2
-151
@@ -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 预算）。
|
||||
|
||||
+35
-100
@@ -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 项目初始化
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
# 项目缘起
|
||||
|
||||
> *（待写：由 Arch AI 在 PRD 完成后撰写）*
|
||||
>
|
||||
> 内容包括：为什么要做错题本、解决什么痛点、为什么选择这个技术方案、为什么用 AI 协作模式。
|
||||
@@ -0,0 +1,8 @@
|
||||
# 框架设计思路
|
||||
|
||||
> *（待写：信息架构重构稳定后撰写）*
|
||||
>
|
||||
> 内容包括：为什么传统的项目文档结构对 AI 不友好、分层信息架构的设计思考、token 预算的概念、"一鸡多吃"的分享层设计。
|
||||
>
|
||||
> 对应 ADR：ADR-007
|
||||
> 背景参考：`.ai/principles.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/ → 开发周记（合并精选）
|
||||
```
|
||||
@@ -0,0 +1,5 @@
|
||||
# ADR-007 决策故事
|
||||
|
||||
> 信息架构为什么从"单体文档"变成"分层设计"
|
||||
>
|
||||
> *（Phase 1 完成时撰写，基于 `.ai/knowledge/decisions.md` 中的 ADR-007 扩展）*
|
||||
@@ -0,0 +1,3 @@
|
||||
# Phase 1: 基础搭建 — 阶段复盘
|
||||
|
||||
> *（Phase 1 完成时由 Arch AI 撰写，基于 `.ai/phases/phase-01-foundation/completion.md` 扩展）*
|
||||
@@ -0,0 +1,38 @@
|
||||
# 决策故事模板
|
||||
|
||||
## 决策编号
|
||||
|
||||
ADR-XXX
|
||||
|
||||
## 标题
|
||||
|
||||
用一句话描述这个决策（吸引人的标题）
|
||||
|
||||
## 背景
|
||||
|
||||
- 当时在做什么
|
||||
- 遇到了什么问题
|
||||
- 有哪些约束条件
|
||||
|
||||
## 选项
|
||||
|
||||
| 选项 | 优势 | 劣势 |
|
||||
|------|------|------|
|
||||
| A | ... | ... |
|
||||
| B | ... | ... |
|
||||
| C | ... | ... |
|
||||
|
||||
## 思考过程
|
||||
|
||||
- 为什么排除了某个选项
|
||||
- 最纠结的点是什么
|
||||
- 最终决策的关键因素
|
||||
|
||||
## 结果
|
||||
|
||||
- 决策带来的影响
|
||||
- 如果有机会重来，会改变什么
|
||||
|
||||
## 一句话总结
|
||||
|
||||
（可引用/可传播的一句话）
|
||||
@@ -0,0 +1,35 @@
|
||||
# 阶段复盘模板
|
||||
|
||||
## 阶段信息
|
||||
|
||||
- 阶段编号：Phase N
|
||||
- 阶段名称：
|
||||
- 时间范围：
|
||||
- 参与角色：
|
||||
|
||||
## 做了什么
|
||||
|
||||
- （列表形式概述本阶段完成的主要工作）
|
||||
|
||||
## 关键决策
|
||||
|
||||
- （本阶段最重要的 3-5 个决策及背后的思考）
|
||||
|
||||
## 踩过的坑
|
||||
|
||||
- （本阶段遇到的主要问题及解决方案）
|
||||
|
||||
## 学到的东西
|
||||
|
||||
- （可复用的经验教训）
|
||||
|
||||
## 数据
|
||||
|
||||
- 新增代码行数：
|
||||
- 任务完成数：
|
||||
- Bug 修复数：
|
||||
- 测试覆盖率：
|
||||
|
||||
## 下一阶段预告
|
||||
|
||||
- （接下来要做什么）
|
||||
+323
@@ -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。本文档随架构演变同步更新。
|
||||
@@ -6,6 +6,7 @@
|
||||
- 创建时间: 2026-05-22
|
||||
- 负责人: Dev AI
|
||||
- 状态: TODO
|
||||
- 阶段: Phase 1
|
||||
|
||||
## 任务描述
|
||||
更新 shared/utils/ 中的工具函数，修复影响 P01 和 P02 的通用问题：
|
||||
|
||||
@@ -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
|
||||
@@ -6,6 +6,7 @@
|
||||
- 创建时间: 2026-05-22
|
||||
- 负责人: Dev AI
|
||||
- 状态: TODO
|
||||
- 阶段: Phase 1
|
||||
|
||||
## 任务描述
|
||||
实现用户登录功能，包括：
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
- 创建时间: 2026-05-22
|
||||
- 负责人: Dev AI
|
||||
- 状态: TODO
|
||||
- 阶段: Phase 1
|
||||
|
||||
## 任务描述
|
||||
实现代码分析API，包括：
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
- 创建时间: 2026-05-22
|
||||
- 负责人: Dev AI
|
||||
- 状态: TODO
|
||||
- 阶段: Phase 1
|
||||
|
||||
## 任务描述
|
||||
实现数据集预处理模块，包括：
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
- 项目：P03_errlens_web
|
||||
- 创建时间：2026-05-22
|
||||
- 状态：TODO
|
||||
- 阶段: Phase 1
|
||||
|
||||
## 任务描述
|
||||
完成 errlens_web 项目的初始化工作。
|
||||
|
||||
Reference in New Issue
Block a user