mattpocock Skills 入門ガイド: AIにTDDと構造化デバッグを身につけさせる

プロジェクト概要

mattpocock/skills は、AI プログラミングツールのための「工学的メソドロジー（方法論）スキルパック」です。出発点はとてもシンプルです。AI コーディングツールは速いが、それで“信頼できる”とは限らない。

Matt Pocock は大量の実践から、AI プログラミングで頻出する失敗パターンが4つあることを見つけました。

• 要件のズレ：AI が理解したと思ったら、実際はどこか別の方向へ走っている
• 出力が冗長：AI が 20 語で済む話を、30 語（あるいはそれ以上）で説明してしまう
• コードが work しない：フィードバックループがなく、AI がブラックボックスの中で闇雲に書いてしまう
• アーキテクチャが速攻で崩れる：AI が開発を加速することで、ソフトウェアの“エントロピー（劣化）”も加速してしまう

これら4つの問題はツールのバグではなく、方法論の欠如です。mattpocock/skills はその“本丸”を狙い、decades 級のエンジニアリング経験を、組み合わせ可能な技能群（Skills）へ圧縮します。そうすることで、AI はどのモデルでも同じ工学的な規律に従います。

難易度 / 所要時間 / 得られるもの

難易度：入門レベル — TDD の経験は不要。コマンドラインと AI コーディングツールの使い方が分かっていればOK
所要時間：プロセスを一通り最後までやって約 30 分
得られるもの：要件のアラインメント → テスト駆動 → 構造化デバッグ → アーキテクチャの振り返りまでを一気通貫で回すワークフロー一式

対象読者

• 経験 1〜5 年のバックエンド / フルスタック開発者
• すでに Claude Code、Codex、または同種の AI コーディングツールを使っている
• AI が生成したコードは「動くけど不安定」で、コントロールできる開発ペースを作りたい
• TDD に興味はあるが、これまで適切な入り口が見つからなかった

コア依存と環境

完全なプロジェクト構造ツリー

skills/
├── CLAUDE.md                          # スキルディレクトリの規約説明
├── README.md                          # 概要と利用ドキュメント
├── skills/
│   ├── engineering/
│   │   ├── diagnose/
│   │   │   └── SKILL.md               # 構造化デバッグの手順
│   │   ├── grill-with-docs/
│   │   │   └── SKILL.md               # 付属ドキュメントを深掘りするインタビュー
│   │   ├── improve-codebase-architecture/
│   │   │   └── SKILL.md               # アーキテクチャ改善の診断
│   │   ├── setup-matt-pocock-skills/
│   │   │   └── SKILL.md               # 初期化設定の入口
│   │   ├── tdd/
│   │   │   ├── SKILL.md               # TDD の縦スライス・ワークフロー
│   │   │   ├── tests.md               # 良い / 悪いテストの例
│   │   │   ├── mocking.md             # Mock のベストプラクティス
│   │   │   ├── refactoring.md         # リファクタリングのタイミング判断
│   │   │   ├── deep-modules.md        # 深いモジュール設計の原則
│   │   │   └── interface-design.md    # テスト可能なインターフェース設計
│   │   ├── to-issues/
│   │   │   └── SKILL.md               # 要件を GitHub Issues に分解
│   │   ├── to-prd/
│   │   │   └── SKILL.md               # PRD 生成
│   │   ├── triage/
│   │   │   └── SKILL.md               # Issue 分診の状態機械
│   │   └── zoom-out/
│   │       └── SKILL.md               # コード全体視点での読み解き
│   ├── productivity/
│   │   ├── caveman/
│   │   │   └── SKILL.md               # 圧縮コミュニケーション（トークンを 75% 削減）
│   │   ├── grill-me/
│   │   │   └── SKILL.md               # 要件の深掘りインタビュー
│   │   └── write-a-skill/
│   │       └── SKILL.md               # 自作スキルの作成ガイド
│   └── misc/
│       ├── git-guardrails-claude-code/
│       │   └── SKILL.md               # Git のセーフティガード
│       └── scaffold-exercises/
│           └── SKILL.md               # 演習ディレクトリの雛形
└── .claude-plugin/
    └── plugin.json                    # プラグインのメタデータ

