Claude Codeを使うたびに「このプロジェクトはPythonで、ビルドコマンドは…」と説明するのは非効率です。CLAUDE.mdを整備すると、この説明が不要になります。
CLAUDE.mdとは
プロジェクトルートに置くと、Claude Codeが毎セッション自動で読み込むコンテキストファイルです。
/init # セッション内でCLAUDE.mdを自動生成（プロジェクト構造を解析して下書きを作成）
3層の階層構造
| ファイルパス | スコープ | 用途 |
|---|---|---|
~/.claude/CLAUDE.md |
グローバル | 全プロジェクト共通のルール・好み |
.claude/CLAUDE.md |
プロジェクト | チームで共有するプロジェクト固有の情報 |
.claude/CLAUDE.local.md |
個人 | gitignoreに入れる個人設定 |
書くべき内容
# プロジェクト名
## コマンド
ビルド: python builder.py
サーバー起動: uvicorn cms.main:app --reload --port 8001
テスト: pytest
## 重要ファイル
- builder.py — 静的HTML生成エンジン
- site.yaml — サイト全体設定
- cms/main.py — FastAPIエントリポイント
## 触ってはいけないもの
- build/ 配下（builder.pyの出力物、直接編集不可）
## 技術スタック
FastAPI + Jinja2 + Python 3.12
Karpathyルールを追加する
元OpenAI創業者のAndrej Karpathyの開発哲学をAIへのルールに落とし込んだもの（github.com/forrestchang/andrej-karpathy-skills）。
AIが犯す典型的な失敗——でたらめな推測・過剰エンジニアリング・無関係な改変——を事前にルールで封じます。
## 開発原則
1. 先に考えろ
要件が曖昧なときは質問する。仮定で進まない。
2. シンプル優先
余計な機能・抽象化を追加しない。
「将来使うかも」で設計しない。
3. 精密に直せ
必要な箇所以外触らない。
無関係なファイルの改変・リファクタを禁止。
4. 目標駆動
「このエラーを消す」「この機能を追加する」など
明確なゴールを持って動く。
このルールをCLAUDE.mdに追加するだけで、AIが「速いけど雑」から「制御された開発者」に変わります。
planモード強制でコストを3分の1に削減する
上記のKarpathyルール「#1 先に考えろ」をさらに具体化した、即効性の高いテクニックです。
CLAUDE.mdに以下の1行を追加するだけで、実装前に必ず設計フェーズを経るようになります。
## 実装ルール
実装を始める前に必ずplanモードで設計を出してから書くこと。
コードを書く前に、アプローチ・変更対象ファイル・手順を提示して確認を取ること。
なぜ効果があるか：
planモードなしの場合、Claudeは「とりあえず実装→エラー→修正→エラー→修正…」のループに入りやすく、このループ1回ごとにトークンを消費します。実装前に計画を確定させることでループ自体が発生しにくくなります。
なお、planモードはCLI起動時のフラグ（--permission-mode plan）としても設定できます。
claude --permission-mode plan
注記： 削減効果の数値はテスト環境・タスクの複雑さに大きく依存します。ただし「計画を立ててから実装する」という原則自体の有効性は、Eric SchluntzやBoris Chernyの講義でも一貫して強調されています。
カスタムスキル・コマンドを作る
現在の推奨方法：.claude/skills/ にSkillを置く
.claude/commands/ は後方互換性のために残っていますが、新規作成は .claude/skills/ が推奨に変わりました（公式ドキュメント更新済み）。
mkdir -p .claude/skills/build
# .claude/skills/build/SKILL.md
---
name: build
description: 静的サイトをビルドするスキル
---
以下を実行して結果を報告すること：
\`\`\`bash
.venv/Scripts/python.exe builder.py
\`\`\`
エラーがあれば原因を特定して修正案を提示する。
→ /build で呼び出せるようになります。