113 lines
7.2 KiB
Markdown
113 lines
7.2 KiB
Markdown
# Harness 参考（方法对照 · 评审 · 健康度 · 接入清单）
|
|
|
|
> 本文合并原 `method-map.md`、`evaluator-rubric.md`、`quality-document.md`、`adoption-checklist.md` 四个元文档，移出每轮必读链路。
|
|
> 日常开工只需 [`../AGENTS.md`](../AGENTS.md) → [`00-ai-start-here.md`](00-ai-start-here.md)。出现失败模式、做阶段性评审或接入已有代码库时再查本文。
|
|
|
|
## 一、失败模式 → 首要修复
|
|
|
|
出问题时先查这张表，对症补对应工件，不要把更多规则一股脑堆进入口文件。
|
|
|
|
| 失败模式 | 实际表现 | 首要修复 | 主要工件 |
|
|
| --- | --- | --- | --- |
|
|
| 新会话摸黑 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | [`current-state.md`](current-state.md) + [`../progress.md`](../progress.md) |
|
|
| 启动脆弱 | 每轮会话都要重新学怎么启动、装依赖、跑测试 | 统一启动与验证路径 | [`../init.sh`](../init.sh) |
|
|
| 范围蔓延 | 一次启动多个任务，最后没有一个完整收尾 | 限制当前活跃范围，一轮只做一个任务 | [`06-tasks.md`](06-tasks.md) |
|
|
| 提前宣布完成 | 代码改了就说"完成了"，但没有可运行证据 | 把完成绑定到验证证据 | [`06-tasks.md`](06-tasks.md) + [`clean-state-checklist.md`](clean-state-checklist.md) |
|
|
| 交接薄弱 | 下一轮看不出哪里可用、哪里坏了、接下来做什么 | 每轮留下明确的当前快照和下一步 | [`current-state.md`](current-state.md) |
|
|
| 评审主观 | 质量判断靠感觉，agent 容易自我说服通过 | 用固定维度做评分 | 本文第二节 |
|
|
| 代码库悄悄退化 | 几轮会话后代码越来越难审、边界越来越糊 | 定期给代码库健康度打分 | 本文第三节 |
|
|
| 文档堆叠失控 | 入口文件越来越长，"每次失败加一句" | 渐进披露，入口保持薄；同一个事实只维护一份 | [`../AGENTS.md`](../AGENTS.md) + 拆分到具体文档 |
|
|
|
|
使用原则：
|
|
|
|
- 优先补最能直接消除当前失败模式的那**一个**工件，不要一次铺开全部。
|
|
- 同一个事实只维护一份，避免多个文件互相打架。
|
|
- 修复落地的同一轮会话里，就把对应工件更新掉。
|
|
|
|
## 二、单轮输出评审表
|
|
|
|
评的是**单次输出质量**；代码库长期健康度见第三节。六个维度，每个 0-2 分（0 不满足 · 1 部分满足 · 2 满足）。
|
|
|
|
| 维度 | 问题 | 分数 (0-2) | 备注 |
|
|
| --- | --- | --- | --- |
|
|
| 正确性 | 实现出来的行为是否符合目标功能 / 验收标准？ | | |
|
|
| 验证 | 要求的检查是否真的跑过，并在 `../progress.md` 留下证据？ | | |
|
|
| 范围纪律 | 这一轮是否基本保持在选定的单个任务范围内？ | | |
|
|
| 可靠性 | 结果是否能在重启或重跑后继续工作？ | | |
|
|
| 可维护性 | 代码和文档是否清楚到足以交给下一轮会话？ | | |
|
|
| 交接准备度 | 新会话是否能只靠仓库内文件继续推进？ | | |
|
|
|
|
结论三选一：**Accept**（达标）· **Revise**（列出必须补的修复）· **Block**（列出阻塞项）。
|
|
|
|
校准提示：agent 自评容易自我说服通过。前几次评审需要把每个维度"什么算 2 分 / 什么算 0 分"落到本项目的真实验收标准上，并在 `../progress.md` 记录校准调整，直到评审判断和人工判断基本一致。
|
|
|
|
## 三、代码库健康度追踪
|
|
|
|
- 开始会话前：读它，了解代码库当前哪里最弱。
|
|
- 会话结束后：如有实质变化则更新评级。
|
|
- 长期：对比不同时间点的快照，看哪些改动真正改善了健康度。
|
|
|
|
评级标准：**A** 验证全部通过、结构干净、测试稳定 · **B** 验证通过、有少量缺口 · **C** 部分可用、有已知缺口 · **D** 不可用或重大结构问题。
|
|
|
|
### 产品领域
|
|
|
|
| 领域 | 评级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键缺口 | 上次更新 |
|
|
|------|------|---------|-------------|-----------|---------|---------|
|
|
| Harness 文档 | B | 文档已初始化并完成瘦身合并 | 高 | 不适用 | 生产代码未初始化 | 2026-07-06 |
|
|
| 内容目录 MVP | D | 未实现 | 中 | 无测试 | Wagtail 项目未初始化 | 2026-07-06 |
|
|
| 筛选与搜索 | D | 未实现 | 中 | 无测试 | 依赖内容模型和列表页 | 2026-07-06 |
|
|
| 后台内容管理 | D | 未实现 | 中 | 无测试 | 依赖 Wagtail 初始化和模型 | 2026-07-06 |
|
|
| SEO 与部署 | D | 未实现 | 中 | 无测试 | 依赖前台页面和部署配置 | 2026-07-06 |
|
|
|
|
### 架构层
|
|
|
|
| 层级 | 评级 | 边界执行 | Agent 可读性 | 关键缺口 | 上次更新 |
|
|
|------|------|---------|-------------|---------|---------|
|
|
| Wagtail / Django 应用层 | D | 尚无代码 | 中 | 未初始化项目 | 2026-07-06 |
|
|
| 模板层 | D | 尚无代码 | 中 | 未建立 base 和页面模板 | 2026-07-06 |
|
|
| 数据 / 存储层 | D | 尚无代码 | 中 | SQLite、迁移和模型未建立 | 2026-07-06 |
|
|
| 部署层 | D | 尚无代码 | 中 | Gunicorn、Nginx、备份和 WAL 未配置 | 2026-07-06 |
|
|
|
|
### 变更历史
|
|
|
|
#### 2026-07-06（第二次）
|
|
|
|
- 变更内容：harness 文档瘦身。合并四个元文档为本文；统一入口为 `AGENTS.md`；修正 git 状态等过期事实；评分维度收敛到 `04-architecture.md` 唯一定义；开发环境定为 WSL/Linux。
|
|
- 提升：重复维护点减少，文档漂移风险下降。
|
|
- 下降：无。
|
|
|
|
#### 2026-07-06
|
|
|
|
- 变更内容：建立 harness coding 文档基线。
|
|
- 提升：项目目标、MVP 范围、技术栈、架构、任务顺序和当前状态已写入仓库。
|
|
- 新发现的缺口：生产代码尚未初始化，无法运行 Wagtail 验证。
|
|
|
|
## 四、已有代码接入 / 恢复清单
|
|
|
|
适用场景：已初始化 Wagtail 但下一轮 agent 不清楚真实启动命令；文档、代码和可运行状态出现偏差；把本项目 harness 文档迁移到其他代码库。
|
|
|
|
最小接入文件：`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`。
|
|
|
|
恢复步骤：
|
|
|
|
1. 确认在仓库根目录（WSL 下为 `/mnt/d/OPC/skelet`）。
|
|
2. 读取 `AGENTS.md`、`docs/00-ai-start-here.md`、`docs/current-state.md`。
|
|
3. 查看 `docs/06-tasks.md`，领取第一个 `TODO` 且依赖均为 `DONE` 的任务。
|
|
4. 生产代码尚未初始化时先做 `T-001`，不要提前实现业务页面。
|
|
5. 初始化 Wagtail 后，立刻更新 `init.sh`、`docs/03-tech-stack.md`、`docs/current-state.md` 中的真实命令。
|
|
6. 运行标准验证，把结果追加到 `progress.md`；验证失败时先修基线，不做新功能。
|
|
|
|
代码现实与文档冲突时：
|
|
|
|
- 以当前可运行代码和真实验证结果为事实起点。
|
|
- 文档描述旧功能但代码不存在：先把差异记录到 `current-state.md`，不要直接补实现。
|
|
- 代码已有行为但文档没写：先补 `02-requirements.md`、`04-architecture.md`、`api.md` 或 `routes.md`，再改代码。
|
|
- 命令不可运行时不要标记任务完成；在 `progress.md` 记录失败命令和错误摘要。
|
|
|
|
不建议做的事：
|
|
|
|
- 不要一次性实现首页、模型、筛选、SEO 和部署。
|
|
- 不要把聊天记录当事实来源。
|
|
- 不要为了让验证通过而降低测试或验收标准。
|
|
- 不要在接入 harness 的同一轮顺手重构无关代码。
|