Claudeをうまく使おう。~claude利用環境を整備しよう~ / how_to_use_claude_effectively

Claude Codeで「CLAUDE.md」「.claude/」ディレクトリを運用する際のベストプラクティスを、公開されている主要な事例(Anthropic公式・shanraisshan・HumanLayerなど)から整理した資料です。
ファイル構成のルールから、行数制限、命名規則、アンチパターン、コンテキスト管理の運用フローまでを12項目でカバーしています。Claude Codeの設定を体系立てて見直したい人向けの実践ガイドです。

Transcript

1. Claudeをうまく使おう。
2. Claudeを使っていますか？
3. 無駄なやり取りしてませんか？
4. それ。 CLAUDE.md で解決するかも。
5. 目次 CLAUDE.md・.claude ディレクトリ・記述のベストプラクティスを、公開されている主要事例から整理 1 CLAUDE.mdの基本 7 命名規則 2 ファイル構成と配置ルール 8 強調キーワードとガードレール 3 推奨される全体構成 9 設定時の注意点（アンチパターン） 4 行数制限 10 運用ワークフローとコンテキスト管理 5 .claude/ ディレクトリの使い方 11 デバッグ・コミット・記憶の階層 6 記述のベストプラクティス 12 設定前チェックリスト
6. 1. CLAUDE.mdの基本 Claude Codeがセッション開始時に自動でコンテキストへ取り込む、プロジェクト固有の「システムプロンプト」 書くべき内容 — Claudeがコードから読み取れない情報のみ 読み込みタイミング セッション起動時に自動読み込み リポジトリの階層構造に応じて、 よく使うbashコマンド（ビルド・テスト・リント） 主要ファイルとユーティリティ関数 複数のCLAUDE.mdが連結されて コードスタイルのガイドライン 読み込まれる テスト手順 例：モノレポ リポジトリのエチケット（ブランチ命名・ merge/rebase） 以下の構成の場合 開発環境のセットアップ（ pyenv、コンパイラ等） ・root/CLAUDE.md プロジェクト特有の予期せぬ挙動や警告 ・root/foo/CLAUDE.md root/foo 起動時に両方を連結して読 み込む 逆に書かないほうがよいもの： Claudeがコードを読めば分かること（詳細は 4章）
7. 2. ファイル構成と配置ルール 配置場所ごとに読み込み範囲と用途が異なる。用途に応じて使い分ける。 場所 ファイル名 読み込み範囲 用途 リポジトリルート CLAUDE.md 全セッションで常時 チーム共有の標準設定（git推奨） リポジトリルート CLAUDE.local.md 全セッションで常時 個人設定（.gitignore推奨） 親ディレクトリ CLAUDE.md 全セッションで常時 モノレポの祖先読み込み 子ディレクトリ CLAUDE.md 該当ファイル操作時のみ ディレクトリ固有の規約（遅延読み込み） ホーム ~/.claude/CLAUDE.md 全セッションで常時 全プロジェクト共通の個人設定 出典： Anthropic公式（ gist: jussker）
8. 2.2 推奨される全体構成 プロジェクトルート / ├── CLAUDE.md # ルート設定（ 100-200行以内） ├── CLAUDE.local.md # カスタム設定 ├── .claude/ │ ├── settings.json # 権限・モデル（決定論的設定） │ ├── rules/ # 分割された規約（遅延読み込み） │ ├── commands/ # スラッシュコマンド │ ├── agents/ # サブエージェント定義 │ └── skills/ # スキル（フォルダ構造） │ └── <name>/ │ ├── SKILL.md │ ├── references/ │ ├── scripts/ │ └── examples/ ├── docs/ # 詳細ドキュメント（ @importで参照） └── README.md ポイント CLAUDE.md本体は短く保ち、 詳細は .claude/rules/ に分割 決定論的な設定（権限・モデル）は settings.json に集約 汎用ワークフローはコマンド、 特化処理はエージェント /スキルへ 長文ドキュメントは docs/ に置き @import で参照する 出典： shanraisshan／MuhammadUsmanGM／josix
9. 2.3 CLAUDE.mdの行数制限 Anthropic公式推奨 200行以内 長いファイルはコンテキストを消費し、規約の遵守率が下がる。実運用ではより厳しく抑えるのが主流。 リポジトリルート サブディレクトリ 60~300行 50~100行 HumanLayerチーム推奨 rosmur推奨 目標 60行 / ハードリミット 300行 目標 50行 / ハードリミット 100行 shanraisshanの見解： 「200行以内で信頼できる遵守が得られる。ただし 100%の保証はない」
10. 3. .claude/ ディレクトリの使い方 1 rules/ 規約を分割 paths: frontmatterがあれば該当ファイル編 集時のみ読み込む遅延読み込み 4 skills/ 手順や背景を定義 SKILL.md＋references/・scripts/・examp les/の完全なフォルダ構造 2 commands/ コマンドショートカットを作成 よく使うワークフローをスラッシュコマンド化 （/setup, /verify, /db） 5 3 agents/ 特化型サブエージェントを定義 機能ごとに特化＋スキルで構成 settings.json ハーネスを定義 権限・モデル・アトリビューション等、決定論 的に強制すべき挙動 出典：shanraisshan（.claude運用パターン全般）
11. 4. 記述のベストプラクティス 判断基準：「 Claudeがコードから読み取れるか？」を自問し、読み取れるなら書かない。 WHAT WHY HOW 技術スタック プロジェクト構造 コードベースマップ 各部分の目的と役割 使うツール テストの実行方法 変更の検証方法 構造化と具体性のポイント Markdownのヘッダと箇条書きで関連指示をグループ化（密な散文にしない） 「いい感じに」ではなく「 npm run typecheck && npm run lint を実行」のように具体的・検証可能に ビルド・テストコマンドを必ず記載し、「テストを走らせて」で動く状態にする キーファイルの場所とアーキテクチャを明記する リポジトリのエチケット（ブランチ命名、 merge/rebase、PR運用）を記載する 出典：chealthガイド／ dev.to／HumanLayer
12. 5. 命名規則 小文字のkebab-caseを使用。コマンド名は動詞や対象を表す短い単語にする。 対象 命名規則 例 ルート設定 CLAUDE.md（固定） CLAUDE.md 個人設定 CLAUDE.local.md（固定） CLAUDE.local.md ホーム設定 ~/.claude/CLAUDE.md（固定） ~/.claude/CLAUDE.md 分割規約 .claude/rules/<名前>.md laravel-conventions.md コマンド .claude/commands/<名前>.md verify.md（→ /verify） エージェント .claude/agents/<名前>.md weather-agent.md スキル .claude/skills/<名前>/SKILL.md weather-fetcher/SKILL.md 出典：Anthropic公式／shanraisshan
13. 6. 強調キーワードとガードレール 重要なルールが無視されるのを防ぐため、強調キーワードや条件付きタグを活用する。 6.1 強調キーワード IMPORTANT No Do NOT 6.2 条件付きガードレール YOU MUST only Always not Never <important if="..."> ファイルが長くなるとドメイン固有ルールが無視されやすい。条件タグでラッ プし無視を防ぐ。 6.3 「Do NOT」セクション # Testing - IMPORTANT: Always run tests before committing - YOU MUST run the typechecker after any series of code changes 禁止事項は「〜しないこと」の明示的な箇条書きリストにまとめる形式が、多 くのテンプレートで採用されている。 出典：MuhammadUsmanGM／shanraisshan／chealthガイド
14. 7. 設定時の注意点 1 1ファイルを 200行超にしない ～やってはいけないこと～ 5 超えるなら .claude/rules/ に分割 2 全タスクに無関係な内容を書かない 「動けばいい」ではなく検証可能な形にする 6 タスク固有内容は commands/ や rules/ へ 3 コードから読み取れることを書かない 規則の矛盾を放置しない 「個別実行」と「毎回全実行」など矛盾を避ける 決定論的に設定できるものを書かない 権限・モデルはsettings.jsonへ 7 情報重複でメンテナンス負荷が上がる 4 曖昧な指示を書かない 中途半端なマイグレーションを放置しない 移行は完遂する 8 個人設定を gitにコミットしない CLAUDE.local.mdは.gitignoreへ 出典：Anthropic公式／shanraisshan／chealthガイド／ dev.to
15. 8. 運用とコンテキスト管理 Explore → Plan → Code → Commit 1 2 Explore(調べる) 関連ファイル・既存パターンを確 認 3 Plan(計画する ) → → 複雑なタスクは計画を立てる 4 Code(起こす) 既存の規約に従い、パターン混用 を避ける Commit(反映) → 個別のタスクステップごとにコミット コンテキスト管理の目安 複雑なタスクは plan mode で計画を固めてから実装する コンテキスト使用量が 50%程度 に達したら手動で /compact を実行 より厳しい目安として「 60kトークン または 30%到達時」にクリアする運用も サブタスクは 50%未満のコンテキストで完了できる粒度に分割する 出典： chealthガイド／ shanraisshan／rosmur
16. デバッグ・コミット・記憶の階層 デバッグ 記憶の階層構造 場所 役割 CLAUDE.md リポジトリ全体の共有規約 .claude/rules/*.md 分割された規約（遅延読み込み） コンソールログ確認にはブラウザ自動操作 MCP （Chrome, Playwright, DevTools） ~/.claude/rules/ 個人の全プロジェクト共通規約 視覚的な問題はスクリーンショットで報告 ~/.claude/projects/<project>/memory/ プロジェクトごとの記憶 /doctor で診断情報を確認 長時間実行コマンドはバックグラウンドタスク化してログを見やすく コミット粒度 ファイルごとに個別のコミットを作成 （複数ファイルを1コミットにまとめない） Conventional Commits形式 （feat:, fix:, chore:, docs: 等）+ スコープ コマンド生成と編集 /init を実行するとClaudeがCLAUDE.mdを自動生成。 コーディング中に # キーで指示を与えると、該当 CLAUDE.mdへ自 動で取り込まれる。 出典： shanraisshan／Anthropic公式／ chealthガイド