多くの人がAgentツール（たとえばClaude Code）を使うときのやり方は、会話を開き、要件を伝え、結果を受け取るというものです。しかし実際のプロジェクトでは、Agentが頻繁に「記憶喪失」を起こすことに気づくはずです——ファイルが散乱し、命名はいい加減で、毎回好みを説明し直す羽目になります。

このチュートリアルでは、上から下へ貫くルール体系を構築し、Agentが目覚めるたびに何をすべきか分かるようにする方法を解説します。

CLAUDE.mdとは

CLAUDE.mdは、Claude Codeが作業ディレクトリに入ったあとに最初に読み込んで従うファイルです。Agentの行動規範と考えてください。2つの階層に分かれます：

• グローバルCLAUDE.md：ユーザーのホームディレクトリに置き、全プロジェクト共通
• プロジェクト単位のCLAUDE.md：プロジェクトのルートに置き、そのプロジェクトにのみ有効

ルールは上から下へ貫通し、グローバルの制約が土台となり、プロジェクトの制約が細部を詰めます。

始める前の準備

• Claude Code（または類似のAgentツール）がインストール済み
• 長期的にメンテナンスするプロジェクトのディレクトリがある
• 所要時間の目安：30-60分

具体的な手順

ステップ1：グローバルCLAUDE.mdを作成

ユーザーのホームディレクトリに~/.claude/CLAUDE.mdを作成し、汎用の仕事の原則を書き込みます。以下は実戦で検証済みのテンプレートです。自分の状況に合わせて修正してください：

## 私について
[あなたの肩書きと役割。例：フルスタック開発者 / プロダクトマネージャー / インディー開発者]

## 第一原理
すべての判断は問題の本質から出発し、「慣例だから」という理由で鵜呑みにしない。
お世辞は不要。私のアイデアを褒めないこと。正直な判断を——案に問題があれば直接指摘する。

## 制約ファースト
開発プロジェクトでもナレッジ管理プロジェクトでも、最初のステップは常にルール作り：
- 新規プロジェクトではまずCLAUDE.mdを書く
- 新規ディレクトリでは先に構造の約束を決める（何をどこに置くか、命名規則、いつ片付けるか）
- 規約のないワークスペースでは手を付けない
- 規約の調整が必要なときは、まずドキュメントを直し、それから運用を直す。逆にしない

## 仕事の進め方
- デフォルトは中国語、コードは英語
- 結論を先に、理由を後に
- 曖昧な要件に遭遇したら、まず最も妥当な案を出し、調整の要否を尋ねる

## 開発習慣
- 修正したら自ら検証を実行する（test / lint / build）。直して確認しない、はしない
- コードを動かすためだけにエラーをコメントアウトせず、根本原因を探す
- シークレット、token、パスワードをコードに入れない

## Gitとデプロイ
- commit messageは英語で、変更の意図を簡潔に記述
- git pushは私が指示したときだけ実行

ヒント: グローバルCLAUDE.mdにはプロジェクト関連のルールをあまり書かず、「あなたは誰か」と「ものごとの進め方の原則」だけを置きます。プロジェクトの詳細は次の階層へ。

ステップ2：プロジェクト単位のCLAUDE.mdを作成

各プロジェクトのルートにCLAUDE.mdを作成し、このプロジェクト専用のルールを定義します：

# プロジェクト名

## プロジェクト概要
[このプロジェクトが何をするかを一文で説明]

## ディレクトリ構成

src/ components/ # UIコンポーネント hooks/ # カスタムHooks utils/ # ユーティリティ関数 pages/ # ページコンポーネント tests/ docs/ _sandbox/ # 実験的なコンテンツ。30日超で自動クリーンアップ

## 命名規則
- コンポーネントファイル：PascalCase（例：UserProfile.tsx）
- ユーティリティ関数：camelCase（例：formatDate.ts）
- 定数：UPPER_SNAKE_CASE
- テストファイル：[元ファイル名].test.ts

## 技術スタック
- フレームワーク：Next.js 14
- 状態管理：Zustand
- スタイリング：Tailwind CSS
- パッケージ管理：pnpm

## 開発規約
- 新規コンポーネントには必ずテストも同時に書く
- APIルートはsrc/app/api/の下に統一配置
- 環境変数は.env.localで一元管理

ステップ3：ルールが効いているか検証する

CLAUDE.mdを保存したら、プロジェクトディレクトリでClaude Codeを起動し、簡単なタスクを実行させて、次の点を観察します：

1. CLAUDE.md内の規約を読み込んだか
2. 定義したディレクトリ構成に従ってファイルを配置したか
3. 命名規則に従ったか

直接こう尋ねても構いません：「このプロジェクトのCLAUDE.mdを読んで、どんな規約があるか教えて」。

なぜ「制約ファースト」がPromptテクニックより重要なのか

Agentの短期記憶は会話を閉じると失われます。次に開いたとき、Agentが見られるのはあなたが残したドキュメントとメモリファイルだけです。ドキュメントに何が書かれているかが、Agentが目覚めるたびに冴えているか混乱しているかを直接左右します。

カギとなる原則：

• ルールはドキュメントに書く。頭の中だけに置かない。頭の中で知っていることは、ドキュメントに書かれていなければ、Agentにとっては存在しないも同然です
• ルールは上から下へ貫通する。グローバルの規約は都市の幹線道路、プロジェクトの規約は地区の生活道路です
• まずドキュメントを直し、それから運用を直す。ルールは固定ではありませんが、ルールを変えるときもルールに沿って行います

よくある質問

• CLAUDE.mdはどのくらいの長さが適切？: グローバルは30-50行以内に抑え、プロジェクト単位は複雑さに応じて調整します。長すぎるとAgentが無視し、短すぎると制約が足りません
• ルールとAgentの実際の挙動が一致しない場合は？: まずドキュメントを直し、それからAgentに再実行させます。会話内で口頭で訂正して放置する、は避けましょう
• プロジェクト間でルールを再利用するには？: 汎用部分はグローバルCLAUDE.mdに、プロジェクト固有のものはプロジェクト単位のファイルに置きます。2階層が重なって機能します