創刊準備号 · 2026年秋English · RSS
AgentKoji

プロンプトより手順書を書く

Claude Codeは起動時に作業ディレクトリとその上のCLAUDE.mdを読みます。最初に何をどこへ書くかが分かります。

要点（TL;DR）

  • 毎回のプロンプトで同じ説明をしているなら、その説明は手順書（CLAUDE.md）に移します。CLAUDE.md はセッションの開始時に読まれます。
  • CLAUDE.md は守らせる設定ではなく、文脈として読まれます。確実に止めたい操作は hook で止めます。
  • /init で下書きを作り、「確かめられるくらい具体的に」書きます。公式は1ファイル200行未満を目安にしています。

毎回のプロンプトで同じ説明をしているなら、その説明は手順書にしてファイルに移します。Claude Code では、その手順書が CLAUDE.md です。この記事では、CLAUDE.md がいつ読まれるか、どこに置くか、/init での下書きの作り方、書く項目、プロンプトに残すものとの分け方、AGENTS.md との関係を順に説明します。すでに長くなった CLAUDE.md を短くする話はCLAUDE.mdは削るほど効くにあります。

CLAUDE.md は何か、いつ読まれるか

CLAUDE.md は、Claude に毎回伝えたい指示を書く Markdown ファイルです。Claude Code はセッションの開始時にこれを読みます。公式は、CLAUDE.md を「毎回説明し直していることを書いておく場所」と位置づけています。書き足すきっかけとして、次のような場面が挙がっています。

CLAUDE.md は守らせる設定ではなく、文脈として読まれます。 確実に止めたい操作は、あとで説明する hook で止めます。

出典：https://code.claude.com/docs/en/memory 、2026-10-18確認

置き場所と読み込み順

公式の置き場所は次の4つです。上から順に読まれ、あとに読んだものほど作業中のディレクトリに近い指示になります。

範囲場所用途
組織の管理ポリシーmacOS は /Library/Application Support/ClaudeCode/CLAUDE.md など組織全体の規約
ユーザー~/.claude/CLAUDE.mdすべてのプロジェクトに共通する自分の好み
プロジェクト./CLAUDE.md または ./.claude/CLAUDE.mdチームで共有する指示。Git に入れる
ローカル./CLAUDE.local.md自分だけのプロジェクト用の指示。.gitignore に入れる

作業ディレクトリとその上の階層にある CLAUDE.md は、起動時に読まれます。見つかったファイルは上書きされず、つなげて読まれます。サブディレクトリの CLAUDE.md は、Claude がそのディレクトリのファイルを読むか編集したときに読まれます。

一部のファイルにだけ関係する指示は、.claude/rules/ に分けられます。frontmatter の paths で対象のファイルを指定すると、そのファイルを扱うときだけ読まれます。

---
paths:
  - "src/api/**/*.ts"
---

API のハンドラーは必ず入力を検証してから処理する。

読み込まれたかどうかは、セッションの中で /context を実行し、Memory files の一覧で確かめます。

出典：https://code.claude.com/docs/en/memory 、2026-10-18確認

/init で下書きを作る

/init を実行すると、Claude がコードベースを調べて、CLAUDE.md の下書きを作ります。下書きには、見つけたビルドのコマンド、テストの手順、プロジェクトの規約が入ります。CLAUDE.md がすでにある場合は、上書きせずに改善案を出します。公式は、下書きを作ったあと、Claude が自分では見つけられない指示を書き足すよう勧めています。編集部の検証環境では /init を実行していません。

出典：https://code.claude.com/docs/en/memory 、2026-10-18確認

書く項目のテンプレート

一般的な Web アプリを想定した架空の例です。公式は「確かめられるくらい具体的に」書くよう勧めています。「テストする」ではなく「コミット前に npm test を実行する」のように書きます。

# my-app

## コマンド
- 依存のインストール: `npm install`
- 開発サーバー: `npm run dev`
- テスト: `npm test`
- lint: `npm run lint`

## ディレクトリ
- `src/api/` : API のハンドラー
- `src/components/` : 画面の部品
- `tests/` : テスト。ファイル名は `*.test.ts`

## 規約
- インデントは2スペース
- 新しい API には必ずテストを付ける
- 環境変数は `.env.example` に名前だけ書く

## 終わったら確かめること
- `npm run lint` と `npm test` が通る
- 変更したファイルの一覧を報告する

## 詳しい資料
- API の約束事: @docs/api-conventions.md

最後の行の @docs/api-conventions.md は import です。@パス と書くと、そのファイルも起動時に読み込まれます。相対パスは、import を書いたファイルからの位置で解決されます。import の中からさらに import でき、深さは最大4段です。バッククォートで囲んだパスは import されません。

出典：https://code.claude.com/docs/en/memory 、2026-10-18確認

公式は、1つの CLAUDE.md を200行未満に収めることを目安にしています。

プロンプトに残すものと手順書に移すもの

内容置き場所
ビルド・テスト・lint のコマンドCLAUDE.md
ディレクトリの役割、命名の規約CLAUDE.md
一部のディレクトリにだけ関係する規約.claude/rules/（paths 指定）
何段階もある作業の手順skill
今回の作業の目的と範囲プロンプト
今回だけの制約（触ってよいファイルなど）プロンプト
個人の環境の URL やテスト用のデータCLAUDE.local.md

基準は、毎回のセッションで必要かどうかです。公式は、何段階もある手順や一部のコードにだけ関係するものは、skill か .claude/rules/ に移すよう書いています。skill の書き方はClaude Codeのskillsの作り方にまとめています。

出典：https://code.claude.com/docs/en/memory 、2026-10-18確認

守らせたい規則は hook へ

CLAUDE.md の指示は文脈として読まれるだけで、必ず守られるとは限りません。公式も、Claude の判断に関係なく操作を止めたいなら PreToolUse hook を使うよう書いています。たとえば「本番用の設定ファイルを編集しない」は、CLAUDE.md に書くだけでなく hook で止めます。具体的な書き方はClaude Code hooks実践を読んでください。

出典：https://code.claude.com/docs/en/memory 、2026-10-18確認

AGENTS.md との関係

Codex などほかのツールも同じリポジトリで使う場合、指示を AGENTS.md にまとめる方法があります。Claude Code v2.1.277 以降は AGENTS.md を直接読めます。既定の動きは次のとおりです。

両方を置く場合は、CLAUDE.md の先頭に @AGENTS.md と書き、その下に Claude Code だけの指示を足します。

@AGENTS.md

## Claude Code
- `src/billing/` の変更は plan mode で進める

出典：https://code.claude.com/docs/en/memory 、2026-10-18確認

Codex 側の AGENTS.md の置き場所はCodex CLIの始め方で扱っています。

まとめ