CLAUDE.md：置き場所、書く内容、AGENTS.md との併用

CLAUDE.md とは

Claude Code は、セッションを始めるたびに前回の記憶を持っていません。CLAUDE.md は、新しいチームメンバーに必要な背景を渡す手段です。起動時に読み込まれ、システムプロンプトの後にメッセージとして Claude に送られます。つまり強制される設定ではなく、あくまでコンテキストです。Claude は通常それに従いますが、必ず実行する、または絶対に起こさないことは hooks や権限ルールに置いてください。

• ふつうの markdown で、必須項目はありません。見出しと短い箇条書きが最も効果的です。
• ファイルは上書きではなく結合されます。該当する CLAUDE.md はすべて読み込まれるため、矛盾する行があると Claude がどちらかを選びます。
• 読み込まれた内容は /context all の Memory files で確認できます。

CLAUDE.md の置き場所と読み込み順

Claude Code は、最も広い範囲から最も具体的な範囲の順に読み込むため、起動した場所に最も近いファイルが最後に読まれます。また、作業ディレクトリから上に向かってたどり、すべての親ディレクトリの CLAUDE.md を読み込みます。

効果のある CLAUDE.md の書き方

1. /init から始める

   プロジェクトで /init を実行します。Claude Code がコードベースを読んで、最初の CLAUDE.md を書きます。すでにある場合は、上書きせずに改善案を提案します。.cursorrules や Copilot の指示も取り込みます。

2. Claude が自分では見つけられないことだけに絞る

   正確なビルド・テスト・lint のコマンド（1つのテストだけを実行する方法を含む）、コードが紛らわしい箇所、どこにも書かれていない決定、2回修正したことがあるものを残します。ファイルツリーや、リポジトリから読み取れるアーキテクチャは削ります。Anthropic は200行以内を勧めています。

   # Commands
   - Install: pnpm install
   - One test file: pnpm vitest run path/to/file.test.ts
   - Typecheck: pnpm tsc --noEmit
   
   # Conventions
   - エラーは src/lib/errors.ts のヘルパーで投げる。生の文字列は投げない。
   - src/legacy/ は今も稼働中だが、そのパターンは真似しない。
   
   # Gotchas
   - 統合テストには DATABASE_URL が必要（.env.example を参照）。

3. 具体的に、ただし大声は出さない

   「コードを適切に整形する」ではなく「インデントは2スペース」と書きます。最新のドキュメントでは、IMPORTANT や全部大文字は古いアドバイスだとされています。Claude がルールを過剰に適用してしまうためです。ある行が守られ続けない場合は、ファイルを短くするか、そのルールを hook にしましょう。

4. インポートとルールで分割する

   @path/to/file は別のファイルをインポートします（インポート元のファイルからの相対パスで、最大4階層）。バッククォート内の @ はそのまま文字として扱われます。コードベースの一部だけに当てはまるルールは、paths の glob を付けて .claude/rules/ に置くと、Claude が一致するファイルに触れたときだけ読み込まれます。

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - すべてのハンドラは src/api/schemas/ のスキーマで入力を検証する。

5. 手順はスキルに移す

   リリースの切り方のような複数ステップのワークフローは、スキル（.claude/skills/<name>/SKILL.md）に置きます。スキルは関係があるときだけ読み込まれます。CLAUDE.md はあらゆるタスクで読まれるので、1行ごとに注意力を消費します。

6. 最新に保つ

   Claude が同じミスを繰り返したときやレビューで指摘があったときに1行足します。編集は /memory を使うか、Claude に更新を頼みます。ファイルが長くなりすぎたら、/doctor が削減案を出します。

出典：Claude Code ドキュメント、How Claude remembers your project

CLAUDE.md と AGENTS.md の違い

AGENTS.md は、コーディングエージェント向けの指示のオープンな形式で、Codex、Cursor、Gemini CLI、GitHub Copilot のコーディングエージェント、opencode などが使っています。Claude Code も読み込めるようになりましたが、既定ではプロジェクトに CLAUDE.md がないときだけです。

Claude Code と Codex で1つのファイルを使う

チームが両方のエージェントを使うなら、共通の指示は AGENTS.md に置き、CLAUDE.md からそれをインポートして、その下に Claude 専用のメモを書きます。二重に読み込まれることはありません。シンボリックリンク（ln -s AGENTS.md CLAUDE.md）でも動きますが、Windows のチームメンバーには使えません。また、「AGENTS.md を読むこと」と文章で書いただけの CLAUDE.md は確実ではありません。

• このサイト自身のリポジトリがまさにそうしています。CLAUDE.md は @AGENTS.md の1行だけです。
• Codex は、リポジトリのルートから作業ディレクトリまでの AGENTS.md ファイルを読み、合計サイズの上限は既定で32 KiBです。

制限と注意点

• 起動時に読み込まれる CLAUDE.md は最大4 MiBまで全体が読まれ、それより大きいファイルはスキップされます。
• サブディレクトリの CLAUDE.md やパス単位のルールのように必要に応じて読み込まれるファイルは、ファイルごとの上限を超えると切り捨てられます（200Kのコンテキストウィンドウでは40,000文字）。
• インポートはファイルを整理するだけで、コンテキストの節約にはなりません。インポートされたテキストも読み込まれます。
• プロジェクト外のインポートは一度承認を求められます。HTML コメント <!-- --> は取り除かれ、コストはかかりません。
• プロジェクトルートの CLAUDE.md は /compact のあとに再度読み込まれます。
• 「これを覚えて」は CLAUDE.md ではなく、自動メモリ（~/.claude/projects/<project>/memory/）に入ります。

CLAUDE.md は仕事の進め方を伝え、Crewmark は何をいつやるかを決めます。

良い CLAUDE.md があれば、Claude Code のセッションはどれも十分な情報を持って始まりますが、セッションはあなたの次のメッセージを待ち続けます。Crewmark は、Claude Code、Codex、DeepSeek Harness、OpenCode のセッションを、職種・目標・勤務時間を持つ AI 社員に変え、ハートビートで起こしてボードから次の issue を取らせます。

1. セッションを社員にする

   ソフトウェアエンジニアや SEO スペシャリストなどの職種を選び、目標を数値で書き、CLAUDE.md がすでにあるプロジェクトでセットアップコマンドを実行します。

2. ハートビートで仕事を始めさせる

   勤務時間中、社員は15分、30分、60分ごとに同じ会話の中で起きます。詳しくはClaude Code を能動的にする方法をご覧ください。1つのリポジトリを複数の社員で共有することもできます。複数の Claude Code エージェントを参照してください。

3. issue を割り当て、メッセージに返信する

   ボードに仕事を置くと、社員がそれを拾い、進めながらコメントし、判断が必要なときはメッセージを送ってきます。AI 社員とはもご覧ください。

CLAUDE.md のよくある質問