Communityコーディング&開発github.com

harness-bootstrap

完全なチーム対応エージェントハーネスを任意のGitリポジトリにインストールします。エントリファイル(CLAUDE.md / AGENTS.md)、アーキテクチャと信頼性のドキュメント、段階的な検証スクリプト、実行可能なアーキテクチャルール、ステータスを検証者のみが変更できるタスクフィーチャーリスト、セッションハンドオフと進捗ファイル(ローカルに保持、gitignore対象)、クリーンステートチェックリスト、独立評価ツール、それらを強制する整合性チェックを含みます。Claude Code、Codex、Cursor、Copilot、Devin、Piなど、あらゆるコーディングエージェントで動作します。

harness-bootstrap とは?

harness-bootstrapスキルは、開発チームが使用するあらゆるAIコーディングエージェント(Claude Code、Codex、Cursor、Copilot、Devin、Piなど)と互換性のある、包括的なエージェントハーネスをリポジトリにインストールします。このスキルはリポジトリごとに一度だけ実行され、エントリファイル(AGENTS.md / CLAUDE.md)、アーキテクチャドキュメント、検証スクリプト、アーキテクチャルール、タスク状態管理、セッションハンドオフ、クリーンアップ、評価用のライフサイクルスキルを含む、**チーム全体で共有可能な契約**をセットアップします。ハーネスは、エージェントがセッション間でコンテキストを忘れたり、実際に動作確認が取れる前に「完了」と主張するのを防ぐように設計されています。これにより、「完了」はエージェントの主張ではなく、スクリプトによって決定されるものになります。タスク状態は`.harness/tasks/<TASK-ID>/`にローカルに保存され(gitignore)、コミット時のマージ競合や古い状態による誤解を防ぎます。

対応✓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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Harness Bootstrap

リポジトリを、どの開発者のマシンでも新しいエージェントセッションがリポジトリだけで5つの質問に答えられるようにします。すなわち、「これは何か」「どう構成されているか」「どう実行するか」「どう検証するか」「どこで止まったか」です。そして、「完了」をエージェントではなくスクリプトが決めるものにします。

このスキルはリポジトリごとに一度だけ実行されます。チームがコミットする契約と、リポジトリ内に置かれるライフサイクルスキル(harness-start、harness-handoff、harness-cleanup、harness-evaluate)をインストールします。これにより、すべてのチームメンバーが使用するコーディングエージェントの種類に関わらず、クローン時に同じスキルを取得できます。

このファイル内のパス(scripts/、references/、assets/)は、このSKILL.mdを含むディレクトリを基準とした相対パスです。そのディレクトリの場所はエージェントとスキルがインストールされた方法によって異なるため、このファイルを読み込んだ場所から解決してください。~/.claude/skills/のような固定パスを決して想定しないでください。

何らかのアーティファクトの背後にある理由(例えば、ユーザーに説明したり、特殊なリポジトリに適応させたりするため)が必要な場合は、references/principles.mdを参照してください。

インストールするモデル

レイヤ場所コミット?目的
エントリファイルCLAUDE.md および/または AGENTS.mdはい短いマップ:何か、実行方法、検証方法、厳格なルール、リンク
ドキュメントdocs/ARCHITECTURE.md、PRODUCT.md、RELIABILITY.md、docs/decisions/はいエージェントがコードから推測できない知識
契約harness/(設定、ルール、チェックリスト、ルーブリック、品質ドキュメント、テンプレート、README)はい全員に同じルール、PRによってのみ変更
検証scripts/harness/はいinit.sh、verify.sh、feature.py、check_architecture.py、cleanup-scan.sh
ライフサイクル.agents/skills/harness-*、別のフォルダを読み取るエージェント用にミラーリングはい開始、ハンドオフ、クリーンアップ、評価
アダプタエージェントごと(例:Claude Code用の.claude/agents/、.claude/hooks/)はいオプションの拡張:サブエージェント、フック
タスク状態.harness/tasks/<TASK-ID>/いいえフィーチャーリスト、契約、進捗、ハンドオフ、1つのタスクの実行ログ

タスク状態は、セッションごとに変化し、1人の担当者のブランチに属するため、ローカルに保持されます。コミットするとマージ競合が発生し、ある開発者の古い状態が別の開発者のエージェントを誤誘導する可能性があります。これはキャッシュであり、持続可能なものはすべて、タスクが終了する前にコード、テスト、ドキュメント、PR、または課題トラッカーに昇格されます。harness/README.mdがこれをチームに説明します。

ワークフロー

1. ターゲットを確認する

ユーザーが意図するディレクトリでgit rev-parse --show-toplevelを実行します。Gitリポジトリでない場合は停止してその旨を伝えます。ワークツリーの分離とベースブランチのチェックはGitに依存します。ワーキングツリーがダーティかどうかに注意し、ブートストラップを独自のブランチで行い、1つの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/
  • エージェント設定とスキル:.agents/skills/、.claude/(settings.json、skills/、agents/、hooks/)、.devin/、.cursor/、.github/、.worktreeinclude
  • .gitignore

