tdd-guide

tdd-guide skill の概要

tdd-guide の用途

tdd-guide は、ユニットテストの生成、カバレッジ不足の発見、fixture や mock の作成、一般的な技術スタックでの red-green-refactor の進行を支援する Test Driven Development 向け skill です。AI アシスタントに単に「テストを書いて」と頼む以上のことをさせたい場合に特に役立ちます。この skill は、会話の焦点をソースコード、要件、対象フレームワーク、カバレッジレポート、検証基準へ自然に寄せてくれます。

向いているユーザーとプロジェクト

tdd-guide skill は、TypeScript、JavaScript、Python、Java で開発するエンジニアリングチーム、個人開発者、QA 寄りのコントリビューターに適しています。特に Jest、Pytest、JUnit、Vitest、Mocha 形式のワークフローと相性があります。既存コードにテストを追加する、新機能をテストファーストで始める、一定のしきい値に向けてカバレッジを改善する、チーム内でテスト出力の形式をそろえる、といった場面で使いやすい skill です。

一般的なテスト生成プロンプトとの違い

一般的なプロンプトでも一見もっともらしいテストは生成できますが、フレームワーク固有の慣習、エッジケース、カバレッジ上の優先度、TDD サイクルそのものを見落としがちです。tdd-guide には、ワークフロー構造、入力例、期待される出力パターン、カバレッジ分析用のツール、fixture 生成、フレームワークへの適応、CI 連携の参考情報が含まれています。そのため、単発のプロンプト実験よりも、繰り返し行うエンジニアリング作業に向いています。

tdd-guide だけでは不十分な場合

tdd-guide for Test Driven Development は、ドメインの振る舞いを理解することの代替にはなりません。期待される結果、依存関係、エラー規則、フレームワークの詳細を提示できない場合、生成されるテストは浅くなる可能性があります。また、生成されたテストがあなたのリポジトリで必ずコンパイルできることを自動的に保証するものでもありません。ローカルのテストコマンドを実行し、imports、setup files、mocks、環境固有の設定を調整する必要があります。

tdd-guide skill の使い方

tdd-guide のインストールとリポジトリ確認

Claude Skills 互換環境で、次のコマンドを使って skill をインストールします。

npx skills add alirezarezvani/claude-skills --skill tdd-guide

その後、上流の skill フォルダ engineering-team/skills/tdd-guide を確認します。まず SKILL.md で起動ルールとワークフローを確認し、次に HOW_TO_USE.md で呼び出し例を読みます。フレームワーク別のセットアップが必要な場合は references/framework-guide.md を確認します。ビルドでの強制を目的にしているなら references/ci-integration.md、TDD の習慣を改善したいなら references/tdd-best-practices.md を読むとよいでしょう。

tdd-guide を効果的に使うための入力

この skill は、コードまたは機能要件、言語、テストフレームワーク、期待される振る舞いの 4 点を渡すと最も効果を発揮します。良い入力には、正常系、エラーケース、境界値、外部依存、カバレッジ目標が含まれます。

弱いプロンプトの例:

“Write tests for my auth service.”

より良いプロンプトの例:

“Use tdd-guide to generate Jest tests for src/auth/password-validator.ts. Cover valid password, too short password, missing uppercase, missing number, missing special character, and null or empty input. Target 90% branch coverage. Use existing project style: describe, beforeEach, and expect(...).toBe(...).”

実践的な tdd-guide ワークフロー

既存コードに対しては、次の順序で進めます。

1. ソースファイルを貼り付けるか参照する。
2. language、framework、テストファイルの命名規則を指定する。
3. P0 の振る舞い、P1 のエッジケース、P2 の回帰テストのように、優先度別にテストを依頼する。
4. 生成されたテストをローカルで実行する。
5. コンパイルエラー、失敗した assertion、カバレッジ出力をアシスタントに戻す。
6. imports、mocks、fixtures、不足している branches の修正を skill に依頼する。

新機能の場合は、red-green-refactor で進めます。まず受け入れ基準から失敗するテストを作成してもらい、次にそれを通すための最小限の実装を行い、その後テストを green に保ったまま安全にリファクタリングする改善案を依頼します。

最初に確認したい便利なファイルとスクリプト

このリポジトリには、本格的に使う前に読んでおきたい実用的な補助ファイルがあります。

