harness-engineering-lifecycle

ハーネスエンジニアリングのライフサイクル

実績のあるリポジトリ内の契約を、汎用的で高性能な宣言型ハーネスシステムへと発展させ、その後、プロデューサーとコンシューマーのリポジトリ境界をまたいで安全に実地検証します。対象リポジトリに steward.yaml の契約と、少なくとも H2 のスモークテストの実証がある場合にのみ、ここから始めてください。それより前の段階では mcp-harness-repo-maintainer を使用してください。

使用する場合

• カスタム検証スクリプトを中央のリンターエンジンへと発展させる場合。
• 大規模なポリリポジトリ向けに steward CLI の機能を拡張する場合。
• ローカルの CLI／ハーネスビルドを兄弟リポジトリに対してテストし、パス解決時のクラッシュや統合上の摩擦を検出する場合。
• 繰り返し見つかったローカルベンチマークやプローブの知見を、再利用可能なハーネス機能にする場合。

使用しない場合

• steward.yaml の初回導入、または単一リポジトリでの最初のクイックプローブ — mcp-harness-repo-maintainer を使用してください。
• スキルの作成、レジストリの更新、マーケットプレイス向けのパッケージ化 — skill-authoring-lifecycle または plugin-marketplace-setup を使用してください。
• コールドスタートの契約がない状態で、製品固有の診断を行う場合 — まず対象リポジトリに、範囲を限定したアクション、プローブ、シナリオを追加してください。

Part 1: カスケード型エージェントサーフェス（アーキテクチャと汎用化）

単一のローカル契約を超えてハーネスを設計する際は、カスケード型エージェントサーフェスのガイドラインに従ってください。リポジトリのワークフローが複数のパッケージ、アダプター、コンシューマーにまたがるようになると、ツールとスキルを厳密に分離する方法ではうまくいかないことがあります。代わりに、ドメインに依存しない抽象化を使って連携させてください。

1. レイヤー 0（組み込みエージェントサーフェス）：対象のアプリケーションまたはエンジンは、明示的なフック（RPC やメモリプローブなど）を介して、内部状態をネイティブに公開する必要があります。脆弱な UI スクレイピングやブラックボックステストに依存しないでください。
2. レイヤー 1（プロトコルアダプター）：レイヤー 0 に接続する、汎用的な MCP サーバーまたはプロトコルアダプターを構築します。これらのツールは生の可視性と操作手段（スクリーンショットの撮影やメモリの読み取りなど）を提供しますが、ビジネスロジックを一切含めてはいけません。
3. レイヤー 2（オーケストレーター）：独自の自動化やスクリプトを使って、複数のレイヤー 1 のアクションを連携させる、特化型のハーネス CLI を構築します。オーケストレーターの主な役割は高速なフィードバックループです。境界をまたいで、どこで何が壊れたのかを正確に特定できるよう、構造化された診断用 JSON を出力する必要があります。
4. レイヤー 3（AI ラッパー）：agentskills.io の仕様に従い、スキルには薄いラッパーのツール（スクリプト）を含めることができ、また含めるべきです。スキルは AI の頭脳として機能し、レイヤー 2 の呼び出し方、複雑な JSON のヒューリスティクスの解釈方法、ドメイン固有の復旧ツールの安全な実行方法を AI に教えます。

汎用化の原則

1. **トランスポートとエンジンを分離する：**コマンドインターフェース（CLI）と JSON-RPC（MCP）は薄いラッパーです。すべてのロジックは再利用可能なコアパッケージに置きます。
2. **宣言型の設定：**設定ファイル（steward.yaml など）を使って、次の項目を指定します。
   • **ブランディング：**ハーネスの名前と説明。
   • **アクション：**効果、制限、出力、エビデンスポリシーを備えた、型付きで範囲を限定したリポジトリ内コマンド。
   • **ドキュメントの格子構造：**ラベルを特定のドキュメントファイルに対応付けるマップ。
3. **枝刈りした走査：**標準的なビルド／VCS フォルダーを早い段階で除外せずに、再帰的なファイル走査（list(recursive: true)）を決して実行しないでください。
4. **汎用的なチェック：**リンターをハードコードしないでください。パラメーター化された宣言型エンジン（disallowed-substrings など）を使用してください。

パート 2：リポジトリ横断の修正（テスト）

ハーネス（Producer）を変更した場合は、依存する下流プロジェクト（Consumer）に対して検証する必要があります。

1. 兄弟リポジトリのベースラインを確立する： コンシューマーのリポジトリ（例：../<consumer-repo-name>）を特定します。テストを実行し、問題なく開始できることを確認します。まだ変更は加えないでください。
2. ローカルの Producer を導入する： ハーネスのローカル開発バージョンをビルドしてインストールします。
3. 導入時の障害を記録する： ローカルの Producer ビルドを使って、コンシューマーの検証スイートを実行します。パスに関するクラッシュや脆弱なルールをスクラッチパッドに記録します。
4. 根本的な修正： 根本原因を Producer のコードベースで修正します。修正は汎用化し、コンシューマー固有の回避策は作成しないでください。
5. コンシューマーの設定を修正する： 新しい汎用機能を活用できるよう、Consumer リポジトリを更新します（例：steward.yaml の更新）。
6. 両方を検証する： コンシューマーのスイートと Producer のスイートの両方が合格することを確認します。
7. 知見を永続化する： repository-governance-lifecycle スキルを使って、学びを ADR または FAQ にまとめます。

迂回の停止ルール： ローカルの Producer ビルドのインストール、有効化、または接続に 2 回失敗した場合は、復旧を中止し、障害を記録してください。可能であれば、コンシューマー固有のゲートまたは移植可能な代替手段を使い、元の受け入れ確認に戻ります。同じ迂回から汎用化されたハーネス機能を昇格させてはいけません。まず観察結果または未知のケースとして記録してください。

Producer/consumer の証明成果物

汎用化されたハーネスの変更を昇格させる前に、両側から証明を取得します。

側	必須の成果物	目的
Producer	テストまたはバリデーター出力を伴う変更済みのスキーマ／アクション／ルール	汎用機能がソースハーネスで機能することを示します。
Consumer	更新済みの steward.yaml またはシナリオマニフェスト	導入にローカルパス固有の仕掛けが不要であることを示します。
Consumer	ベンチマークの概要、または実態を反映した durability_blocked の出力	新しいエージェントが、証明済みの内容とブロックされている内容を確認できることを示します。
両方	検証コマンドとバージョン	リポジトリをまたいで障害を再現できるようにします。
ドキュメント	境界が変更された場合の ADR／FAQ の更新	今後のエージェントが同じ境界の違いを再発見せずに済むようにします。

1 つのコンシューマーだけが独自のパス回避策を使っている場合は、ローカル修正を汎用ハーネスに昇格させないでください。契約、スキーマ、またはルールに再利用可能な形があり、少なくとも 1 回、保留中の別のケースまたは将来のエージェントによる再試行で移行できることが証明されるまでは、ローカルに留めてください。

インストール

npx skills add arenukvern/skill_steward --skill harness-engineering-lifecycle

ソース

references/sources.md を参照してください。