Claude Code × Python プロジェクト: CLAUDE.md テンプレートと AGENTS.md パターン完全ガイド（2026）

Python には、Claude Code が即座に露わにする「設定の問題」がある。パッケージマネージャー（pip・poetry・uv・conda）、フォーマッター（black・ruff・autopep8）、型チェッカー（mypy・pyright・pytype）、テストランナー（pytest・unittest・nose）、そして仮想環境の戦略——ほぼすべてが複数の流派に分かれている。CLAUDE.md なしで Claude Code がプロジェクトを開いた時、それは推測で動く。うまくいくこともある。しかし多くの場合、システム Python に依存関係をインストールし、python コマンドで実行するのに対してプロジェクトが python3.12 を要求し、ruff を使うべきところで black でフォーマットしてしまう。

CLAUDE.md と AGENTS.md はこれを解決する。適切に書かれた CLAUDE.md は、最初のセッションからそれ以降のすべてのセッションで、Claude Code を特定のツールチェーンに固定する。このガイドでは主要な Python プロジェクト向けの即戦力テンプレートを提供し、各判断の根拠も説明するので自分のプロジェクトに合わせた調整ができる。

なぜ Python は特に CLAUDE.md が必要なのか

コンパイル言語の多くには「明らかな一本道」がある。Python にはない。TypeScript プロジェクトの Claude Code セッションは npm install と tsc を合理的に仮定できる。Python プロジェクトでは uv sync・poetry install・pip install -e .・conda env create のいずれかかもしれない。CLAUDE.md なしでは毎回聞くか（遅い）、推測するか（間違う）のどちらかになる。

仮想環境の問題は特に深刻だ。Claude Code は venv が存在することだけでなく、その場所・（生成するコマンドにとって概念的に）どうアクティベートするか・どの Python バイナリを使うかを知る必要がある。venv の指示がなければ、Claude Code が間違ったインタープリターでコードを実行した後に定番の ModuleNotFoundError が発生する。

型チェックも悩みの種だ。mypy と pyright は設定ファイルが異なり、厳密さのレベルが異なり、同じコードベースで異なる挙動をする。どちらを使うか——どの厳密さで——を Claude Code に伝えることで、一方を通過して他方で落ちるコードの生成を防げる。

Python 向けミニマル CLAUDE.md

今日どんな Python プロジェクトにも投入できるテンプレートはここから始めよう:

# CLAUDE.md

## Python 環境

- Python バージョン: 3.12
- パッケージマネージャー: uv
- 仮想環境: `.venv/`（プロジェクトルート）

## コマンド

```bash
# セットアップ
uv sync                    # uv.lock から依存関係をインストール
uv sync --extra dev        # dev 依存関係も含む

# 実行
uv run python src/main.py  # 常に uv run を使う、python を直接叩かない

# テスト
uv run pytest              # 全テスト実行
uv run pytest -x           # 最初の失敗で停止
uv run pytest --cov=src    # カバレッジ付き

# Lint / フォーマット
uv run ruff check .        # リント
uv run ruff format .       # フォーマット
uv run mypy src/           # 型チェック

# ビルド
uv build                   # 配布物をビルド

コードスタイル

• フォーマッター: ruff（black でも autopep8 でもない）
• リンター: ruff
• 型チェッカー: mypy
• 行長: 88
• 関数シグネチャには必ず型アノテーションを付ける
• 前方参照には from __future__ import annotations を使う

プロジェクト構造

src/
  mypackage/
    __init__.py
    core.py
tests/
  test_core.py
pyproject.toml
uv.lock
CLAUDE.md

ルール

• pip install でパッケージをインストールしない。代わりに uv add <package> を使う。
• uv.lock を直接編集しない。
• 変更のコミット前に uv run ruff format . を実行する。
• タスクを完了とする前に uv run mypy src/ を実行する。
• テストは tests/ に配置する。ソースファイルと並べて置かない。

これは動作するが汎用的だ。以下のセクションで特定のプロジェクト種別に深みを加える。

## 完全版 CLAUDE.md テンプレート: Web API（FastAPI）

FastAPI プロジェクトには Claude Code が知るべき特有のパターンがある: 至るところにある async 関数・バリデーション用の Pydantic モデル・`Depends` による依存性注入・app ファクトリーとルーターモジュールの分離。

```markdown
# CLAUDE.md

