mcp-harness-repo-maintainer

Action Contract & Harness Repo Maintainer

エージェントが実行し、人間が方向付けを行う、リポジトリ内のアクションコントラクトとハーネスを構築・保守します。歴史的な mcp- という名称は、多くの導入者がMCP関連の作業を通じてこのツールにたどり着くため、そのまま残していますが、このスキルはMCPに限定されません。一般的なアプリ、ライブラリ、ツール、プラグイン、メタリポジトリの保守の基準には、まず repo-quality-system-lifecycle を使用してください。このスキルを使うのは、型付きアクション、プローブ、ベンチマーク、またはCLI/MCP間の同等性が対象となる場合だけです。

コア原則（アクションコントラクトとハーネスのリポジトリ）

MCPとCLIは薄いインターフェースであり、エージェントとCI向けのAPIです。 Core に実際のロジック、スキーマ、レジストリを配置します。アダプターはワイヤーフォーマット（argv、MCP JSON-RPC）を解析し、直ちに処理を委譲します。

Agents / CI  →  CLI ──┐
                      ├──► Core (logic, contracts, tests)
Agents / chat →  MCP ──┘

完全なレイヤー構成については、core-and-interfaces.mdを参照してください。**同等性：**すべてのMCPツールは、対応するCLIと同じCoreエントリポイントを呼び出す必要があります。

**段階的な自動化（エージェント主導のワークフロー）：**ハーネスでは、エージェントが繰り返し発生する摩擦を、レビュー済みの持続的な機能に変えられるようにします。エージェントが複雑な修正やコマンドの一連の手順を見つけた場合は、担当者、リスククラス、入力、出力、作用、来歴、検証を伴う未対応ケースまたは型付きアクション候補として記録します。恒久的な steward.yaml の変更には、レビュー可能な差分と検証が必要です。エージェントに、MCPから生のbashを恒久的に保存するよう教えてはいけません。

**目標優先の導入：**当初のユーザー目標を、引き続き受け入れ判定の基準とします。ツールの修復、インストール作業、ラッパー、アクション候補、評価、リファクタリングは、その目標を直接解決するか、再利用可能な知見を残す場合を除き、寄り道です。修復やセットアップを2回試して失敗したら、ツールの復旧を中止します。可能であれば、型に適したコマンドまたは移植可能な代替手段を使い、摩擦を記録して作業に戻ります。同じ寄り道から機能を昇格させてはいけません。

**プロダクト実験の責任：**目標がビジュアル品質、シェーダーの挙動、ローダーの正確性、レンダラーのスループット、またはパフォーマンスに関する場合、高スループットの実験ランナーとオラクルはプロダクトのリポジトリで管理します。プロダクト側のループでキャプチャやメトリクスが生成された後、Stewardは experiment-campaign-summary/v1 アーティファクトを検証または要約できます。プロダクトのキャンペーンで、どのサーフェスが変更されたか、または直接実証されたかが明示されていない限り、Stewardのアクション、ベンチマーク、MCPツールをプロダクトの高速化手段として昇格させてはいけません。

**昇格前に懐疑的に検討：**より小さなレイヤーで解決できない場合に限り、機能不足をハーネスの不足と見なします。まず、修正がネイティブコマンド、エラーメッセージ、FAQ、ドキュメントマップ、公開API、スキーマ／コード生成、または削除・統合のいずれに属するかを確認します。Stewardのアクション、MCPツール、またはベンチマークを昇格させるのは、実際の検証経路を改善し、反証手段を備えている場合に限ります。

**インターフェースにおける進化的なシンプルさ：**所有者、検証、作用、実行頻度、対象者が異なる場合は、Coreのエントリポイントを分割します。ユーザーまたはCIの意図が1つである場合は、CLI/MCP/ヘルプのサーフェスを統合します。ただし、ラッパーが検証、作用、または未主張の事項を平坦化しないよう、子要素の結果は構造化されたまま保持します。

コアとなる信念と文化