手順を順に進める

Step 1: mattpocock Skills をインストール

Skills に対応した任意の AI コーディングツールで、以下のコマンドを実行してインストールしてください：

npx skills@latest add mattpocock/skills

インストールスクリプトが、有効化するスキルの選択と、それらのスキルをどの AI ツールに紐づけるかを案内します。重要なステップ：/setup-matt-pocock-skills を選択していることを確認してください。これは以降すべてのスキルの初期化入口です。

Step 2: 初期設定を行う

インストールが完了したら、AI コーディングツール上で次を実行します：

/setup-matt-pocock-skills

この Skill は順番に次を質問します：

1. Issue Tracker：Issues を管理するツールは何を使いますか（GitHub / Linear / ローカルファイル）
2. Triage Labels：Issue にラベルを付けるときに使う語彙（/triage スキルで使用されます）
3. ドキュメントの保存先パス：生成される ADR とドキュメントはどこに置くか

設定が完了すると、プロジェクトのルートディレクトリに CONTEXT.md が生成されます。これは AI とあなたの間の「共有言語の辞書」です。このファイルは非常に重要です——プロジェクト内の用語の使い方を統一し、以降のすべての命名や注釈がこれに基づいて行われます。

Step 3: /grill-me で要件をアラインする

新しい要件や設計案を AI に渡したいとき、いきなり着手しないでください。まずこれを実行します：

/grill-me

AI は決定木の各分岐を漏れなく洗い出すように、1つずつ質問してきます。たとえば「支払いモジュールに返金機能を追加する」なら、AI はこう追問します：

• 返金は全額か一部か？
• 返金のトリガー条件は何か（ユーザー主導 / 风控自動 / カスタマーサポート手動）？
• 返金後の在庫はどう扱う？
• 返金ログは永続化が必要か？

各質問に対して回答案を提示してくれるので、あなたはそれを確認するか、必要なら修正するだけです。このプロセスは構造化されたインタビューのようなもので、AI が「あなたが何をやりたいのか」を本当に理解していることを確認し、文字通りの思い込みでズレるのを防ぎます。

Step 4: /tdd で縦スライスのテスト駆動開発

要件をアラインしたら、開発フェーズへ進みます。ここが mattpocock/skills の最重要パートです——水平スライスは禁止。

水平スライスとは何でしょう？まず全部のテストを書き、次に全部のコードを書き切ることです。TDD の誤解が集中する地雷で、AI は特にこのやり方をしがちです。その結果、テストが検証しているのは「想像上のふるまい」であり、「実際のふるまい」ではありません。

正しいやり方は、一度に1つだけ縦スライスを行うことです。

RED:   テストを書いて、最初の挙動を記述する → テスト失敗
GREEN: テストを通すための最小コードを書く → テスト成功
REFACTOR: リファクタリング（任意）

このループを繰り返します。AI はテストを書くたびに、その実装コードを「すでに見ている」状態になるため、検証しているのは期待値ではなく実際の挙動です。

具体例を見てみましょう。仮に、カートの決済機能を実装するとします。

// 1周目：まず「カートに商品を追加できる」だけをテストする
import { describe, it, expect } from 'vitest';
import { Cart } from './cart';

describe('Cart', () => {
  it('allows adding an item', () => {
    const cart = new Cart();
    cart.addItem({ id: 'book-1', name: 'TypeScript 入門', price: 59 });
    expect(cart.items).toHaveLength(1);
  });
});

// cart.ts — テストを通すための最小実装
export interface CartItem {
  id: string;
  name: string;
  price: number;
}

export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }
}

// 2周目：「カートが合計金額を計算できる」ことをテストする
it('calculates total price', () => {
  const cart = new Cart();
  cart.addItem({ id: 'book-1', name: 'TypeScript 入門', price: 59 });
  cart.addItem({ id: 'book-2', name: 'React 実戦', price: 79 });
  expect(cart.totalPrice()).toBe(138);
});