## プロジェクト: FastAPI REST API

## 環境

- Python: 3.12
- パッケージマネージャー: uv
- 仮想環境: `.venv/`
- フレームワーク: FastAPI 0.115+
- ASGI サーバー: uvicorn（dev）/ gunicorn + uvicorn ワーカー（prod）

## コマンド

```bash
# セットアップ
uv sync --extra dev

# 開発サーバー（ホットリロード）
uv run uvicorn app.main:app --reload --port 8000

# テスト
uv run pytest                            # 全テスト
uv run pytest tests/unit/               # ユニットテストのみ
uv run pytest tests/integration/        # 統合テストのみ
uv run pytest -k "test_users"           # 名前でフィルタリング
uv run pytest --cov=app --cov-report=html  # カバレッジレポート

# リント
uv run ruff check app/ tests/
uv run ruff format app/ tests/
uv run mypy app/

# データベースマイグレーション（Alembic）
uv run alembic upgrade head             # 未適用マイグレーションを適用
uv run alembic revision --autogenerate -m "説明"  # 新規マイグレーション
uv run alembic downgrade -1             # 1つ前にロールバック

# ローカル env を読み込む
cp .env.example .env && uv run uvicorn app.main:app --reload

プロジェクト構造

app/
  __init__.py
  main.py           # FastAPI app ファクトリー、lifespan、ミドルウェア
  config.py         # pydantic-settings による設定
  dependencies.py   # 共有 FastAPI 依存関係
  routers/
    __init__.py
    users.py
    items.py
  models/
    __init__.py
    user.py         # SQLAlchemy モデル
  schemas/
    __init__.py
    user.py         # Pydantic リクエスト/レスポンススキーマ
  services/
    __init__.py
    user_service.py # ビジネスロジック、HTTP の関心事なし
  repositories/
    __init__.py
    user_repo.py    # データベースアクセス
tests/
  conftest.py       # pytest フィクスチャ（非同期クライアント、テスト DB）
  unit/
    test_user_service.py
  integration/
    test_users_api.py
alembic/
migrations/
pyproject.toml
.env.example

アーキテクチャルール

• ルーターは HTTP のみ扱う: リクエストをパース、サービスを呼び出し、レスポンスを返す。
• サービスはビジネスロジックを扱う: SQLAlchemy も FastAPI のインポートも入れない。
• リポジトリはデータベースを扱う: ORM の行ではなくドメインオブジェクトを返す。
• 設定には pydantic-settings を使う。アプリコードに os.environ.get() を書かない。
• すべてのルート関数は async def であること。
• 依存性注入には Annotated を使う: user: Annotated[User, Depends(get_current_user)]

テストパターン

# 常に非同期テストクライアントを使う
import pytest
from httpx import AsyncClient, ASGITransport
from app.main import app

@pytest.fixture
async def client():
    async with AsyncClient(
        transport=ASGITransport(app=app),
        base_url="http://test"
    ) as ac:
        yield ac

• テストは本物のデータベースに触れてはならない。conftest.py で get_db をオーバーライドする。
• 統合テストはテスト専用データベースを使う（SQLite インメモリまたは pytest-postgresql 付き Postgres）。
• 外部サービスは unittest.mock.AsyncMock でモックする。

型アノテーション

• すべての関数シグネチャに型アノテーションを付ける。
• すべての API スキーマに pydantic.BaseModel を使う。
• SQLAlchemy モデルは Mapped[T] 構文を使う（SQLAlchemy 2.0 スタイル）。
• ルート関数の戻り値型は response_model と一致させる。

やってはいけないこと

• ルーターで app.include_router() を使わない（main.py のみで使う）。
• ルート関数にビジネスロジックを置かない。
• .env ファイルをコミットしない。
• async エンドポイントで同期データベース呼び出しを使わない。

## 完全版 CLAUDE.md テンプレート: Django

Django プロジェクトはより多くの意見を内包しているが、Claude Code には特定の設定——特にデータベースマイグレーション・admin・DRF を使うかどうか——についての指示が依然として必要だ。

```markdown
# CLAUDE.md

