test

出力スタイル（平易な言葉、ダッシュやハイフンなし）

このスキルが作成するものは、ファイルもメッセージもすべて、平易で簡潔な言葉にしてください。読者には「あなた」と呼びかけ、同僚のように親しみやすく率直に話してください。各手順は、必須の指示ではなく、実行しても省略してもよい提案として示してください。本当に意味のある技術用語はそのまま使い、平易な言葉で説明してください。句読点としてダッシュやハイフンは使わないでください。emダッシュ、enダッシュ、ハイフンでつないだ複合語も使わないでください。read only と書き、read-only は使わないでください。簡単な言葉で表すか、文を書き換えてください。コード、ファイルパス、コマンドフラグ、ほかのスキルが一致判定に使う値に含まれるハイフンはそのままにしてください。短い文を使い、読点や括弧を活用してください。巧みさより明快さを優先してください。

このスキルの内容

役割：コードにふさわしいテストスイートを作成する、シニアテストエンジニアです。カバレッジの数値を上げるためではなく、呼び出し元が頼りにしている動作や、実際に誰かに影響を与える不具合をテストしてください。各ファイルの内容を読んで、適切なテスト戦略を選んでください。その範囲を実用的なものにする意図がなかった足場を固定するテストは作成しないでください。

対象：このブランチで変更され、まだコミットされていないコードです。変更された各ファイルを、純粋なロジック、コンポーネント、API ルート、ページやフローに分類し、適切な戦略でテストします。メインスレッドがテストを作成します（ファイル数が多い場合は、read only の scout が大半のファイルを読み取ってもかまいません）。適用する仕様がある場合は、テストをその受け入れ条件に対応させてください（ステップ 7 と 8）。

アプリケーションコードは作成しません。AGENTS.md と CLAUDE.md のコンテキストファイルも更新しません（その作業は /sync が担当します）。

質問と実行

• test-preferences.json があり、ツールがインストール済みで、未コミットのソースファイルがある場合は、質問せずにテストの作成に進みます。
• 設定があっても、実行のたびに必ず一つ質問します。作成後にテストスイートを実行するか、手動で実行するための手順を渡すかを尋ねます（ステップ 7.5）。この選択は実行ごとに行い、保存しません。
• それ以外の場合、次のときに限り質問します。test-preferences.json がない場合（フレームワーク。ページやフローに変更がある場合に限り E2E アドオンも確認します）、選択したツールがインストールされていない場合（最初に確認します）、未コミットの変更がない場合（ステップ 3）、ファイル数が 15 を超える場合（ステップ 1b）。
• 対象範囲については質問しません。Git のワーキングツリーが対象範囲を決めます。

成果物の担当範囲

• このスキルが作成するテストファイル（*.test.ts、*.spec.ts、test_*.py、*_test.go など）
• このスキルがプロジェクトのルートに作成し、管理する test-preferences.json

---

移植性（あらゆる OS、あらゆるエージェント）

macOS、Linux、Windows 上のどの Agent Skills クライアントでも使用できます。

• 必須のコマンドラインツールは git だけです。どの環境でも同じなので、表示どおりに git の行を実行してください。それ以外のシェルの記述は POSIX の参考例であり、そのまま実行するスクリプトではありません。find、grep、sed、cat、test／[ ]、xargs、mkdir -p、node -e が使えるとは限りません。エージェントのクロスプラットフォーム対応のファイルツール（読み取り、検索やグロブ、書き込み）を使い、分岐処理はシェルの if、変数、リダイレクトではなく、自分で行ってください。
• バンドルファイル：このスキルのフォルダーからの相対パスで参照します。メインスレッドがフォルダーの絶対パスを解決し、書き込み時にバンドルファイルである agent-prompt.md と writing-guide.md を自分で読み取ります（ステップ 8）。
• 対話形式の質問に対応していない場合は、同じ選択肢を使い、質問をプレーンテキストで提示してください。

以下の Ask ブロックでは、各選択肢は "label": "description" の形式です。エージェントの選択ツール（Claude Code の AskUserQuestion）で提示するか、プレーンテキストで提示してください。

実行

事前確認（メインスレッド）

1. git からスコープを特定する（最初に実行します。対象が空の場合、質問する意味はありません）

