humanlayerのブログから学ぶ、良いCLAUDE.mdの書き方

Transcript

1. humanlayer のブログから学ぶ 良い CLAUDE.md の書き方
2. 自己紹介 • NCDC株式会社 所属 • モバイルアプリ エンジニア（自称） • Flutter, ReactNative, Swift, Kotlin 案件の経験の末、 Flutter が一番好き（一番使い慣れてるだけ）
3. はじめに • 本スライド内容は「humanlayer / Writing a good CLAUDE.md」の記載をベー スに作成しています • Claude Code 以外のAgent Tool でも汎用的に通ずる内容です • 本日のゴール：良いCLAUDE.mdを書けるようになろう • ≒ 最大限Claude Codeを活かせるようになろう
4. はじめに 本日のポイント • ①WHY・WHAT・HOW を定義する • ②記載は簡潔に少ないほど良い • ③詳細情報は直接書かずに参照先を示す • ④エージェントツールは linter や formatter ではない • ⑤ /init による自動生成はやめよう
5. 前提・原則 • 基本原理として、LLM は Stateless である • セッションが終われば全て忘れる、情報は保持しない • セッションをまたいでメモリの役割をしてくれるのが CLAUDE.md • 命令に関連しないCLAUDE.mdの内容は、Claude側の判断次第で無視される • 処理中のタスクに適用できない情報が多いほど、Claude が CLAUDE.md の指示を無視する 可能性が高くなる
6. ① WHY・WHAT・HOW を定義する エージェントツールは、セッション開始時にコード情報を一切持っていない そのため、コード情報を読み込ませるために “WHY・WHAT・HOW” の定義が必要 • WHY：プロジェクトや機能の目的 • PJ 概要、PJ コード概要、etc. • WHAT：どういった技術構成か • ディレクト構成、技術スタック、主要機能・パッケージ、 etc. • HOW: どのように動かすか • 基本的なコマンド指示など（node, npm、yarn、pnpm どれを使うかとか）
7. ② 記載は簡潔に少ないほど良い CLAUDE.md に細かく情報（命令）を詰め込みたくなるが、 どんなプロンプトに対しても、普遍的に適用できる情報のみを含めるのが理想 理由: • モデル毎に “命令対応量” は限られている • 命令数の増加によって ”命令追従能力” が著しく低下する • Claude Code のシステムプロンプトには約 50 個の命令がデフォルトで 含まれており、Agent が実質実行できる 1/3 ぐらいの命令に相当 • 300行 未満の記載が最適 とのこと
8. ② 記載は簡潔に少ないほど良い 【適当な軽めの Skills 発火後】 【セッション開始時】
9. ③ 詳細情報は直接書かずに参照先を示す 「じゃあ細かい情報はどこで Claude に渡せばいいの？」 → Claude Code が「必要な時に、必要な部分だけ」を参照できるようにすること 【CLAUDE.md 記述 sample】
10. ④ エージェントツール は linter や formatter ではない • linter や formatter を実行させるのはもったいない • 本来の命令に対して無関係なコンテキストが大量に増える • パフォーマンスや追従性の低下要因に • 基本的には LLM が既存コードの文脈を読み取って、既存規則やルールに従う傾向 • 不安な場合は hook 機能を使うことも推奨 • hook の STOP 時に linterなどのスクリプトを実行させ、修正が必要なら別途依頼する流れ
11. ④ エージェントツール は linter や formatter ではない 【.claude/settings.json】 【セッション終了時】 stop hook例
12. ⑤ /init による自動生成はやめよう 自動生成だと不要な記載が多い傾向 ↓ 全ての命令に対して最初に読まれるが CLAUDE.md ↓ 最良の結果を得るには、/init による自動生成はやめよう
13. まとめ CLAUDE.md の書き方ポイント • ①WHY・WHAT・HOW を定義する • ②記載は簡潔に少ないほど良い • ③詳細情報は直接書かず、参照先を示す • ④エージェントツールは linter や formatter ではない • ⑤ /init による自動生成はやめよう
14. humanlayer のブログから学ぶ 良い CLAUDE.md の書き方 ご清聴ありがとうございました。