## プロジェクト: Django Web アプリケーション

## 環境

- Python: 3.12
- パッケージマネージャー: uv
- フレームワーク: Django 5.1
- API: Django REST Framework 3.15
- データベース: PostgreSQL（ローカル: テスト用 SQLite）

## コマンド

```bash
# セットアップ
uv sync --extra dev
uv run python manage.py migrate
uv run python manage.py createsuperuser

# 開発
uv run python manage.py runserver

# テスト
uv run pytest                          # 全テスト（pytest-django 経由）
uv run pytest apps/users/              # 単一アプリ
uv run pytest --reuse-db               # テストデータベースを再利用（高速）
uv run pytest --create-db              # テストデータベースを強制再作成

# データベース
uv run python manage.py makemigrations # マイグレーション生成
uv run python manage.py migrate        # マイグレーション適用
uv run python manage.py showmigrations # マイグレーション状態確認

# 静的ファイル
uv run python manage.py collectstatic --noinput

# 品質管理
uv run ruff check .
uv run ruff format .
uv run mypy .

プロジェクト構造

config/
  settings/
    base.py
    local.py
    production.py
    test.py
  urls.py
  wsgi.py
  asgi.py
apps/
  users/
    migrations/
    admin.py
    apps.py
    managers.py
    models.py
    serializers.py
    views.py
    urls.py
    tests/
      test_models.py
      test_views.py
  core/
    models.py        # 抽象ベースモデル（TimeStampedModel 等）
templates/
static/
manage.py
pyproject.toml

Django 規約

• ローカル開発は DJANGO_SETTINGS_MODULE=config.settings.local を使う。
• アプリは apps/ に置く。プロジェクトルートには置かない。
• 全モデルは TimeStampedModel を継承する（created_at・updated_at を提供）。
• プロジェクト開始からカスタム User モデルを使う。django.contrib.auth.User を直接使わない。
• URL ネームスペース必須: すべての urls.py に app_name = "users"。

テストパターン

• pytest-django を使う。pyproject.toml で設定:

  [tool.pytest.ini_options]
  DJANGO_SETTINGS_MODULE = "config.settings.test"

• フィクスチャ生成は baker（model_bakery）を使う。手書きインスタンスは使わない。
• データベースに触れるテストには @pytest.mark.django_db を付ける。
• API テストは DRF の APIClient を使う。Django の TestClient は使わない。

マイグレーションルール

• チームの合意なしにマイグレーションをスカッシュしない。
• すべてのマイグレーションはロール可能（backwards の実装か自動ロール確認）。
• CI で uv run python manage.py migrate --check を実行する。

## Python プロジェクト向け AGENTS.md

AGENTS.md は CLAUDE.md とは異なる目的を持つ: CLAUDE.md が Claude Code を特定の設定に固定するのに対し、AGENTS.md はどの AI エージェントツールとも共有できる契約だ。チームが複数のツール（Claude Code・Cursor・GitHub Copilot・OpenAI Codex）を使う場合、AGENTS.md が共通の取り決めになる。

本番稼働レベルの Python プロジェクト向け AGENTS.md:

```markdown
# AGENTS.md

## プロジェクト概要

FastAPI で構築した Python 3.12 REST API。依存関係管理に uv、テストに pytest、
フォーマット/リントに ruff、型チェックに mypy を使用。

## クイックスタート

