CLAUDE.mdとは何か｜AIへの指示をファイルで管理する

CLAUDE.mdとは何か｜AIへの指示をファイルで管理する 自動化のはじめ方
2026.08.12

AIに作業を頼むとき、毎回同じ前提を説明していませんか。

「このフォルダは経理用で」「データはスプレッドシートから取ってきていて」「このファイルは自動生成だから直接編集しないで」——私は最初、チャットのたびにこれを打ち込んでいました。

CLAUDE.md は、その説明を1回書いてファイルに置いておく仕組みです。AIが作業を始める前に自動で読むので、毎回説明する必要がなくなります。

この記事では、実際に運用しているファイルをそのまま公開しながら、何を書くと効くのかを解説します。

何が問題だったか

AIに作業を頼むとき、失敗のパターンは決まっていました。

失敗 原因
自動生成されるファイルを直接書き換えられた それが自動生成だと知らない
データの命名規則を無視した処理を書かれた 規則を伝えていない
例外的な仕様を無視された 例外の存在を知らない
毎回、口調や出力形式が変わる 指定していない

どれも「知らなかったから」起きています。 AIが悪いのではなく、伝えていない自分の問題でした。

そして厄介なのは、一度説明しても、次の会話では忘れられていることです。会話が変われば前提はリセットされます。

CLAUDE.md の実例

実際に使っているファイルです。拠点名だけ伏せて、そのまま載せます。

# CLAUDE.md

このフォルダは経理・管理業務を行うためのワークスペースです。

## 概要
- 5拠点（拠点A・拠点B・拠点C・拠点D・拠点E）の売上／利益を管理する。
- 元データは Google スプレッドシートで管理し、xlsx として取得して集計・予測する。
- 回答は日本語・簡潔に。

## ディレクトリ構成
- `経理/` — 経理関連の本体
  - `predict.py` — 利益表から「月末着地予想」を日割り（ランレート）で算出
  - `sync.sh` — Google スプレッドシートの最新版を xlsx でダウンロードして上書き
  - `run_prediction.sh` — `sync.sh` → `predict.py` を実行し、結果保存＋通知（毎月15日 launchd 起動）
  - `利益表.xlsx` / `売上帳.xlsx` — スプレッドシートから同期したデータ（自動生成・直接編集しない）
  - `着地予想_YYYY-MM.txt` — 予測レポート出力
  - `実行ログ.txt` — 実行履歴

## よく使うコマンド
```bash
cd 経理
./sync.sh                 # 最新データを取得
python3 predict.py        # 当月の着地予想
python3 predict.py 6      # 月を指定（例: 6月）
./run_prediction.sh       # 同期→予測→保存→通知 を一括実行
```

## 注意点
- `利益表.xlsx` / `売上帳.xlsx` は同期で上書きされるため、手作業で編集しない。
  修正は Google スプレッドシート側で行う。
- シート名は「`<月>月<拠点>`」形式（例: `6月拠点A`）。
  表記ゆれ（スペース）は `predict.py` 側で吸収している。
- 拠点Eのみ売上ラベルが「売上」、他拠点は「清掃売上」。
- 集計ロジックや拠点を変更する際は `predict.py` の `LOCS` と各ラベル定義を確認する。

たったこれだけです。30行程度。

4つのセクションの役割

① 概要 — 「ここは何の場所か」

最初の3行で、このフォルダが何のためのものかを伝えます。

回答は日本語・簡潔に のような出力の好みもここに書けます。毎回「簡潔に」と打つ必要がなくなります。

② ディレクトリ構成 — 「どのファイルが何か」

各ファイルの役割を1行で書きます。

ここで重要なのは、（自動生成・直接編集しない） のような但し書きです。ファイル名だけでは、それが手作りなのか自動生成なのか判別できません。

③ よく使うコマンド — 「どう動かすか」

コピペで動く形で書いておきます。

