【警告】CLAUDE.mdに全部書くのは今すぐやめて。Claude Code公式ベストプラクティスと最強のディレクトリ構成

Claude Codeを導入した現場で、いま最も起きている「事故」を知っていますか？
それは、「プロジェクトのルールをすべて CLAUDE.md に書き込んでしまうこと」です。

• 「Pythonの型ヒントを必ず書いて」

• 「AWSのデプロイ手順はこうで…」

• 「Kaggleの特徴量エンジニアリングのコツは…」

• 「PRレビューのチェックリストはこれ」

これらをすべて CLAUDE.md に詰め込むとどうなるか。AIは混乱し、最も重要な指示を見落とし始めます。

海外のClaude Code開発者界隈（awesome-claude-code や shanraisshan などの著名リポジトリ）と公式ドキュメントを読み解くと、現在のベストプラクティスには明確な「正解」があります。

今日は、AIエージェントの能力を100%引き出すための「4層アーキテクチャ」の解説と、Pythonソフトウェア開発でそのままコピペして使える「最小構成テンプレート」を公開します。

「CLAUDE.md」は憲法。法律や条例を混ぜるな

公式ドキュメントは明確にこう述べています。
「CLAUDE.md は短く保て。長すぎる指示は逆効果だ」

Claude Codeの拡張要素は、用途に合わせて以下の「4つ」に分解して配置するのが現在のグローバルスタンダードです。

1. CLAUDE.md (憲法): 毎回のチャットで常に効かせる基本原則。

2. commands/ (手順書): 人間がスラッシュ（/）で呼び出す作業の入口。

3. skills/ (専門書): 必要な時だけAIが本棚から取り出して読む専門知識。

4. hooks/ (強制ゲート): お願いベースではなく「システム的に絶対やらせる」処理。

すべての知識をCLAUDE.mdに置くのではなく、「コマンドで作業を始めさせ、必要に応じてSkillを読ませ、Hookで品質を強制する」。これが正しいハーネス（制御環境）の設計です。

【コピペ用】ソフトウェア開発のための最小構成テンプレ

理屈はここまでにして、実際にPython開発で使える最小構成を作りました。
以下のディレクトリ構造を作成し、コードをコピペするだけで、あなたのリポジトリのClaude Codeは「凄腕のシニアエンジニア」に化けます。

📂 ディレクトリ構成

project-root/
├─ CLAUDE.md
└─ .claude/
   ├─ settings.json
   ├─ commands/
   │  └─ fix-bug.md
   ├─ skills/
   │  └─ python-debugging/
   │     └─ SKILL.md
   └─ hooks/
      ├─ post-edit-lint.sh
      └─ protect-sensitive-files.sh

1. CLAUDE.md（基本方針：短く保つ）

プロジェクトのルートに配置します。ここには「毎回必ず守らせること」だけを書きます。

# このプロジェクトの基本方針

## 開発原則
- 既存コードの責務分離を尊重し、不要な全面改修は避ける。最小変更で価値を出す。
- 関数やクラスの責務が曖昧になる変更は避ける。

## Python コーディング方針
- 型ヒントを優先する。
- コード内のコメントは日本語で書く。
- 例外は握りつぶさず、原因が追跡できるようにする。

## 修正時の説明方針（重要）
- いきなりコードを書き換えず、先に以下を整理すること。
  1. エラー内容または症状 / 2. 原因 / 3. 修正方針 / 4. 修正前後の差分
- その後に修正コードを提示する。

## よく使うコマンド
- lint: `ruff check .`
- format: `ruff format .`
- test: `pytest -q`

2. commands（作業の入口を定型化）

人間が /fix-bug と打った時に読み込まれるテンプレートです。
配置先: .claude/commands/fix-bug.md

---
description: バグ修正の標準フローで原因調査から最小修正まで進める
---

以下の流れで対応すること。

1. 症状またはエラー内容を整理する
2. 原因候補を列挙し、もっとも有力な原因を示す
3. 影響範囲を確認する
4. 最小修正案を提示する
5. 修正前と修正後の違いを要約する
6. 最後に修正コード全体を提示する

出力ルール:
- 修正理由が曖昧な変更は避ける
- 既存構造を尊重し、不要な全面改修はしない

3. skills（AIの専門知識）

バグ調査時にAIが「自発的に」読み込む専門知識です。ファイル名ではなく、メタデータ（nameとdescription）が発火のトリガーになります。
配置先: .claude/skills/python-debugging/SKILL.md

---
name: python-debugging
description: Pythonの例外、pytest失敗、型エラー、非同期処理の不具合を調査し、原因・影響範囲・最小修正案を整理する。バグ調査を依頼された際に使用する。
---