```bash
uv sync --extra dev
uv run uvicorn app.main:app --reload

リポジトリレイアウト

app/          ソースコード（FastAPI アプリケーション）
tests/        テストスイート（app/ の構造をミラーリング）
alembic/      データベースマイグレーション
docs/         API ドキュメント
scripts/      ユーティリティスクリプト（アプリの一部ではない）

重要: すべてのインポートは app パッケージ名前空間を使う。 トップレベルモジュール間で相対インポートを使わない。

タスク完了前に必須のコマンド

この順番で実行すること。エラーがあれば作業完了とする前に修正する:

uv run ruff check app/ tests/   # エラー 0 件で通過必須
uv run ruff format app/ tests/  # フォーマット適用
uv run mypy app/                # エラー 0 件で通過必須
uv run pytest                   # 全テストが通過必須

Python 規約

型アノテーション

すべての関数に型アノテーションが必要:

# 正しい
def get_user(user_id: int, db: Session) -> User | None:
    ...

# 間違い — アノテーションがない
def get_user(user_id, db):
    ...

Optional[X] ではなく X | None（ユニオン構文）を使う。Python 3.10+ の構文。

エラーハンドリング

• app/exceptions.py で定義したカスタム例外クラスを使う。
• FastAPI エンドポイントは例外ハンドラー経由で例外をキャッチする。ルートで try/except しない。
• 例外を黙って飲み込まない。

非同期処理

• すべてのルート関数は async def。
• データベース操作は async SQLAlchemy（AsyncSession）を使う。
• 独立した並行処理には asyncio.gather() を使う。
• 同期・非同期のデータベース呼び出しを混在させない。

依存関係

• 新しい依存関係の追加: uv add <package>
• dev 専用依存関係の追加: uv add --dev <package>
• pyproject.toml の依存関係を手動で編集しない。
• pip install を実行しない。

テストルール

• 新しいコードにはテストが必要。例外なし。
• テストファイルはソースをミラーリングする: app/services/user_service.py → tests/unit/test_user_service.py
• 最低カバレッジ: 新しいコードの 80% ライン（--cov-fail-under=80）。
• 統合テストでデータベースをモックしない——テストデータベースフィクスチャを使う。

やってはいけないこと

• デバッグに print() を使わない。logging.getLogger(__name__) を使う。
• 設定値をハードコードしない。app/config.py（pydantic-settings）を使う。
• シークレットをコミットしない。新しいファイルタイプを追加する前に .gitignore を確認する。
• 理由のコメントなしに # type: ignore で mypy を回避しない。

## Python 向け .claudeignore パターン

Claude Code は `.claudeignore` を git が `.gitignore` を扱うのと同じように尊重する。Python プロジェクトには、Claude Code に読んだり変更したりしてほしくないファイルが確実に存在する:

```gitignore
# .claudeignore

# Python キャッシュ — 読む必要は一切ない
__pycache__/
*.pyc
*.pyo
*.pyd
.Python

# 仮想環境
.venv/
venv/
env/
ENV/
.env.bak

# ビルド成果物
dist/
build/
*.egg-info/
.eggs/

# テスト成果物
.pytest_cache/
htmlcov/
.coverage
coverage.xml
*.cover

# 型チェックキャッシュ
.mypy_cache/
.dmypy.json
dmypy.json
.pyright/

# Jupyter
.ipynb_checkpoints/

# IDE
.idea/
.vscode/settings.json

# ローカルシークレット（絶対に読まれてはいけない）
.env
.env.local
.env.*.local
secrets.yml

# 大きなデータファイル
data/raw/
data/processed/
*.csv
*.parquet
*.h5

ここで重要なのは __pycache__ と .venv だ。これらのディレクトリには数千のファイルが含まれうる。Claude Code にそれらをインデックスさせるとコンテキストが無駄になり、有益な情報を何も提供しないバイトコードファイルを「読む」ことにもなりかねない。.claudeignore に列挙することで、Claude Code は実際のソースコードだけに集中できる。

uv との連携