副次効果として、自分が久しぶりに触るときの備忘録になります。3ヶ月後の自分は、コマンドを覚えていません。

④ 注意点 — ここが最も効く

後述しますが、このセクションだけで価値の半分以上があります。

「注意点」が効く理由

注意点セクションは、AIがやりがちなミスを先回りして防ぐ場所です。

実例を3つ挙げます。

例1：自動生成ファイルの保護

利益表.xlsx は同期で上書きされるため、手作業で編集しない。修正はスプレッドシート側で行う。

これを書かないと、AIは親切心で xlsx を直接修正します。そして次回の同期でその修正は消えます。

例2：命名規則の共有

シート名は「<月>月<拠点>」形式。表記ゆれ（スペース）は predict.py 側で吸収している。

規則を書いておくと、新しい処理を書くときも同じ規則に従ってくれます。さらに「表記ゆれは吸収済み」と書いておけば、同じ対策を二重に実装されずに済みます。

例3：例外の明示

拠点Eのみ売上ラベルが「売上」、他拠点は「清掃売上」。

実務のデータには必ず例外があります。 統一すべきなのは分かっていても、過去分まで直すのは現実的ではありません。

こういう「きれいでない事実」こそ書く価値があります。書かなければ、AIは全拠点が同じ形式だと仮定して処理を書き、そして失敗します。

💡 注意点セクションに書くべきは「一度失敗したこと」です。
最初から完璧に書こうとせず、AIが間違えるたびに1行ずつ足していくのが実際の運用です。

CLAUDE.md と AGENTS.md を両方置く

私は同じ内容のファイルを2つ置いています。

ファイル 読むツール
CLAUDE.md Claude Code
AGENTS.md 他のAIコーディングツール

AIツールによって、読みに行くファイル名が違います。 片方しか置いていないと、別のツールを使ったときに何も参照されません。

内容はほぼ同一で構いません。中身を書くコストはすでに払っているので、コピーして名前を変えるだけです。ツールを乗り換えたり併用したりする可能性があるなら、両方置いておくのが安全です。

書くべきこと・書かなくていいこと

書く 書かない
自動生成ファイルの識別 コードを読めば分かること
データの命名規則 一般的なプログラミング知識
例外的な仕様 一度きりの作業指示
よく使うコマンド 長大な仕様書
出力の好み（言語・簡潔さ） 機密情報・認証情報

「コードを読めば分かること」は書かなくて構いません。 AIはコードを読めます。

書くべきは、コードを読んでも分からないことです。「なぜそうなっているか」「触ってはいけないもの」「例外」——このあたりが該当します。

⚠️ APIキー・パスワード・Webhook URLは絶対に書かないでください。 これらは別ファイルに分離し、.gitignore などで管理します。

運用の実際

最初から完成させる必要はありません。私の場合はこうなりました。

  1. 最初は概要3行だけ書いた
  2. AIが xlsx を直接編集した → 注意点に1行追加
  3. シート名の揺れで処理が止まった → 1行追加
  4. 拠点ごとのラベル差で失敗した → 1行追加

失敗するたびに1行増える、という育て方です。これで30行になりました。

そしてこの30行は、そのまま引き継ぎ資料になります。人が増えたときも、この1ファイルを読めば前提が伝わります。AIのために書いたものが、結果的に人にも効きました。

まとめ

  • CLAUDE.md はAIへの前提説明を1回で済ませるためのファイル
  • 構成は概要・ディレクトリ・コマンド・注意点の4つで足りる
  • 最も効くのは「注意点」。自動生成ファイル・命名規則・例外を書く
  • 書くべきはコードを読んでも分からないこと
  • CLAUDE.md と AGENTS.md を両方置くとツールを変えても効く
  • 最初から完璧を目指さず、失敗するたびに1行足す

30行のファイル1つで、毎回の説明がなくなります。AIを業務で使うなら、最初に作るべきファイルだと思っています。

あわせて読みたい

コメント

タイトルとURLをコピーしました