tdd

tdd skill の概要

tdd skill は、厳密な red-green-refactor ループでテストファースト開発を進めるための実践ガイドです。単に「とりあえずテストを書いて」と指示する汎用プロンプトではありません。実装の細部ではなく、公開インターフェースを通じた振る舞いにテストを結びつけたまま、AI に機能追加やバグ修正を手伝ってほしい開発者に特に向いています。

tdd は何のための skill か

次のような進め方をモデルに取らせたいなら、Test Driven Development のための tdd を使う価値があります。

• 機能を小さな縦切りの単位で計画する
• 一度に 1 つだけ失敗するテストを書く
• テストを通すのに必要最小限のコードだけ実装する
• green のあとに安全にリファクタリングする
• 無害なリファクタで壊れる脆いテストを避ける

tdd が最もハマる人

tdd skill が特にフィットするのは、すでに次の条件がある場合です。

• 実行可能なテストを持つコードベースがある
• 対象にできる明確な public API、endpoint、command、またはユーザーフローがある
• テストコードと本番コードの両方を変更できる
• 過度な mocking より integration-style のテストを重視したい

特に、backend service、library、domain logic、実際のインターフェース経由で振る舞いを検証しやすい application flow で有効です。

この tdd skill が他と違う点

この skill の大きな違いは、テスト品質に対する考え方がかなり明確なことです。

• 内部実装ではなく振る舞いをテストする
• integration-style のテストを優先する
• mock は system boundary に限る
• 最初にテストを全部書き、後からまとめて実装する “horizontal slicing” を避ける
• TDD をカバレッジ追加の手段ではなく、より良いインターフェースを形作る手段として使う

そのため、tdd usage は単に AI に「テストと実装を書いて」と頼むよりも、かなり規律ある進め方になります。

導入の障害になりやすい点

テストを実行できない環境、安定した public seam がないコードベース、snapshot-heavy あるいは mock-heavy な unit test を主に求めるチームには、この skill は相性がやや弱めです。また、一気に完成形を生成するのではなく、小さなステップで反復する前提もあります。

tdd skill の使い方

skills 環境に tdd をインストールする

リポジトリの Skills system を使っている場合、よくあるインストール方法は次のとおりです。

npx skills add mattpocock/skills --skill tdd

その後、テストファーストのワークフローで振る舞いを実装・修正したい依頼を出す際に tdd を呼び出します。

tdd を本格利用する前に先に読むべきファイル

この skill を最短で理解したいなら、次の順で読むのが効率的です。

1. SKILL.md
2. tests.md
3. mocking.md
4. interface-design.md
5. refactoring.md
6. deep-modules.md

この順番には意味があります。SKILL.md で全体の思想をつかみ、その後のファイルで「良いテスト」「良い設計」が実務でどういうことかを具体化していきます。

tdd が前提にしている基本ワークフローを理解する

この skill は、次のような短いループを前提にしています。

1. ひとつの小さな振る舞いを選ぶ
2. public interface 経由で失敗するテストを 1 つ書く
3. そのテストを通す最小限のコードを実装する
4. テストを green のまま保ってリファクタリングする
5. 次の最小の slice で繰り返す

最初から機能全体を一括で依頼すると、tdd usage の価値はかなり薄れます。

実装案ではなく、まず振る舞いから始める

強い入力例:

• “Add checkout support for expired cards. Public entrypoint is checkout(cart, paymentMethod). Existing test file is checkout.test.ts. Keep using integration-style tests.”

弱い入力例:

• “Create classes for payment orchestration and add unit tests for each method.”

前者は skill に対して振る舞いの的を与えています。後者は内部設計の憶測や、壊れやすいテストの方向へ寄せてしまいます。

public interface と test command を必ず渡す

tdd install 後に安定して使うためにも、実行時には次の情報を含めるのが効果的です。

• テスト対象となる function、route、CLI command、または UI action
• テストファイルの場所
• test runner と実行コマンド
• DB、HTTP、外部サービスなどの制約
• mock してよいもの／してはいけないもの

実用的なプロンプトのひな型:

Use the tdd skill.

Goal: Add [behavior].
Public interface: [function/route/command].
Test location: [path].
Run tests with: [command].
Boundaries to mock: [external API, clock, filesystem].
Do not mock: [internal modules/classes].
Work in red-green-refactor steps and explain each step briefly.

horizontal slices ではなく vertical slices を使う

