Harness Bootstrap
将一个仓库改造为:任何新的 Agent 会话,在任何开发者的机器上,仅凭仓库本身就能回答五个问题:这是什么、如何组织、如何运行、如何验证、以及上次进行到哪了。然后让“完成”这件事由脚本决定,而不是 Agent。
此技能每个仓库只运行一次。它会安装一个团队提交的契约,以及一些生命周期技能(harness-start、harness-handoff、harness-cleanup、harness-evaluate),这些技能存放在仓库内部,这样每位团队成员在克隆时都能获得它们,无论他们使用什么编码 Agent。
此文件中的路径(scripts/、references/、assets/)是相对于包含此 SKILL.md 的目录而言的。该目录的位置取决于 Agent 以及技能的安装方式,因此请根据你加载此文件的位置来解析它;切勿假定固定路径,例如 ~/.claude/skills/。
如果你需要任何工件背后的原理(例如,向用户解释或适配到不寻常的仓库),请阅读 references/principles.md。
你正在安装的模型
| 层级 | 位置 | 是否提交? | 目的 |
|---|---|---|---|
| 入口文件 | CLAUDE.md 和/或 AGENTS.md | 是 | 简短地图:是什么、如何运行、如何验证、硬性规则、链接 |
| 文档 | docs/ARCHITECTURE.md、PRODUCT.md、RELIABILITY.md、docs/decisions/ | 是 | Agent 无法从代码推断出的知识 |
| 契约 | harness/(配置、规则、检查清单、评分标准、质量文档、模板、README) | 是 | 所有人的相同规则,仅通过 PR 修改 |
| 验证 | scripts/harness/ | 是 | init.sh、verify.sh、feature.py、check_architecture.py、cleanup-scan.sh |
| 生命周期 | .agents/skills/harness-*,并为读取其他文件夹的 Agent 创建镜像 | 是 | 开始、交接、清理、评估 |
| 适配器 | 每个 Agent 对应,例如 Claude Code 的 .claude/agents/、.claude/hooks/ | 是 | 可选附加功能:子 Agent、钩子 |
| 任务状态 | .harness/tasks/<TASK-ID>/ | 否 | 一个任务的特性列表、契约、进度、交接、运行日志 |
任务状态是本地的,因为它每个会话都会更改,并且属于某个人的分支。提交它会导致合并冲突,并让一个开发者的过期状态误导另一个开发者的 Agent。它是一个缓存:所有持久性内容在任务结束前都会提升为代码、测试、文档、PR 或问题跟踪器。harness/README.md 会向团队解释这一点。
工作流程
1. 确认目标
在用户指定的目录中运行 git rev-parse --show-toplevel。如果不是 Git 仓库,则停止并告知:工作树隔离和基础分支检查依赖于 Git。注意工作树是否脏了;建议在自己的分支上进行引导,以便作为单个 PR 进行审查。
2. 盘点已有内容
在写入之前先查看。查找并读取:
- 指令文件:
AGENTS.md、CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md、GEMINI.md、.cursorrules、.cursor/rules/、.github/copilot-instructions.md、.windsurfrules - 文档:
README*、docs/、ADR 文件夹、CONTRIBUTING* - 现有的工作框架组件:
feature_list.json、progress.md、init.sh、Makefile、harness/、scripts/harness/、.harness/ - Agent 配置和技能:
.agents/skills/、.claude/(settings.json、skills/、agents/、hooks/)、.devin/、.cursor/、.github/、.worktreeinclude .gitignore
已有内容优先。你扩展它;未经询问,绝不替换团队编写的文件。
3. 发现项目如何运行
遵循 references/discovery.md。目标是每个验证层都有一个经过验证的命令列表,每个命令都附有其发现位置(CI 配置是最强的证据,因为它是团队实际信任的)。还要识别代码的层或模块以及它们之间的依赖方向;这些将成为架构规则。
4. 仅询问缺失的部分
将你无法从仓库中回答的问题批量处理为一次结构化的问题调用(如果你的环境支持),否则为一条消息。典型的缺口:
- 你推断出的架构边界但不确信(“
ui/允许导入db/吗?”) - 端到端或冒烟命令(如果不存在)
- 基础分支和分支命名约定(如果未记录)
- 团队使用的编码 Agent(Claude Code、Codex、Cursor、Copilot、Devin、Pi 等)。这决定入口文件以及安装哪些 Agent 适配器。
- 如果团队使用 Claude Code:是否安装其钩子(推荐;它们在会话开始时显示任务状态,并在手动编辑任务状态发生前阻止该操作)
不要询问具有常规默认值的事情;选择一个并在最终报告中提及。
5. 复制脚手架
bash <此技能目录>/scripts/install.sh <仓库根目录> --agents <ID>
--agents 采用步骤4中团队的 Agent,以逗号分隔的 ID 形式,这些 ID 与 npx skills CLI 使用的相同(claude-code、codex、cursor、github-copilot、gemini-cli、opencode、pi、devin、windsurf、kiro-cli、...;--help 列出它们)。
脚本将 assets/project/ 复制到仓库中,包括 .agents/skills/ 中的生命周期技能,大多数 Agent 可以直接读取这些技能。对于读取其他文件夹的 Agent(claude-code、devin、windsurf、kiro-cli),它会添加指向这些技能的相对符号链接,对于在 assets/adapters/<id>/ 中有适配器的 Agent,它会复制适配器文件。当团队使用不支持符号链接的 Windows 签出时,传递 --copy 以进行复制而不是符号链接;init.sh 随后会报告发生漂移的复制件。该脚本从不覆盖现有路径,将脚本标记为可执行,并按路径打印 CREATED / LINKED / SKIPPED。如果仓库已有工作框架组件,请先使用 --dry-run。对于每个 SKIPPED 的路径,读取现有文件并手动将缺失的想法合并到其中,而不是强制使用模板。
如果脚本报告 FAILED 路径,你的 Agent 沙盒可能保护了例如 .agents/ 或 .claude/ 之类的文件夹(Codex 默认对 .agents/ 这样做)。使用你的环境提供的权限重新运行相同的命令,或要求用户运行它。切勿将技能重新定位到其他文件夹以绕过此限制:Agent 仅在他们读取的文件夹中发现技能,因此重新定位的技能会静默停止工作。
6. 填充项目特有内容
脚手架无法知道的所有内容都由你来编写,基于你在步骤2-4中读取的内容:
harness/config.sh:每层(设置、静态、测试、冒烟、端到端)一行一个命令,以及基础分支和堆栈的调试模式。仅当一层确实不存在时才保留为空;verify.sh会将空的要求层报告为 UNVERIFIED(未验证)而不是通过。切勿用另一层已运行的命令来填充一层(例如将集成测试作为“端到端”):每一层都必须添加其他层没有的证据。请参阅references/discovery.md。harness/architecture-rules.json:每个边界一条规则,遵循references/architecture-rules.md。每条规则都需要为 Agent 编写why和fix,因为错误消息就是反馈循环。- 文档:仅在仓库没有等效文档的地方创建
docs/ARCHITECTURE.md、docs/PRODUCT.md、docs/RELIABILITY.md,从assets/docs-skeletons/开始。根据你读取的代码编写,每份文档保持在约150行以内,并将任何你无法确认的内容标记为TODO(confirm): ...而不是猜测。如果等效文档存在于别处,链接到它们而不是重复。 - 决策记录:脚手架添加
docs/decisions/。如果仓库已在其他地方维护 ADR(doc/adr/、docs/adr/),则删除新文件夹,并将harness/README.md、交接和清理技能以及模板指向现有位置。 harness/quality-document.md:列出真实的模块,并给出诚实的初始评分,或者在没有证据的情况下给出unknown。切勿凭感觉评分。
7. 连接入口文件
将 assets/snippets/entry-section.md 中的节插入入口文件,靠近顶部或底部(模型对长文件的边缘记忆比中间更好)。保持入口文件作为一个路由器:如果它增长到超过约200行,则将细节移到 docs/ 并链接到它。
AGENTS.md 是规范的入口文件:大多数编码 Agent 直接读取它。其他 Agent 获得一个指向它的简单指针,而不是规则的第二个副本,这样文件就不会漂移分开。
| 情况 | 执行此操作 |
|---|---|
AGENTS.md 和 CLAUDE.md 都不存在 | 根据你学到的内容创建 AGENTS.md,并包含该节。 |
仅存在 AGENTS.md | 将该节添加到 AGENTS.md。 |
仅存在 CLAUDE.md,团队仅使用 Claude Code | 将该节添加到 CLAUDE.md。 |
仅存在 CLAUDE.md,团队还使用其他 Agent | 在移动前询问:建议将其内容移到 AGENTS.md,并在 CLAUDE.md 中保留 @AGENTS.md。如果团队拒绝,将该节添加到 CLAUDE.md,并创建包含该节和指向 CLAUDE.md 链接的 AGENTS.md。 |
| 两者都存在 | 将该节添加到 AGENTS.md,并确保 CLAUDE.md 使用 @AGENTS.md 导入它。 |
然后为团队使用的、默认不读取 AGENTS.md 的每个 Agent 添加指针:
| Agent | 指针 |
|---|---|
| Claude Code | CLAUDE.md 包含 @AGENTS.md。默认情况下,只有当不存在 CLAUDE.md 或 CLAUDE.local.md 时,Claude Code 才会读取 AGENTS.md,因此同时存在两者的仓库会静默丢弃 AGENTS.md(如果没有导入)。 |
| Gemini CLI | GEMINI.md 包含 @AGENTS.md,或在 .gemini/settings.json 中设置 "contextFileName": "AGENTS.md"。 |
任何在仓库中已有其规则文件的 Agent(.github/copilot-instructions.md、.cursor/rules/、.windsurfrules) | 在该文件中添加一行,说明读取储存规则的 AGENTS.md。 |
对于你不确定的 Agent,在其自己的文档中检查其当前行为,而不是猜测;Agent 会更改它们读取的文件。
8. 合并配置
.gitignore:追加assets/snippets/gitignore.txt中缺失的行。- 仅 Claude Code,
.claude/settings.json:合并assets/adapters/claude-code/settings-hooks.json中的钩子。读取现有文件,追加到现有的hooks.SessionStart/hooks.PreToolUse数组,而不是替换它们,并保持 JSON 有效。如果团队拒绝了钩子,则跳过此操作,并删除适配器复制的.claude/hooks/。工作框架不依赖于钩子:feature.py封印任务状态并在手动编辑后拒绝工作,而入口文件告诉每个 Agent 在会话开始时运行init.sh。 - 仅 Claude Code,
.worktreeinclude:如果项目需要被 gitignore 的文件(如.env)才能运行,请将它们列出,以便每个工作树 Claude Code 创建时都获得一份副本。对于普通的git worktree add,请在harness/README.md中提及这些文件,以便人们复制它们。
9. 一次性证明
运行 bash scripts/harness/init.sh 和 python3 scripts/harness/check_architecture.py 并报告真实结果。如果某些内容因项目本身(而非工作框架)而失败,请如实说明并将其保留为报告中的第一个条目;不要为了使其通过而放松规则或删除命令。然后执行 references/principles.md 中的新会话测试:仅使用文件回答五个问题,并修复你无法回答的任何问题。
10. 报告
简要告诉用户:
- 创建了什么、合并了什么、以及因为已存在而跳过了什么
- 每层的命令及其来源
- 每个
TODO(confirm)和你做出的每个假设 - 初始化/验证结果,包括失败项
- 如果此技能本身已安装到仓库中(
.agents/skills/harness-bootstrap/或其他 Agent 的技能文件夹,加上skills-lock.json),请说明:团队在引导后不需要它,可以删除或保留以便稍后重新运行。不要自行删除它。 - 下一步:在一个分支上审查并提交引导程序,然后使用
harness-start技能开始一个任务(在具有斜杠命令的 Agent 中,使用/harness-start <TASK-ID>)
除非用户要求,否则不要提交或推送。
调整脚手架的设计规则
- 优先使用项目现有的工具。如果仓库有一个包含
make check的Makefile,则将make check放入config.sh,而不是重新列出其组成部分。 - 保持运行时依赖为
bash、git和python3(仅标准库)。不要为项目的工作框架添加包。 - 任何工作框架脚本的错误消息都应说明失败原因、原因以及如何修复。
- 脚本中不包含破坏性操作。清理仅报告;人类或 Agent 根据报告采取行动。
- 在可能的情况下使工作框架更小。一个在此仓库上不改变 Agent 行为的组件是多余的;请说明这一点,而不是为了完整性而安装它。