メインコンテンツへスキップ
見出し画像

失敗したらAGENTS.mdに1行追加、で本当にいいのか――AIの失敗をルールへ昇格する5段階

    あるモノレポで、AIコーディングエージェントがnpm installを実行した。対象パッケージはpnpm管理だったため、レビューで修正する。

    ここで「今後は必ずpnpmを使う」とAGENTS.mdへ追記したくなる。しかし、そのリポジトリには移行前のnpm管理ディレクトリも残っていた。全体ルールにした瞬間、別の場所では誤りになる。

    これは仮想例だが、構造はよくある。エージェントの失敗は見つかった。再発も防ぎたい。けれど、失敗をそのままルールへ変えると、指示書が太り、別の作業を縛り、何のための一文かも分からなくなる。

    この記事は、AIコーディングをチームで運用する開発責任者、アーキテクト、テックリード向けだ。失敗を見つけてから、指示・Skill・CI・権限のどこへ対策を置くかを決め、評価したルールだけを正本へ昇格する5段階を整理する。

    「失敗したら1行追加」には、原因の判定が抜けている

    AGENTS.mdやCLAUDE.mdは、モデルがコードだけから推測できないプロジェクト固有の判断を渡すのに向いている。VS Codeの公式文書も、指示を対象に合う最小スコープへ置き、代表タスクで発見・適用を確認するよう勧めている。

    一方、指示文書は操作を物理的に止める仕組みではない。禁止コマンド、機密データへのアクセス、必須テストの実行など、違反を確実に防ぎたいものは、ツール権限、hook、CI、サンドボックスの仕事になる。

    つまり、失敗の次に考えるべき問いは「何と書くか」ではない。

    この失敗は、どの制御層で再発を防ぐべきか。

    ここを飛ばして文章を増やすと、読まれない指示と、守れない禁止事項が同じファイルに積み上がる。

    5段階で、失敗をルール候補から正本へ上げる

    1. 失敗を「解釈」ではなく「証拠」で残す

    最初に残すのは反省文ではない。再現に必要な事実だ。

    • 何を依頼したか

    • 期待した結果は何か

    • 実際に何が起きたか

    • どのファイル、コマンド、出力で確認したか

    • リポジトリ、ツール、モデル、権限はどの状態だったか

    • 人は何を修正したか

    「エージェントが雑だった」では、次の対策を選べない。「packages/new-appでnpm installを実行し、pnpm-lock.yamlと不整合になった」まで書けば、対象範囲と検証条件が見える。

    2. 原因を、少なくとも6つに分ける

    同じ症状でも原因は違う。

    1. プロジェクト固有の判断が、どこにも書かれていない

    2. 指示はあるが、対象のハーネスや作業範囲から発見されていない

    3. 指示が抽象的で、どの場面に適用するか判断できない

    4. 一度きりの依頼を、永続ルールへ持ち込もうとしている

    5. 文書ではなく、CI・hook・権限で強制すべき事項である

    6. 古い指示、重複、別階層の指示と矛盾している

    原因1に対しては追記が効くかもしれない。原因2なら置き場所や適用条件の修正が先だ。原因5なら、文章を強くしても解決しない。

    3. 最も狭い場所に、最小の候補を置く

    候補ルールは、広く置くほど便利になるとは限らない。誤適用の範囲も広がる。

    • 今回だけの条件:そのタスクの依頼文

    • 特定ディレクトリや言語だけ:範囲指定した指示ファイル、入れ子のAGENTS.md

    • 複数手順を繰り返す:Skillやワークフロー

    • 違反を機械判定できる:lint、テスト、CI、hook

    • 実行自体を止めたい:ツール許可、サンドボックス、承認

    • 再発性も原因も弱い:まだルールにしない

    先ほどの例なら、「常にpnpm」では広すぎる。packages/new-app/**にだけ適用し、「この配下はpnpm workspaceに含まれるため、依存追加にはpnpmを使う」と理由を添える方がよい。

    4. 正例だけでなく、負例でも試す

    候補ルールを書いた後、同じ作業が成功すれば終わり、ではない。

    最低でも二つ試す。

    • 正例:ルールを適用すべき作業で、期待どおりに変わるか

    • 負例:ルールを適用してはいけない作業を、誤って縛らないか

    できれば新しいセッションで、対象ハーネスが指示を発見した証拠、使ったツール、最終成果を比べる。OpenAIのAgent Skill評価の記事では、初期の回帰検知には10〜20件ほどの小さな評価セットでも役立ち、呼び出すべき例と呼び出すべきでない例の両方を含める考え方が示されている。

    ルールの評価も同じだ。守ったかだけでなく、余計な場所で発火しなかったかを見る。

    5. 所有者と「消す条件」を付けて承認する

    検証に通った候補だけを正本へ入れる。そのとき、ルール本文だけを残さない。

    • 何を防ぐか

    • なぜ必要か

    • 適用範囲

    • 根拠となる失敗記録

    • 所有者

    • 再評価する条件

    • 削除または移動する条件

    たとえばパッケージ管理を統一する移行が完了したら、ディレクトリ別の例外ルールは役目を終える。廃止条件がなければ、正しかったルールほど長く残り、後から古い制約になる。

    追記前に確認する最小チェック

    新しい1行を書く前に、次の7項目だけを見る。

    • 同じ失敗をもう一度、無害な条件で再現できるか

    • 原因は「知識不足」「発見失敗」「曖昧さ」「強制力不足」「矛盾」のどれか

    • 一度きりの依頼ではなく、再利用する判断か

    • もっと狭い適用範囲にできないか

    • 文書よりCI・hook・権限で守るべきではないか

    • 正例と負例の両方で試したか

    • 見直す人と、消す条件が決まっているか

    一つでも答えが曖昧なら、まだ「承認済みルール」ではない。失敗ログか、候補ルールのまま置いてよい。

    この先で提供するもの

    ここまでで、失敗をルールへ昇格する5段階と、対策を置く場所の基準は使える。以下は、この判断をチーム運用へ持ち込むための実装キットだ。

    対象は、AGENTS.mdやCLAUDE.mdを複数人・複数エージェントで運用し、同じ指摘やレビュー手戻りを減らしたいチーム。個人で数行の指示だけを使い、まだ再発や矛盾が起きていない場合は、ここから先は不要だ。

    有料部分には、次を含む。

    • 複製して使えるRule Promotion Card

    • 原因から配置先を決める判断表

    • モノレポのパッケージ管理を題材にした記入例

    • 正例・負例を含む8ケースの評価セット

    • 導入、承認、計測、廃止までの運用手順

    特定製品の設定代行、万能なAGENTS.md完成例、モデルごとの性能保証は含まない。前提は、失敗時の依頼・出力・変更差分を安全に保存でき、テスト環境で再実行できること。情報は2026年10月7日時点。価格は100円。複数の完成資産を含む一方、この記事シリーズでは購入データがまだ少ないため、初回検証価格にしている。

    ここから先は、Rule Promotion Kitです

     
     
    ユーザー企業の立場から、生成AI活用、社内SE、システム企画・設計を考えます。AIエージェントの権限・検証・運用や設計情報の活かし方を、実務で使える判断基準として整理します。

    あなたへのおすすめ