1. 機能不足 → ハーネスの不足の可能性 — エージェントが失敗したときは、何が 理解可能 または 強制可能 でないのかを問い、ネイティブコマンド、エラーメッセージ、ドキュメント／FAQ、スキーマ、リンター、スキル、アクション、削除の中から、役立つ最小のレイヤーを選びます。インターフェースの形状には進化的なシンプルさを適用します。検証、作用、または担当者が異なる場合は内部を分割し、ユーザーの意図が1つで子要素の結果が構造化されたままなら、CLI/MCP/ヘルプのラッパーを統合します。
2. 設計の曖昧さ → 意思決定のチェックポイント — 分岐を実装する前に repository-governance-lifecycle を使用し、合意後に承認済みADRを記録します。
3. 機械的な強制 — リンター、検証コマンド、境界でのスキーマ検証を使います。エラーメッセージによって、エージェントに修正方法を伝えます。構造化パーサー（YAML、JSON、AST）を使用します。
4. 段階的な開示 — ルーター → ADR / DESIGN_FAQ（理由） → DX_FAQ（方法） → スキル（手順） → コード（動作のSSOT）。

構築するハーネスのレイヤー

Human intent (prompt, plan, review)
        │
        ▼
┌───────────────────┐
│ Skills + AGENTS   │  Map & procedures (when to do what)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ CLI               │  doctor, exec, validate, contracts (deterministic)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ MCP server        │  fmt_* / tools for chat agents (same schemas)
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ App / runtime     │  Legible UI, logs, metrics per worktree (optional)
└───────────────────┘

エキスパートの組み合わせ（担当を1つ選択）

リポジトリがハーネスまたはアクションコントラクトを中心とする場合は、主要な成果物に基づいて担当を割り当てます。より広範なアプリ／ライブラリ／ツールの分類には、repo-quality-system-lifecycle を使用します。

エキスパートの視点	リポジトリの例	担当範囲	担当しない範囲
プラグイン／MCP	<plugin_repo>	plugin/mcp.json、ツールのプレフィックス付け、初期化ユーティリティ	ハーネススクリプト、視覚的な比較
ライブラリ	<library_repo>	プラットフォームパッケージ／モジュール、アダプター	配布可能なプラグインツリー、dogfood アプリ
ハーネス／CLI	<harness_repo>	ハーネスエンジン、アプリレジストリ、フィクスチャのリント	MCP サーバーバイナリ、マーケットプレイスのマニフェスト
D — ビジュアルサイドカー	<visual_sidecar>	プロファイル設定、比較／分解 CLI	VM／MCP、動的レジストリ
メタ／ガバナンス	skill_steward	skills/、plugins/、バリデーター CLI、ドキュメント	プロダクト MCP、ドメインツール
F — セキュリティ／運用	すべてのリモート	OAuth ゲートウェイ、トークン仲介	機能コード

あらゆるアーキタイプに共通するメンテナーの基本方針

1. 憲章とアーキタイプ — docs/NORTH_STAR.mdx（またはルートのポインター）。AGENTS.md はマップのみとします。
2. 動作の SSOT — コードとスキーマを正とし、ドキュメントには理由と方法を記載します。
3. 薄いアダプター、厚いコア — 実装はコアで一度だけ行い、CLI と MCP はラッパーとします。
4. 機械的なゲート — マージ前にコントラクトチェック／検証コマンド／ユニットテストを実施します。
5. 計画の整理 — ADR／FAQ／コード／スキルに内容を移したうえで、計画ファイルを削除します。
6. バージョンの正確性 — VERSION または release-please マニフェストのいずれか1つを使用します。
7. 配布とユニバーサル翻訳 — チャネルごと（npx skills、git マーケットプレイスなど）に記録します。独自エコシステムへのロックインは避けます。CLI ツールでガバナンス設定を上流の IDE 形式へネイティブにコンパイルできるようにします（例：steward bundle で .cursor/rules と .clinerules を生成）。

ワークフロー：エージェント優先の機能を追加する

1. 意図を明確にする — 達成する結果を1文で記述し、受け入れチェックを定めます。
2. 懐疑的／世代的なチェックを行う — これは繰り返し発生しますか？ 下位レイヤーで解決できますか？ コードを削除または集約すると保守が容易になりますか？ ツールループの逸脱を防ぐ反証条件は何ですか？
3. 提供面を選ぶ
   • CI／スクリプト／ゲート → まず CLI
   • 対話型のデバッグループ → MCP ツール（CLI コアを再利用）
   • 一度限りのガイダンス → skills/ 内の スキル
   • イベントの適用 → プラグインフック
