エージェントスキル：AIコーディングエージェントに優れたエンジニアリングプラクティスを守らせる

以下の記事は、もともとAddy Osmani氏のブログに掲載されたもので、著者の許可を得て転載しています。

AIコーディングエージェントのデフォルトの動作は、「完了」への最短ルートを取ることです。機能を要求すると、その機能を書きます。仕様があるかどうか尋ねることも、実装前にテストを書くことも、変更が信頼境界を越えるかどうかを考慮することも、PRがレビュー担当者にどのように見えるかを確認することもありません。コードを生成し、勝利を宣言して、次に進みます。

これは、すべてのシニアエンジニアがキャリアを通じて避けることを学んできたのと同じ失敗パターンです。タスクのシニアバージョンには、差分に現れない作業が含まれます：前提を明らかにすること、仕様を書くこと、作業をレビュー可能なチャンクに分割すること、退屈な設計を選択すること、結果が正しいという証拠を残すこと、人間が実際にレビューできるように変更のサイズを調整すること。これらのステップは、大規模で信頼性の高いソフトウェアを出荷するエンジニアと、壊れるコードをプッシュする人々を分けるものの大部分です。

エージェントがこれらのステップをスキップする理由は、ジュニアエンジニアがそうするのと同じです。それらは見えないのです。報酬信号は「タスク完了」を指しており、「タスク完了かつ設計ドキュメントが存在する」ではありません。そのため、シニアエンジニアの足場を再び取り付ける必要があります。

Agent Skillsは、その足場への私の試みです。ちょうど27,000スターを超えたところで、明らかに私だけがこれを欲しがっているわけではありません。この記事はREADMEが完全にはカバーしていない部分です：各設計選択が存在する理由、それが標準的なSDLCとGoogleの公開エンジニアリングプラクティスにどのようにマッピングされるか、そしてスキルを一つもインストールしなくてもプロジェクトから盗むべきもの。

スキルとは実際には何か

「スキル」という言葉は、Claude Code/Anthropicの語彙で多くの重みを持っており、正確に理解することが役立ちます。スキルは、フロントマター付きのMarkdownファイルであり、状況に応じてエージェントのコンテキストに注入されます。システムプロンプトの断片とランブックの中間のようなものです。

スキルはリファレンスドキュメントではありません。「テストについて知っておくべきすべて」ではありません。それはワークフローです：エージェントが従う一連のステップで、証拠を生成するチェックポイントがあり、定義された終了基準で終わります。

この区別がすべての鍵です。テストのベストプラクティスに関する2,000語のエッセイをエージェントのコンテキストに入れると、エージェントはそれを読み、もっともらしいテキストを生成し、実際のテストをスキップします。そこにワークフローを置くと（最初に失敗するテストを書き、実行し、失敗するのを見て、合格するための最小限のコードを書き、合格するのを見て、リファクタリングする）、エージェントはやるべきことがあり、あなたは検証すべきものがあります。

プロセスを散文よりも。ワークフローをリファレンスよりも。終了基準のあるステップを、それなしのエッセイよりも。この単一の区別が、有用なスキルを単なるきれいなMarkdownファイルから分けます。また、なぜ多くの「AIルール」リポジトリが実際には何も機能しないのかを説明します。ルールはエッセイだからです。

スキルがエンコードするSDLC

リポジトリ内の20のスキルは、6つのライフサイクルフェーズの周りに編成され、上部に7つのスラッシュコマンドがあります。定義（/spec）は、実際に何を構築するかを決定する場所です。計画（/plan）は作業を分解します。構築（/build）は垂直スライスで実装します。検証（/test）は機能することを証明します。レビュー（/review）は見逃したものをキャッチします。出荷（/ship）は安全にユーザーに届けます。/code-simplifyは全体の下部に位置します。

これは偶然ではありません。これはすべての機能するエンジニアリング組織が実行するのと同じSDLCであり、単に語彙が異なるだけです。Googleはそれを設計ドキュメント→レビュー→実装→可読性レビュー→起動チェックリストと呼びます。Amazonはそれを逆向き作業メモとバーレイザーと呼びます。すべての健全なチームにはこのループの何らかのバージョンがあります。

AIコーディングエージェントで新しいのは、ほとんどのエージェントがデフォルトでこれらのフェーズのほとんどをスキップすることです。機能を要求すると、実装が得られますが、仕様、計画、テスト、レビュー、起動チェックリストはすべて単に発生しません。スキルは、シニアエンジニアが自分自身に強制するのと同じフェーズをエージェントに通させます。なぜなら、それらなしでコードを出荷することは、インシデントを発生させる方法だからです。