// cart.ts — totalPrice メソッドを追加
export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }

  totalPrice(): number {
    return this.items.reduce((sum, item) => sum + item.price, 0);
  }
}

各周の基本は：テスト失敗 → 最小コードで通す → 次の周へ。これが縦スライスの肝となるリズムです。

Step 5: /diagnose で構造化デバッグ

コードに問題が出たとき、AI に「バグを直して」といきなり頼むのはやめましょう。まずフィードバックループを構築して、次を実行します：

/diagnose

/diagnose は、AI に次の6段階のデバッグループを強制的に完走させます：

なぜこのプロセスが重要？ AI の最もよくあるデバッグ手法は「当てずっぽうで直して、結果を見て、違ったらまた推測する」というものです。フィードバックループがない場合、それは暗闇でダーツを投げているのと同じです。/diagnose により、デバッグは“工学”になり、魔術ではなくなります。

典型的なシーン——たとえば、支払いAPIが突然 500 エラーを返すとします。

// 段階 1：フィードバックループを構築 — 失敗を特定できるテストを書く
import { describe, it, expect } from 'vitest';
import { createHonoServer } from './server';
import fetch from 'node-fetch';

describe('Payment API', () => {
  it('returns 200 for valid checkout', async () => {
    const app = createHonoServer();
    const response = await fetch('http://localhost:3000/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ id: 'book-1', quantity: 1 }],
        userId: 'user-123',
      }),
    });
    expect(response.status).toBe(200); // 現時点では失敗。実際は 500 を返している
  });
});

段階 3 では仮説リストが生成されます。

1. もし「在庫サービスのタイムアウトが未捕捉例外につながっている」なら、在庫サービスをモックして成功を返せば 500 は消える
2. もし「データベーストランザクションがコミットされていない」なら、transaction.commit() の呼び出しを確認すれば問題が見つかる
3. もし「決済ゲートウェイのレスポンス形式のパースエラー」なら、ゲートウェイのモックデータの形式を検証すれば再現できる

AI は、変更をまとめて一気に試すのではなく、仮説を 1つずつ検証します。

Step 6: /write-a-skill でカスタムスキルを作る

あるプロジェクトで積み上げた一連の専用ワークフローがあるなら、それを Skill に封入して、このプロジェクトでいつでも AI が呼び出せるようにできます。

/write-a-skill

AI は順番に質問します：

1. この Skill がカバーする領域は？
2. 具体的な利用シーンは？
3. スクリプトも添付が必要か、それとも純粋な指示だけか？
4. 参考資料はあるか？

その後、標準構造を生成します。

my-custom-skill/
├── SKILL.md              # メイン指示ファイル（必須）
├── REFERENCE.md          # 詳細ドキュメント（100行を超える場合は分割）
├── EXAMPLES.md           # 使用例
└── scripts/
    └── helper.ts         # ツール用スクリプト（任意）

SKILL.md の description フィールドは、この Skill を AI が認識する唯一の入口であり、フォーマットには厳密な要件があります。

---
name: my-custom-skill
description: JSON Schema から型安全な API クライアントを生成し、Mock データを注入する。
              Use when user mentions "API client", "generate types", or "mock data".
---

description の 1文目で「何をするか」を述べ、2文目で「どんな場面で発火するか」を述べます。さらにトリガーワードで AI が自動的にこの Skill を読み込めるようにします。

よくある問題の切り分け

1. AI がテストを実行せずにコードを書き始める

現象：/tdd を呼び出したのに、AI が実装へ直行し、RED フェーズを飛ばす。

切り分け：

• CONTEXT.md にプロジェクトのテストフレームワークとテストの約束事が定義されているか確認
• /tdd 開始時に「テストを1つだけ書き、それ以外のコードは書かない」と明確に伝える
• それでも AI が飛ばす場合、会話内で手動に「まず失敗するテストを書く」と入力して RED に戻す

