Enhance harness template adoption workflow

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 执行时用的约束、事实来源和验收标准。

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
 # 示例

docs/05-coding-rules.md

@@ -56,6 +56,7 @@
 - [ ] 对得上需求验收标准。
 - [ ] 没有夹带无关改动。
 - [ ] 涉及文档事实变化时，文档已同步。
+- [ ] 已在 `../progress.md` 记录跑过的命令和结果作为证据，不靠"代码已写"判定完成。
 - [ ] 回复里如实说明跑了什么命令、结果如何。
 
 把真实命令填在这里：

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` 的链接。
 

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`，不要直接领取新功能。
 
 ## 维护原则
 

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 的同一轮顺手重构业务代码，除非是修复启动或验证基线所必需。

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` 和原因。
+- [ ] 代码处于可安全恢复的状态（必要时已提交，提交信息清晰）。
+
+任意一项不满足，就先补到满足，再结束会话。

docs/current-state.md

@@ -17,6 +17,9 @@
 - 生产代码：【入口文件和关键目录】
 - 测试：【已有测试与命令】
 - 数据：【已有数据源或 seed 文件】
+- 标准启动路径：【`./init.sh` 或本项目把应用跑起来的命令】
+- 标准验证路径：【跑 smoke / 基础测试的命令】
+- 当前 blocker：【如有，写明卡在哪里、需要谁决策；没有写"无"】
 
 ## 当前目录要点
 

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` 记录改了什么、为什么改。

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 守住长期趋势。

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. 对比——评级没降，说明那个组件多余，可以去掉；降了，就恢复。

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 "如果基础验证失败，先修复基线状态，不要在坏的起点上继续叠新功能。"
+}

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 "如果基础验证失败，先修复基线状态，不要在坏的起点上继续叠新功能。"

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 文档”的迁移清单。
 - 增加“任务拆分质量检查表”。
 - 增加“文档与代码现实不一致时的处理流程”。