複雑な機能は、順番に11のスキルをアクティブにするかもしれません。小さなバグ修正は3つを使用するかもしれません。ルーター（using-agent-skills）がどれが適用されるかを決定します。ポイントは、ワークフローが想定された範囲ではなく、実際の範囲にスケーリングすることです。

機能している5つの原則

プロジェクトの5つの設計決定が耐荷重壁です。システムの残りはそれらに従います。

**1. プロセスを散文よりも**

既にカバーしました。ワークフローはエージェントがアクション可能です；エッセイはそうではありません。人間のチームにも同じことが言えます。チームのハンドブックが200ページある場合、時間的プレッシャーの下で誰もそれを読みません。チェックポイント付きの小さなワークフローのセットであれば、人々は実際にそれを実行します。

**2. 反合理化テーブル**

これはプロジェクトの中で最も特徴的な設計決定であり、他のチームに最も盗んでほしいものです。

各スキルには、エージェント（または疲れたエンジニア）がワークフローをスキップするために使うかもしれない一般的な言い訳の表と、それに対する書面による反論が含まれています。原文に近いいくつかの例：

• 「このタスクは単純すぎて仕様は必要ない」 → 受け入れ基準は依然として適用されます。5行で十分です。0行はダメです。
• 「後でテストを書く」 → 「後で」は耐荷重語です。後でなんてありません。最初に失敗するテストを書いてください。
• 「テストが通った、出荷しよう」 → テストが通ることは証拠であり、証明ではありません。ランタイムを確認しましたか？ユーザーに見える動作を検証しましたか？人間が差分を読みましたか？

これが機能する理由は、LLMが合理化に非常に優れているからです。LLMは、なぜこの特定のタスクに仕様が必要ないのか、またはなぜこの特定の変更がレビューなしでマージしても問題ないのかを説明する、もっともらしい段落を生成します。反合理化テーブルは、エージェントがまだ言っていない嘘に対する事前に書かれた反論です。

このパターンは人間のチームにも同様に有効です。ほとんどのエンジニアリングの衰退は、誰かが悪い仕事をすることを選んでいるからではありません。人々が、やりたくない部分をスキップするためにもっともらしい正当化を受け入れているからです。反合理化を書き留めたチームは、それらが少ないチームです。

**3. 検証は不可譲**

すべてのスキルは具体的な証拠で終了します。テストが通る。ビルド出力がクリーン。ランタイムトレースが期待される動作を示す。レビュー担当者が承認する。「正しいように見える」では決して十分ではありません。

これは、Anthropicのハーネスが障害から回復できるようにし、Cursorのplanner/worker/judge分割が実際にバグをキャッチできるようにし、長時間実行されるエージェントを回復可能にするのと同じ原則です。エージェントは生成器です。作業が完了したという独立した信号が必要です。スキルはその信号をすべてのワークフローに組み込んでいます。

**4. 段階的開示**

セッション開始時に20のスキルすべてをコンテキストにロードしないでください。フェーズに基づいてアクティブにしてください。小さなメタスキル（using-agent-skills）がルーターとして機能し、現在のタスクにどのスキルが適用されるかを決定します。

これは、スキルの粒度に適用されたハーネスエンジニアリングの教訓です。コンテキストにロードされたすべてのトークンはどこかでパフォーマンスを低下させるため、関連するものだけをロードし、残りはディスクに置いておきます。段階的開示は、20スキルのライブラリを5Kトークンのスロットに、井戸を汚染せずに入れる方法です。

**5. スコープ規律**

メタスキルは、できればすべてのエージェントに留めたい不可譲の要件をエンコードしています：「依頼されたものだけに触れること」。隣接するシステムをリファクタリングしない。完全に理解していないコードを削除しない。TODOに遭遇したからといってファイルを書き換えると決めない。

これは、エージェントが1つのバグを修正するために3つの無関係なファイルを近代化する必要があると決定するのを見るまでは明白に聞こえます。スコープ規律は、エージェントのPRがマージ可能か、元に戻さなければならないかを決定する最大の単一要因です。また、Googleのコードレビューノルムに最もきれいにマッピングされる原則でもあり、そこでレビュー担当者は複数のことを行うPRをブロックします。

GoogleのDNA

スキルは、『ソフトウェアエンジニアリング at Google』とGoogleの公開エンジニアリング文化からの実践で飽和しています。これは意図的です。Google規模のソフトウェアを機能させるもののほとんどは文書化され公開されており、それはエージェントが最もスキップしやすい部分です。

どのスキルがどの実践をエンコードするかの部分的なマップ：

