Community编程与开发github.com

harness-bootstrap

在任何 Git 仓库中安装一套完整的、团队就绪的 Agent 工作框架:包含入口文件、架构文档、分层验证脚本、可执行的架构规则、任务特性列表、会话交接文件以及完整性检查。

harness-bootstrap 是什么?

Harness Bootstrap 是一个针对 AI 编码 Agent(如 Claude Code、Codex、Cursor、Copilot、Devin、Pi 等)的技能,用于将一个普通的 Git 仓库转变为“Agent 就绪”状态。它通过一次性安装一套契约文件(包括配置、规则、检查清单等)和生命周期脚本(启动、交接、清理、评估),确保任何新 Agent 会话都能从仓库本身回答五个核心问题:这是什么、如何组织、如何运行、如何验证、上次进行到哪。其核心价值在于解决 Agent 跨会话上下文丢失、虚假声明“完成”、以及团队成员间交接混乱等问题。工作流程包括:确认目标仓库、盘点已有文件、发现项目运行方式、询问缺失信息、复制脚手架、填充项目特有配置、连接入口文件、合并配置、进行一次性验证并报告结果。该技能支持多种 Agent 平台,并强调不覆盖已有文件,通过 PR 审查来维护团队约定。

兼容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode✓Windsurf
npx skills add https://github.com/Gabriel-Valin/harness-bootstrap/tree/HEAD

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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中读取的内容:

  1. harness/config.sh:每层(设置、静态、测试、冒烟、端到端)一行一个命令,以及基础分支和堆栈的调试模式。仅当一层确实不存在时才保留为空;verify.sh 会将空的要求层报告为 UNVERIFIED(未验证)而不是通过。切勿用另一层已运行的命令来填充一层(例如将集成测试作为“端到端”):每一层都必须添加其他层没有的证据。请参阅 references/discovery.md。
  2. harness/architecture-rules.json:每个边界一条规则,遵循 references/architecture-rules.md。每条规则都需要为 Agent 编写 why 和 fix,因为错误消息就是反馈循环。
  3. 文档:仅在仓库没有等效文档的地方创建 docs/ARCHITECTURE.md、docs/PRODUCT.md、docs/RELIABILITY.md,从 assets/docs-skeletons/ 开始。根据你读取的代码编写,每份文档保持在约150行以内,并将任何你无法确认的内容标记为 TODO(confirm): ... 而不是猜测。如果等效文档存在于别处,链接到它们而不是重复。
  4. 决策记录:脚手架添加 docs/decisions/。如果仓库已在其他地方维护 ADR(doc/adr/、docs/adr/),则删除新文件夹,并将 harness/README.md、交接和清理技能以及模板指向现有位置。
  5. 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 CodeCLAUDE.md 包含 @AGENTS.md。默认情况下,只有当不存在 CLAUDE.md 或 CLAUDE.local.md 时,Claude Code 才会读取 AGENTS.md,因此同时存在两者的仓库会静默丢弃 AGENTS.md(如果没有导入)。
Gemini CLIGEMINI.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 行为的组件是多余的;请说明这一点,而不是为了完整性而安装它。

相关技能