2026 年には uv が事実上のデファクトな高速 Python パッケージマネージャーになっている。CLAUDE.md は uv のワークフローを明確に伝える必要がある。pip や poetry とはコマンドが異なるからだ。

## uv ワークフロー

# 依存関係のインストール
uv sync               # uv.lock からインストール（npm ci に相当）
uv sync --extra dev   # オプションの [dev] 依存関係も含む

# パッケージの追加
uv add requests                  # [dependencies] に追加
uv add --dev pytest ruff mypy    # [dev-dependencies] に追加
uv add "httpx>=0.27"             # バージョン制約付きで追加

# コードの実行
uv run python script.py          # プロジェクトの Python で実行
uv run pytest                    # uv 経由で pytest を実行
uv run --no-sync python script.py # 同期チェックをスキップ（スクリプトでは高速）

# 更新
uv lock --upgrade-package requests  # 単一パッケージを更新
uv lock --upgrade                   # 全パッケージを更新

# Python バージョン
uv python install 3.12           # 特定の Python バージョンをインストール
uv python pin 3.12               # プロジェクトを 3.12 に固定

この指示がないと Claude Code が最もよく犯すミス: uv add <package> とすべきところで pip install <package> を実行してしまう。pip install はロックファイルをバイパスして不整合を生む可能性がある。CLAUDE.md のルール「pip install は使わない。uv add を使う。」は短いが必須だ。

テストワークフロー

Claude Code が知るべきパターンを網羅した CLAUDE.md の完全なテストセクション:

## テスト

フレームワーク: pytest（pytest-cov 付き）

### テストの実行

```bash
# 完全なテストスイート
uv run pytest

# 単一ファイル
uv run pytest tests/unit/test_user_service.py

# 単一テスト
uv run pytest tests/unit/test_user_service.py::test_create_user_success

# カバレッジ付き
uv run pytest --cov=app --cov-report=term-missing

# 最初の失敗で停止
uv run pytest -x

# 詳細出力
uv run pytest -v

# fast マークのテストのみ実行
uv run pytest -m "not slow"

テスト構造

# 標準的なテストファイルレイアウト
import pytest
from unittest.mock import MagicMock, patch

from app.services.user_service import UserService
from app.schemas.user import UserCreate


class TestUserService:
    """UserService のテスト。"""

    @pytest.fixture
    def service(self, db_session: AsyncSession) -> UserService:
        return UserService(db=db_session)

    async def test_create_user_success(
        self,
        service: UserService,
        valid_user_data: UserCreate,
    ) -> None:
        """有効なデータでユーザーを作成する。"""
        user = await service.create_user(valid_user_data)

        assert user.email == valid_user_data.email
        assert user.id is not None

    async def test_create_user_duplicate_email(
        self,
        service: UserService,
        existing_user: User,
    ) -> None:
        """メールアドレス重複時に ValueError を発生させる。"""
        with pytest.raises(ValueError, match="already exists"):
            await service.create_user(
                UserCreate(email=existing_user.email, password="test")
            )

カバレッジ要件

• 新しいコード: 最低 80% のライン カバレッジ
• クリティカルパス（認証・決済・データ変更）: 95% 以上
• CI で強制するには uv run pytest --cov-fail-under=80

## データサイエンスと Jupyter Notebook パターン

データサイエンスプロジェクトでは、ノートブックからモジュールへのパイプラインを CLAUDE.md で説明する必要がある。Claude Code はノートブック（探索）とモジュール（本番）をいつ使うかを理解しなければならない。

```markdown
## データサイエンス設定

## 環境

- Python: 3.12
- パッケージマネージャー: uv
- ノートブックランナー: jupyter lab
- コアスタック: pandas・numpy・scikit-learn・matplotlib

## コマンド

