Claude Code Changed My Productivity — CLAUDE.md Design Is the Key

Claude Code is Anthropic's official CLI tool for interacting with Claude in the terminal — reading/writing files, Git commands, code execution, and generation, all without requiring any editor.

After six months of use, the author concludes: the quality of your CLAUDE.md file (project-level AI context configuration) directly determines the ceiling of Claude Code's effectiveness. Deep dive into designing high-quality CLAUDE.md so AI truly understands your project structure, style, and workflow.

Claude Codeを使い始めて生産性が変わった話 ― CLAUDE.mdの設計が鍵

Claude Codeを使い始めて生産性が変わった話 ― CLAUDE.mdの設計が鍵

Claude CodeはAnthropicが公式に提供しているCLIツールだ。ターミナル上でClaudeと対話しながら、ファイルの読み書き、Git操作、コマンド実行、コードの生成・修正まで全部やってくれる。

CopilotやCursorとの違いは、エディタに依存しないこと。ターミナルさえあれば動く。そしてプロジェクト全体のコンテキストを読み込んだうえで作業するので、ファイル単位ではなくリポジトリ単位で仕事ができる。

自分は約半年使っているが、最初の1週間で「これは開発スタイルが変わる」と確信した。ただし、ただインストールして使い始めるだけだと本来の力の半分も出ない。鍵になるのはCLAUDE.mdを含む設定ファイル群の設計だ。

この記事では実際に使っている設定をベースに、機密情報（社名・API鍵・個人情報など）を除去・匿名化した上で紹介しています。

npm install -g @anthropic-ai/claude-code

Node.js 18以上が必要。インストールしたら claude コマンドで起動できる。

プロジェクトのディレクトリで起動するのが基本だ。Claude Codeはカレントディレクトリのファイルを読み込んでコンテキストとして使う。

初回起動時にAnthropicアカウントとの認証が走る。ブラウザが開いてログインするだけ。APIキーを環境変数に設定する方法もある。

export ANTHROPIC_API_KEY=sk-ant-xxxxx

ここまでで動く状態にはなる。だが、ここからが本番だ。

settings.json：最初に設計すべき権限管理

多くの入門記事が触れていないが、インストール直後にやるべきことがある。~/.claude/settings.json の設定だ。これはClaude Codeに「何を許可し、何を禁止するか」を定義するファイルで、安全に使いながらも許可確認の手間を減らすバランスを設計する。

"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"

"Bash(git commit:*)",

"Bash(pip3 install:*)",

"Bash(gh run list:*)",

"Bash(gh workflow run:*)",

"WebFetch(domain:github.com)",

"WebFetch(domain:api.github.com)"

"defaultMode": "acceptEdits"

allow（許可リスト） は「毎回確認されると面倒なコマンド」を入れる。パターンマッチで Bash(git commit:*) のように書くと、git commit で始まるコマンドは全て自動許可される。自分が許可しているのは主に3カテゴリ:

Git系 — git commit, git pull など

スクリプト実行 — python, curl など。パイプラインやAPI確認で頻繁に使う

WebFetch — 特定ドメインへのアクセスだけ許可

deny（拒否リスト） は絶対に実行させたくないコマンドを入れる。rm を含むコマンドは全てブロックしている。Claude Codeが「不要なファイルを削除します」と言ってきても、denyに入っていれば実行されない。

defaultMode は acceptEdits にしている。ファイルの編集提案を毎回Yes/Noで確認する手間を省くためだ。ただし、初めて使う人は default（毎回確認）から始めて、慣れてきたら切り替えることを勧める。

Claude Codeにはプロジェクト固有のルールや知識を伝える仕組みがある。それがCLAUDE.mdだ。プロジェクトルートに置くと、Claude Codeが毎回の起動時に自動で読み込む。

Claude Codeは賢い。だが、プロジェクト固有の事情は知らない。

テストは pytest なのか go test なのか

使っているフレームワークのバージョンは何か

これらを毎回口頭で伝えるのは面倒だし、どこかで漏れる。CLAUDE.mdに書いておけば、Claude Codeが毎回自動でルールを守ってくれる。

CLAUDE.mdを整備する前と後で、Claude Codeへの指示回数が体感で半分以下になった。「あ、それじゃなくてこっちのフォーマットで」「テストはこのコマンドで」みたいな修正指示がほぼなくなる。最初の1時間をCLAUDE.mdに使うことで、その後の何十時間が楽になる。

CLAUDE.mdは3つのレベルで配置できる。

グローバルには「どのプロジェクトでも共通のルール」を書く。自分の場合、ここにサブエージェントのルーティングテーブルを書いている（後述）。プロジェクトルートには技術スタックや開発コマンドを書く。この使い分けが効く。

では実際にどう書くか。自分が使っているパターンを紹介する。

グローバルCLAUDE.md：サブエージェントのルーティング

~/.claude/CLAUDE.md にはこう書いている:

グローバル Claude Code 設定

Task ツールでチームを構成する際、~/.claude/agents/ のエージェントを適切に選択する。

|-----------|-----------------|

| Go開発 | golang-pro |

| TypeScript/JS | typescript-pro, javascript-pro |

| Next.js | nextjs-developer |

| React | react-specialist |

| Python | python-pro |

| DB設計・SQL | sql-pro, database-administrator |

| コードレビュー | code-reviewer |

| セキュリティ | security-auditor |

| DevOps | devops-engineer |

  • 単純なタスク → 直接実行（エージェント不要）
  • 専門的なタスク → 該当ドメインのエージェントを選択
  • 複合タスク → 複数エージェントを並列で活用

これが何をしているかというと、Claude Codeが「Goのコードレビューをして」と頼まれたとき、golang-pro と code-reviewer を組み合わせてサブエージェントを起動する判断材料になる。CLAUDE.mdは「指示書」であると同時に「ルーティングテーブル」としても機能する。

プロジェクトCLAUDE.md：技術スタックと「罠」を書く

プロジェクトルートのCLAUDE.mdには、そのプロジェクト固有の情報を書く:

業務管理システム — Next.js 14 + Go + PostgreSQL

  • Frontend: ローカル `npm run dev` (port 3000)
  • Backend: Docker内で起動 (port 8080)