変更済みの未コミットファイル（クロスプラットフォーム対応の git）：

• 削除を除く追跡対象ファイル（ステージ済み＋未ステージ）：git diff --name-only --diff-filter=ACMR HEAD
• 未追跡かつ無視されていないファイル：git ls-files --others --exclude-standard
• コミットがまだない場合（git diff HEAD がエラーになる場合）：git diff --name-only --diff-filter=ACMR --cached を使います。

これらをまとめて重複を除き、テストできないファイルを除外します：

• テストファイル：*.test.*、*.spec.*、test_*.py、*_test.go、__tests__/、e2e/、tests/、cypress/ 以下のすべて
• 設定ファイル：*.config.*、.*rc、tsconfig*、*.json（ロジックが JSON に含まれる場合を除く）、Dockerfile、CI の YAML
• ロックファイル、.lock、生成物／ビルド出力（dist/、build/、.next/、coverage/）
• スタイル関連：*.css、*.scss、*.module.css、型宣言のみのファイル：*.d.ts
• ドキュメントと Markdown、仕様書、design.md、test-preferences.json

残ったファイルがスコープです。空の場合はステップ 3 に進みます。それ以外の場合は続行します。

1b. スコープ内の各ファイルを分類する

パスとファイル名だけから簡易的に分類します。本当に判断が難しい場合は logic とタグ付けし、書き込み時にファイルを読んだ際に再度タグ付けします。書き込みステップで使えるよう、各ファイルの分類を記録します。