4. 明確にする — JSON スキーマ、--json 出力、安定したエラーコード、アクションの効果、制限、秘匿化ポリシーを用意し、DX_FAQ に記載します。
5. 理由を記録する — ADR または DESIGN_FAQ の Q&A に記載します。
6. マップに追加する — AGENTS.md／docs_map の行を更新します。
7. 検証する — pnpm run validate またはプロジェクトのコントラクトテストを実行します。
8. 人間が連携する — PR にハーネスの変更内容を記載します。

コールドスタート時のローカルハーネス検証ループ

リポジトリがハーネス対応済みだと表明する前、またはリポジトリ固有の症状を診断する前に、このループを使用してください。新しいリポジトリには、意味のある症状カタログがまだありません。まず、エージェントが宣言されたコントラクトを見つけ、安全に実行できることを検証してください。

移植可能な Steward の実行方法

リリース済み CLI をインストールするか、ローカルクローンをグローバルコマンドとして有効化した後にのみ、steward <command> を使用してください。導入手順として、絶対ローカルパス、非公開 SDK パス、兄弟チェックアウトのパスを案内しないでください。

推奨順序：

1. リリース済みの利用者向けまたは CI 向けの方法：curl -fsSL https://raw.githubusercontent.com/Arenukvern/skill_steward/main/install.sh | bash を実行し、その後 steward <command> を実行します。
2. Skill Steward のクローンから実行する Dart メンテナー向けの方法：cd packages/steward_cli && dart run :steward <command> を実行します。
3. ローカルクローンをグローバルに有効化する方法：dart pub global activate --source path packages/steward_cli を実行し、その後 steward <command> を実行します。

dart --packages=... bin/steward.dart を直接実行するコマンドは、ローカル環境での実行経路を示すものに限ります。証拠としてこれらが必要な場合は、移植可能なコマンドブロックと併記し、マシン固有のパスにはコピー不可であることを明記してください。

1. 小さな契約を宣言する — steward.yaml に安全性の高いアクションを 1 つ追加するか、既存のものを更新します。最初のアクションでは状態を変更せず、状態を調査します。

2. アクションを公開する — クイックポリシーに適合する場合に限り、probes.quick.actions にアクションを配置します。適合条件は、default_policy: auto、確認不要、シェル不使用、ネットワーク／シークレット／破壊的な影響なし、リポジトリの変更なし、fs_write 不使用です。

