mcpField
A
agent-harness

agent-harness

github.com/netresearchAgent 工作流635 次安装1 天前更新
代码仓库

关于 agent-harness

agent-harness 是用于让代码仓库适配 Agent 协作的技能，通过验证、初始化和成熟度审计建立项目级约束。适合希望由 CI、钩子和约定持续检查仓库结构的团队。

主要功能

  1. 01验证仓库引用、文件与命令配置
  2. 02按模板初始化缺失文件
  3. 03审计并报告成熟度等级
  4. 04运行已声明的技能检查点

适用场景

  1. 01检查仓库是否满足 harness 约定
  2. 02为仓库补充基础架构文档与 CI
  3. 03评估项目达到下一成熟度等级的差距

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/netresearch/agent-harness-skill --skill agent-harness

安装后在 Claude Code 中输入/agent-harness确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

checkpoints.yaml
references/
agent-first-architecture.md
enforcement-mechanisms.md
harness-engineering-overview.md
maturity-levels.md
skill-integration-map.md
references/adr/
001-verify-first-design.md
002-enforcement-layers.md
003-skill-delegation-model.md
004-agents-md-as-index.md
005-checkpoint-maturity-model.md
scripts/
run-shipped-checkpoints.sh
verify-harness.sh
templates/
AGENTS.md.tmpl
ARCHITECTURE.md.tmpl
envrc.tmpl
exec-plan.md.tmpl
forgejo-harness-checkpoints.yml.tmpl
forgejo-harness-verify.yml.tmpl
gitlab-ci-harness-checkpoints.yml.tmpl
gitlab-ci-harness-verify.yml.tmpl
harness-checkpoints.yml.tmpl
harness-verify.yml.tmpl
Makefile.harness.tmpl
merge_request_template.md.tmpl
pull_request_template.md.tmpl

详细介绍

Agent Harness

Agent Harness 通过自我维持的强制机制，让代码仓库为 Agent 做好准备。此技能负责安装它；随后由 CI、钩子和约定来强制执行。

模式

1. 验证（主要模式）

始终从这里开始。在目标代码仓库根目录中运行：

${CLAUDE_SKILL_DIR}/scripts/verify-harness.sh

分析输出并修复问题或提出修复建议。验证会检查失效引用、行数、缺失的产物，以及命令与目标是否一致。

2. 引导设置

缺少产物时，请根据模板创建：

产物模板平台
AGENTS.mdtemplates/AGENTS.md.tmpl全部
docs/ARCHITECTURE.mdtemplates/ARCHITECTURE.md.tmpl全部
docs/exec-plans/{active,completed}/创建目录全部
.github/workflows/harness-verify.ymltemplates/harness-verify.yml.tmplGitHub
.gitlab-ci.yml（harness-verify 作业）templates/gitlab-ci-harness-verify.yml.tmplGitLab
.forgejo/workflows/harness-verify.ymltemplates/forgejo-harness-verify.yml.tmplForgejo/Gitea
.github/workflows/harness-checkpoints.ymltemplates/harness-checkpoints.yml.tmplGitHub
.gitlab-ci.yml（harness-checkpoints 作业）templates/gitlab-ci-harness-checkpoints.yml.tmplGitLab
.forgejo/workflows/harness-checkpoints.ymltemplates/forgejo-harness-checkpoints.yml.tmplForgejo/Gitea
.github/pull_request_template.mdtemplates/pull_request_template.md.tmplGitHub
.gitlab/merge_request_templates/Default.mdtemplates/merge_request_template.md.tmplGitLab
.forgejo/pull_request_template.mdtemplates/pull_request_template.md.tmplForgejo/Gitea
.envrctemplates/envrc.tmpl全部
Makefile harness 目标templates/Makefile.harness.tmpl全部
scripts/verify-harness.sh${CLAUDE_SKILL_DIR}/scripts/verify-harness.sh（直接复制）全部
.harness/checkpoints.yml参见 references/enforcement-mechanisms.md § 12全部

填入代码仓库专属的值；未经确认，绝不覆盖现有文件。

3. 审计

报告代码仓库的成熟度级别（1、2 或 3），并说明达到下一级别所需的工作。详细标准请参见 references/maturity-levels.md。

运行技能附带的检查

只有当 Agent 自行决定运行某项技能的验证器时，才会运行该验证器；在最明显适用的案例上进行六次试验测量，结果仅运行了一次（#61）。因此，代码仓库会在 .harness/checkpoints.yml 中声明适用于它的技能检查点，并固定其 ref；CI 作业会运行这些检查点：

${CLAUDE_SKILL_DIR}/scripts/run-shipped-checkpoints.sh

若检查点失败且严重性为 error，作业就会失败；其余检查点则会报告。如果声明无法解析，则退出码为 2，而不会悄然通过。verify-harness.sh 会在声明没有对应作业，或作业没有对应声明时报错。

核心原则

  • AGENTS.md 是索引，不是百科全书。 控制在 150 行以内。详细内容放在 docs/ 中。
  • 强制机制属于项目层面。 CI 工作流、git 钩子和分支保护负责强制执行 Agent Harness，而不是由此技能在运行时执行。
  • 先验证，再引导设置。 创建产物前始终先运行验证。此技能检查产物，不检查工具。
  • 委派专业工作。 技能路由（@agent-rules、@github-project、@enterprise-readiness、@retro）请参见 references/skill-integration-map.md。
  • 不负责学习。 会话回顾、结果审查和宪章审计均委派给 retro-skill。Agent Harness 会验证集成点是否存在（AH-22、AH-23），但不会在运行时调用 retro。

成熟度等级

等级 1 —— 基础： 存在 AGENTS.md，作为索引并记录命令。

等级 2 —— 已验证： CI 强制检查工具链完整性，AGENTS.md 中的引用均可解析，命令与 Makefile/脚本一致，存在 ARCHITECTURE.md。

等级 3 —— 已强制执行： 分支保护要求通过工具链 CI，git 钩子自动激活，PR 模板包含检查清单，推送时检测偏移。

完整说明请参见 references/maturity-levels.md。

参考资料

  • references/maturity-levels.md —— 成熟度标准与进阶路径
  • references/harness-engineering-overview.md —— 理论：四项功能、模式
  • references/agent-first-architecture.md —— 可读性、分层依赖、Agent 优先的技术
  • references/enforcement-mechanisms.md —— 12 种机制表（CI、钩子、保护、偏移、随附检查点）
  • references/skill-integration-map.md —— 技能路由图 + 与配套技能的集成契约

评论

支持 Markdown