• Hyrumの法則はapi-and-interface-designに。APIのすべての観察可能な動作は最終的に誰かに依存されるので、それを念頭に置いて設計してください。
• テストピラミッド（約80/15/5）とBeyoncéルールはtest-driven-developmentに。「あなたがそれを気に入ったなら、テストを書くべきだった」。インフラストラクチャの変更はバグをキャッチしません；テストがキャッチします。
• テストにおけるDAMP over DRY。Googleのテスト哲学は、テストコードはたとえ多少の重複を犠牲にしても仕様のように読めるべきであると明確に述べています。過度に抽象化されたテストは既知のアンチパターンです。
• 約100行のPRサイズ、code-review-and-qualityでのCritical/Nit/Optional/FYI重大度ラベル。Googleのコードレビューノルムから直接。大きなPRはレビューされず、ゴム印が押されます。
• Chestertonのフェンスはcode-simplificationに。なぜそこに置かれたのかを理解するまで物を削除しないでください。
• トランクベース開発とアトミックコミットはgit-workflow-and-versioningに。
• シフトレフトとフィーチャーフラグはci-cd-and-automationに。問題をできるだけ早くキャッチし、デプロイをリリースから切り離します。
• コードは負債としてdeprecation-and-migrationに。保持するすべての行は永遠にメンテナンスしなければならないため、より小さな表面を優先します。

これらは新しいアイデアではありません。ポイントは、それらがデフォルトでエージェントに備わっていないことです。フロンティアモデルは訓練データで「Hyrumの法則」というフレーズを読んでいますが、午前3時にAPIを設計するときにHyrumの法則を適用しません。スキルはそれを確実に適用させる方法です。

実際の使用方法

3つのモード。おおよそのコミットメントの増加順。

モード1：マーケットプレイスからインストール。Claude Codeを使用している場合：

/plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills

スラッシュコマンド（/spec、/plan、/build、/test、/review、/ship、/code-simplify）を取得し、エージェントがコンテキストに基づいて関連スキルを自動的にアクティブにします。これがほとんどの人に始めることをお勧めするパスです。

モード2：Markdownを選択したツールにドロップ。スキルはフロントマター付きのプレーンなMarkdownです。Cursorユーザーは.cursor/rules/に配置します。Gemini CLIには独自のインストールパスがあります。Codex、Aider、Windsurf、OpenCode、システムプロンプトを受け入れるものはすべて読み取ることができます。ツールは重要ではなく、その下のワークフローが重要です。

モード3：仕様として読む。何もインストールしなくても、スキルはAIエージェントを使った優れたエンジニアリングがどのように見えるかの文書化された説明です。code-review-and-quality.mdを読み、5軸フレームワークをチームのレビュープロセスに適用してください。test-driven-development.mdを読み、ジュニアとの次の「最初にテストを書く必要があるか」という議論を解決するために使用してください。メタスキルを読み、5つの不可譲の要件をあなた自身のAGENTS.mdに盗んでください。

この3つ目のモードが実際に始める場所です。現在の痛みに最も近い4つか5つのスキルを選んでください。どのワークフローを強制したいかを決めてください。その後、ランタイムをインストールするか、独自のものを作成して強制を行ってください。

インストールしなくても盗むべきもの

プロジェクトからのいくつかのパターンで、AIコーディングエージェントをまったく使用しない場合でも盗むことをお勧めします：

反合理化をチームプラクティスとして。チームが自分自身に言う嘘を書き留めてください。「テストはリリース後に修正する」「この変更は小さすぎて設計ドキュメントは不要」「大丈夫、監視がある」。それぞれに反論をペアにしてください。それをAGENTS.mdまたはエンジニアリングWikiに置いてください。議論を節約し、次の疲れた金曜午後のショートカットをキャッチします。

内部で書くものすべてに対してプロセスを散文よりも。もし「Xにどのようにアプローチするか」というタイトルの2,000語のドキュメントを書いていることに気づいたら、それはリファレンス資料です。チェックポイント付きのワークフローに変換してください。ドキュメントは400語に縮まり、人々は実際にそれを実行します。これはオンボーディングガイドやランブックだけでなく、エージェントスキルにも同様に適用されます。

検証をハードな終了基準に。すべてのタスクの終了ステップを「証拠を生成する」にしてください。エージェントにも、エンジニアにも、自分自身にも。証拠とは、作業が完了したことを証明するもの：グリーンテストラン、スクリーンショット、レビュー担当者の承認。証拠が生成されなければ、タスクは完了していません。

これらのパターンこそが、Agent Skillsプロジェクトが提供するものです。たとえインストールしなくても。