```bash
# セットアップ
uv sync --extra dev

# Jupyter
uv run jupyter lab              # Jupyter Lab を起動
uv run jupyter nbconvert --execute notebooks/analysis.ipynb  # ヘッドレスでノートブックを実行

# データパイプライン
uv run python src/pipeline/ingest.py    # データ取り込みを実行
uv run python src/pipeline/transform.py # 変換を実行
uv run python src/pipeline/train.py     # トレーニングを実行

# テスト
uv run pytest tests/
uv run pytest tests/ -m "not slow"  # 完全なデータセットを必要とする遅いテストをスキップ

# 品質管理
uv run ruff check src/
uv run mypy src/

プロジェクト構造

notebooks/
  01_exploration.ipynb    # 探索専用、インポートしない
  02_feature_analysis.ipynb
src/
  data/
    loader.py       # データロードユーティリティ
    validator.py    # スキーマバリデーション
  features/
    engineering.py  # 特徴量エンジニアリング関数
  models/
    trainer.py
    evaluator.py
  pipeline/
    ingest.py
    transform.py
    train.py
tests/
  test_features.py
  test_models.py
data/
  raw/              # コミットしない、.gitignore に記載
  processed/        # コミットしない、.gitignore に記載

ノートブック vs モジュール

ノートブック: 探索と可視化専用。ノートブックからインポートしない。 ノートブックのコードを保持する価値がある場合は src/ にリファクタリングする。

src/ のモジュール: 再利用可能な関数、テスト済み、型アノテーション付き、リント済み。 すべての本番コードはここに置く。

データルール

• 生データファイルをコミットしない（.gitignore に追加済み）。
• pathlib.Path を至るところで使う。os.path.join() は使わない。
• DataFrame: pandera または手動チェックでロード時にスキーマを常に検証する。
• 生データを変更しない。常にコピーから作業する。
• DataFrame の列名と dtype をモジュールの docstring に記録する。

Claude Code が従うべき pandas パターン

# 推奨: 型アノテーション付きのメソッドチェーン
def process_sales(df: pd.DataFrame) -> pd.DataFrame:
    return (
        df
        .assign(revenue=lambda x: x["price"] * x["quantity"])
        .query("revenue > 0")
        .groupby("product_id", as_index=False)
        .agg(total_revenue=("revenue", "sum"))
        .sort_values("total_revenue", ascending=False)
    )

# 避けるべき: 明示的な列参照なしのインデックスベースアクセス
# df[0]  <- 壊れやすい。df.iloc[0] か df["column_name"] を使う

# read 時に明示的な dtype を優先する
df = pd.read_csv("data.csv", dtype={"id": int, "price": float})

## 型チェック: mypy vs pyright

mypy と pyright は Python プロジェクトで一般的に使われている。両者は意味のある違いがあるため、CLAUDE.md でどちらを使うか、どの設定レベルで使うかを指定する必要がある。一方を通過して他方で落ちるコードを Claude Code が生成するのは、2行の CLAUDE.md エントリで防げるフラストレーティングな問題だ。

```markdown
## 型チェック

ツール: mypy
設定ファイル: pyproject.toml

```toml
[tool.mypy]
python_version = "3.12"
strict = true
plugins = ["pydantic.mypy"]

[[tool.mypy.overrides]]
module = ["tests.*"]
disallow_untyped_defs = false

実行: uv run mypy src/

strict モードとは以下を意味する:

• すべての関数引数と戻り値型にアノテーションが必要
• 暗黙的な Any は禁止
• 型なし関数定義は禁止
• 未使用の ignore に警告

mypy がエラーを報告した場合は、根本的な型の問題を修正する。 # type: ignore[specific-error] は、サードパーティライブラリのスタブが不完全な場合のみ使い、 常になぜかのコメントを付ける。

## マルチ環境問題

Python プロジェクトは多くの場合、複数の環境で実行される: ローカル開発・CI・Docker・本番。CLAUDE.md は Claude Code にどの環境で操作しているか、どの仮定が安全かを伝えるべきだ。

```markdown
## 環境

### ローカル開発（現在のコンテキスト）