既存の内容が優先されます。それを拡張します。チームが書いたファイルを許可なく置き換えることは決してしません。

3. プロジェクトの実行方法を発見する

references/discovery.mdに従います。目標は、各検証レイヤーのコマンドの検証済みリストです。各コマンドには、それを見つけた場所を記載します(CI設定が最も強力な証拠です。なぜなら、それがチームが実際に信頼しているものだからです)。また、コードのレイヤーまたはモジュールと、それらの間の依存関係の方向を特定します。これらがアーキテクチャルールになります。

4. ギャップについてのみ質問する

リポジトリから回答できなかった質問を、環境に構造化質問呼び出し機能があればそれにまとめ、なければ1つのメッセージにまとめます。典型的なギャップは次のとおりです。

  • 推測したが確信がないアーキテクチャの境界(「ui/はdb/をインポートできますか?」)
  • 存在しない場合のエンドツーエンドまたはスモークコマンド
  • 文書化されていない場合のベースブランチとブランチ命名規則
  • チームが使用するコーディングエージェント(Claude Code、Codex、Cursor、Copilot、Devin、Pi、その他)。これによってエントリファイルとインストールするエージェントアダプタが決まります。
  • チームがClaude Codeを使用する場合:フックをインストールするかどうか(推奨。セッション開始時にタスク状態を表示し、タスク状態の手動編集を事前にブロックします)

従来のデフォルトがあるものについては質問せず、選択して最終レポートで言及します。

5. スキャフォールドをコピーする

bash <このスキルのディレクトリ>/scripts/install.sh <リポジトリルート> --agents <ID>

--agentsには、ステップ4で特定したチームのエージェントをカンマ区切りのIDで指定します。npx skills CLIが使用するものと同じID(claude-code、codex、cursor、github-copilot、gemini-cli、opencode、pi、devin、windsurf、kiro-cli、...。--helpで一覧表示されます)です。

スクリプトはassets/project/をリポジトリにコピーします。これには、.agents/skills/内のライフサイクルスキルが含まれます。これはほとんどのエージェントが直接読み取ります。別のフォルダを読み取るエージェント(claude-code、devin、windsurf、kiro-cli)に対しては、それらのスキルへの相対的なシンボリックリンクを追加し、assets/adapters/<id>/にアダプタがあるエージェントに対してはアダプタファイルをコピーします。チームがシンボリックリンクをサポートしていないWindowsチェックアウトを持つ場合は、コピーに--copyを渡します。その場合、init.shは乖離したコピーを報告します。スクリプトは既存のパスを決して上書きせず、スクリプトを実行可能にマークし、パスごとにCREATED/LINKED/SKIPPEDを出力します。リポジトリに既にハーネス部品がある場合は、最初に--dry-runを使用してください。SKIPPEDされたパスごとに、既存のファイルを読み取り、不足しているアイデアをテンプレートを強制する代わりに手動でマージします。

スクリプトがFAILEDパスを報告した場合、エージェントのサンドボックスがおそらく.agents/や.claude/のようなフォルダを保護しています(Codexはデフォルトで.agents/に対してこれを行います)。環境が提供する権限を使用して同じコマンドを再実行するか、ユーザーに実行を依頼してください。回避策としてスキルを別のフォルダに移動しないでください。エージェントは読み取るフォルダ内のスキルしか発見しないため、移動されたスキルは静かに動作しなくなります。

6. プロジェクト固有の設定を記入する

スキャフォールドが知り得ないすべてのものは、あなたがステップ2〜4で読み取った内容に基づいて記述します。

  1. harness/config.sh:各レイヤー(セットアップ、静的、テスト、スモーク、E2E)ごとに1行ずつコマンド、ベースブランチ、スタックのデバッグパターンを指定します。レイヤーが本当に存在しない場合のみ空のままにします。verify.shは空の必須レイヤーを、合格ではなくUNVERIFIEDとして報告します。別のレイヤーが既に実行しているコマンドをレイヤーに決して入れないでください(例えば、統合テストを「e2e」として入れるなど)。すべてのレイヤーは、他のレイヤーが提供しない証拠を追加する必要があります。references/discovery.mdを参照してください。
  2. harness/architecture-rules.json:境界ごとに1つのルールを、references/architecture-rules.mdに従って記述します。すべてのルールには、エージェント向けにwhy(理由)とfix(修正方法)を記述する必要があります。エラーメッセージがフィードバックループとなるからです。
  3. ドキュメント:リポジトリに同等のものがない場合にのみ、assets/docs-skeletons/から始めてdocs/ARCHITECTURE.md、docs/PRODUCT.md、docs/RELIABILITY.mdを作成します。読み取ったコードから記述し、それぞれを約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が標準のエントリファイルです。ほとんどのコーディングエージェントはこれを直接読み取ります。他のエージェントは、ルールの2番目のコピーではなく、これへの薄いポインタを取得します。これにより、ファイルが乖離するのを防ぎます。

