AGENTS.md

项目概览

本项目是 harness-workflow agent workflow skills 仓库，把 Learn Harness Engineering 的方法落成一组可执行 workflow skills；安装面以 skills.sh 为主（一条命令多端可选：选择目标 agent 与要装的技能），Claude Code 另有托管插件路径，未列入 skills.sh 的 CLI 手动拷贝。核心目标是让 agent 工作具备项目入口、状态协议、验证闸门、恢复路径和收尾纪律。

项目地图

• .claude-plugin/: Claude Code plugin manifest 和 marketplace catalog（source 指向仓库根）。
• .harness/: 恢复面合同 v2：index.md（轨道索引）、tracks/<id>.md（每轨道一份状态）、lessons.md。
• hooks/: 插件级 Claude Code hook——harness_guard.py 拦截已迁移项目里写入 .harness/ 清单外路径的操作。
• README.md / README.zh-CN.md: 用户入口，说明安装（skills.sh 多端可选）、workflow 分层、使用场景和验证命令。
• CONTEXT.md: 术语和边界澄清。
• docs/harness-method-contract.md: Harness Method Contract，解释 C1-C10 稳定方法论。
• docs/install.md: 统一安装指南（skills.sh、Claude Code 插件路径、Grok/ZCode/Kimi 手动拷贝）。
• docs/skills.md / docs/skills.zh-CN.md: 双语技能详解指南，面向第三方用户的逐技能通俗导读（协议权威仍在 skills/*/SKILL.md）。
• docs/specs/: brainstorm 默认 Spec 产物目录，允许多份独立 Spec（目录按需重建）。
• docs/plans/: plan 默认 Executable Plan 产物目录，允许多份独立计划和恢复记录（目录按需重建）。
• docs/adr/: 架构决策记录目录（目录按需重建）。
• docs/research/、docs/reviews/: 调研日志与审查报告的默认落点（目录按需重建）。
• docs/out-of-scope/: 不做清单——每个被拒想法一个文件（拒绝内容/理由/替代做法/来源），含改动门槛说明。
• .github/workflows/ci.yml: GitHub Actions，运行结构检查、README 资产检查、Claude 插件可选校验与 harness-builder 脚本测试。
• scripts/check-plugin.mjs: 仓库结构与安装面一致性的快速验证脚本。
• scripts/agent/check.sh: agent-facing 快速验证入口，串联默认结构检查。
• skills/*/SKILL.md: 每个 active workflow skill 的主入口和执行协议。
• skills/*/references/: 按需读取的细节政策、检查表和参考资料。
• skills/*/templates/: skill 使用或 backend 生成时复用的模板。

快速开始

• 快速验证：node scripts/check-plugin.mjs
• Agent 快速验证：bash scripts/agent/check.sh
• Skill 脚本测试：python3 -B skills/harness-builder/tests/test_scripts.py、python3 -B skills/harness-builder/tests/test_harness_lint.py、python3 -B hooks/test_harness_guard.py（skills-en/ 各有一份同名测试）
• 恢复面检查：python3 skills/harness-builder/scripts/harness_lint.py .
• Windows 上 python3 可能是应用商店占位程序（退出码 49），改用 python。
• 当前没有 package install 或测试框架配置；不要虚构 npm test、npm install 或不存在的 agent 脚本。

项目铁律

