Claude Code ベストプラクティス

多くの開発者はClaude Codeをチャットボットとして扱う。曖昧なリクエストを入力し、曖昧な結果を受け取り、ツールのせいにする。10倍の成果を出している開発者は別のことをしている。彼らはClaude Codeの周りにシステムを構築し、毎セッションが前のセッションより生産的になるようにしている。

これが、出荷し続けるエンジニアと苦労するエンジニアを分ける5つの習慣だ。プラグインも特別なセットアップも不要。エージェントAIと作業するためのより良い運用モデルだ。

1. PRDファースト開発

エージェントによるコーディングで最大の単一ミスは、計画なしに始めることだ。Claude Codeを開き、2文でフィーチャーを説明し、動かし始める。20分後には実際に必要なものと一致しないコードの中で3つの脱線深くにいる。

プロダクト要件ドキュメント（PRD）がこれを解決する。50ページの企業仕様書ではない。5分でできる軽量なMarkdownファイルだ。

# Feature: User Authentication
 
## Mission
 
Add email/password authentication with session management.
 
## In Scope
 
- Sign up, login, logout flows
- Password hashing with bcrypt
- JWT session tokens with 24-hour expiry
- Protected route middleware
 
## Out of Scope
 
- OAuth providers (Phase 2)
- Two-factor authentication (Phase 3)
- Password reset flow (separate task)
 
## Architecture
 
- Auth routes: /api/auth/signup, /api/auth/login, /api/auth/logout
- Middleware: src/middleware/auth.ts
- Database: users table with email, password_hash, created_at

PRDなしではコンテキストが漂流する。Claudeは一度も議論しなかったアーキテクチャの判断を始める。「ほとんどの認証システムに含まれているから」OAuthを追加する。「関連しそうだから」パスワードリセットフローを作る。修正に費やす時間が構築に費やす時間より多くなる。

PRDがあれば、すべてのセッションにガードレールがある。「PRDを読んで、サインアップフローを実装して」とClaudeに伝える。スコープの内外と一致すべきパターンを正確に把握している。あるセクションが完了したら「PRDに基づいて次に何を作るべき？」と聞けば、軌道から外れない。

これは既存のプロジェクトにも効く。グリーンフィールド作業では、PRDはMVPのブリーフだ。ブラウンフィールド作業では、PRDは今持っているものを記録し、次に欲しいものを明示する。出発点は異なるが、構造は同じだ。

PRDはマルチセッションの問題も解決する。Claude Codeはセッション間に記憶を持たないが、PRDは持つ。各新しいセッションは同じドキュメントで始まるので、正確に中断したところから再開できる。

2. モジュラーなルールアーキテクチャ

多くの開発者はCLAUDE.mdで同じミスを犯す。すべてを1つのファイルに詰め込む。技術スタック、コーディング規約、テストルール、デプロイ手順、APIパターン。1つの巨大な指示の壁。

問題はコンテキストの無駄遣いだ。ClaudeはセッションのPの冒頭にCLAUDE.md全体を読み込み、その中のすべてのトークンが注意を奪い合う。データベースマイグレーションのデバッグ中にReactのパターンが読み込まれる。ユニットテストを書いているときにデプロイルールが読み込まれる。

より良いアプローチ: CLAUDE.mdはリーンに保ち、タスク固有のドキュメントを指し示す。

# CLAUDE.md
 
## Tech Stack
 
- Next.js 15 with App Router
- TypeScript strict mode
- PostgreSQL with Prisma ORM
- Tailwind CSS
 
## Standards
 
- Use path aliases (@/components, @/lib, @/utils)
- All functions require explicit return types
- Error handling: guard clauses with early returns
- Tests required for business logic
 
## Reference Docs (load when relevant)
 
- Frontend conventions: .claude/skills/react/SKILL.md
- API patterns: .claude/skills/api/SKILL.md
- Database rules: .claude/skills/postgres/SKILL.md
- Deployment: .claude/skills/infra/SKILL.md

約15行。すべてのタスクに適用される汎用ルールをカバーしている。詳細な知識は別ファイルに存在し、タスクが必要とするときだけClaudeが読み込む。

フォルダ構成:

.claude/
├── skills/
│   ├── react/          # Component patterns, hooks, state
│   ├── api/            # Route conventions, validation, auth
│   ├── postgres/       # Schema patterns, query optimization
│   └── infra/          # Docker, CI/CD, deployment
└── CLAUDE.md           # Lightweight global rules

CLAUDE.mdに200行以上の指示が入っている「何でも1ファイル」の習慣と比べてほしい。そのファイルは関係があるかどうかに関わらず、すべてのセッションでコンテキストを消費する。モジュラーなアプローチはドメインの知識をオンデマンドで読み込む。

3. すべてをコマンド化する

何かを2回プロンプトするなら、コマンドにすべきだ。

Claude Codeのコマンドは.claude/commands/内のMarkdownファイルで、再利用可能なワークフローを定義する。/commitと入力すると、Claudeがコマンドファイルを読み込んで指示に従う。再入力なし。ステップの忘れなし。

シンプルなコマンドの例:

# /commit
 
Review all staged changes with `git diff --cached`.
Write a commit message that:
 
- Starts with a verb (add, fix, update, remove)
- Summarizes the WHY, not the WHAT
- Stays under 72 characters
- Uses lowercase
 