このリポジトリから得られる実務上の大きな学びの 1 つは、最初に大量のテストをまとめて書かないことです。ここでの良い tdd usage とは、次のような進め方です。

• 実際の 1 シナリオを選ぶ
• それを通す
• その結果を踏まえて次のシナリオを決める

このやり方のほうが、空想上の抽象化を減らし、結果として API の形も良くなりやすいです。

tdd では integration-style のテストを優先する

このリポジトリは、public API を通って実際のコードパスを動かすテストを強く支持しています。実務的には、次のような方針です。

• private helper ではなく export された function を呼ぶ
• route handler はサポートされたインターフェース経由で叩く
• 内部の呼び出し順ではなく、外から観測できる結果を検証する
• テスト名は “user can checkout with valid cart” のように能力・結果ベースで付ける

内部実装が変わっても振る舞いが同じなら、良いテストは通常そのまま green を保つはずです。

mock は system boundary だけに限定する

tdd skill は mock そのものに否定的なのではなく、自分たちの実装まで mock することに否定的です。mock してよい例は次のとおりです。

• payment gateways
• email providers
• time/randomness
• テスト構成によっては database や filesystem

mock すべきでないもの:

• 自分たちの modules
• internal collaborators
• private methods
• 自分たちが制御している薄い wrapper

このガイドライン 1 つだけでも、多くのプロンプト調整より出力品質に効きます。

コードを書きすぎる前に、テストしやすい形へ寄せる

補助ドキュメントで繰り返し強調されているのは、インターフェースが良いほど TDD はやりやすいという点です。モデルには、次のようなコードを優先するよう伝えると効果的です。

• dependency を内部生成せず受け取る
• 隠れた state を mutate するより、結果を返す
• public surface area を小さく保つ

今の設計だとテストが書きにくいなら、先に「より小さく、テストしやすい public interface を提案してから進めて」と頼むのが有効です。

tdd の強いプロンプト例

Use the tdd skill to add password reset token expiry.

Context:
- Node + TypeScript
- Public API: `requestPasswordReset(email)` and `resetPassword(token, newPassword)`
- Tests: `src/auth/password-reset.test.ts`
- Run with: `pnpm test password-reset`
- Mock only email sending and time
- Do not mock repository code or internal services

Please:
1. choose the smallest failing behavior first
2. write integration-style tests through public APIs
3. implement minimum code to pass
4. refactor after green
5. avoid asserting internal call counts unless at an external boundary

この例がうまく機能するのは、対象、boundary policy、そして実際の実行経路が明確だからです。

tdd の出力品質を見るときの主要なサイン

この skill で良い tdd guide の結果になっている場合、たいてい次の特徴があります。

• テスト名がユーザーに見える振る舞いベースになっている
• 一度に扱うのは小さなシナリオ 1 つ
• 各ステップの実装が最小限
• green のあとにリファクタリングの説明がある
• private structure への結びつきが少ない、またはほぼない

逆に質が低い出力では、次の傾向が出やすいです。

• 内部コードに対する mock が多い
• 呼び出し順の検証が多い
• 最初の一手で巨大なテスト群を書く
• 何か 1 つも振る舞いを通していないのに抽象化を先行させる

tdd skill FAQ

tdd は新規機能にしか使えませんか？

いいえ。tdd skill はバグ修正にもよく合います。成熟したコードベースでは、まず public interface 経由でバグを再現する失敗する regression test を 1 つ作り、その後に最小修正を入れて、最後に整理するのが最も自然なケースも多いです。

この tdd skill は初心者向けですか？

はい。ただし、少なくとも自分のプロジェクトでテストをどう実行するかは理解している前提です。ガイダンス自体は明快で、振る舞いをテストし、slice を小さく保ち、実装詳細へのアサーションを避ける、というものです。完全な初心者だと、プロジェクト構成やテストツールの理解で別途サポートが必要な場合はあります。

AI に「テストを書いて」と頼むのと tdd はどう違いますか？

普通のプロンプトだと、カバレッジ志向だったり mock-heavy だったりするテストが出やすくなります。tdd skill は、モデルを次の方向へ強く寄せます。

• 振る舞いベースの仕様化
• より安全なリファクタリング
• よりクリーンなインターフェース
• 小さな反復ステップ

変わるのはテストだけでなく、本番コードの設計そのものです。

どんなときは tdd を使わないほうがいいですか？

次のような状況では、Test Driven Development のための tdd は見送るか、限定的に使うのが無難です。

