Claude CodeにpytestのCLAUDE.md規約を教える

pytestプロジェクトでClaude Codeにテストを書かせると、test_*.pyという命名やTestプレフィックスのクラス名から外れたファイルができることがあります。CLAUDE.mdやパススコープ付きのルールファイルにpytestの検出規則とプロジェクト固有の運用を明文化しておくと、このブレを減らせます。ここでは具体的な書き方と、明文化しても効かないときに見直す点をまとめます。

Claude CodeはCLAUDE.mdをどう読み込むか

CLAUDE.mdはシステムプロンプトの一部ではなく、セッション開始時のユーザーメッセージとして渡されます。Claudeはこれを読んで従おうとしますが、特に曖昧な指示や矛盾した指示については、厳密に守られる保証はありません。

Claude CodeはプロジェクトルートのCLAUDE.md(または./.claude/CLAUDE.md)を起動時に読み込みます。実際に読み込まれたかどうかはセッション中に/contextコマンドを実行し、「Memory files」欄に該当ファイルが出ているかで確認できます。ファイルを置いた場所が起動ディレクトリの上位にない、あるいはサブディレクトリの奥にある場合、そのファイルは起動時には読み込まれず、Claudeがそのディレクトリ配下のファイルを読んだタイミングで読み込まれます。

指示の書き方も効き目を左右します。公式ドキュメントは「フォーマットをちゃんと守って」ではなく「2スペースインデントを使う」のように、検証可能な粒度で書くことを勧めています。この原則はpytestの規約にもそのまま当てはまります。

/initで叩き台を作ってから調整する

Claude Codeには、既存コードベースを解析してCLAUDE.mdの叩き台を自動生成する/initコマンドがあります。ビルドコマンドやテスト実行コマンド、Claudeがコード自体から読み取れるプロジェクトの慣習を書き出してくれるため、pytestプロジェクトならpytestという実行コマンドくらいは自動で拾われる可能性があります。すでにCLAUDE.mdがある場合、/initは既存ファイルを上書きせず、改善案を提示する動作になります。

ただし/initが拾えるのはコードから読み取れる範囲の情報だけです。test_*.pyという命名を徹底したいのか、Testプレフィックスのクラスを使う方針なのか、assert文で統一するのかといった、コードだけでは判別しにくいチームの方針は、/initのあとに手で書き足す必要があります。

pytestの検出規則をCLAUDE.mdに書き出す

pytestはデフォルトでtest_*.pyまたは*_test.pyという名前のファイルを収集します。テストクラスはTestで始まる名前でなければ収集対象から外れ、関数名にはtest_プレフィックスが必要です。この規則自体はpytest側の仕様として決まっているので、CLAUDE.mdに書くのはこの規則を前提にした自分のプロジェクトの運用ルールです。

具体例として、次のような節をCLAUDE.mdに追加できます。

## テスト
 
- 実行コマンド: `pytest -q`
- ファイル名は `test_*.py` に統一する(pytestのデフォルト検出規則に合わせる)
- テストクラスを使う場合は `Test` から始まるクラス名にする(それ以外は収集されない)
- 新しいアサーションは `assert` 文を使う(`self.assertEqual` は使わない)
- 例外の送出を確認するテストは `pytest.raises` を使う
- 一時ディレクトリが必要なテストは `tmp_path` フィクスチャを使う
- 浮動小数点の比較には `pytest.approx()` を使う

assert文を使う指定は、pytestが標準のassert文を書き換えて中間値を詳しくレポートする仕組み(Advanced assertion introspection)を持っているためです。self.assertEqualのようなunittest由来の書き方を混ぜなくても、失敗時の情報量は変わりません。

テストをクラスにまとめる場合、テストメソッドごとに独立したクラスインスタンスが割り当てられるので、あるテストでself.value = 1のようにインスタンス属性へ書き込んでも、次のテストには持ち越されません。一方でクラス変数(クラス直下で定義した属性)はインスタンス間で共有されるため、状態を持ち越したくない場合はインスタンス属性側に閉じるという方針も、CLAUDE.mdに一言添えておく価値があります。

プロジェクトにどんなフィクスチャが用意されているかは、次のコマンドで一覧できます。

pytest --fixtures

このコマンド自体をCLAUDE.mdに書いておくと、Claudeが新しいテストを書く前に既存のフィクスチャを自分で調べる手がかりになります。

手順が複数ステップにまたがる長い運用は、CLAUDE.mdに書き込むと肥大化しがちです。公式ドキュメントも、複数ステップの手順やコードベースの一部だけに関係する内容はSkillかパススコープ付きルールへ移すよう案内しています。CLAUDE.mdをSkillsへ移す判断基準はCLAUDE.mdをSkillsに移行してコストを削減する方法にまとめています。

.claude/rules/でtests配下だけに絞り込む