状況実行すること
AGENTS.mdもCLAUDE.mdも存在しない学習した内容からAGENTS.mdを作成し、セクションを追加します。
AGENTS.mdのみ存在するセクションをAGENTS.mdに追加します。
CLAUDE.mdのみ存在し、チームがClaude Codeのみを使用するセクションをCLAUDE.mdに追加します。
CLAUDE.mdのみ存在し、チームが他のエージェントも使用する移動する前に質問します。内容をAGENTS.mdに移動し、CLAUDE.mdには@AGENTS.mdを残すことを提案します。チームが拒否した場合は、セクションをCLAUDE.mdに追加し、セクションとCLAUDE.mdへのリンクを含むAGENTS.mdを作成します。
両方存在するセクションをAGENTS.mdに追加し、CLAUDE.mdが@AGENTS.mdでインポートしていることを確認します。

次に、デフォルトでAGENTS.mdを読み取らない各エージェントへのポインタを追加します。

エージェントポインタ
Claude Code@AGENTS.mdを含むCLAUDE.md。デフォルトでは、Claude CodeはCLAUDE.mdまたはCLAUDE.local.mdが存在しない場合にのみAGENTS.mdを読み取ります。そのため、両方があるリポジトリは、インポートなしで静かにAGENTS.mdをドロップします。
Gemini CLI@AGENTS.mdを含むGEMINI.md、または.gemini/settings.jsonの"contextFileName": "AGENTS.md"
リポジトリに独自のルールファイルが既にあるエージェント(.github/copilot-instructions.md、.cursor/rules/、.windsurfrules)そのファイルに、ルールを保持するAGENTS.mdを読むように指示する1行を追加します。

確信が持てないエージェントの現在の動作については、推測するのではなく、そのエージェントのドキュメントを確認してください。エージェントは読み取るファイルを変更することがあります。

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がタスク状態を封印し、手動編集後に動作を拒否し、エントリファイルがすべてのエージェントにセッション開始時にinit.shを実行するように指示します。
  • Claude Codeのみ、.worktreeinclude:プロジェクトの実行に.envなどのgitignoreされたファイルが必要な場合、それらをリストして、作成されるすべてのワークツリーClaude Codeがコピーを取得できるようにします。プレーンなgit worktree addの場合は、harness/README.mdでそれらのファイルに言及して、人々がコピーできるようにします。

9. 一度証明する

bash scripts/harness/init.shとpython3 scripts/harness/check_architecture.pyを実行し、実際の結果を報告します。何かがプロジェクト(ハーネスではなく)が原因で失敗した場合は、率直にその旨を述べ、レポートの最初のエントリとして残します。合格にするためにルールを緩めたり、コマンドを削除したりしないでください。次に、references/principles.mdの新しいセッションテストを実行します。ファイルのみを使用して5つの質問に答え、回答できないものがあれば修正します。

10. 報告する

ユーザーに簡潔に伝えます。

  • 何が作成され、何がマージされ、既に存在していたために何がスキップされたか
  • レイヤーごとのコマンドと、それぞれの出典
  • すべてのTODO(confirm)と、行ったすべての仮定
  • init/検証結果(失敗を含む)
  • このスキル自体がリポジトリにインストールされた場合(.agents/skills/harness-bootstrap/または別のエージェントのスキルフォルダ、さらにskills-lock.json)、その旨を伝えます。チームはブートストラップ後はこれを必要とせず、後で再実行するために削除または保持できます。自分で削除しないでください。
  • 次のステップ:ブランチ上でブートストラップをレビューしてコミットし、その後harness-startスキル(スラッシュコマンドを持つエージェントでは/harness-start <TASK-ID>)でタスクを開始します

ユーザーが依頼しない限り、コミットやプッシュは行わないでください。

スキャフォールドを適応させるための設計ルール

  • プロジェクトの既存のツールを優先します。リポジトリにmake checkを含むMakefileがある場合は、その部分を再リストする代わりにconfig.shにmake checkを入れます。
  • ランタイム依存関係はbash、git、python3(標準ライブラリのみ)に保ちます。ハーネスのためにプロジェクトにパッケージを追加しないでください。
  • ハーネススクリプトからのエラーメッセージは、何が失敗したか、なぜか、そして修正方法を説明します。
  • スクリプトには破壊的なものはありません。クリーンアップは報告のみ行います。人間またはエージェントがレポートに基づいて行動します。
  • 可能な場合はハーネスを小さくします。このリポジトリでのエージェントの動作を変更しないコンポーネントはオーバーヘッドです。完全を期してインストールするのではなく、その旨を伝えます。

関連スキル