• その振る舞いをまだ意味のある形で実行できない
• 反復中に環境を動かすコストが高すぎる
• 探索目的の throwaway spike をしている
• リネームや依存関係更新のような、ほぼ機械的な作業が中心

ただし、public seam が明確になった段階で TDD に戻ることは十分可能です。

tdd は integration test しか前提にしませんか？

厳密には違います。ただし、軸足は real interface を通した integration-style テストにあります。目標は「とにかく大きいテスト」ではなく、「安定した seam で振る舞いを検証すること」です。小さく絞ったテストでも、public interface に留まり、内部結合を増やさないなら問題ありません。

どんな言語やフレームワークに向いていますか？

考え方そのものはかなり language-agnostic です。例は TypeScript と JavaScript に寄っていますが、明確な public interface と test boundary を定義できるなら、Python、Java、Go、Ruby など近いエコシステム全般に応用できます。

tdd skill をより良く使うには

tdd の最初の slice をもっと小さくする

tdd の結果を改善する最も簡単な方法は、最初の一歩を小さくすることです。“build user invitations” ではなく、“user with valid email can request an invitation” から始めてください。slice が小さいほど、幻覚的なアーキテクチャ生成が減り、テストもきれいになります。

boundary のルールを明示する

質の悪い出力の多くは、mocking policy が曖昧なことから起きます。モデルには次をはっきり伝えてください。

• mock してよい external system は何か
• 実体のまま扱うべき internal module は何か
• test DB が使えるか
• time は inject すべきか、freeze すべきか

これだけで、skill の出力がリポジトリの思想とかなり揃いやすくなります。

public interface ベースのテスト名を求める

より良いテストが欲しいなら、結果を表すテスト名を指定すると効果的です。

• good: user can checkout with valid cart
• weaker: checkout calls payment service

この 1 行の指示だけで、実装詳細へ流れていくのを防げることがよくあります。

red-green-refactor を見える形で強制する

最初の返答が実装の一括ダンプになってきたら、そのまま受け取らず再構成を求めてください。

• 最初の failing test を示す
• それを通す最小コードを示す
• refactor は分けて説明する
• 必要なら 1 slice で止める

tdd skill は、ループが暗黙ではなく明示されているときに最も機能します。

テストが書きにくいなら設計を疑う

モデルがきれいなテストを書けず苦戦しているなら、問題は test syntax ではなく interface design であることが少なくありません。次の方向へ設計を見直すよう依頼すると改善しやすいです。

• dependency injection
• 明示的な inputs and outputs
• より小さな public surface
• 少ない side effects

この局面では interface-design.md と deep-modules.md が特に役立ちます。

refactoring を独立した品質改善フェーズとして使う

いくつかの slice が green になったら、リポジトリの観点に沿って明示的に refactor review を依頼すると効果的です。

• duplication
• long methods
• shallow modules
• feature envy
• primitive obsession

これにより、tdd usage が「テストが通った」で止まらず、振る舞いを変えずに保守性まで改善できます。

よくある失敗パターンは早めに修正する

出力品質が落ちてきたら、原因はたいてい次のどれかです。

• 最初の failing test 前にコードを出しすぎている
• internal collaborators を過剰に mock している
• テストが実装詳細を検証している
• 機能要求が 1 サイクルで扱うには大きすぎる
• public interface が曖昧、または毎ステップ変わっている

こうなったら、1 つの振る舞い、1 つの seam、1 つの failing test に立ち戻るのが最短です。

リポジトリ内のファイルを判断材料として使う

より良い結果のために、課題に応じて補助ドキュメントを引き分けてください。

• テストの書き方が弱いなら tests.md
• boundary の判断が曖昧なら mocking.md
• seam が不自然なら interface-design.md
• green の後なら refactoring.md
• API の形が広がりすぎているなら deep-modules.md

SKILL.md だけをざっと読むより、この読み分けのほうが実際には役立ちます。

同じプロンプトを繰り返すのではなく、制約を絞って反復する

最初の出力が今ひとつでも、ただ “try again” と言うだけでは改善しにくいです。次のラウンドでは、制約を具体的に追加してください。

• 対象は 1 つの振る舞いだけにする
• 現在の public API を維持する
• internal module は mock しない
• repository mocks より test DB を優先する
• 最初の red-green-refactor cycle で止める

この種の反復のほうが、単に詳細を増やしてと頼むより tdd guide の品質を安定して引き上げられます。