From 791211363e45a54fedfa99f7f577c4821aed4988 Mon Sep 17 00:00:00 2001 From: QiuSW Date: Sun, 28 Jun 2026 22:32:49 +0800 Subject: [PATCH] Enhance harness template adoption workflow --- README.md | 53 ++++++++++++++++++++++++----- docs/00-ai-start-here.md | 15 +++++++- docs/05-coding-rules.md | 1 + docs/06-tasks.md | 5 +-- docs/README.md | 8 ++++- docs/adoption-checklist.md | 64 +++++++++++++++++++++++++++++++++++ docs/clean-state-checklist.md | 16 +++++++++ docs/current-state.md | 3 ++ docs/evaluator-rubric.md | 43 +++++++++++++++++++++++ docs/method-map.md | 31 +++++++++++++++++ docs/quality-document.md | 64 +++++++++++++++++++++++++++++++++++ init.ps1 | 51 ++++++++++++++++++++++++++++ init.sh | 52 ++++++++++++++++++++++++++++ tasks.md | 30 ++++++++++++++-- 14 files changed, 422 insertions(+), 14 deletions(-) create mode 100644 docs/adoption-checklist.md create mode 100644 docs/clean-state-checklist.md create mode 100644 docs/evaluator-rubric.md create mode 100644 docs/method-map.md create mode 100644 docs/quality-document.md create mode 100644 init.ps1 create mode 100644 init.sh diff --git a/README.md b/README.md index 430eafd..17872f1 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ | [`AGENTS.md`](AGENTS.md) | Codex / 通用 AI coding agent 的仓库级入口 | | [`CLAUDE.md`](CLAUDE.md) | Claude Code 的仓库级薄入口 | | [`tasks.md`](tasks.md) | 本样本库自身的维护任务列表 | +| [`init.sh`](init.sh) | 标准启动与验证入口脚本（Unix shell / WSL / Git Bash），统一安装 + 验证 + 打印启动命令 | +| [`init.ps1`](init.ps1) | 标准启动与验证入口脚本（Windows 原生 PowerShell），与 `init.sh` 等价，按操作系统二选一 | | [`progress.md`](progress.md) | 复制到新项目后的执行历史流水，记录任务执行、验证、阻塞和决策 | | [`docs/README.md`](docs/README.md) | 文档导航，总览所有项目文档 | | [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) | AI coding agent 的入口、阅读顺序、任务领取规则 | @@ -20,20 +22,55 @@ | [`docs/04-architecture.md`](docs/04-architecture.md) | 系统结构、职责边界、数据模型、开发顺序 | | [`docs/05-coding-rules.md`](docs/05-coding-rules.md) | AI 写代码前必须遵守的硬规则 | | [`docs/06-tasks.md`](docs/06-tasks.md) | 可逐步交付的任务看板 | +| [`docs/adoption-checklist.md`](docs/adoption-checklist.md) | 已有项目接入 harness 文档的迁移清单 | | [`docs/api.md`](docs/api.md) | API 合约模板 | | [`docs/routes.md`](docs/routes.md) | 页面路由、组件归属、导航规则 | +| [`docs/clean-state-checklist.md`](docs/clean-state-checklist.md) | 会话收尾检查清单，保证下一轮无需人工修复即可开工 | | [`docs/current-state.md`](docs/current-state.md) | 当前实现状态快照，防止计划和代码现实脱节 | +| [`docs/method-map.md`](docs/method-map.md) | 失败模式 → 首要修复 → 工件的诊断 / 导航对照表 | +| [`docs/evaluator-rubric.md`](docs/evaluator-rubric.md) | 单次会话输出的结构化评审评分表 | +| [`docs/quality-document.md`](docs/quality-document.md) | 代码库长期健康度追踪（产品域 × 架构层评级） | ## 使用方式 -1. 复制 `docs/`、`progress.md` 和需要的仓库级 agent 入口文件到新项目。 -2. 从 `01-vision.md` 和 `02-requirements.md` 开始替换业务内容。 -3. 在 `03-tech-stack.md` 固定技术选型，不确定的选项标为待定。 -4. 在 `04-architecture.md` 写清事实来源、数据模型、系统边界。 -5. 在 `06-tasks.md` 拆出小任务，要求 AI 每轮只领取一个任务。 -6. 用 `progress.md` 追加记录每轮执行历史，用 `current-state.md` 覆盖更新当前快照。 -7. 开始编码前，让 agent 先读 `00-ai-start-here.md`。 +### 最小必选集 + +只想先让 agent 稳定工作时，先复制这些文件： + +- `AGENTS.md` +- `CLAUDE.md` +- `docs/00-ai-start-here.md` +- `docs/05-coding-rules.md` +- `docs/06-tasks.md` +- `docs/current-state.md` +- `progress.md` +- `init.sh` 或 `init.ps1` + +### 完整推荐集 + +新项目从零开始时，建议复制根目录入口文件、`docs/` 目录、`progress.md`，并按操作系统选择 `init.sh` 或 `init.ps1`。复制后按顺序处理： + +1. 从 `docs/01-vision.md` 和 `docs/02-requirements.md` 开始替换业务内容。 +2. 在 `docs/03-tech-stack.md` 固定技术选型，不确定的选项标为待定。 +3. 在 `docs/04-architecture.md` 写清事实来源、数据模型、系统边界。 +4. 在 `docs/06-tasks.md` 拆出小任务，要求 AI 每轮只领取一个任务。 +5. 替换 `init.sh` 或 `init.ps1` 顶部三个命令，并把真实命令同步到 `docs/03-tech-stack.md`、`docs/00-ai-start-here.md` 和 `docs/current-state.md`。 +6. 用 `progress.md` 追加记录每轮执行历史，用 `docs/current-state.md` 覆盖更新当前快照。 +7. 开始编码前，让 agent 先读 `docs/00-ai-start-here.md`。 + +### 已有项目接入 + +已有代码仓库不要急着让 agent 做新功能。先按 [`docs/adoption-checklist.md`](docs/adoption-checklist.md) 建立当前状态、启动路径、验证路径和任务看板；第一轮任务优先修复基线，而不是扩大功能范围。 + +### 可选增强集 + +项目进入多轮长期开发后，再按需启用： + +- `docs/clean-state-checklist.md`：每轮结束前检查仓库是否可恢复。 +- `docs/method-map.md`：遇到失败模式时定位该补哪个工件。 +- `docs/evaluator-rubric.md`：评审单次 agent 输出质量。 +- `docs/quality-document.md`：追踪代码库长期健康度。 `tasks.md` 是本样本库自身的维护任务；复制到新项目后，项目任务默认写在 `docs/06-tasks.md`。如果新项目希望把任务看板放在根目录，可把 `docs/06-tasks.md` 复制或改名为根目录 `tasks.md`，并同步更新 `docs/README.md`、`docs/00-ai-start-here.md` 和 `docs/current-state.md` 中的链接。 -核心原则：文档不是给人看的装饰，而是给 agent 执行时用的约束、事实来源和验收标准。 +核心原则：文档不是给人看的装饰，而是给 agent 执行时用的约束、事实来源和验收标准。 \ No newline at end of file diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 81c0bf0..31eb6f0 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -23,6 +23,18 @@ 如果仓库根目录有 `AGENTS.md`、`CLAUDE.md` 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。 +## 固定开工流程 + +读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手： + +1. `pwd`：确认在正确的仓库根目录。 +2. 读 [`../progress.md`](../progress.md) 和 [`current-state.md`](current-state.md)：恢复已验证状态、下一步和当前 blocker。 +3. `git log --oneline -5`：看清最近发生了什么。 +4. 运行 `./init.sh`（Windows 原生 PowerShell 用 `./init.ps1`）：统一安装、验证、打印启动命令；如果脚本提示命令未替换，先配置脚本顶部三个命令。 +5. 跑一条基础 smoke / 端到端路径，确认基线没坏。 +6. **如果基线已坏，先修基线**，不要在坏的起点上叠新功能。 +7. 基线绿了，再从 [`06-tasks.md`](06-tasks.md) 领取唯一任务。 + ## 当前阶段 当前项目处于：【例如：MVP 起步 / 原型验证 / 功能开发 / 上线前收尾】。 @@ -44,6 +56,7 @@ - 本轮只完成这一个任务。 - 验收通过后把状态改为 `DONE`。 - 完成后把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md) 的当前快照。 +- 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)，确保下一轮无需人工修复即可开工。 - 做完即停，汇报验证结果，等待下一步指令。 如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。 @@ -108,7 +121,7 @@ MVP 不做： ## 验证命令 -把本项目真实命令填在这里： +统一启动与验证入口建议收敛到根目录 `./init.sh`（Windows 原生 PowerShell 用 `./init.ps1`，两者等价、按操作系统二选一），完成安装 + 基础验证 + 打印启动命令，避免每轮会话重新拼命令。脚本不绑定技术栈；复制到新项目后必须先替换脚本顶部三个命令变量，并把真实命令同步到 `03-tech-stack.md` 和 `current-state.md`。下面按场景把真实命令填全： ```bash # 示例 diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md index f8b8370..afbc7d8 100644 --- a/docs/05-coding-rules.md +++ b/docs/05-coding-rules.md @@ -56,6 +56,7 @@ - [ ] 对得上需求验收标准。 - [ ] 没有夹带无关改动。 - [ ] 涉及文档事实变化时，文档已同步。 +- [ ] 已在 `../progress.md` 记录跑过的命令和结果作为证据，不靠"代码已写"判定完成。 - [ ] 回复里如实说明跑了什么命令、结果如何。 把真实命令填在这里： diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 08aa5be..9134b28 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -8,8 +8,9 @@ 2. **做完即停**：完成该任务、自测通过、把状态改成 `DONE` 后，停下来汇报。 3. **不跳步**：依赖未完成的任务不能开工。 4. **完成定义**：以 [编码规则](05-coding-rules.md) 的验证清单为准。 -5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。 -6. **完成后**把任务状态同步到本文，把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md)。 +5. **passing 需证据**：标记 `DONE` 前，必须在 [`../progress.md`](../progress.md) 记录跑过的验证命令和结果作为证据；只有"代码已写"而没有可运行证据，不得标 `DONE`。验收要点要写成可执行、可观察的步骤，不写"应该能用"这类无法验证的描述。 +6. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。 +7. **完成后**把任务状态同步到本文，把执行记录追加到 [`../progress.md`](../progress.md)，覆盖更新 [`current-state.md`](current-state.md)，并过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)。 如新项目希望任务看板放在根目录，可把本文复制或改名为根目录 `tasks.md`，并同步更新 `README.md`、`docs/README.md`、`00-ai-start-here.md` 和 `current-state.md` 的链接。 diff --git a/docs/README.md b/docs/README.md index af569ab..746a670 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,9 +23,15 @@ - [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。 - [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。 - [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。 +- [已有项目接入清单](adoption-checklist.md)：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。 - [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。 - [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。 - [当前实现状态](current-state.md)：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。 +- [收尾检查清单](clean-state-checklist.md)：会话结束前逐项检查，保证下一轮无需人工修复即可继续。 +- [方法对照表](method-map.md)：失败模式 → 首要修复 → 工件；出问题先查这里对症补工件。 +- [评审评分表](evaluator-rubric.md)：单次会话输出的结构化评审（6 维 0-2 分 + 校准说明）。 +- [质量文档](quality-document.md)：代码库长期健康度追踪，区别于单次输出评审。 +- [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1)：标准启动与验证入口脚本（根目录），统一安装、验证和启动命令。按操作系统二选一：WSL / Git Bash / macOS / Linux 用 `init.sh`，Windows 原生 PowerShell 用 `init.ps1`；换技术栈只改脚本顶部三个命令变量；未替换前脚本会主动失败，避免把示例命令误当真实项目命令。 ## 任务 / 进度 / 当前状态 @@ -33,7 +39,7 @@ - `../progress.md` 维护执行进度：每轮实际做了什么、跑了什么验证、遇到什么阻塞、做了什么决策。 - `current-state.md` 维护当前快照：当前目录、当前可运行命令、已完成任务摘要和下一个可领取任务。 -如果新项目希望任务看板放在根目录，可把 `06-tasks.md` 复制或改名为根目录 `tasks.md`，并同步更新本文、`00-ai-start-here.md` 和 `current-state.md` 的链接。 +如果新项目希望任务看板放在根目录，可把 `06-tasks.md` 复制或改名为根目录 `tasks.md`，并同步更新本文、`00-ai-start-here.md` 和 `current-state.md` 的链接。已有项目接入时，先读 `adoption-checklist.md`，不要直接领取新功能。 ## 维护原则 diff --git a/docs/adoption-checklist.md b/docs/adoption-checklist.md new file mode 100644 index 0000000..c52b74e --- /dev/null +++ b/docs/adoption-checklist.md @@ -0,0 +1,64 @@ +# 已有项目接入清单 + +> 用于把本模板补进一个已经存在的项目。目标是先建立 agent 可读的事实来源，再继续开发新功能。 + +## 适用场景 + +- 项目已经有代码，但缺少清晰的 agent 入口、任务看板、当前状态和验证路径。 +- 项目被多轮 AI 修改过，文档、代码和真实可运行状态已经不一致。 +- 想从“靠聊天记录推进”切换到“靠仓库内工件推进”。 + +如果是全新空项目，优先按根目录 `README.md` 的“空项目接入”流程复制模板。 + +## 最小接入文件 + +先复制或建立这些文件： + +| 文件 | 作用 | +| --- | --- | +| `AGENTS.md` | 仓库级 agent 入口和总规则 | +| `CLAUDE.md` | Claude Code 薄入口，指向 `AGENTS.md` | +| `docs/00-ai-start-here.md` | 每轮开工流程 | +| `docs/05-coding-rules.md` | 编码纪律和验证底线 | +| `docs/06-tasks.md` | 任务看板 | +| `docs/current-state.md` | 当前实现状态快照 | +| `progress.md` | 只追加的执行流水 | +| `init.sh` 或 `init.ps1` | 标准启动与验证入口，按操作系统二选一 | + +推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`。 + +## 接入步骤 + +1. 确认仓库根目录，读取已有 `README`、运行脚本、测试配置和主要入口文件。 +2. 复制最小接入文件，并把所有 `【占位符】` 替换成当前项目事实。 +3. 在 `docs/current-state.md` 写清真实目录、真实启动命令、真实验证命令、当前 blocker。 +4. 在 `docs/03-tech-stack.md` 固定已经实际使用的技术栈，不确定项标为“待定”，不要让 agent 自行选择。 +5. 在 `docs/04-architecture.md` 记录当前代码的真实模块边界；不清楚的地方标为“待确认”。 +6. 在 `docs/06-tasks.md` 只放下一阶段能小步交付的任务，不要把历史愿望清单全部搬进去。 +7. 配置 `init.sh` 或 `init.ps1` 顶部三个命令，让它能安装依赖、运行基础验证、打印启动命令。 +8. 运行标准验证；如果失败，第一轮任务应先修基线，不做新功能。 +9. 把接入过程、验证结果和遗留 blocker 追加到 `progress.md`。 + +## 第一轮 agent 任务建议 + +已有项目接入后的第一轮，不建议直接做新功能。推荐任务是： + +| ID | 任务 | 验收要点 | +| --- | --- | --- | +| T-000 | 建立当前状态基线 | `current-state.md` 写清真实状态；`init` 脚本已配置；基础验证结果已记录到 `progress.md` | +| T-001 | 修复启动 / 验证基线 | 标准启动路径和标准验证路径可运行；失败原因已消除或记录为 blocker | +| T-002 | 对齐任务看板 | `06-tasks.md` 只保留可执行的小任务；第一个 TODO 依赖清楚、验收可观察 | + +## 代码现实与文档冲突时 + +- 以当前可运行代码和真实验证结果为事实起点。 +- 文档描述旧功能但代码不存在时，先把差异记录到 `current-state.md`，不要直接补实现。 +- 代码已有行为但文档没写时，先补 `02-requirements.md`、`04-architecture.md` 或 `api.md`，再继续修改代码。 +- 命令不可运行时，不要标记任务完成；在 `progress.md` 记录失败命令和错误摘要。 + +## 不建议做的事 + +- 不要一次性把所有模板都填满；先让入口、当前状态、任务和验证路径可用。 +- 不要把聊天记录当事实来源。 +- 不要为了让验证通过而降低测试或验收标准。 +- 不要在接入 harness 的同一轮顺手重构业务代码，除非是修复启动或验证基线所必需。 \ No newline at end of file diff --git a/docs/clean-state-checklist.md b/docs/clean-state-checklist.md new file mode 100644 index 0000000..4a62421 --- /dev/null +++ b/docs/clean-state-checklist.md @@ -0,0 +1,16 @@ +# 干净收尾检查清单 + +> 每轮会话结束前逐项过一遍，确保仓库处于"下一轮无需人工修复即可直接开工"的状态。 +> 这是把"提前宣告完成"挡在门外的最后一道关卡，配合 [`05-coding-rules.md`](05-coding-rules.md) 的验证清单使用。 + +收尾前确认： + +- [ ] 标准启动路径仍可用（`./init.sh` 或本项目等价命令能跑通）。 +- [ ] 标准验证 / smoke 仍可运行，结果如实。 +- [ ] 本轮执行记录已追加到 [`../progress.md`](../progress.md)（含跑过的命令和结果作为证据）。 +- [ ] [`06-tasks.md`](06-tasks.md) 任务状态真实反映 `DONE` 与未验证的边界，没有"假 DONE"。 +- [ ] [`current-state.md`](current-state.md) 已覆盖更新到当前快照（目录、命令、下一步、blocker）。 +- [ ] 没有半成品改动处于未记录状态；如有，已写明 `BLOCKED` / `PARTIAL` 和原因。 +- [ ] 代码处于可安全恢复的状态（必要时已提交，提交信息清晰）。 + +任意一项不满足，就先补到满足，再结束会话。 diff --git a/docs/current-state.md b/docs/current-state.md index 88a228d..93d7c11 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -17,6 +17,9 @@ - 生产代码：【入口文件和关键目录】 - 测试：【已有测试与命令】 - 数据：【已有数据源或 seed 文件】 +- 标准启动路径：【`./init.sh` 或本项目把应用跑起来的命令】 +- 标准验证路径：【跑 smoke / 基础测试的命令】 +- 当前 blocker：【如有，写明卡在哪里、需要谁决策；没有写"无"】 ## 当前目录要点 diff --git a/docs/evaluator-rubric.md b/docs/evaluator-rubric.md new file mode 100644 index 0000000..e46d263 --- /dev/null +++ b/docs/evaluator-rubric.md @@ -0,0 +1,43 @@ +# 评审评分表 + +> 在一轮（或几轮）会话实现完成后、正式验收前，用这张表做一次结构化评审，回答"这轮 agent 做得好不好"。 +> 它评的是**单次输出质量**；代码库长期健康度见 [`quality-document.md`](quality-document.md)。 + +## 评分维度 + +六个维度，每个 0-2 分（0 不满足 · 1 部分满足 · 2 满足）。 + +| 维度 | 问题 | 分数 (0-2) | 备注 | +| --- | --- | --- | --- | +| 正确性 | 实现出来的行为是否符合目标功能 / 验收标准？ | | | +| 验证 | 要求的检查是否真的跑过，并在 `../progress.md` 留下证据？ | | | +| 范围纪律 | 这一轮是否基本保持在选定的单个任务范围内？ | | | +| 可靠性 | 结果是否能在重启或重跑后继续工作？ | | | +| 可维护性 | 代码和文档是否清楚到足以交给下一轮会话？ | | | +| 交接准备度 | 新会话是否能只靠仓库内文件继续推进？ | | | + +## 结论 + +从下面三选一： + +- **Accept** — 达标，可验收。 +- **Revise** — 需要修补才能接受（列出必须补的修复）。 +- **Block** — 有根本性问题，需要先解决（列出阻塞项）。 + +## 后续动作 + +- 缺失的证据： +- 必须补的修复： +- 下次复审触发条件： + +## 关于校准（重要） + +开箱即用的 agent 做评审很弱——它会发现问题，然后把自己说服到通过。所以这张表的通过/失败标准需要反复校准到和人工判断一致： + +1. 用本表给一个已完成的任务打分。 +2. 把它的分数和你自己的人工判断对比。 +3. 有分歧的地方，把对应维度的"什么算 2 分 / 什么算 0 分"写得更具体，落到本项目的真实验收标准上。 +4. 对同一个输出重新打分，看是否对齐。 +5. 重复直到评审判断和人工评审基本一致。 + +预计需要 3-5 轮校准。每轮在 `../progress.md` 记录改了什么、为什么改。 diff --git a/docs/method-map.md b/docs/method-map.md new file mode 100644 index 0000000..f2de077 --- /dev/null +++ b/docs/method-map.md @@ -0,0 +1,31 @@ +# 方法对照表 + +> 把最常见的长时 coding-agent 失败模式，对应到本仓库里最该先补的工件或规则。 +> 出问题时先查这张表，对症补对应工件，不要把更多规则一股脑堆进一个超长入口文件。 + +## 失败模式 → 首要修复 → 工件 + +| 失败模式 | 实际表现 | 首要修复 | 主要工件 | +| --- | --- | --- | --- | +| 新会话摸黑 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | [`current-state.md`](current-state.md) + [`../progress.md`](../progress.md) | +| 启动脆弱 | 每轮会话都要重新学怎么启动、装依赖、跑测试 | 统一启动与验证路径 | [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1) | +| 范围蔓延 | 一次启动多个任务，最后没有一个完整收尾 | 限制当前活跃范围，一轮只做一个任务 | [`06-tasks.md`](06-tasks.md) | +| 提前宣布完成 | 代码改了就说"完成了"，但没有可运行证据 | 把完成绑定到验证证据 | [`06-tasks.md`](06-tasks.md)（passing 需证据）+ [`clean-state-checklist.md`](clean-state-checklist.md) | +| 交接薄弱 | 下一轮看不出哪里可用、哪里坏了、接下来做什么 | 每轮留下明确的当前快照和下一步 | [`current-state.md`](current-state.md) | +| 评审主观 | 质量判断靠个人记忆和感觉，agent 容易自我说服通过 | 用固定维度做评分 | [`evaluator-rubric.md`](evaluator-rubric.md) | +| 代码库悄悄退化 | 速度上去了，但几轮会话后代码越来越难审、边界越来越糊 | 定期给代码库健康度打分 | [`quality-document.md`](quality-document.md) | +| 文档堆叠失控 | 入口文件越来越长，"每次失败加一句" | 渐进披露，入口保持薄 | [`00-ai-start-here.md`](00-ai-start-here.md) + 拆分到具体文档 | + +## 使用原则 + +- 优先补最能直接消除当前失败模式的那**一个**工件，不要一次铺开全部。 +- 工件之间用链接互相引用，让全新 agent 不问人也能从一个文件跳到相关规则。 +- 同一个事实只维护一份，避免多个文件互相打架。 +- 修复落地的同一轮会话里，就把对应工件更新掉。 + +## 评审 vs 健康度：两个不同的问题 + +- [`evaluator-rubric.md`](evaluator-rubric.md) 回答：**"这轮 agent 做得好不好？"**（单次输出质量） +- [`quality-document.md`](quality-document.md) 回答：**"这个项目在变强还是变弱？"**（代码库本身质量） + +两者配合：rubric 守住每轮交付，quality document 守住长期趋势。 diff --git a/docs/quality-document.md b/docs/quality-document.md new file mode 100644 index 0000000..691b354 --- /dev/null +++ b/docs/quality-document.md @@ -0,0 +1,64 @@ +# 质量文档 + +> 给项目的每个产品领域和架构层打分，跟踪代码库随时间是变强还是变弱，回答"这个项目在变强还是变弱"。 +> 它评的是**代码库本身的质量**；单次 agent 输出质量见 [`evaluator-rubric.md`](evaluator-rubric.md)。 + +## 使用时机 + +- **开始会话前**：读它，了解代码库当前哪里最弱，优先处理。 +- **会话结束后**：更新评级。 +- **长期**：对比不同时间点的快照，看哪些改动真正改善了代码库健康度。 +- 做基准对比、清理简化、或换新 agent / 新模型时，也更新一次。 + +## 评级标准 + +- **A**：验证全部通过，结构干净，agent 能读懂，测试稳定。 +- **B**：验证通过，基本干净，可读性或测试覆盖有少量缺口。 +- **C**：部分可用，有已知缺口，部分代码 agent 不容易理解。 +- **D**：不可用，或存在重大结构问题。 + +--- + +## 产品领域 + +> 把下面的占位领域换成本项目 `02-requirements.md` 里的真实功能域。 + +| 领域 | 评级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键缺口 | 上次更新 | +|------|------|---------|-------------|-----------|---------|---------| +| 【核心流程 1】 | - | - | - | - | - | - | +| 【核心流程 2】 | - | - | - | - | - | - | +| 【数据 / 持久化】 | - | - | - | - | - | - | +| 【账号 / 鉴权】 | - | - | - | - | - | - | + +## 架构层 + +> 把下面的占位层换成本项目 `04-architecture.md` 里的真实分层 / 模块边界。 + +| 层级 | 评级 | 边界执行 | Agent 可读性 | 关键缺口 | 上次更新 | +|------|------|---------|-------------|---------|---------| +| 【前端 / 客户端 / CLI】 | - | - | - | - | - | +| 【后端 API / 核心模块】 | - | - | - | - | - | +| 【数据 / 存储层】 | - | - | - | - | - | +| 【外部服务适配】 | - | - | - | - | - | + +## 变更历史 + +### YYYY-MM-DD + +- 变更内容： +- 提升： +- 下降： +- 新发现的缺口： +- 已关闭的缺口： + +--- + +## 进阶：验证 harness 是否可以简化 + +Harness 里的每个组件（规则、脚本、检查清单）都编码了一个假设——"模型做不到这件事"。模型变强后，这些假设可能过时。用本文档检查某个组件是否还有必要： + +1. 拍一份本文档快照。 +2. 移除一个 harness 组件。 +3. 跑一轮基准任务。 +4. 再拍一份快照。 +5. 对比——评级没降，说明那个组件多余，可以去掉；降了，就恢复。 diff --git a/init.ps1 b/init.ps1 new file mode 100644 index 0000000..dd73d88 --- /dev/null +++ b/init.ps1 @@ -0,0 +1,51 @@ +#!/usr/bin/env pwsh + +# 标准启动与验证入口（Windows PowerShell 版），与 init.sh 等价，二选一： +# - Windows 原生 PowerShell：用本文件 ./init.ps1 +# - WSL / Git Bash / macOS / Linux：用 ./init.sh +# 一条命令完成：依赖安装 -> 基础验证 -> 打印启动命令。 +# 复制到新项目后，必须先替换下面三个命令，让每轮会话用同一条路径启动，不靠记忆。 +# 本文件不绑定任何技术栈；换技术栈时只替换这三个命令，脚本结构不用动。 + +$ErrorActionPreference = "Stop" +Set-Location -Path $PSScriptRoot + +# 按你的项目实际情况替换这三个命令。未替换前脚本会主动失败。 +$InstallCmd = "__REPLACE_INSTALL_CMD__" # 依赖安装，如 uv sync / poetry install / npm install +$VerifyCmd = "__REPLACE_VERIFY_CMD__" # 基础验证 / smoke，如 python -m pytest / go test ./... +$StartCmd = "__REPLACE_START_CMD__" # 开发启动，如 uvicorn app:app --reload / npm run dev + +function Assert-Configured { + param( + [string]$Name, + [string]$Value + ) + + if ($Value -like "__REPLACE_*") { + Write-Error "请先在 init.ps1 中替换 $Name。同步更新 docs/03-tech-stack.md、docs/00-ai-start-here.md 和 docs/current-state.md 中的命令。" + exit 2 + } +} + +Assert-Configured -Name "InstallCmd" -Value $InstallCmd +Assert-Configured -Name "VerifyCmd" -Value $VerifyCmd +Assert-Configured -Name "StartCmd" -Value $StartCmd + +Write-Host "==> 当前目录: $($PWD.Path)" + +Write-Host "==> 同步依赖" +Invoke-Expression $InstallCmd + +Write-Host "==> 运行基础验证" +Invoke-Expression $VerifyCmd + +Write-Host "==> 启动命令" +Write-Host " $StartCmd" + +if ($env:RUN_START_COMMAND -eq "1") { + Write-Host "==> 启动应用" + Invoke-Expression $StartCmd +} else { + Write-Host "如果希望 init.ps1 直接启动应用，请设置环境变量 RUN_START_COMMAND=1。" + Write-Host "如果基础验证失败，先修复基线状态，不要在坏的起点上继续叠新功能。" +} diff --git a/init.sh b/init.sh new file mode 100644 index 0000000..02a381d --- /dev/null +++ b/init.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash + +# 标准启动与验证入口（Unix shell 版），与 init.ps1 等价，二选一： +# - WSL / Git Bash / macOS / Linux：用本文件 ./init.sh +# - Windows 原生 PowerShell：用 ./init.ps1 +# 一条命令完成：依赖安装 -> 基础验证 -> 打印启动命令。 +# 复制到新项目后，必须先替换下面三个变量，让每轮会话用同一条路径启动，不靠记忆。 +# 本文件不绑定任何技术栈；换技术栈时只替换这三个变量，脚本结构不用动。 + +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +cd "$ROOT_DIR" + +# 按你的项目实际情况替换这三个命令。未替换前脚本会主动失败。 +INSTALL_CMD=(__REPLACE_INSTALL_CMD__) # 依赖安装，如 uv sync、poetry install、npm install +VERIFY_CMD=(__REPLACE_VERIFY_CMD__) # 基础验证 / smoke，如 python -m pytest、go test ./... +START_CMD=(__REPLACE_START_CMD__) # 开发启动，如 uvicorn app:app --reload、npm run dev + +ensure_configured() { + local name="$1" + local first="$2" + if [[ "$first" == __REPLACE_* ]]; then + echo "ERROR: 请先在 init.sh 中替换 ${name}。" + echo " 同步更新 docs/03-tech-stack.md、docs/00-ai-start-here.md 和 docs/current-state.md 中的命令。" + exit 2 + fi +} + +ensure_configured "INSTALL_CMD" "${INSTALL_CMD[0]}" +ensure_configured "VERIFY_CMD" "${VERIFY_CMD[0]}" +ensure_configured "START_CMD" "${START_CMD[0]}" + +echo "==> 当前目录: $PWD" + +echo "==> 同步依赖" +"${INSTALL_CMD[@]}" + +echo "==> 运行基础验证" +"${VERIFY_CMD[@]}" + +echo "==> 启动命令" +printf ' %q' "${START_CMD[@]}" +printf '\n' + +if [ "${RUN_START_COMMAND:-0}" = "1" ]; then + echo "==> 启动应用" + exec "${START_CMD[@]}" +fi + +echo "如果希望 init.sh 直接启动应用，请设置 RUN_START_COMMAND=1。" +echo "如果基础验证失败，先修复基线状态，不要在坏的起点上继续叠新功能。" diff --git a/tasks.md b/tasks.md index a03b961..60d0277 100644 --- a/tasks.md +++ b/tasks.md @@ -59,11 +59,37 @@ Get-ChildItem -Recurse -File | H-301 | 检查入口文件之间的职责是否重复 | H-005 | `AGENTS.md`、`CLAUDE.md`、`README.md`、`docs/README.md`、`docs/00-ai-start-here.md`、`progress.md` 各自职责清楚 | TODO | | H-302 | 检查所有模板是否保持通用占位符 | H-201, H-202, H-203 | 没有混入只适用于某个真实项目的业务事实 | TODO | | H-303 | 检查链接和文件名引用一致性 | H-301 | `rg` 搜索无旧名称、坏路径或冲突说明 | TODO | -| H-304 | 补充复制到新项目后的使用流程 | H-302 | README 和入口模板能指导用户从复制、替换占位符到开始编程 | TODO | +| H-304 | 补充复制到新项目后的使用流程 | H-302 | README 和入口模板能指导用户从复制、替换占位符到开始编程 | DONE | +| H-305 | 增加已有项目接入清单 `docs/adoption-checklist.md` | H-304 | 说明已有代码库如何补齐最小接入文件、建立当前状态、配置验证路径和规划第一轮任务 | DONE | + +## Phase 4 · Harness 执行可靠性层 + +> 参考 learn-harness-engineering（OpenAI / Anthropic harness 工程实践）补齐跨会话可靠性机制，保持纯 markdown + 脚本、不绑定技术栈。 + +| ID | 任务 | 依赖 | 验收要点 | 状态 | +| --- | --- | --- | --- | --- | +| H-401 | 增加标准启动入口 `init.sh` | H-106 | 根目录存在统一 install+verify+print-start 脚本；占位变量可替换；未替换时主动失败并提示同步文档命令 | DONE | +| H-406 | 增加 PowerShell 版入口 `init.ps1` 并说明按操作系统二选一 | H-401 | 根目录存在与 `init.sh` 等价的 PowerShell 脚本；脚本头和文档说明二选一、换技术栈只改三个命令变量；导航已登记 | DONE | +| H-402 | 增加干净收尾检查清单 `docs/clean-state-checklist.md` | H-203 | 会话结束前可逐项确认下一轮无需人工修复即可开工 | DONE | +| H-403 | 在 `06-tasks.md`/`05-coding-rules.md` 引入“证据绑定完成” | H-107, H-108 | passing 需在 `progress.md` 记录可运行证据，禁止“代码已写即 DONE” | DONE | +| H-404 | 在 `00-ai-start-here.md` 加固定开工/收尾流程 | H-102 | 含 pwd→读状态→git log→init.sh→smoke 基线→坏先修→领任务，收尾链接检查清单 | DONE | +| H-405 | 在 `current-state.md` 加启动/验证路径和 blocker 字段 | H-203 | 快照含标准启动路径、标准验证路径、当前 blocker | DONE | + +## Phase 5 · Harness 评审与健康度层（Tier 2） + +> 补齐"评审单次输出"和"追踪代码库长期健康度"两套机制，保持通用占位符、不绑定技术栈。 + +| ID | 任务 | 依赖 | 验收要点 | 状态 | +| --- | --- | --- | --- | --- | +| H-501 | 增加方法对照表 `docs/method-map.md` | H-401, H-402, H-403 | 失败模式 → 首要修复 → 工件，链接到本仓库真实工件，作为诊断 / 导航入口 | DONE | +| H-502 | 增加评审评分表 `docs/evaluator-rubric.md` | H-403 | 6 维 0-2 分 + Accept/Revise/Block 结论 + 校准说明 | DONE | +| H-503 | 增加质量文档 `docs/quality-document.md` | H-106 | 产品域 × 架构层 A-D 评级 + 变更历史，区别于单次输出评审 | DONE | ## Backlog +- 【Tier 3】增加初始化阶段 playbook：第一轮会话产出基线工件 + 第一个 clean commit。 +- 【Tier 3】给 `04-architecture.md` 补可选分层领域架构小节（Types→Config→Repo→Service→Runtime→UI）。 +- 【Tier 3】增加可观测性 / UI 验证闭环 SOP（query→reason→implement→restart→rerun→verify）。 - 增加“从空项目初始化文档”的操作清单。 -- 增加“已有项目补齐 harness coding 文档”的迁移清单。 - 增加“任务拆分质量检查表”。 - 增加“文档与代码现实不一致时的处理流程”。