前回の記事でClaude Code(Anthropicのターミナル型AIコーディングエージェント)のコスト管理・Hooks・Skills・Subagents・並列実行・権限モードをまとめました。今回はその続編として、CLAUDE.mdの設計方法・大きな機能を作る際のワークフロー・よくある失敗パターンなど、日々の使い方に関わる部分を中心にまとめます。
- 検証時点のバージョン: Claude Code v2.1.207
- 主な出典:
code.claude.com/docs/en/配下の公式ドキュメント、Claude Code開発者(Boris Cherny氏)の公開投稿
目次
- 1. CLAUDE.mdのベストプラクティス
- 2. 大きな機能はインタビュー→SPEC.md
- 3. プロンプトのレベルアップ技法
- 4. 5大失敗パターン
- 5. MCP関連Tips
- 6. その他の便利コマンド
1. CLAUDE.mdのベストプラクティス
CLAUDE.mdは毎セッション読み込まれる特別なファイルです。/init で雛形を生成できます。
含めるべき/含めるべきでない
公式ドキュメントが挙げる基準は明快です: 「この行を消したらClaudeがミスするようになるか？」 ノーなら消します。
| ✅ 含める | ❌ 除外する |
|---|---|
| Claudeが推測できないBashコマンド | コードを読めば分かること |
| 既定と異なるコードスタイルのルール | Claudeが既に知っている標準的な言語の慣習 |
| テスト手順・使用するテストランナー | 詳細なAPIドキュメント(リンクで代替) |
| リポジトリのエチケット(ブランチ命名等) | 頻繁に変わる情報 |
| プロジェクト固有のアーキテクチャ判断 | 長い説明・チュートリアル |
| 開発環境の癖(必須の環境変数等) | 「きれいなコードを書く」のような自明な作法 |
「IMPORTANT」「YOU MUST」等の強調で遵守度を上げられます。CLAUDE.mdは200行未満を目安に、それを超える詳細は次項の方法で分割します。
大きくなったら分割する
-
.claude/rules/にトピック別ファイル(code-style.md,testing.md,security.md等)を置き、frontmatterにpaths: ["src/api/**/*.ts", ...]を書くと適用範囲を特定パスに限定できる - CLAUDE.md内で
@path/to/file構文により他ファイルをインポート可能 - 配置場所は用途で使い分ける:
~/.claude/CLAUDE.md(全セッション共通)/./CLAUDE.md(Git管理・チーム共有)/./CLAUDE.local.md(個人用、.gitignore対象)/ モノレポでは親子ディレクトリのCLAUDE.mdが自動結合される
# CLAUDE.md
See @README.md for project overview and @package.json for available npm commands.
# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md
圧縮方針もCLAUDE.mdに書ける
# Compact instructions
When you are using compact, please focus on test output and code changes
2. 大きな機能はインタビュー→SPEC.md
大きな機能を作る前に、Claudeに要件を掘り下げさせてから仕様書を書かせ、実装は新しいセッションで行うという公式推奨の手順です。
I want to build [機能の概要]. Interview me in detail using the AskUserQuestion tool.
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs.
Don't ask obvious questions, dig into the hard parts I might not have considered.
Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.
仕様が固まったら新しいセッションを始めて実装に着手します。新セッションはコンテキストが実装だけに集中でき、SPEC.mdという書かれた仕様書を参照点にできます。良い仕様書の条件は、対象となるファイル・インターフェースを明記していること、スコープ外を明示していること、そして「機能が実際に動くことを証明するエンドツーエンドの検証手順」で終わっていることです。
3. プロンプトのレベルアップ技法
Claude Code開発者(Boris Cherny氏)の公開投稿より、いくつか実用的な技法です。
- 厳しくレビューさせる: 「これらの変更について私を厳しく評価して、テストに合格するまでPRを作成しないで」と言い、Claude自身にレビュアー役を演じさせる
- 動作を証明させる: 「これが機能することを証明して」と言い、mainブランチとfeatureブランチの動作差分をdiffさせる
- 2段階レビュー: 1つ目のセッションにプランを書かせ、2つ目のセッションを「スタッフエンジニア」役としてそのプランをレビューさせる
- ミス→CLAUDE.md更新のループ: Claudeを訂正するたびに「そのミスを繰り返さないためにCLAUDE.mdを更新して」と締めくくる。地道だがCLAUDE.mdの質が着実に上がる
- 「1日1回ルール」: 1日1回以上行う作業はスキル/コマンド化する
4. 5大失敗パターン
公式ドキュメントが挙げる、よくある失敗とその対処法です。
| パターン | 症状 | 対処 |
|---|---|---|
| kitchen sink session | 1つのタスクの途中で無関係な話題を挟み、また元のタスクに戻る。コンテキストが無関係な情報で埋まる | 無関係なタスクの間は /clear
|
| 訂正ループ | 同じ間違いを2回訂正しても直らない。コンテキストが失敗した試行で汚染される | 2回失敗したら /clear して、学びを反映した具体的な初期プロンプトで仕切り直す |
| CLAUDE.mdの肥大化 | CLAUDE.mdが長すぎて重要なルールが埋もれ、Claudeが半分無視するようになる | 容赦なく刈り込む。既にできていることは削除するかhook化する |
| 検証なき信頼 | もっともらしいが、エッジケースを処理していない実装ができあがる | 常にテスト・スクリプト・スクリーンショット等の検証手段を用意する。検証できないものは出荷しない |
| 無限探索 | 「調査して」とだけ頼み、スコープを絞らない。数百ファイルを読まれてコンテキストが圧迫される | 調査範囲を狭く指定するか、subagentに委譲してメインの会話を汚さない |
5. MCP関連Tips
- MCPツール定義は既定で遅延読込され、ツール名のみがコンテキストに乗る(実際に使うまで詳細は読み込まれない)
-
gh/aws/gcloud/sentry-cli等のCLIツールは、ツール一覧が一切コンテキストに乗らないためMCPよりさらに軽量。既に知らないCLIツールもfoo --helpから学習させられる -
claude mcp addでMCPサーバーを接続できる -
/mcpで設定済みサーバーを一覧・無効化できる。使っていないMCPサーバーは切っておくとコンテキスト節約になる
6. その他の便利コマンド
前回紹介しきれなかったコマンドです。
| コマンド | 用途 |
|---|---|
/tasks |
バックグラウンドで実行中のタスク一覧を表示 |
/background [prompt] |
現在のセッションをバックグラウンドエージェント化して端末を解放 |
/insights |
セッションの分析レポートを生成 |
/recap |
現在のセッションの要約を生成 |
/diff |
ターンごとの変更を表示するインタラクティブな差分ビューア |
/simplify [target] |
バグ検出なしのクリーンアップ専用レビュー(v2.1.154+) |
/teleport |
Webセッションをターミナルに取り込む |
/reload-skills |
スキルを再スキャン(v2.1.152+、新しく追加したSkillを反映させたい時に) |
本記事の内容は2026年7月時点のClaude Code(v2.1.207)公式ドキュメントを元にしています。バージョンアップにより仕様が変わる可能性があるので、最新情報は 公式ドキュメント を参照してください。