Matt PocockのスキルツールキットでAIエージェントを飼い慣らす方法

開発者がClaude CodeやCodexと緊密に合作し始めると、すぐに同じ壁にぶつかる。エージェントは気軽にタスクに合意し、5分間のコード作成に出かけ、壊れたスパゲッティコード500行を戻してくる。身に覚えはないだろうか？ Total TypeScriptの著者であるMatt Pocockは、この問題にエンジニアリングの規律で挑み、AIエージェント向けの実用的な指示（スキル）のリポジトリを作成した。そしてvinvcn/mattpocock-skills-zh-CNプロジェクトが、このツールキット全体を中文言語モデルや混合コンテキストでの作業用に改変した。

これは開発の未来についての抽象的な議論ではない。言語モデルに、整頓された中堅またはシニア開発者のように行動させるための具体的なコマンドとシナリオの組み合わせだ。

エージェントが一般的に失敗する4つのシナリオ

Mattは、AIにタスクを引き渡す際に開発者がよく陥る典型的な落とし穴を特定し、それぞれに対して個別の作業プロトコルを作成した。

エージェントが依頼した内容と全く違うことをする

最も一般的な開発上の頭痛の種は、期待値の不一致と呼ばれる。人があるアーキテクチャを思い描き、モデルが自分の口味で詳細を埋める。このギャップを埋めるために、著者は/grill-meコマンド（とそのエンジニアリング変種である/grill-with-docs）を生み出した。

コードに触れる前に、エージェントは正式な尋問を行う。エッジケース、データ構造、インターフェース要件について、的を絞った一連の質問をする。決定木が収束するまで、モデルは1行も書かない。これにより、コードの書き直しに何時間も費やすことを節約できる。

モデルがコンテキストを不必要なおしゃべりに浪费する

エージェントが見知らぬプロジェクトに入ると、独自の用語を作り始め、明白なことを説明するのに何十ものトークンを費やし始める。解決策は、统一されたドメイン語彙を含むドキュメントを作成することだ（プロジェクトではCONTEXT.mdと呼ばれている）。

/grill-with-docsコマンドは単に調査するだけでなく、プロジェクトの用語とアーキテクチャ上の決定（ADR）を即座に記録する。あなたとエージェントが共通言語を共有するようになると、対話が劇的に減り、コード内の変数名がすべてのモジュールで統一して命名されるようになる。

生成されたコードが動かない

モデルがフィードバックなしでコードを書くと、盲目的に作業ことになる。テストが必要だ。/tddスキルは、エージェントにRed-Green-Refactorサイクルを厳密に遵守させる。最初にモデルが失敗するユニットテストを書き、次にテストをパスするために必要な最小限のコードを実装し、その後に初めてクリーンアップを行う。

複雑なバグに対しては、別の/diagnosing-bugsシナリオがある。これは厳格なプロトコルを通じてモデルを導く：テストでエラーを再現し、検索範囲を絞り込み、仮説を立て、ロギングを追加し、コードを修正し、回帰テストを実行する。

アーキテクチャがごちゃごちゃになる

コード生成の速度がエントロピーの成長を促進する。プロジェクトが一つの絡み合ったスパゲッティにならないようにするために、/improve-codebase-architectureコマンドが使用される。

これはプロジェクトをスキャンし、深いモジュール（シンプルな公開インターフェースと隠された複雑なロジックを持つ）の候補を探し、レポートを生成する。本質的には、ターミナル内で定期的なコード品質監査を行うものだ。

なぜ中国語にローカライズしたのか

元のリポジトリは英語書かれているが、vinvcnのローカライズには興味深い技術的な目的がある。それは単に中国語話者の開発者のためだけではない。

QwenやDeepSeekのようなアジアのLLMで作業する場合、中国語のシステムプロンプトと指示はコンテキストロスを減らす。モデルは表現のニュアンスに惑わされることが少なくなる。一方、すべての識別子、コマンド名、ファイルパス、設定キーは英語のまま残す。スクリプト実行時に何も壊れない。

スキルのアーキテクチャの仕組み

リポジトリ内のすべてのスキルは2つのカテゴリに分類される：

1. ユーザー起動型コマンド。これらは人間がスラッシュ経由で手動でトリガーする。例えば、/ask-mattは現在の手タスクに合ったスキルを選択するのを助け、/to-specは議論をチケットにまとめ、/wayfinderは数セッション先の主要な機能を計画する。
2. モデル起動型スキル。ユーザーとエージェントの両方が、適切なサブタスクを見つけたときに自発的にトリガーできる。これにはTDDサイクル、ハード中断なしのgitコンフリクト解決、コードレビュー、下書き作成が含まれる。

スキルは指示を含むシンプルなMarkdownファイルとして書かれている。読みやすく、チームルールに合わせて編集することも簡単だ。

数分でのセットアップ

skills.shインストーラーを使用して、スキルをプロジェクトに追加できる：

npx skills@latest add vinvcn/mattpocock-skills-zh-CN

ユーティリティは、どのスキルをコピーし、どのエージェントディレクトリに登録するか尋ねる。必ず/setup-matt-pocock-skillsを選択するように。

インストール後、エージェントの対話内で初期セットアップを実行する：

/setup-matt-pocock-skills

エージェントは、タスクを追跡する場所（GitHub Issues、Linear、またはローカルファイル）、トリアージに使用するラベル、アーキテクチャドキュメントを保存するフォルダを確認してくる。

Claude Codeで作業しており、すべてのリポジトリにファイルのコピーを保存したくない場合は、スキルをプラグインとして接続できる：

claude plugin marketplace add vinvcn/mattpocock-skills-zh-CN
claude plugin install mattpocock-skills@mattpocock

このモードでは、新しいバージョンがリリースされるとスキルが集中管理で更新される。

誰が使うべきか

2つのカテゴリーのエンジニアがこのリポジトリを检討すべきだ。

まず、Claude Code、Codex、またはOpenCodeInterpreter активно используют и устали бороться с галлюцинациями модели. Подход Мэтта Покока возвращает предсказуемость в разработку через строгие ограничения и короткие циклы обратной связи.

Во-вторых, это отличный пример того, как писать системные инструкции для AI-ассистентов. Даже если вам не нужна китайская локализация, структура файлов в этом репозитории дает четкий урок по проектированию навыков для агентов. Попробуйте включить пару команд, таких как /grill-me, в свой ежедневный рабочий процесс, и к вечеру вы заметите разницу.