- OS: macOS / Linux
- Python バイナリ: uv で管理（`.venv/bin/python`）
- データベース: ポート 5432 のローカル PostgreSQL
- 環境変数: プロジェクトルートの `.env` ファイル
- ファイルパス: 常に `pathlib.Path` を使う。`/home/...` のハードコードパスは使わない

### CI（GitHub Actions）

- Python: `actions/setup-python` でインストール
- データベース: PostgreSQL サービスコンテナ
- 環境変数: GitHub Actions シークレット経由で設定
- `.env` ファイルなし——すべての設定は環境変数経由

### Docker（本番に近いテスト）

```bash
docker compose up -d          # 全サービスを起動
docker compose exec api pytest # コンテナ内でテストを実行
docker compose down           # サービスを停止

「ローカルでは動くが CI で失敗する」問題のデバッグ時は以下を確認:

1. Python バージョンの不一致（.python-version に固定済み）
2. 環境変数の欠落
3. パス区切り文字の違い（/ vs \）
4. データベースマイグレーションの状態

## よくあるミスと CLAUDE.md による防止策

**ミス: Claude Code が間違った Python を実行する**

`uv run` プレフィックスなしだと、Claude Code はシステム Python か間違った venv を使うかもしれない。修正: CLAUDE.md で「すべてのコマンドは `uv run <command>` を使う」ルール。

**ミス: Claude Code がパッケージをシステム全体にインストールする**

アクティブな venv なしの `pip install` はシステム Python にインストールする。修正: CLAUDE.md に「pip install は使わない。uv add を使う。」

**ミス: Claude Code が型チェックをスキップする**

完了の定義に型チェックが含まれていない場合、型エラーが蓄積する。修正: AGENTS.md の「終了前に必須」リストに mypy/pyright を追加。

**ミス: Claude Code が `X | None` の代わりに `Optional[X]` を生成する**

3.10 以前の構文が生成コードに現れる。修正: 型アノテーションセクションに「`Optional[X]` ではなく `X | None` を使う」を追加。

**ミス: Claude Code が `pathlib.Path` の代わりに `os.path` を使う**

`pathlib.Path` が現代の標準でクロスプラットフォームのパスを正しく処理する。修正: CLAUDE.md に明示的なルール。

**ミス: Claude Code がデバッグに print 文を追加する**

生成コードで一般的。修正: AGENTS.md に「`print()` ではなく `logging.getLogger(__name__)` を使う」。

## まとめ

上記の CLAUDE.md・AGENTS.md テンプレートは出発点だ。実際に機能するのは、チームが実際にメンテナンスするものだ。有用な状態を保つためのいくつかの原則:

**コマンドは実行可能な状態に保つ。** CLAUDE.md のすべてのコマンドは、ターミナルに貼り付けてそのまま実行できるものでなければならない。ドキュメント化されていない環境セットアップが必要なコマンドは無意味だ。

**ルールは検証可能にする。** 「良いコードを書く」は Claude Code が確認できないルールだ。「完了とする前にエラー 0 件で mypy を実行する」は検証できる。明確な合格/不合格の状態があるルールを書く。

**規約が変わったら更新する。** チームが black から ruff に、あるいは poetry から uv に切り替えたら、同じコミットで CLAUDE.md を更新する。古くなった CLAUDE.md は CLAUDE.md なしよりも悪い——積極的に間違った方向に導く。

**最小限から始め、問題が起きたら追加する。** 正確な 20 行の CLAUDE.md は、30% 間違っている 200 行のものより価値がある。Claude Code が犯す特定のミスを防ぎたい時にセクションを追加していく。

Python エコシステムは変化し続ける。2 年前は uv が明らかな選択肢ではなかった。次に何が来ようとも、CLAUDE.md のパターンは同じだ: プロジェクトで何を使うかを Claude Code に正確に伝えれば、それを使ってくれる。

[ルールコレクション](/rules) では、コミュニティが投稿した Python プロジェクト向け CLAUDE.md・AGENTS.md テンプレートをさらに多く掲載している。