shimo4228/agent-stocktake

agent-stocktake — エージェント定義品質監査

<harness>/agents/*.md にあるすべてのエージェント定義を評価し、各エージェントに次の判定を割り当てます。 維持 / 改善 / 更新 / 統合 / スキルへ格下げ / 解散 / 廃止。監査の単位はファイルですが、コストの単位は 2つのレイヤーに分割 されます。この分割こそが、このスキルが skill-stocktake や rules-stocktake とならぶ第三の兄弟スキルとして存在する理由です。

設計ノート — ハイブリッドコストモデル。スキルのコストはトリガー汚染（確率的な発動が選択品質を低下させる）であり、ルールのコストは常駐（常に読み込まれる）です。エージェントは その両方を同時に 持ちます。エージェントの description は「利用可能なエージェントタイプ」一覧を通じてすべてのセッションに注入され（ルールのような常駐）、一方で本文はエージェントが呼び出されたときのみ読み込まれます（スキルのような起動 — ただし、ユーザーの言葉との説明文マッチングではなく、Claude の委譲判断によってトリガーされます）。したがって、説明文は常駐密度で監査され、本文は起動品質で監査され、それぞれに異なる質問が設定されています。

設計ノート 2 — 承認された編集は、このスキル自体によって apply ブランチに適用されます。rules-stocktake と同じ理由です。エージェント定義に改善エンジンは存在せず、コーパスは1つのコンテキストで読める程度に小さいため、委譲は設計の過剰になります。唯一の例外は「スキルへ格下げ」で、これはスキル作成者の仕事です。

ルーツ。 以下の <harness> はこの監査が対象とするハーネスです。デフォルトは ~/.claude、またはスキル harness-stocktake がプロジェクトモードで実行される場合はリポジトリの .claude/ です（その Roots セクションはパスをマッピングし、そこでは該当しないエビデンスを n/a とし、適用される規約チェックを示します）。台帳 <ledger> はそのハーネスに属します。このスキルのディレクトリが <harness> 内にある場合は ${CLAUDE_SKILL_DIR}/results.json（ハーネスはスキルのコピーを自身で保持）、そうでない場合は <harness>/stocktake/agent-stocktake.json（インストールされたプラグイン、またはプロジェクトモード）です。どちらの場合も、apply ブランチ上でハーネスの他の変更と共にコミットされます。

モード（$ARGUMENTS）

引数	動作
なし / full	すべてのエージェント定義を読み取り評価する（デフォルト）
changed	最終更新日時が <ledger> の evaluated_at より新しいファイルのみを再評価し、残りは台帳から引き継ぐ

changed はインラインで変更を検出します（スクリプトは使用しません）。

以下のパスは ${CLAUDE_SKILL_DIR}（この SKILL.md を保持するディレクトリ）からの相対パスです。変数を置換しないエージェントは、それをそのディレクトリとして読み取ります。

find <harness>/agents -name "*.md" -newermt "$(jq -r .evaluated_at "<ledger>")"

rules-stocktake と同様、フェーズ1の整合性チェックは 常に全セットに対して実行 されます。スキルやフックを廃止すると、変更されていないエージェント本文内の参照が静かに壊れ、mtime はそれを検出できません。ステップ3（以下）の参照チェックに新たに失敗したエージェントは、再評価セットに追加されます。また、このスクリプトには changed モードはありません。その理由は異なります。ニアデュープペアと常駐総数は集合の特性であり、部分的なコーパスでは誤った数値（少ない数値ではなく）が得られるからです。

フェーズ1 — エビデンス、インベントリ、使用状況

ステップ1 — エビデンススクリプトを実行する（手動でカウントしないこと）

uv run --frozen --project "${CLAUDE_SKILL_DIR}" \
       --directory "${CLAUDE_SKILL_DIR}" \
       python scripts/agent_evidence.py --root <harness>

エビデンスモード：JSON を標準出力に出力し、発見事項の数にかかわらず終了コード0（コーパスが読み取れない場合のみ終了コード2）。測定と列挙を行いますが、判定は割り当てません。

JSON を発見事項に書き写すこと — 決して目視で再測定しないでください。 JSON が提供するもの：

JSON フィールド	置き換えるもの
desc_words / body_lines / total_desc_words	wc -w / wc -l によるパス
tools.items[].status + registry.known_tools	builtin / unverified / mcp。unverified は「スクリプトの日付付きリストにない」という意味であり、「存在しない」という意味ではありません。あなたは最新のツールレジストリを保持しており、スクリプトは保持していないため、unverified を Update のエビデンスと呼ぶ前に、自分のツールリストと照らし合わせて確認してください。registry.known_tools.as_of はそのリストの日付です（--known-tools で置き換えられた場合は null）
tools.items[].server_in_config + registry.mcp_config_files	判定ではありません。 これは、サーバーがリストされているローカル設定ファイルに出現するかどうかのみを示します。コネクタによって提供されるサーバーはそこに一切出現しないため、false は「廃止」を意味しません。null は設定ソースが解析されなかったことを意味します。これを使用する前に、各ソースの status を確認してください。ok でないソースの横にある false はエビデンスではありません。
unreadable	スキャンが開けなかったファイルとその理由。空でない場合、スキャンは不完全です — それらを特定して修正してから合計を述べてください。読み取れないファイル内の抑制指示が認証されていないためです。
tools_unparsable	tools: 行が解析できなかったエージェント（例：YAML フロースタイル）。それらの items は [] となり、tools: キーがないエージェント（すなわち無制限）と同一に見えます。しかし、実際はそうではありません。単にリストが読み取られなかっただけです。
description_near_duplicates	ほぼ同一の説明文チェック。双子は委譲トラフィックを分割するため、各ペアはステージ1の重複質問に影響します。
suppression_candidates	ステージ1の抑制質問の候補（行番号付き）。カタログはバイリンガルです（コーパスがそうであるため）。
always_never_candidates	過剰制約質問の候補（行番号付き）。本文のみ — 説明文は委譲トリガーであり、エージェントへの指示ではありません。

最後の2つは発見事項ではなく候補です — 報告する前に引用された各行を読んでください。カタログは下限であり、全数調査ではありません。1つのコーパスから抽出された5つの表現を保持しており、別の方法で書かれた抑制（「よくわからないものはスキップする」、「単なるノイズになるような発見は避ける」）はどの JSON フィールドにも出現しません。それらのために読み続けてください。空のリストは無傷であることを意味しません。

測定された偽陽性率はこのファイルの外部に存在するため、このステップでは古くなる数値は扱いません。

ステップ2 — 残りをすでに所有しているゲートを読む

3つのチェックはスクリプトの外部に残されています。なぜなら、lint ゲート（<harness>/scripts/hooks/harness_lint.py）を持つハーネスでは、そのゲートがそれらを所有するからです。存在する場合はその出力を読み、存在しない場合は Read / Grep で3つのチェックを行います。

• フロントマターが解析され、name、description、origin、model を保持し、model がエイリアスであること → lint スクリプトの lint_agents（作成者のハーネスでは .claude/verify.sh と pre-commit フックで実行）。origin が欠落している場合、ハーネスが origin の規約を述べているときは、依然として整合性の問題であり、改善に分類されます。
• name がファイル名のステムと一致すること → 同じ lint_agents。これは判断を許さず、委譲レジストリはそれに基づいてキー付けされるため、コミットを阻止するゲートに属します。読者が書き写すかもしれないエビデンスではありません。ここでの発見は ブロックされたコミット であり、ストックテイクの判定ではありません。
• エージェント本文内の Markdown リンクが解決されること → 同じスクリプトの lint_markdown_links（そのスコープには agents が含まれます）。

ステップ3 — ベアパス参照を解決する（他の誰も所有していない唯一のチェック）

lint_markdown_links はリンク構文のみを認識し、skill-health の scan_refs.py は スキル ツリーをスキャンします。エージェント本文内に散文として書かれたパス（<harness>/hooks/foo.sh、skills/foo/SKILL.md）はどちらでもカバーされません。コーパスを grep で検索し、それぞれを ls で確認します。

ステップ4 — インベントリ

Glob で列挙：<harness>/agents/*.md。すべてのファイルを1つのコンテキストに読み込みます（コーパスは小さいです）。常駐列と本文列はステップ1の JSON から取得します — ドキュメント（このドキュメントを含む）に書かれた数値を信頼しないでください。

ステップ5 — 使用状況カウント

エビデンス入力：低使用状況は候補を指名し、内容が判定を決定します。セットアップがエージェント使用状況ログを保持している場合（<harness>/metrics/agent-usage.jsonl。存在しない場合＝使用状況 n/a）、それをインラインで読み取ります（log-agent-usage.sh などの使用状況ロギングフックは、Agent ツールが起動されるたびに1つの invoke イベントを追加し、その agent フィールド（値は subagent_type）をキーとします）。エージェントごとのイベントを7日/30日/90日でカウントします。使い捨ての python3 / jq ワンライナーで集計します。

• ログが欠落しているか、最初のイベントが90日未満の場合、使用状況を —（未測定）として表示します。決して 0 として表示しないでください — 未測定と未使用は異なる事実です。
• カウントは下限です。Agent（Task）ツールの起動のみがキャプチャされます。ワークフローの agent() ワーカー、プラグイン内部のディスパッチ、ツール呼び出しをバイパスする組み込み機構はフックに到達しません。低使用状況のエージェントは、廃止/解散の候補としてステージ1に入ります。その価値はエピソード的である可能性があるため（例：論文レビューアは入稿時にのみ起動する）、内容が判定を決定します。
• ログは 2026-07-27 から存在します。それ以前の日付の測定は一切ありません。

スキャン結果を最初に述べ、ステップ1の JSON からカウントを取得します。agents_total から unreadable にあるもの（名前を指定する必要があります）を差し引いたもの、total_desc_words（一覧表示のセッションごとの常駐税）、整合性の失敗、使用状況が測定可能かどうか。失敗をステージ1に事前計算済みエビデンスとして引き継ぎます。

フェーズ2 — 評価（完全インライン、全体論的）

すべての本文を読みながら、セット全体を把握します。

ステージ1 — 二値スクリーニング（すべてのエージェント）。 各項目に対して明示的な Yes/No。No の回答のみを表面化します。最初の2つの質問は 説明レイヤー（常駐）を監査し、残りは 本文レイヤー（起動）を監査します。

• 説明文は常駐に値するか？ — 常時読み込まれる一覧において、密度が高く、明確で、選択を可能にする。いつ委譲すべきか、いつ委譲すべきでないかを述べている。
• 説明文は本文に忠実か？ — 説明文で約束されていることが本文で行われている（漂流した説明文は、本文が問題なくても、すべてのセッションで委譲を誤ってルーティングする）。
• 本文に抑制指示がないか？ — このエージェントのフェーズ1 JSON の suppression_candidates から開始し、ステップ1に従って処理する。抑制としてカウントされるもの：信頼度しきい値（「N%以上確信がある発見のみ報告する」、「各発見に信頼度を割り当て、低いものを破棄する」）、重大度フロア（「高重大度のみ」）、「控えめに」というフレーミング。現在の世代のガイダンスは、すべてを報告し、別のパスでフィルタリングすることです。抑制指示は文字通りに従われ、発見事項を静かに削除します。ここでの No は 反転による改善 の候補です。指示を反対方向に書き換え、決してセクションを削除しないでください（削除すると抑制的な枠組みが残り、反転はそれを置き換えます）。
• 外部由来のコピーは最新か？ — origin が外部リポジトリであり、本文がそのままのコピーであるエージェント（例：Explore などの組み込みオーバーライド）の場合、本文の先頭コメントに記載されたソースバージョンがインストールされているツール（claude --version）と一致するか。不一致は更新です（バンドルとの差分を確認し、再コピー）。抑制と過剰制約の質問は、これらのコピーではスキップされます — 本文はベンダーのものであり、私たちのものではありません。
• 本文に旧世代の過剰制約がないか？ — 現在のモデルがネイティブに保持している判断のための網羅的なステップバイステップ手順、繰り返しの強調、周囲のコンテキスト判断が所有すべき ALWAYS/NEVER ペア。フェーズ1の always_never_candidates はトークンを特定します。ヒットが単に単語を引用しているだけなのか、それとも指示であるのかを判断するのがこの質問の役割です。
• 基盤に吸収されていないか？ — ハーネスは現在、このエージェントの仕事をネイティブにカバーしているか（ネイティブレビュー機構、計画モード、組み込みスラッシュコマンド）？吸収 → 解散の候補。主張は吸収するものを具体的に指名しなければなりません。新鮮/リッチコンテキスト軸 で判断します。 新鮮な コンテキストから恩恵を受ける役割（レビュー、敵対的検証、本質評価 — 提案者のサンクコストからの非相関）は、正当にサブエージェントに存在します。リッチな コンテキストから恩恵を受ける役割（計画、生成、実装 — ユーザーの意図、会話内の制約）はメインループの仕事であり、それらについてはメインループ自体が吸収者としてカウントされます。2つの補助理論は、リッチコンテキストの引力を正当にオーバーライドします。凍結入力レンダリング契約 — 呼び出し元は呼び出し前に自己完結したパケットをフリーズするため、会話コンテキストは設計上不要（プロンプトフォージャーは意図的に1行のみを取得） — および バルクコンテキスト分離 — 作業はメインコンテキストを汚染する可能性のあるボリュームを読み取るか生成する（研究者、1回の実行につき1つのウェブ検索アングル）。
• 技術的参照は最新か？ — 無条件に検証する。本文が名前を挙げるすべてのアーティファクトについて、各参照パスを ls し、名前付きのコマンド、フラグ、モデル名、ツールリストに対して --help / バージョンチェックを実行する。「古そうなら確認する」という表現は禁止されています。条件が緩和の原因です。決定的にチェック可能な主張は、毎回、決定的にチェックされます。
• セット内で一意か？ — 同じ仕事を所有する他のエージェント（またはスキル）がいない。文書化されたオーケストレーター→サブエージェント分割は重複ではありません。

8つの質問、それ以上はありません。これ以上分解すると全体判断が劣化します（参考文献を参照）。

ステージ2 — 判定のストレステスト（Keep 以外の候補のみ）。 暫定判定を 反駁 しようとする、エージェント固有の1〜3の原子的是/否質問を生成します。各質問は1行のエビデンス（ファイル読み取り、パスチェック、--help、WebSearch、ハーネス文書チェック）で回答されます。解散 候補については、1つの質問が必須です。「吸収するハーネス機能を具体的に名前を挙げられるか — Yes/No」。吸収するものを名前を挙げられない吸収主張は反駁されます。そして、基盤側の対応物が欠いている機能（ツール、配線されたサブエージェント）によって解散が反駁されようとしている場合、反駁を受け入れる前に1つの反論質問が必須です。「その機能を使用するのにサブエージェントは適切な場所か — それともメインループもそれを保持しているか？」機能の存在は必要ですが十分ではありません。新鮮/リッチコンテキスト軸が、機能が属する場所を決定します（先例：プランナーの反駁は、メインループが完全な Agent ツールを保持しているために崩壊しました）。Keep にバインドされたエージェントには動的質問は生成されません。

評価は *