Files

T

ilaandClaude Fable 5 d98bfb7531 Repo hygiene: fix .gitignore, normalize line endings, correct repo paths

- Replace misspelled/ineffective ignore file with a real .gitignore:
  deploy/ (contains SSH private key), *.pem, .env*, and Python/Django/
  Wagtail runtime artifacts are now excluded from version control
- Add .gitattributes (* text=auto eol=lf) to stop CRLF/LF churn that
  made all 26 tracked files show spurious full-file diffs
- Correct repo root path /mnt/d/OPC/skelet -> /mnt/d/opc_project/skelet
  in AGENTS.md, 00-ai-start-here, 03-tech-stack, 90-harness-reference,
  current-state (progress.md history left as-is, append-only)
- Update current-state.md snapshot and append maintenance record to
  progress.md per harness rules

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-06 15:56:00 +08:00

7.2 KiB

Raw Blame History

Harness 参考（方法对照 · 评审 · 健康度 · 接入清单）

本文合并原 method-map.md、evaluator-rubric.md、quality-document.md、adoption-checklist.md 四个元文档，移出每轮必读链路。日常开工只需 ../AGENTS.md → 00-ai-start-here.md。出现失败模式、做阶段性评审或接入已有代码库时再查本文。

一、失败模式 → 首要修复

出问题时先查这张表，对症补对应工件，不要把更多规则一股脑堆进入口文件。

失败模式	实际表现	首要修复	主要工件
新会话摸黑	新会话花大量时间重新摸索状态和启动方式	让仓库成为唯一事实来源	`current-state.md` + `../progress.md`
启动脆弱	每轮会话都要重新学怎么启动、装依赖、跑测试	统一启动与验证路径	`../init.sh`
范围蔓延	一次启动多个任务，最后没有一个完整收尾	限制当前活跃范围，一轮只做一个任务	`06-tasks.md`
提前宣布完成	代码改了就说"完成了"，但没有可运行证据	把完成绑定到验证证据	`06-tasks.md` + `clean-state-checklist.md`
交接薄弱	下一轮看不出哪里可用、哪里坏了、接下来做什么	每轮留下明确的当前快照和下一步	`current-state.md`
评审主观	质量判断靠感觉，agent 容易自我说服通过	用固定维度做评分	本文第二节
代码库悄悄退化	几轮会话后代码越来越难审、边界越来越糊	定期给代码库健康度打分	本文第三节
文档堆叠失控	入口文件越来越长，"每次失败加一句"	渐进披露，入口保持薄；同一个事实只维护一份	`../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。

恢复步骤：

确认在仓库根目录（WSL 下为 /mnt/d/opc_project/skelet）。
读取 AGENTS.md、docs/00-ai-start-here.md、docs/current-state.md。
查看 docs/06-tasks.md，领取第一个 TODO 且依赖均为 DONE 的任务。
生产代码尚未初始化时先做 T-001，不要提前实现业务页面。
初始化 Wagtail 后，立刻更新 init.sh、docs/03-tech-stack.md、docs/current-state.md 中的真实命令。
运行标准验证，把结果追加到 progress.md；验证失败时先修基线，不做新功能。

代码现实与文档冲突时：

以当前可运行代码和真实验证结果为事实起点。
文档描述旧功能但代码不存在：先把差异记录到 current-state.md，不要直接补实现。
代码已有行为但文档没写：先补 02-requirements.md、04-architecture.md、api.md 或 routes.md，再改代码。
命令不可运行时不要标记任务完成；在 progress.md 记录失败命令和错误摘要。

不建议做的事：

不要一次性实现首页、模型、筛选、SEO 和部署。
不要把聊天记录当事实来源。
不要为了让验证通过而降低测试或验收标准。
不要在接入 harness 的同一轮顺手重构无关代码。

7.2 KiB Raw Blame History