原因：AI が TDD の概念を文字どおりに理解してしまっている——「テストを書いた」ことをもって TDD と見なしており、「テスト失敗そのものがシグナルである」ことを理解していない。

---

2. 水平スライスの罠——テストを一気に全部書く

現象：AI が /tdd の中で 10 個のテストファイルを一度に生成し、その後にすべての実装も一気に書き切る。

切り分け：

• 直接介入：AI に「最初のテストだけ書いて、それを実装して」と伝える
• CONTEXT.md に反パターン警告を追記：「水平スライスは禁止。毎回1つだけ縦スライスを行う」

原因：AI は「一気に片付ける」幻覚が好きであり、水平スライスは“完成している感じ”を与える一方で、実際には成果物が脆くなります。

---

3. デバッグループにフィードバックシグナルがない

現象：/diagnose を呼び出しているのに、AI はコードを繰り返し直すだけで、再現可能な失敗シグナルを作らない。

切り分け：

• Phase 1 が通っていないなら Phase 2 に進まない。AI に「まだ再現可能な失敗シグナルがない。フィードバックループを作り続けて」と明確に伝える
• node-fetch と実際の HTTP リクエストを使って、モジュール全体をモックするのではなく、E2E シグナルを構築してみる

原因：フィードバックループこそがデバッグの核です。これがなければ、その後のすべてのアクションは行き当たりばったりになります。

---

4. スキル説明が機能しない——Skill が自動でトリガーされない

現象：カスタム Skill を書いたのに、AI がロードしない。

切り分け：

• plugin.json にその Skill が登録されているか確認
• description にトリガーワード（ユーザーが実際に口にする語彙）が含まれているか確認
• SKILL.md の name と description のフォーマットが要件どおりか確認（YAML frontmatter）

原因：Skills のロードは description 内のキーワード一致に依存しており、説明が精密でないとトリガーされません。

---

5. /grill-me のインタビューが一方通行の報告になる

現象：/grill-me を実行すると AI はあなたの情報を受け取るだけで、主導して質問しない。

切り分け：

• AI が質問するときに「インタビューモードに入った」と説明したら、そのまま回答を続けて中断しない
• AI が3ターン以上黙った場合は、手動で「質問を続けて。まだ他にも情報がある」と言う
• 根本原因は、AI が「もう理解した」と思っていて、実際には文字どおりの理解にとどまっていることが多い

原因：AI は、すべての分岐を洗い出すよりも「理解できたように見える状態」に素早く収束しがちです。

---

6. CONTEXT.md が大きすぎて token が爆発する

現象：プロジェクトが進むにつれて CONTEXT.md がどんどん大きくなり、AI が文脈オーバーフローを起こしたり、応答が遅くなったりする。

切り分け：

• 定期的に CONTEXT.md をリファクタして、「すでに安定している汎用用語」は残し、「一時的な意思決定記録」は docs/adr/ ディレクトリへ移す
• /improve-codebase-architecture を使うと、CONTEXT.md から抽出すべき内容を見つけるのに役立ちます

原因：CONTEXT.md は動的に増殖するファイルで、メンテしないと2つ目の monorepo になってしまいます。

追加の読み物 / さらなる発展

方法論の拡張：Matt Pocock 本人は TypeScript の型体操を推進する立場で、彼の Total TypeScript コースは、型駆動開発を理解するための優れた補完です。

TDD からアーキテクチャ改善へ：コードベースが数ラウンドの TDD リファクタリングを経たら、/improve-codebase-architecture でアーキテクチャ診断を行えます。これは CONTEXT.md のドメイン言語と docs/adr/ の意思決定記録に基づき、「浅いモジュール」（インターフェースは複雑だが機能が少ない）や、リファクタリングの機会を識別します。

カスタムスキルのエコシステム：mattpocock/skills の設計思想は「小さくて組み合わせ可能」。提供されている全スキルを使う必要はありません。まずは /tdd と /diagnose だけ導入し、日常開発の中で段階的に取り入れていけます。このフレームワークに基づいてスキル群を構築している他の開発者もいます。注目する価値があります。