# この Skill の目的
Pythonコードの不具合調査を、場当たり的ではなく再現性のある手順で進める。

# 確認観点（典型原因）
- None参照 / 型不一致 / import循環
- 非同期の `await` 漏れ
- 依存注入漏れ / 例外の握りつぶし
- 想定外の空配列や空DataFrame

# 修正方針
- 原因が特定できるまでは大きく書き換えない。
- その場しのぎの `if` 文追加で逃げない。
- 入力値の検証、境界条件、初期化順を確認する。

# 注意
- 修正が関数単位で済むなら関数単位で提示する。

4. hooks（ゼロ例外の品質強制）

「保存後にLintを回して」と口で言うのではなく、システム的に強制します。
配置先: .claude/hooks/post-edit-lint.sh （※ chmod +x で実行権限を付与してください）

#!/usr/bin/env bash
set -e
target_file="$1"

if [[ -z "$target_file" ]]; then
  exit 0
fi

if [[ "$target_file" == *.py ]]; then
  # 編集されたファイルに対してruffを強制実行
  ruff check "$target_file"
fi

配置先: .claude/settings.json （Hookの登録）

{
  "hooks": {
    "PostToolUse":[
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks":[
          {
            "type": "command",
            "command": ".claude/hooks/post-edit-lint.sh"
          }
        ]
      }
    ]
  }
}

実務での運用イメージ

この構成をセットアップしたリポジトリで、あなたがやることはこれだけです。

これだけで、

1. Claude Codeが commands/fix-bug.md の手順を読み込む。

2. 「バグ調査だ」と判断し、自動的に python-debugging Skillをロードして深掘りする。

3. CLAUDE.md の指示に従い、日本語で原因と修正方針を解説してからコードを直す。

4. ファイル編集直後に post-edit-lint.sh が裏で走り、構文エラーがないか自動チェックする。

これこそが、AIに「お願い」するのではなく、「エージェントの業務フローをオーケストレーション（指揮）する」ということです。

全部CLAUDE.mdに書く、素人のような運用は今日で終わりにしましょう。
この4層アーキテクチャを組むだけで、あなたの開発体験は劇的に変わります。

【必読】本記事の参考リポジトリ

本記事のアーキテクチャ設計は、以下の公式ドキュメントおよびグローバルトップクラスの参照実装（Reference Implementation）をベースに再構築しています。
コピペで動かした後は、必ず自身の目で一次情報を確認し、自社のドメイン知識に合わせてSkillを拡張してください。

• Anthropic公式: Claude Code Documentation (Best Practices)

  • 読むべき理由: すべての前提となる「憲法」。公式が「CLAUDE.mdは短く保て」「フック（Hooks）を使え」と明言していることが確認できます。まずはここから読んでください。

• GitHub: shanraisshan/claude-code-best-practice

  • 読むべき理由: 本記事の「4層アーキテクチャ」の元ネタとも言える、最も美しい参照実装リポジトリです。「コマンド・エージェント・スキル」の責務分離（オーケストレーション）をコードレベルで学びたいテックリードは必読です。

• GitHub: awesome-claude-code ※URLは代表的なCurated Listを想定

  • 読むべき理由: 思想ではなく「カタログ」です。UIレビュー用、重厚なPMワークフロー用、ステータスライン拡張など、「自社に足りないSkillのパーツ」を探す際の辞書としてブックマーク推奨です。

• GitHub: awattar/claude-code-best-practices

  • 読むべき理由: Gitワークフローや安全な自動化（Safe Automation）など、より実務・運用レイヤーに寄った軽量なガイド。テストやデバッグのプロンプトデザインの参考になります。

参考にした本

Claude Code や AI コーディングを実務で使いこなすには、ツールの使い方だけでなく、
設計・リファクタリング・アーキテクチャの土台 も大事だと感じています。

今回の内容に近い本としては、まず
『実践Claude Code入門』。Claude Code の基本から、実務での活用やスペック駆動開発まで扱っている本です。

設計の土台としては、
『ちょうぜつソフトウェア設計入門』。オブジェクト指向、SOLID、テスト駆動開発、デザインパターンなどを通して、設計の考え方を整理しやすい一冊です。

さらに全体の視点を広げるなら、
『ソフトウェアアーキテクチャの基礎 第2版』。アーキテクチャ設計を体系的に学べる本で、Claude Code のような AI コーディングツールを「どう開発プロセスに組み込むか」を考える上でも参考になります。

個人的には、
Claude Code の使い方 と ソフトウェア設計の基礎 をセットで学ぶと、かなり実務に効くと思っています。

#AI #生成AI #AIエージェント #ClaudeCode #プロンプトエンジニアリング #Python #開発環境 #エンジニアの生存戦略 #DX #業務効率化