Review architecture audit

review-architecture-audit

主题分组：review
来源：docs/02-像项目主管一样使用 Agent.md §3.7 「Review Gate」、§4.5；docs/03-两种 Agent 使用模式的协作与切换.md §2.3「Review Mode 是切换的关口」

1. 目的与适用边界

• 目的：在快速模式与设计师模式之间插入审查缓冲层。让 Agent 停止写代码、解释当前系统，区分「真实核心 / demo 临时方案 / 过度设计 / 边界不清」，为下一阶段决定是重构、加固还是丢弃原型。
• 适用：Project Manager Mode 收束后；准备切到 Designer Mode 之前；每个里程碑结束。
• 不适用：项目还没有可运行物；正在写新功能（请先 stop-and-converge）。

2. 输入 / 输出

输入：审查 prompt

现在进入 Review Mode。

请基于当前项目输出一份架构审查报告：

1. 当前项目的核心闭环是什么？
2. 当前项目最重要的模块有哪些？
3. 哪些设计可以保留？
4. 哪些设计只是 demo 临时方案？
5. 哪些地方存在过度设计？
6. 哪些地方边界不清？
7. 哪些依赖可以移除或替换？
8. 哪些文件最需要我人工审查？
9. 当前最危险的技术债是什么？
10. 如果要转为长期项目，请给出 5 个最小重构 checkpoint。

注意：不要直接改代码。先帮我重新理解项目。

输出：架构审查报告（10 段）

Agent 必须按 1–10 编号回答；每段引用具体文件 / 行号 / 函数名，不接受抽象描述。

3. 执行步骤

1. 确认前置条件：核心闭环已跑通；已经走过 stop-and-converge；ASSUMPTIONS.md / DECISIONS.md 已存在。
2. 粘贴 prompt，等 Agent 输出 10 段报告。
3. 用三色标注每个模块：
   • 🟢 保留（变成长期架构的种子）
   • 🟡 重画（进入 Designer Mode 重构）
   • 🔴 丢弃（demo 临时方案，新阶段直接删）
4. 把第 10 项「5 个最小重构 checkpoint」拆成 5 个 Designer Mode 薄片任务，存成清单。
5. 关闭本 session；下一 session 重新声明 mode = Designer。

4. 失败处理 / 回滚

• Agent 在 Review 中又开始写代码 → 「停。Review Mode 不写代码，只输出文本。」
• 报告太抽象 → 要求每条都引用文件路径和行号；不允许出现「整体架构良好」之类无锚点描述。
• Agent 把所有模块都说成「保留」 → 让它强制至少标 2 项「demo 临时」+ 2 项「过度设计」，目的是逼出取舍。
• 回滚：报告本身不会改代码，但若误信报告导致后续重构失败，回退到 Review 之前的 commit。

5. 示例

示例：task tracker demo 的审查报告（节选）

输出：

1. 核心闭环：CLI add → store.append → store.read → CLI list
2. 重要模块：src/cli.ts、src/store.ts、src/model.ts
3. 可保留：model.ts 的 Task 数据形状；store 的 read/append 接口形状
4. 临时方案：store.ts 全量 JSON 读写（src/store.ts:14）；CLI 直接 console.log（src/cli.ts:30）
5. 过度设计：src/plugins/（空目录但已注册插件加载逻辑） — 当前无插件需求
6. 边界不清：cli.ts 直接调用 fs（绕过 store 层）src/cli.ts:55
7. 可移除依赖：commander（自写 argv 解析够用了）
8. 最需审查：store.ts、cli.ts、plugins/loader.ts
9. 最危险技术债：并发写 JSON 文件可能损坏数据
10. 5 个重构 checkpoint：
    1) 把 fs 调用集中到 store 层
    2) 删除 plugins/ 整个目录
    3) Task 抽出 Repository 接口
    4) CLI 错误用 Result，统一退出码
    5) 给 store.append 加文件锁或换 SQLite

6. 关联 skill

• 上游 ↖：stop-and-converge
• 下游 ↘：designer-design-card（按第 10 项的 5 个 checkpoint 切薄片）
• 配套 ：mode-switch-gate（判断该不该切到 Designer / Harden）