3. シナリオマニフェストを追加する — コミット対象のシナリオを steward/scenarios/*.yaml に配置します。シナリオでナビゲーションや診断が実証されるまでは、contract-status-smoke のような具体的な名前を使います。

4. 検証ループを実行する：

   steward doctor --json
   steward schema check-outputs --json
   steward schema drift --json
   steward actions list --json
   steward action inspect <action-id> --json
   steward probe --profile quick --json
   steward benchmark --scenario <scenario-id> --strict --output .steward/benchmark-summaries/<scenario-id>.json --json
   

5. 誠実に解釈する — doctor／actions list は検出を証明し、schema check-outputs は機械可読な出力のドリフトを検出し、schema drift は生成された契約／スキーマのドリフトを検出し、action inspect は実行可能な境界を証明し、probe は最初の安全な観察を証明します。benchmark が永続的な実行を証明するのは、result: "pass" を返した場合に限られます。厳密なベンチマーク入力が変更済み、または未追跡の場合、durability_blocked はブロックされた状態を正確に示す証拠であり、H2 の証拠ではありません。

   • 新しいコンソール JSON がブロックされた場合は、steward blocked explain --stdin --json にパイプして、設定の修復、不明ケースの記録、同一ベンチマークの再実行のいずれかを選びます。既存の永続化済みサマリーに対してのみ、steward blocked explain --input <result.json> --json を使います。
   • 永続化済みのベンチマークサマリーは、そこに記載されたコミットと入力に関する機械的な証拠として扱います。コンソールにのみ出力された JSON は、--output を指定して再実行しない限り、セッションの証拠として扱います。現在の台帳または再実行の手順に従って、過去のサマリーが現在も有効な証拠かどうかを判断します。
   • ベンチマークの成功は、まず、そこに記載された入力に関するローカルまたはリポジトリ所有の証拠として扱います。ソースを取得でき、対象コミットが解決済みの SHA であり、コマンドが移植可能で、保持される成果物に CI 成果物名またはハッシュがある場合に限り、公開された再現可能性の証拠となります。
   • 無効な steward.yaml、変更済みの宣言入力、スキーマ／出力のドリフト、ネイティブ起動の失敗があれば、同じ寄り道で新しいアクション、ベンチマークシナリオ、PDSA ノート、証拠パケットを追加する前に、担当する領域で対処します。

6. ローカル状態を保護する — 厳密なベンチマーク入力は、実行前に追跡済みで変更がない状態にする必要があります。対象は steward.yaml、ファイルベースのシナリオマニフェスト、およびベンチマークが読み取る、宣言済みのアクション入力です。.steward/benchmark-summaries/*.json、観察結果、不明ケース、アクション候補などのローカル実行出力は、レビューで編集済みの成果物を意図的に昇格させる場合を除き、ローカルに留めます。リポジトリ内にそのまま残す必要がある一時的な変更ファイルがある場合は、変更禁止の例外を記録し、それらのファイルをアクション入力に含めないでください。保護対象のローカル状態は、契約またはシナリオの入力として宣言されていない限り、ベンチマークを妨げる要因ではありません。

7. 証拠に基づいて拡張する — プローブで未知の障害が見つかった場合は、まず不明ケースを記録します。所有者、影響、制限、秘匿化、検証コマンド、ベンチマークの証拠が揃ってから、型付きアクション候補に昇格させます。同じ実行で発見した診断を昇格させないでください。

   • 証拠をドキュメントに昇格させる場合は、docs/core/evidence-artifacts.mdx の status、evidence_type、claim_tested、proof_level、limitations、non_claims、next_disposition、current_status_pointer を含む形式を使います。生ログ、シークレット、または非公開の関係性に関する記憶を証拠として残さないでください。

ネイティブな決定論的ゲートへの昇格

Steward だけでスコアを記録するよりも、有用なネイティブゲートを優先してください。次の条件を満たす場合、リポジトリでは既存の決定論的なスクリプト、テスト、検証コマンドを Steward アクションに昇格できます。

• 現在の状態に対する肯定的な証明
• 回帰の種類を検出する反証テストまたはフィクスチャ
• オーナー、リスク分類、効果、制限、秘匿化ポリシー
• 機能を見つけられるようにする厳格なベンチマークまたは評価
• 転用可能性を証明するホールドアウトベンチマークまたは将来のエージェントによる再実行
• 製品のランタイムの正しさと、幅広い H5 の成熟度についての明示的な非主張

ビジュアル／パフォーマンスキャンペーンでは、製品スタックが許す場合、ネイティブゲートは仮説ごとに再ビルドすることなくバリアントを実行でき、ランタイムのスイープではブラウザーとサーバーのウォーム状態を維持し、スクリーンショットの生データを大量に出力するのではなく、最良の証拠を出力できる必要があります。2 回のハーネスループを経ても製品のオラクルやメトリクスが改善しない場合は、ハーネスの作業を中止し、製品ネイティブな実験に戻ってください。

これは、証拠をツール改善パケットに変えるための道筋です。その結果から後続のエージェントがリポジトリの実際のツール面を維持または改善する方法を学べない場合は、昇格させず、観察結果または未知のケースとして扱ってください。

導入実行の分類

S/H の主張を行う前に、adoption-run/v2 の証拠形式を使用してください。次の項目を記録します。

• user_goal：元のプロンプト、要求された成果、受け入れ確認、ステータス、証拠。
• capability：ID、クラス、スコープ、ユーザー価値、ネイティブオーナー。
• direct_problem_path：宣言されたサーフェスと、生のシェルを調べる前に使用したネイティブゲート。
• tool_detour：理由、試行、成果物、中止ルール、目標に戻る手順。
• generational_architecture_check：繰り返し現れるパターン、検討したより小さなレイヤー、削除／統合の選択肢、選択したパターンレイヤー、保守の差分、昇格ガード。
• outcome：続行、リファクタリング、中止、断念、昇格。
• hot_path_claim：問題のクラス、作成したサーフェス、反証、肯定的な証明、観察された効果、ホールドアウトまたは将来のタスク、非主張。

1 件の洗練された証明を根拠に、「リポジトリ全体に完全に導入済み」という表現を使わないでください。「機能レベルの H5」または「機能レベルの S5/H5」と記し、対象の機能を明示してください。リポジトリの成熟度は、別個のより広範な主張です。

導入成熟度の段階

主張に見合う証明段階に達するまでは、リポジトリをハーネス対応と呼ばないでください。

段階	名称	証明
H0	スキルのインストール済み	エージェントが、関連する Skill Steward スキルを見つけられます。
H1	ローカル契約の宣言済み	steward.yaml が、クイックかつ安全なアクションを 1 つ含めて存在し、ドキュメントからそのアクションを参照できます。
H2	スモークループの証明済み	コールドスタートの証明ループによって、result: "pass" を含む永続的なベンチマーク概要が生成されます。durability_blocked がある場合、クリーンな状態で再実行するまでは H2 未満です。
H3	リポジトリのフィードバックループ	実作業から、ベンチマーク概要、未知のケース、アクション候補が蓄積されます。
H4	新規エージェントのワークフロー	新規エージェントが、生のシェルを掘り下げることなく、リポジトリのワークフローを 1 つ完了します。
H5	昇格済みハーネス機能	少なくとも 1 件のホールドアウトベンチマークまたは将来のエージェントによる再実行を含む反復的な証拠によって、診断、アクション、評価、ローカルハーネス機能が昇格します。

アーキタイプの詳細

• アーキタイプ A（製品 MCP）： plugin/ が SSOT です。カスタムサーバーを提供し、製品ロジックのためにコミュニティサーバーへパッチを適用しないでください。
• アーキタイプ B（プラットフォームライブラリ）： コアモジュールとワイヤプロトコルアダプターのみを使用し、ドメインごとのフォークは作成しません。
• アーキタイプ C（CLI ハーネス）： MCP は使用しません。製品 MCP のコアモジュールに依存します。
• アーキタイプ D（ビジュアルサイドカー）： MCP は使用しません。SSOT は profiles/*.yaml です。
• アーキタイプ E（メタ Steward）： コアバリデーターと薄い CLI チェックを使用します。mcp.json は使用しません。
• アーキタイプ F（本番 MCP）： 読み取り専用にはリソース、変更にはツールを使用します。長時間のタスクにはジョブ ID を返します。OAuth を使用します。

兄弟レイアウト

<workspace>/
  <plugin_repo>/               # toolkit + MCP/plugin init
  <library_repo>/              # SDK platform/library packages
  <harness_repo>/              # CLI/harness runner
  <visual_sidecar>/            # D — comparison sidecar
  <meta_governance_repo>/      # meta skills & validation

「ハーネス対応済み」と表明する前のチェックリスト

共通の証拠：

• エージェントが、リポジトリ内のドキュメントだけを見て実行する内容を特定できます
• リポジトリが採用成熟度ラダーで少なくとも H2 に達しています
• エラーメッセージに対処方法が記載されています
• 設計上の分岐点がチェックポイントとして記録されています（repository-governance-lifecycle）
• コントラクトゲートまたは検証スクリプトに合格しています

アーキタイプ固有の証拠：

アーキタイプ	必要な証拠
プロダクト MCP	MCP ツールと CLI コマンドが同じコアスキーマ／検証エントリーポイントを共有しています。
プラットフォームライブラリ	プロトコルアダプターが薄く、コアテストが動作を網羅し、プロダクト固有のフォークが組み込まれていません。
CLI ハーネス	CI／ゲート用の CLI コマンドが存在します。リポジトリが MCP を公開していない限り、MCP との同等性は必須ではありません。
ビジュアルサイドカー	プロファイル／設定スキーマと比較／分解コマンドが検証されています。MCP との同等性は必須ではありません。
メタスチュワード	スキル／プラグイン／バリデーターの各サーフェスがスキル検証と、動作に重大な影響を与える T1 のルーティングケースに合格しています。プロダクトランタイムは同梱されていません。
セキュリティ／運用	変更を伴うサーフェスには、明示的なリスク分類、編集・伏せ字処理、認可ポリシーが必要です。

インストール

npx skills add arenukvern/skill_steward --skill mcp-harness-repo-maintainer

参考資料

• core-and-interfaces.md
• repo-archetypes.md
• maintainer-checklists.md
• mcp-production-practices.md
• sibling-layout.md
• harness-principles.md
• cli-mcp-pattern.md
• steward-composition.md
• preferred-tooling.md

情報源

references/sources.md を参照してください。調査する際は、skill-source-citations に従ってください。