パス／ファイル名の特徴	分類	テスト戦略
ルート／ページパス以下ではない *.tsx／*.jsx／*.vue／*.svelte	component	コンポーネントテスト（レンダリング＋操作＋DOM／ARIA の検証）
app/**/page.*、pages/**（pages/api を除く）、*Screen.*、*View.*	page/flow	E2E の候補＋各パーツのコンポーネントテスト
app/**/route.*、pages/api/**、*.controller.*、*.handler.*、*.resolver.*、actions.*	api/server	統合テスト（ハンドラーを呼び出し、境界でモックします）
通常の .ts／.js／.py／.go／.rs、ユーティリティ、フック、サービス、ドメインロジック	logic	単体テスト（入力 → 出力、境界ケース、エラー）
cli.*、bin/**、*.command.*、cmd/**	cli	コマンドを実行する統合テスト

いずれかのファイルが page/flow の場合は E2E_RELEVANT = yes、それ以外は no です。

差分が大きい場合のガード：ソースファイルが 15 個を超える場合は、一度にすべてを書こうとしないでください。分類ごとに優先順位を付け（ロジックと api/server を最優先にし、リスクが高く、十分なテストを最も低コストで書けるものを優先）、次のように尋ねます：

Ask: "<N> changed files is a lot for one pass. How should I focus?"  (header: "Scope size")
- "Logic & API first (recommended)": "Test the <count> logic/api files now; I'll note the rest as not-yet-covered"
- "Test everything in batches": "Cover all <N> files across multiple passes, slower but complete"
- "Let me narrow it": "I'll tell you which files or directory matter most"

モノレポの解決方法：スコープ内の各ファイルについて、最も近い package.json を探します（上位ディレクトリを順にたどります）。ルートが異なる場合はルートごとにグループ化します（それぞれのフレームワーク、パッケージマネージャー、テスト用ディレクトリに従い、グループごとにインストールと書き込みを行います）。共有ルートが 1 つの場合（一般的なケース）は、単一のプロジェクトとして扱います。書き込みステップで使えるよう、各ファイルの packageRoot を記録します。

---

2. 設定を読み込む

プロジェクトルートにある test-preferences.json を読み込みます（ファイルツールを使用。「見つからない」場合は設定なし）。ファイルの有無ではなく、tool の指定有無に応じて分岐します：

• tool が設定されている（一般的な書き込みパス）：tool、additionalTools、e2eTool、testDir、filePattern、packageManager を読み込み、ステップ 5 に進みます。
• tool が null で、gate が設定されている（GATE_ONLY）：このプロジェクトは以前の意図的な選択により、テストランナーではなくゲートで検証します。テストスイートを書かず、テストランナーをインストールせず、再度質問せず、modes/setup.md も読み込まないでください。プロジェクトの型チェック／lint のゲートを実行してから終了し、次のように報告します：「このプロジェクトはテストスイートではなく、<gate> で検証します。型チェックのゲートを実行しました。動作を確認するには /check verify を使ってください。」
• ファイルがない（NO_PREFS、初回実行）：modes/setup.md を読み込み、そのステップ 4（スタックの検出とフレームワークに関する質問）を実行してから、ステップ 5（インストールの確認）のためにここへ戻ります。次に、そのステップ 6（設定の保存）を実行し、その後ステップ 7 に進みます。書き込み実行時には modes/setup.md を読み込まないでください。
• 形式が不正（tool も gate もないファイル、または解析できない JSON）：その旨を伝え、NO_PREFS として扱ってセットアップを再実行します。その際、ファイルは上書きされます。

---

3. コミットされていない変更がないこと

対象範囲が空の場合：フレームワークに関する質問は省略し、エンジニアに伝えて、代替案を提示します。

Ask: "No uncommitted source changes found. What should I test?"  (header: "No changes")
- "The last commit": "Diff HEAD~1..HEAD and test what that commit changed"
- "Specific files": "I'll test the files or directory you name"
- "Nothing right now": "Stop. I'll run /test after I make changes"

• 直近のコミット：対象範囲 = git diff --name-only --diff-filter=ACMR HEAD~1 HEAD。ステップ 1b を再実行します。
• 特定のファイル：指定されたファイルを分類して、続行します。
• 該当なし：ここで終了します。

---

5. インストール状況の確認

ファイルツールで、選択した単体テストツール、E2E ツール（ある場合）、アドオン（ある場合）を確認します。

• JS/TS：node_modules/<pkg> にあるか、package.json の devDependencies にあるか。
• Python：pyproject.toml／requirements.txt にあるか（または Python を利用できる場合は pip show <tool>）。
• Go：go.sum に stretchr/testify があるか。

すべて揃っている場合 → ステップ 6。1 つでも不足している場合 → まず確認します。

Ask: "<missing tools> not installed. Install now?"  (header: "Install")
- "Yes, install and continue": "Run the install with the detected package manager, then write tests"
- "No, write runnable stubs": "Skip install; write tests I can run once I install the tools myself"

はい：検出されたパッケージマネージャーを <pkgmgr> として示し、それを使ってインストールします（検出された npm／yarn／pnpm／bun。Python／Go の場合は各言語のパッケージマネージャーを使用します）。

<pkgmgr> add -D vitest                                            # unit
<pkgmgr> add -D @testing-library/<framework> @testing-library/user-event @testing-library/jest-dom  # addon
<pkgmgr> add -D @playwright/test && <pkgmgr> exec playwright install  # E2E (Playwright)
<pkgmgr> add -D cypress                                          # E2E (Cypress)
pip install pytest pytest-mock                                    # Python
go get <testify module path>                                      # Go

「いいえ」：INSTALL=deferred と記録します。テストはすべて記述し、実行コマンドは「インストール後に実行」として報告します。

---

7. 軽量な手がかりを収集する（ここでは重いファイルを読まないでください）

パスと簡単に確認できる情報のみを調べます。重いファイルを読むのは、作成時（あなた自身、または作業を委任された場合は scout）です。ここでは仕様書、design.md、ソースファイルを全体にわたって読まないでください。

ファイルツールを使用します。

• docs/specs/ 以下で、最近変更された仕様書のパスを 3 つ列挙します（パスのみ）。
• 適用される仕様書を特定します。このファイル群が実装する機能ディレクトリ docs/specs/NNNN-<feature>/（または単一ファイル docs/specs/NNNN-<feature>.md）を、ブランチ名／機能名または変更対象のサーフェスに基づいて照合します（docs/scope/ の項目があれば、参照先が示されています）。そのパスと、隣接する位置に verify.md があるかどうか（docs/specs/NNNN-<feature>/verify.md）を記録します。テストはこの契約仕様をたどります。これは最近の 3 つのパスに含まれていない場合があります。適用される仕様書が存在する場合は TRACE_TO_CONTRACT = yes、存在しない場合は no に設定します。
• プロジェクトルートに design.md があるかどうかを確認します。スコープに コンポーネント または ページ／フロー ファイルが含まれる場合に限り、そのパスを使用します。それ以外は none にします。
• プロジェクトのコンテキストとして AGENTS.md（正規ファイル。不在の場合は CLAUDE.md）を読みます（短く、すぐ確認できます）。また、ビルドアプローチを 1 行で記録します。これはチームが選んだスライスの形成方針で、スコープヘッダー（またはルートの AGENTS.md）に記録されています。例：エンドツーエンドの薄い経路、利用可能な最小限のコアループ全体、プレースホルダーを使った UI ファーストのシェル、フェーズごとの完全なユーザージャーニー。これはロジックの分岐には使いません。記述時（ステップ 8、ルール a）の判断基準として使います。
• package.json を読み、scripts.test を記録します。test スクリプトがある場合は RUN_COMMAND = <pkgmgr> test（npm の場合は <pkgmgr> run test）に設定します。ない場合に限り、直接実行するコマンド（例：<pkgmgr> exec vitest run）を設定します。

---

7.5 テストスイートを実行するか確認する（必ず実行）

Ask: "Tests will be written for <N> changed files. Run the suite after writing?"  (header: "Run tests?")
- "Yes, run and fix to green": "Execute the suite; I'll fix any test mistakes and flag real bugs the tests catch"
- "Skip, just write them": "Write the tests and give me manual run-and-verify instructions instead"

RUN_AFTER = yes | no に設定し、記述時に適用します。

8. テストスイートを書く（メインスレッド）

メインスレッドでテストを記述します。ライターを起動してはいけません。このスキルのフォルダーを絶対パスに解決し、今（記述時に限り）agent-prompt.md と writing-guide.md を読みます。agent-prompt.md は作業時に従うテンプレート、writing-guide.md は方針、ツールのルール、反復ループ、レポート形式です。テスト対象の変更ファイルを読む作業が、最もコストのかかる部分です。対象が大規模な場合や、なじみのないファイルが含まれる場合は、読み取り専用の scout サブエージェントに読み取りだけを委任し、最も安価なモデル（Claude Code ではセッションモデルを引き継がない haiku）を使って、簡潔なマップを作成させ、その内容に基づいてテストを記述します。

適用する入力（収集したラベル付きの値）：

1. ユニットテストツール、E2E テストツール、追加ツール、INSTALL の状態、testDir、filePattern、パッケージマネージャー、スタック／フレームワーク、packageRoot、分類した対象範囲（各ファイルパスとその分類：logic／component／page flow／api server／cli）、RUN_COMMAND、RUN_AFTER、プロジェクトのコンテキストとビルドアプローチの行、直近の仕様書パス 3 件または none（テスト対象に関連する場合に限り読み取る）、design.md のパスまたは none、TRACE_TO_CONTRACT、適用される仕様書のパス、verify.md のパス（存在しない場合はそれぞれ none）。
2. 適用するルールは 2 つです。（a）ビルドアプローチに基づいて、この対象範囲で確実に実装されている動作（安定したアサーションとして固定する）と、設計上意図的にスタブ化されている部分（計画でまだ実装されていない機能の実装を前提とするアサーションは行わない。例：データをスタブ化したシェルに対して、実際のバックエンドを前提とする期待を置かない）を見極めます。（b）TRACE_TO_CONTRACT = yes の場合、受け入れ基準を読み（verify.md があれば、そこで解決済みの AC-N タグ付きチェックリストを優先し、なければ仕様書の ## Requirements を読む）、確実に実装されている基準を固定します。安定したアサーションとして固定できる各基準に対し、自動テストを 1 件ずつ作成し、各テストに、そのテストが対象とする AC-N のタグを付けます（例：covers: AC-3 コメント、またはテストタイトルの AC-3）。これにより、テストスイートを仕様にひも付けます。自動化できない基準（「メールが実際に届く」など、視覚的／手動／環境依存のもの）を偽装してはいけません。NOT_COVERED に AC-N, <自動化できない理由> → /check verify の手動ステップに委ねる と記録します。

モノレポ（Step 1b で複数のパッケージルートがある場合）：各ルートのファイル、ツール、パッケージマネージャーに対象を絞り、各ルートのテストスイートを順に記述します（ファイル数が多い場合は、各ルートのファイル読み取りを専用の scout に委任します）。単一ルート（一般的なケース）：そのルートのテストスイートだけを記述します。

スイートの作成後

書き込みに失敗した、またはレポートが出力されなかった場合は、その旨を伝えて再度実行してください。実際に作成していないスイートについて、合格または不合格と報告してはいけません。それ以外の場合は、RUN_AFTER に一致する形式で結果を伝えてください。

スコープを更新します。この機能がスコープ（docs/scope/）に含まれていて、スイートが合格した場合は、その Test it ボックスにチェックを入れ、完了扱いにはせず、提案にとどめてください：「テストが追加され、合格しました。done にしますか？」エンジニアの了承を得たら、ステータスを done（概要テーブルと見出し）に設定し、仕様の **Status**: を Accepted に合わせます。仕様が Assumed でも done の妨げにはなりません。その場合は「承認が必要です。都合のよいときに /architect を実行してください」と伝え、判断は相手に委ねます。テストが不合格、またはカバレッジが部分的な場合は、Test it にチェックを入れず、その旨を報告してください。更新内容を締めくくりの確認として報告してください（省略しないでください）。各ファイルで何にチェックを入れたかを正確に報告します。例：「スコープ：Test it にチェック、ステータス → done。仕様：ステータス → Accepted。」一致するスコープの行がなければ、その旨を伝え、何も言わずに終了してはいけません。done にした場合は、次の機能に進む前に /clear を実行するよう案内してください。スコープと仕様にすべて記載されているため、新しいセッションを開始すれば、次のビルドを低コストで進められます。**Git：**最も近い AGENTS.md の ## Git に integration: on とあり、commit が manual でない場合は、1 行の件名（test(<scope>): …）と Co-Authored-By トレーラーを付けてスイートをコミットすることを提案してください。プッシュはしてはいけません。（有効なティアは、機能固有のティアタグが設定されていればその値、なければプロジェクトの **Workflow:** の既定値です。Beta／GA では /test が締めくくりのステップです。Prototype は /develop、Alpha は /check verify で完了するため、これらのティアでは、この機能はすでに done であるか、/test を使用しません。オーバーライドタグがあればそれに従い、固定のチェーンを既定として使用してはいけません。）

結果を先に示してください。ファイルごとの一覧と AC との対応はテストファイルに記載されています（docs/conventions.md を参照）。

## /test <feature> · <all N passed | Y failed | not run>

**Wrote <N> tests across <M> files (happy path / edges / errors / a11y). <X passed, Y failed via `<RUN_COMMAND>` | not run>.**
Next (this feature's next unticked box in the scope): all pass → `/check review` if a `Review it` box remains, else `/sync` or the next feature · Y failed → fix them, or `/debug <feature>` if the code is wrong · not run → `<RUN_COMMAND>`
Heads up: <bugs the tests caught · file:line + the failing expectation> · <uncovered AC-N or area, why>   (omit the whole line if none)

RUN_AFTER = no の場合に限り、実行手順を追加してください：<INSTALL=deferred の場合はセットアップ手順> の後に <RUN_COMMAND>（1 つのファイルを監視する場合は <focused command>）を記載します。フレームワークの選択は test-preferences.json にあります。テストごとの詳細と AC との対応はテストファイルに記載されているため、再掲しないでください。

未カバー（追加を検討してください）：

• <不足している部分とその理由>
• AC-N、<自動化できない基準（視覚的／手動／環境要件）> → /check verify の手動ステップに委ねる　← TRACE_TO_CONTRACT=yes の場合

If `BUGS_FOUND` is not empty, lead with it: a test that correctly fails on real broken code is a genuine finding, not something to silence. /test does not modify application code to make a test pass.

This skill is complete after relaying the report: it does not invoke other skills.

---

## Reference files (in this skill's folder; referenced by relative path)

- `modes/setup.md`: first run only steps (stack detection, framework questions, save preferences); read on the main thread only when `NO_PREFS`
- `agent-prompt.md`: the operating template the main thread reads at write time (Step 8)
- `writing-guide.md`: strategy, tool rules, iteration loop, report format; the main thread reads it at write time too