agent-harness

エージェントハーネス

エージェントハーネスは、継続的に自己維持される適用の仕組みによって、リポジトリをエージェント対応にします。このスキルがハーネスをインストールし、その後は CI、フック、規約によって適用されます。

モード

1. 検証（主なモード）

必ずここから始めます。対象リポジトリのルートから、次を実行します。

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

出力を分析し、修正するか、修正案を提示します。検証では、無効な参照、行数、欠落している成果物、コマンドとターゲットの整合性を確認します。

2. ブートストラップ

成果物が欠落している場合は、テンプレートから作成します。

成果物	テンプレート	プラットフォーム
AGENTS.md	templates/AGENTS.md.tmpl	すべて
docs/ARCHITECTURE.md	templates/ARCHITECTURE.md.tmpl	すべて
docs/exec-plans/{active,completed}/	ディレクトリを作成	すべて
.github/workflows/harness-verify.yml	templates/harness-verify.yml.tmpl	GitHub
.gitlab-ci.yml（harness-verify ジョブ）	templates/gitlab-ci-harness-verify.yml.tmpl	GitLab
.forgejo/workflows/harness-verify.yml	templates/forgejo-harness-verify.yml.tmpl	Forgejo/Gitea
.github/workflows/harness-checkpoints.yml	templates/harness-checkpoints.yml.tmpl	GitHub
.gitlab-ci.yml（harness-checkpoints ジョブ）	templates/gitlab-ci-harness-checkpoints.yml.tmpl	GitLab
.forgejo/workflows/harness-checkpoints.yml	templates/forgejo-harness-checkpoints.yml.tmpl	Forgejo/Gitea
.github/pull_request_template.md	templates/pull_request_template.md.tmpl	GitHub
.gitlab/merge_request_templates/Default.md	templates/merge_request_template.md.tmpl	GitLab
.forgejo/pull_request_template.md	templates/pull_request_template.md.tmpl	Forgejo/Gitea
.envrc	templates/envrc.tmpl	すべて
Makefile のハーネスターゲット	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 を参照してください。

スキルに付属するチェックの実行

スキル独自のバリデーターは、エージェントが実行すると判断した場合にのみ実行されます。最も明らかに関連性の高いケースで 6 回試行したところ、実行されたのは 1 回でした（#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 フック、ブランチ保護がハーネスを適用します。このスキルが実行時に適用するわけではありません。
• まず検証し、その後にブートストラップします。 成果物を作成する前に、必ず検証を実行します。このスキルが確認するのは成果物であり、ツールではありません。
• 専門的な作業は委任します。 スキルの振り分けについては、references/skill-integration-map.md（@agent-rules、@github-project、@enterprise-readiness、@retro）を参照してください。
• 学習は担当しません。 セッションの振り返り、結果のレビュー、原則に照らした監査は retro-skill に委任されます。ハーネスは統合ポイントが存在すること（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 -- 理論：4 つの機能とパターン
• references/agent-first-architecture.md -- 可読性、階層化された依存関係、エージェントファーストの技術
• references/enforcement-mechanisms.md -- 12 のメカニズムをまとめた表（CI、フック、保護、ドリフト、リリース済みチェックポイント）
• references/skill-integration-map.md -- スキルのルーティングマップと、関連スキルとの統合契約