プロジェクト全体のCLAUDE.mdにpytestの規約を書くと、テストを触らない作業のセッションでも毎回読み込まれます。.claude/rules/配下にファイルを置き、YAMLフロントマターのpathsフィールドでスコープを絞ると、該当パターンにマッチするファイルをClaudeが読んだときだけ読み込まれるようになります。

---
paths:
  - "tests/**/*.py"
---
 
# pytest規約
 
- ファイル名は `test_*.py`
- クラス名は `Test` プレフィックス必須
- アサーションは `assert` 文

このファイルを.claude/rules/testing.mdのような名前で置いておけば、.claude/CLAUDE.md本体の行数を増やさずに済みます。pathsにはブレース展開も使え、"tests/**/*.{py}"のように複数パターンをまとめて指定できます。pathsフィールドを持たないルールファイルは、.claude/CLAUDE.mdと同じ優先度で起動時に読み込まれる点に注意します。

個人の実行環境の違いはCLAUDE.local.mdに逃がす

pytestを回すテスト用データベースのURLや、手元だけで使うテストデータの置き場所など、チームでは共有しない個人固有の設定はCLAUDE.local.mdに書きます。プロジェクトルートに置く個人用のファイルで、CLAUDE.mdと一緒に読み込まれますが、.gitignoreに加えてバージョン管理からは外す運用です。公式ドキュメントも、サンドボックスのURLや好みのテストデータの置き場所としてこのファイルを挙げています。

複数のgit worktreeを行き来する場合、.gitignore済みのCLAUDE.local.mdは作成したworktreeの中にしか存在しません。worktreeをまたいで個人設定を共有したいときは、ホームディレクトリに置いたファイルを@~/.claude/my-test-settings.mdのような形でインポートする方法があります。

モノレポや複数チームでの運用

Claude Codeは、作業ディレクトリとその上位にあるCLAUDE.mdをすべて連結して読み込みます。読み込み順はファイルシステムのルート側から作業ディレクトリ側へで、作業ディレクトリに近いファイルほど後に読まれます。サブパッケージごとにpytestの使い方が違うモノレポでは、これを役割分担に使えます。ルート直下のCLAUDE.mdにプロジェクト共通の実行コマンドを書き、サブパッケージ側のCLAUDE.mdにそのパッケージ固有の命名規則を書く、という分け方です。ただし他チームのpytest規約まで混ざり込むと、同じ話題について異なる指示が並び、Claudeがどちらかを恣意的に選ぶ状態になりかねません。他チームのCLAUDE.mdを読み込み対象から外したい場合はclaudeMdExcludesが使えます。設定手順はclaudeMdExcludesの設定手順にまとめています。

チームでCursorやClineなど他のAIコーディングツールも併用している場合、規約をAGENTS.mdに一本化し、CLAUDE.mdからはそれを読み込むだけにする運用もあります。詳細はAGENTS.mdとCLAUDE.mdで設定を統合する運用パターンを参照してください。

明文化しても従わないときに見直す点

• 指示が曖昧: 「テストをちゃんと書いて」ではなく「新しいテストはtests/直下にtest_*.pyで追加する」のように、検証可能な粒度に書き直します
• 指示が競合している: ネストしたCLAUDE.mdや.claude/rules/の中に、同じ話題について異なる指示が書かれていないか確認します
• ファイルが読み込まれていない: /contextの「Memory files」欄に対象ファイルが出ているか確認します。出ていなければ配置場所やパスの指定が誤っています
• CLAUDE.mdが長くなりすぎている: 200行を目安に、それを超えるとコンテキスト消費が増え、遵守率が下がるとされています。長くなってきたら.claude/rules/への分割を検討します
• いつ読み込まれたか追いたい: InstructionsLoadedフックを使うと、CLAUDE.mdとルールファイルがいつ・なぜ読み込まれたかをログに残せます。パススコープ付きルールが期待どおり発火しているかのデバッグに使えます

pytestの規則とCLAUDE.mdの書き方の対応

右列はpytestの検出ルールそのものではなく、CLAUDE.mdの性質(曖昧な指示は厳密に守られる保証がない)から起こりうる現象です。どこまでブレるかはプロジェクトとモデルの組み合わせ次第なので、断定はできません。

まとめ

pytestの検出規則(test_*.py、Testプレフィックス、assert文)自体はpytest側の仕様として固定されていますが、それをどう守らせるかはCLAUDE.md側の書き方次第です。検証可能な粒度で書き、テスト関連だけなら.claude/rules/にパススコープを絞り、/contextで実際に読み込まれているかを確認する。この3点を押さえておくと、pytestの規約がテストのたびに崩れる事態を減らせます。Claude Codeの基本的な設定と運用はClaude Code完全ガイド、テストが失敗したあとの解析手順はpytestの失敗をMCPサーバーでClaudeに解析させるも参考になります。