• assets/sample_input_python.json と assets/sample_input_typescript.json は、出力品質を高める構造化入力の粒度を示しています。
• assets/expected_output.json は、この skill が生成することを想定しているテスト、カバレッジ、品質サマリーの形式を示しています。
• scripts/test_generator.py は、テスト生成パターンを支援します。
• scripts/coverage_analyzer.py は、LCOV、JSON、XML のカバレッジデータがある場合に関係します。
• scripts/fixture_generator.py、framework_adapter.py、tdd_workflow.py は、この skill が mocks、フレームワークの慣習、TDD の各フェーズをどう扱うかを読み取る手がかりになります。

tdd-guide skill FAQ

tdd-guide は初心者にも向いていますか？

はい。初心者でも、テストしたい具体的な機能や関数があるなら有用です。tdd-guide skill は、実用的な例を生成しながら red、green、refactor のリズムを学ぶ助けになります。ただし、初心者でも生成されたテストは必ず実行し、失敗内容を読むべきです。学習効果は、期待される振る舞い、生成された assertions、実際の実装を比較することで得られます。

tdd-guide が特に得意なフレームワークは？

最も相性がよいのは Jest、Pytest、JUnit、Vitest で、skill の説明では Mocha も言及されています。含まれているフレームワーク参考資料は、TypeScript/JavaScript、Python、Java のパターンを扱っています。あまり一般的でないフレームワークを使う場合は、リポジトリ内のテストファイル例を渡してください。そうすることで、imports、命名、setup hooks、assertion style を合わせやすくなります。

カバレッジレポートを分析できますか？

はい。tdd-guide は、LCOV、JSON、XML などのカバレッジレポートを扱うことを想定しています。良い結果を得るには、単なるパーセンテージだけでなく、未カバーのファイルや branches を貼り付けてください。“coverage is 65%” と伝えるだけよりも、coverage/lcov.info、未カバーの行範囲、その不足に紐づくソースファイルを共有するほうが有用です。

tdd-guide を使うべきでない場面は？

セキュリティ上重要な処理、金融、医療、コンプライアンスに関わる振る舞いについて、唯一の品質ゲートとして使うべきではありません。テストの下書きを作り、抜けを見つける助けにはなりますが、権威あるルールなしにビジネス上の正しさを確認することはできません。また、コードベースを共有できない場合、公開された振る舞いが定義されていない場合、隠れた統合環境への依存が大きいプロジェクトにも向きません。

tdd-guide skill を改善する方法

より良いプロンプトで tdd-guide の結果を改善する

tdd-guide の出力を最も早く改善する方法は、コードだけでなく振る舞いを伝えることです。有効な入力例、無効な入力例、期待される例外、境界値、既存のテスト規約を含めてください。mocks が必要な場合は、依存関係の名前を挙げ、何を stub し、何を実際に動かすべきかを定義します。

役立つプロンプトの追記例:

• “Do not mock the pure calculation function.”
• “Mock the payment gateway and assert it is called once.”
• “Use parameterized Pytest cases for boundary values.”
• “Prefer behavior-focused test names over implementation names.”

初回出力後によくある失敗を修正する

よくある問題は、誤った imports、過剰な mocking、壊れやすい実装詳細への assertions、async 処理の不足、信頼性を高めずに行カバレッジだけを上げるテストです。初回結果の後は、テスト失敗やコンパイルエラーを貼り付け、狙いを絞った修正を依頼します。たとえば次のように依頼します。“These Jest tests fail because the service constructor requires a repository dependency. Revise using a typed mock and keep the same behavioral coverage.”

カバレッジデータで作業の優先度を決める

カバレッジ改善が目的なら、未カバー行すべてにテストを生成するのではなく、リスクに基づいてギャップを順位付けするよう skill に依頼します。単純な getters や防御的な branches より前に、未テストの条件分岐、エラー branches、public methods、ビジネスルールを優先してください。このリポジトリのカバレッジワークフローは P0/P1/P2 の優先度付けを支援しており、生のパーセンテージだけを追うより実用的です。

保守しやすい TDD 実践へ反復する

tdd-guide の最も良い使い方は反復です。まず要件から失敗するテストを依頼し、次に最小限の実装の形を相談し、その後テストを安定させたまま行えるリファクタリング案を求めます。アシスタントの焦点は、観測可能な振る舞いに置き続けてください。つまり、inputs、outputs、side effects、exceptions、integration boundaries です。これにより、実装が変わった後も役立ち続けるテストを作れます。