Claude Codeモノレポのテスト戦略をSKILL.mdで教える手順

Claude Codeがモノレポのテスト規約を外すのはなぜか

packages/apiはsupertestでHTTPアサーションを書き、DBテストは必ずトランザクションでロールバックする。packages/webはまた別の道具立てでコンポーネントをテストする。モノレポではパッケージごとにテストの作法が違うのが普通です。Claude Codeにテストを書かせると、この作法をリポジトリ全体で共有されたCLAUDE.mdだけから読み取ろうとして外します。rawなfetchでHTTPを叩いたり、ロールバックを忘れたテストを書いたりするのはこのためです。

原因は情報の置き場所です。CLAUDE.mdは起動時に常に読み込まれる分、内容を絞らざるを得ません。パッケージ固有のテスト規約のような細部を書き込むと、無関係な作業でも毎回読み込まれてコンテキストを圧迫します。Claude Codeの公式ガイドlarge-codebasesは、この種の細部をSkillsに切り出すことを勧めています。Skillは名前と説明だけが常時ロードされ、本文はClaudeが関連すると判断したときだけ読み込まれます。

本記事は、パッケージ単位のSKILL.mdでテスト規約を教える具体的な書き方と、教えた規約を確実に発火させ、実際に使われているか確認するところまでを手順化します。モノレポのCLAUDE.md階層設計そのものはClaude Codeモノレポ設計で扱っているので、権限スコープやworktreeの絞り込みはそちらを参照してください。

始める前に確認すること

SKILL.mdでテスト規約を教える対象は、パッケージごとに違うテストの書き方です。全パッケージ共通のルール(コミットメッセージの書式、PRレビューの通し方など)はリポジトリルートのCLAUDE.mdかルートのSkillに置いたままにします。パッケージ固有かどうかの見分けが、置き場所を決める最初の判断です。

もう一つの前提は起動場所です。Claude Codeをどのディレクトリから起動するかで、後述する可視範囲の挙動が変わります。packages/api/から起動する運用が主なのか、リポジトリルートから起動して複数パッケージを横断する運用が主なのかを先に確認しておくと、次の手順で迷いません。

手順1: SKILL.mdの4節でパッケージのテスト規約を書く

パッケージのディレクトリ内に.claude/skills/を作り、その下にSKILL.mdを置きます。

mkdir -p packages/api/.claude/skills/api-testing

packages/api/.claude/skills/api-testing/SKILL.mdの中身は、次の4節を軸に書きます。テスト構造・実行コマンド・ヘルパー関数・禁止パターンの4つは、テストを書く判断のたびに必要になる情報とちょうど一致します。

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---
 
## Test structure
 
Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.
 
## Running tests
 
- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`
 
## Test utilities
 
- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints
 
## Patterns
 
- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

Test structureはテストファイルの置き場所、Running testsは実行コマンド、Test utilitiesは使い回すヘルパー関数、Patternsはやってはいけないことを含む書き方の癖です。この4節があれば、Claude Codeは新しいテストを書くときにディレクトリを推測する必要がなく、実行コマンドをpackage.jsonから探し回ることもありません。packages/web/には同じ形で別のcomponent-patternsスキルを置き、フロントエンドのテスト作法を教えます。パッケージが違えば読み込まれるスキルも自動的に切り替わり、互いのテストを書くときにもう一方の規約が混ざり込むことはありません。

規約を書くだけでなく、実行コマンドの承認プロンプトを毎回出したくない場合はallowed-toolsフロントマターを足します。

allowed-tools: Bash(npm test *)

このスキルが呼ばれたターンの間だけnpm test系のBash実行が許可プロンプトなしで通ります。許可はメッセージを送るたびにクリアされるため、セッション全体で許可したい場合は.claude/settings.jsonのallowルールに書くほうが向いています。

手順2: pathsフロントマターでテストファイルだけに自動発火させる

上のSKILL.mdはdescriptionの文面だけでClaudeの関連判断に頼っています。これをテストファイルに触れたときだけ確実に発火させたいなら、pathsフロントマターでグロブパターンを指定します。

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
paths: "packages/api/src/**/*.test.ts,packages/api/src/__tests__/**"
---

pathsはカンマ区切りの文字列かYAMLリストで指定でき、指定した場合はClaudeが対象パターンに一致するファイルを操作するときだけ自動ロードされます。リポジトリルートの.claude/skills/に置きつつ、paths: "**/migrations/**"のようにパターンだけで対象を絞る書き方も可能です。パッケージ単位で配置場所を分けるか、ルートに置いてpathsで絞るかは、そのスキルが1パッケージ専用か複数パッケージで共有されるかで選びます。

手順3: 起動場所ごとの可視範囲とdescription短縮に備える

Claude Codeがどのスキルを候補に挙げるかは、起動場所で変わります。

数百パッケージ規模のモノレポをルートから触り続けるセッションでは、見えるSkillsの一覧が数百件に膨れることがあります。ここで効いてくるのがdescriptionの短縮です。Claude Codeは一覧に含める説明文をコンテキストウィンドウの1%を目安にした文字数予算に収めようとし、超過分は呼び出し頻度の低いスキルから説明を削っていきます。予算を超えたときは--debug実行時のデバッグログに警告が出ます。

対策は3つあります。1つはdescriptionとwhen_to_useの冒頭に最も重要な用途を書き、途中で切られても要点が残るようにすること。1つは複数パッケージで共有するスキルをリポジトリルートに集約し、重複を減らすこと。もう1つはskillListingBudgetFraction設定で予算そのものを引き上げることです。/doctorを実行すると、一覧のコンテキスト消費量と主な内訳を確認できます。

手順4: 複数リポジトリに配るならプラグイン化する

api-testingのようなパッケージ専用スキルはリポジトリ内に置くだけで十分ですが、PRレビュー規約やデプロイ手順のように複数リポジトリで共有したいテスト運用ルールはプラグインにまとめます。プラグインルートのworkflows/に相当する位置として、スキルはskills/ディレクトリに置きます。

プラグイン化すると名前空間がplugin-name:skill-nameの形に切られるため、パッケージ単位で置いたスキルと名前が衝突しません。プラットフォームチームがテスト規約を1か所で更新し、各リポジトリはプラグインの更新を取り込むだけで最新の規約に追従できます。バージョン管理も各リポジトリのコミット履歴とは切り離されるため、規約の変更履歴を追いやすくなります。

教えた規約が実際に使われているか確認する

SKILL.mdを書いただけでは、実際に発火しているかは分かりません。OpenTelemetryのログエクスポーターを有効にし、環境変数OTEL_LOG_TOOL_DETAILS=1を設定すると、claude_code.skill_activatedイベントがスキル名を伏せ字にせず記録します。skill.nameにスキル名、invocation_triggerにuser-slash(手動起動)・claude-proactive(自動判断)・nested-skill(別スキルからの呼び出し)のいずれかが入ります。

このイベントを1〜2週間分集めれば、書いたテスト規約スキルが実際に発火しているか、発火しているならユーザーの明示指定なのかClaudeの自発判断なのかが分かります。まったく発火していないスキルは、descriptionのキーワードが実際の依頼文と噛み合っていないか、そもそも不要という判断材料になります。

CLAUDE.mdとSkillの使い分け早見表

パッケージのテスト情報をどこに書くかは、情報の性質によっておすすめ度が変わります。

よくあるつまずき

スキルが発火しない: descriptionが実際にユーザーが打ちそうな言葉を含んでいるか確認します。「packages/apiでテストを書くとき」のような具体的な文言が、抽象的な「テスト規約」よりも一致しやすくなります。claude plugin validate .claude/skillsを実行すると、frontmatterのYAMLが壊れて説明が読み込まれていないケースも見つけられます。

逆にスキルが発火しすぎる: descriptionを具体的にするか、手動起動だけにしたいならdisable-model-invocation: trueを付けます。この設定はサブエージェントへの事前ロードやスケジュールタスクからの起動も同時に止めます。

モノレポで意図しないスキルが読み込まれる: リポジトリルートから起動するセッションほど、セッション中に触れたサブディレクトリのSkillsが積み上がります。パッケージ横断の作業をしないセッションは、可能な限りパッケージ内から起動するほうが読み込まれるスキルの数を抑えられます。

よくある質問

CLAUDE.mdに直接テストコマンドを書くのとSkillに分けるのはどちらがよいですか

常時読み込まれてよいほど短い1行のコマンドならCLAUDE.mdでも困りません。ヘルパー関数の一覧や禁止パターンのように分量が増える情報は、Skillに切り出したほうが無関係な作業時のコンテキスト消費を避けられます。

pathsを指定しなかった場合、スキルはいつ読み込まれますか

pathsを省略すると、配置されたディレクトリとその祖先から起動したセッションの候補一覧に常に載り、descriptionの内容だけでClaudeが関連性を判断します。特定のファイルパターンに絞りたい場合だけpathsを追加します。

1つのパッケージに複数のテストスキルを置いてもよいですか

問題ありません。単体テスト用と統合テスト用でスキルを分けるような運用も可能です。ただしスキルが増えるほど一覧の文字数予算を消費するため、内容が薄いスキルは統合を検討します。

まとめ

モノレポのテスト規約は、パッケージ単位の.claude/skills/にTest structure・Running tests・Test utilities・Patternsの4節で書くと、Claude Codeが該当パッケージの作業時だけ読み込みます。pathsフロントマターでファイルパターンに絞る、起動場所ごとの可視範囲とdescription短縮に備える、複数リポジトリに配るならプラグイン化する。この3つを押さえたうえで、skill_activatedイベントで実際の発火状況を確認すれば、規約が書かれているだけで読まれていない状態を避けられます。