• 这是 skills 仓库；安装面以 skills.sh 为主、Claude Code 插件为辅；所有改动必须保持 README.md（含 zh-CN）、docs/install.md、docs/skills.md（含 zh-CN）、.claude-plugin/、docs/harness-method-contract.md 和 skills/*/SKILL.md 之间语义一致；docs/ 顶层只放面向第三方用户的文档，内部任务产物在关轨道时删除，不留存（git 历史即归档）。
• Active workflow skills 只有 harness-builder、brainstorm、plan、implement、diagnose、review、ship、cleanup、autoresearch；verify 只是 review 的历史触发词别名，不再是独立 skill；autoresearch 是研究循环编排总控（同 ship 只编排底层阶段，自带授权边界与预算规则，研究日志为保留交付物）；find-skills、writing-for-agents 是辅助 skill，不是额外 workflow lane；tdd 是被 implement 驱动的纪律 skill；工具 skill 四个：remove-deadcode-py（按需全仓 Python 死代码清理）、sweep（按需全仓对账）由 cleanup 路由或显式触发，research（轻量单发调研：后台跑腿、一手来源、产物自登记落 docs/research/）、handoff（会话交接：压缩当前会话给下一个 agent，有恢复面时只改本轨道 tracks 文件）显式触发；四个工具 skill 均不做任务收尾。
• AGENTS.md 只做薄入口（T1）；临时计划、会话摘要、active slice 和当前任务 plan/Spec 路径不要写进这里。
• 本插件仓库使用 .harness/；生成到目标项目时按所选 backend 复用恢复入口，不强制迁移已有系统。
• harness-builder 是 canonical 项目 harness skill；"bootstrap" 只能作为历史别名或触发词出现。
• 每个 SKILL.md 必须保留 YAML frontmatter，并让 name 与目录名匹配。
• 没有 fresh verification，不声明插件结构、流程图或方法论覆盖已经可用。
• 修改 skill 行为须附观察到的失败（真实会话里跑了什么、技能做了什么、期望什么）；借鉴上游或纸面推演的改动在 commit/state 标注「未首跑」并写首跑观察点，首跑后回填。被拒想法落 docs/out-of-scope/，提议前先查。
• 关键里程碑必须使用 Git commit，commit 信息使用中文，清晰简洁。

恢复面（Recovery surface）

本仓库按恢复面合同 v2 使用 .harness/，权威描述见 skills/writing-for-agents/references/recovery_surface_policy.md。

会话入口按顺序读：本文件 → .harness/lessons.md → .harness/index.md → 本会话推进的那条轨道的 tracks/<id>.md 与它的 Entry。

只在三个时刻写 .harness/：开轨道（plan 在 index 加一行、建 tracks 文件）、阶段变化或交接（只改本轨道 tracks 文件）、关轨道（cleanup 在同一 commit 删行与 tracks 文件、经验进 lessons、删本轨道计划与 Spec）。过程证据写进计划文件、docs/research/ 或 git，不进 .harness/。格式由 skills/harness-builder/scripts/harness_lint.py 检查，node scripts/check-plugin.mjs 会调用它；插件的 hooks/harness_guard.py 拦截写入清单外的路径。

不要在 AGENTS.md 里写当前任务名或某个 plan/Spec 路径。架构级不可逆决策走 docs/adr/。

真相源优先级（Source-of-truth priority）

事实冲突按来源和适用性核对；新证据只能纠正过期事实，不能覆盖指令权限、用户目标或项目验收合同。

Required Reading By Task Type

• 修改 skill 行为：先读对应 skills/<skill>/SKILL.md，再按需读同目录 references/。
• 修改 harness builder：先读 skills/harness-builder/SKILL.md（总控 / Helper routing），再按需读 references/recommendation_matrix_policy.md、install_policy.md、decision_matrix.md。
• 修改 recovery surface 语义：读 skills/writing-for-agents/SKILL.md 与 skills/writing-for-agents/references/recovery_surface_policy.md。
• 修改验证、ready 或 evidence 规则：读 skills/review/SKILL.md 和 docs/harness-method-contract.md。
• 修改安装面、manifest 或能力声明：同步检查 .claude-plugin/、README.md/README.zh-CN.md、docs/install.md 和 scripts/check-plugin.mjs。

Protected Paths

• .claude-plugin/plugin.json 与 marketplace.json: 改 name、source 或 version 前必须确认影响面并跑验证。
• 用户级配置、全局 skills、MCP、hooks、外部 plugin marketplace：只有用户明确要求时才能修改。

验证

默认验证命令：

node scripts/check-plugin.mjs

在 Windows PowerShell 中运行命令时，若用户 profile 因 execution policy 报错但目标命令成功，要把 profile 报错作为环境噪声说明，不把它当成项目验证失败。

Definition of Done

• 改动范围能对应用户请求或当前 active slice（见 .harness/tracks/ 中本轨道文件）。
• 相关文档、manifest、脚本和生成物保持一致。
• 已运行最窄有意义验证，或明确说明无法验证的原因。
• git status 已检查，未混入无关改动。
• 关键里程碑已提交中文 commit。