Create the commit. Do not push.

これを.claude/commands/commit.mdとして保存すれば、二度とコミットの指示を書く必要はない。

作る価値のある5つのスターターコマンド:

/commit: 一貫した整形されたgitコミット
/review: プロジェクトの基準に対するコードレビュー
/plan: コード作成前の構造化された実装プランの生成
/prime: 各会話の開始時にセッションコンテキストを読み込む
/execute: 前のセッションで作成したプランドキュメントを実行する

各コマンドは5分で書け、プロジェクトの生涯で何百ものプロンプトを節約する。また一貫性も強制する。コミットは常に同じフォーマットに従う。コードレビューは常に同じことをチェックする。複利効果は本物だ。

4. コンテキストリセット

これが直感に反する唯一の習慣だ。計画と実行は別々の会話で行うべきだ。

フロー:

計画セッション: 問題を調査し、トレードオフを議論し、アプローチを探索する。Claudeが構造化されたプランドキュメント（プロジェクトに保存されたMarkdownファイル）を出力する。
コンテキストをクリア: 会話を完全に終了する。セッションを終わらせる。
実行セッション: フレッシュに始める。ステップ1のプランドキュメントだけをClaudeに渡す。他は何も渡さない。

なぜこうするのか？コンテキストウィンドウの劣化は本物だからだ。

長い計画会話の後、Claudeのコンテキストは探索的な脱線、却下されたアプローチ、もはや適用されない中間推論で満たされている。「では作ってください」と言うと、Claudeはそのノイズをすべて実行に持ち込む。議論して却下したアプローチを避けるかもしれない。最終プランがそれを推薦しているにもかかわらず。会話の早い段階で後から修正した前提を引き継ぐかもしれない。

プランだけのフレッシュなコンテキストは、Claudeがクリーンな状態で実行を開始することを意味する。計画フェーズからの荷物なし。古い前提なし。仕様だけ。そして計画の履歴でトークンを燃やさないので、Claudeは実装の詳細について推論し、作業を自己チェックする余地がある。

プランドキュメントは単独で成立しなければならない。良いプランにはフィーチャーの説明、ユーザーストーリー、アーキテクチャのコンテキスト、関連するコンポーネントへの参照、タスクごとの内訳が含まれる。実行中にClaudeが確認の質問をする必要があれば、プランにギャップがある。

実際には:

# Planning session
claude "Research auth patterns for our Next.js app and create
an implementation plan. Save it to docs/auth-plan.md"
 
# (exit, start new session)
 
# Execution session
claude "Read docs/auth-plan.md and implement Phase 1"

プランドキュメントは計画する脳と実行する脳のハンドオフとして機能する。どちらのセッションも両方の仕事をしようとしないため、どちらもより鋭くなる。

5. システム進化の思考法

すべてのバグはシステムの失敗であり、一回限りのミスではない。優れたエージェントエンジニアリングと優れたエージェントエンジニアリングの差は、インスタンスを修正するかシステムを修正するかだ。

3つの実際の例:

誤ったインポートスタイル。 Claudeがパスエイリアスの代わりに相対インポート（../../components/Button）を使い続ける。一つ一つ手で修正することもできる。あるいはCLAUDE.mdに1行追加する: 「インポートには常に@パスエイリアスを使い、相対パスは使わない」。バグは二度と来ない。

テストを実行し忘れた。 フィーチャーを完成させ、CIにプッシュし、Claudeがローカルで実行しなかったためテストが失敗する。毎回「テストを実行して」とプロンプトするのではなく、/executeコマンドテンプレートを更新して、すべての実装セッションの終わりに必須のテストステップを含める。これですべての実行セッションはデフォルトでテスト実行で終わる。

誤った認証フロー。 プロジェクトがヘッダーのベアラートークンを使っているのに、ClaudeがCookieを使ったJWT認証を作る。それは認証パターンの参照ドキュメントがないために起きた。トークンフォーマット、ヘッダー規約、ミドルウェアパターンを含む.claude/skills/auth/SKILL.mdを作成する。次回誰か（将来の自分も含む）が認証に取り組むとき、Claudeは自動的に正しいパターンを読み込む。

パターンは常に同じだ。何かがうまくいかない、欠けている指示や欠けている参照に遡り、システムに追加する。数週間で設定が引き締まる。システムのギャップが少なくなるため、Claudeのミスが減る。

習慣を作る実践的な方法: すべてのフィーチャーの後、Claudeにルールとコマンドをレビューさせ、実行とプランを比較させ、改善すべき点を提案させる。「CLAUDE.mdと使ったコマンドを読んで。遭遇した問題を防ぐために、どんなルールやプロセスの変更があればよかった？」これでシステム進化は後付けから定例ステップになる。

これがClaude Codeのユーザーとクラフトマンを分ける。ユーザーはバグを修正する。クラフトマンはバグを生み出したシステムを修正する。

まとめ

これら5つの習慣は独立したヒントではない。システムを形成している。

PRDが作業のスコープを定める。モジュラーなルールがコンテキストをクリーンに保つ。コマンドが繰り返しを排除する。コンテキストリセットがセッションを鋭く保つ。システム進化が全体を時間とともに改善する。

これは新しいツールも高価なセットアップも必要としない。構築するすべてのプロジェクトで複利として機能する習慣のセットだ。今日の最大の痛みに対処するものから始め、他は追加していく。