CLAUDE.md を最初から書き込むのをやめた話と、そのためのスキル

Claude Code で開発を始めるとき、最初に CLAUDE.md を気合いを入れて書いていました。規約、ディレクトリ構成、禁止事項。1時間くらいかけて 150 行くらいのものを用意して、さあやるぞと。

で、1機能作り終えた頃に読み返すと、半分は守られていないし、残りの半分は書く必要のなかったものでした。守られていないルールは、そもそもエージェントがそこで間違えなかっただけかもしれないし、長すぎて埋もれただけかもしれない。どちらにせよ、事前に書いた分は回収できていない。

事前に書いた 10 行より、1周回した後の追記 1 行のほうが効きます。これがこのスキルの前提です。エージェントが何を間違えるかは、走らせるまで分からない。分からないことを想像で埋めても、精度の低いルールが増えるだけでした。

その運用を毎回手でやるのが面倒になったので、スキルにしました。dev-docs-scaffold という名前です。

何をするものか

Claude Code で開発するときのドキュメント一式を作ります。

• CLAUDE.md
• docs/architecture.md
• docs/plan.md
• docs/requirements/overview.md と機能ごとの詳細
• docs/adr/
• .claude/agents/developer.md、.claude/agents/reviewer.md

ただ、雛形を吐くだけなら zip を配れば済む話です。このスキルの中身は、どちらかというとその後どう育てるかのほうにあります。あとで書く「観察された誤り」の表がそれです。

インストール

.skill ファイルは中身が zip なので、展開して置くだけです。

unzip dev-docs-scaffold.skill -d ~/.claude/skills/

~/.claude/skills/ に置くと全プロジェクトで使えます。特定のプロジェクトだけで使いたい、あるいはチームで共有したいなら、リポジトリ側の .claude/skills/ に置いてコミットします。

.claude/ をコミットするかは好みが分かれるところですが、自分はしています。エージェント定義は個人の設定ではなくチームの資産なので、手元にだけ置いておく理由がない。

claude.ai でも使えますが、リポジトリが無いのでファイルを生成しても行き先がありません。構成の相談用と割り切っています。

呼び方

スキル名を打つ必要はありません。description にそれらしい言い回しを並べてあるので、自然文で拾われます。想定している入り口は3つです。

新規プロジェクトを始めるとき

新しく勤怠管理の Web アプリを作る。ドキュメントの構成から整えたい

まずこの3つを聞かれます。

• 技術スタック（言語・フレームワーク・DB）
• 最初に作る1機能は何か
• docs/plan.md の更新責任者は人か Claude か

答えると一式が生成されます。この時点で中身が薄いのは正しい状態です。要件も、overview.md に機能一覧とスコープ外を書いて、最初の1機能だけ詳細化する。残りは見出しだけ残します。先に全部書くと、最初の1機能で前提が崩れて書き直しになるからです。

一往復で終わらせたいなら、最初のメッセージにスタックと最初の1機能を書いておけば聞き返されません。

生成されたら、雛形に残っている <!-- 例 --> から <!-- /例 --> までを自分のプロジェクトの内容に書き換えます。ここは Next.js + Supabase を仮定した記入例なので、消し忘れると別スタックのプロジェクトに Supabase の話が残ります。実際これをやらかして、reviewer が「Supabase クライアントの生成場所を確認せよ」と言い続ける状態になったことがあります。

1機能を終えたとき

ここが本命です。

F-01 終わった。CLAUDE.md を更新したい

やることは2つ。ルール化と、削除です。

ルール化のほうは、docs/plan.md に置いてある「観察された誤り」の表を読みます。実装中にエージェントが間違えたら、その場で1行足しておく表です。判断はしません。数えるだけ。

内容	回数	最終発生
コンポーネント内で直接 DB クエリを書いた	2	2026-08-27
要件に無いローディング表示を追加した	1	2026-08-26

回数が 2 になったものだけを CLAUDE.md にルールとして起こし、表から消します。1 のものは残す。次に起きたら 2 になります。

この表は最初の版には無くて、後から足しました。「2回以上再発した誤りはルール化する」と書いておきながら、数える場所を用意していなかった。当然、誰も数えないので、この方針は一度も発火しませんでした。ルールを書くときは、それがどこで発火するかまで決めないと動かないという、当たり前の話です。

削除のほうも同じタイミングでやります。CLAUDE.md を上から読んで、その1機能の間に一度も関係しなかったルールを候補に挙げ、消していいか確認します。追記だけを繰り返すとファイルは必ず膨らむし、膨らんだ CLAUDE.md は読まれません。1回の振り返りで、足す行と消す行を両方出すのを原則にしています。

既存プロジェクトが手に負えなくなったとき

CLAUDE.md が長くなりすぎた。整理したい

作り直しはしません。各行を「守るルール」「参考情報」「一度きりの記録」に仕分けて、参考情報は docs/ へ移し、一度きりの記録は消します。残ったルールのうち実際に守られていないものは、理由を添えて削除を提案します。勝手には消しません。

ついでに、参照ルール表に出てくるファイルが実在するかも確認します。ここが地味に効きます。

参照ルール表というやつ

CLAUDE.md に、作業種別ごとに開始前に読むファイルを書いた表を入れています。

作業	開始前に読む
機能の実装	docs/requirements/<機能ID>.md
DBスキーマ変更	docs/architecture.md の「データモデル」
設計方針の判断	docs/adr/ の関連するもの

そのうえで、該当ファイルが無いか記載が曖昧なら実装せず質問すると書きます。

「不明なら参照して」だけでは効きません。エージェントは自分が不明だと自覚しないまま、それらしいコードを書いてしまう。読むタイミングを人間側で決め打ちにして、迷ったら止まる条件まで明文化する必要がありました。

ここで一つ罠があって、表に書いた参照先が存在しないと逆効果になります。docs/architecture.md を読めと書いてあるのにファイルが無いと、毎回「曖昧なので質問します」で止まるか、ルールごと無視するかのどちらかになる。なので中身が空でも先に置きます。

サブエージェントで詰まったところ

developer と reviewer の2体だけです。最初は tester を含めた4体でやろうとして、戻り値の受け渡しで詰まりました。サブエージェントは独立したコンテキストで動いて、結果は要約されて親に返ってくる。体数を増やすほど、要約で情報が落ちる回数が増えます。

統括はメインスレッドに持たせます。統括をサブに置くと、全体の状態が二重に劣化しました。

あと、これは自分のミスなんですが、reviewer が git diff で差分を見る作りにしていたのに、developer 側にコミットを禁止していませんでした。developer がコミットすると差分が空になって、reviewer が「指摘なし」と返してくる。レビューが素通りしていることに、しばらく気付きませんでした。

今は CLAUDE.md の禁止事項に「サブエージェントはコミットしない」を入れて、reviewer 側は git diff HEAD を使い、差分が空なら「差分なし」と報告して止まるようにしてあります。

もう一つ、指摘が残る間は developer に戻す と書くと止まらなくなります。reviewer は毎回何かしら軽微な指摘を出せてしまうので。往復は2回まで、残ったら人に上げる、という上限を入れました。

効くところと効かないところ

効いたのは、CLAUDE.md が短いまま保たれることです。追記と削除を同じタイミングでやる決まりにしてから、100 行を超えなくなりました。長さそのものがコストなので、これは効果として分かりやすい。

要件の「未決事項」に書いたことで developer が止まってくれるのも助かります。決まっていないことを空欄にせず明記しておくと、そこを推測で埋めずに聞き返してくる。逆に言うと、未決を空欄にしていた頃は、勝手に埋められたものを後から剥がす作業が発生していました。

一方で、このスキルは楽をするためのものではありません。むしろ手数は増えます。実装中に誤りを表へ書き足すのは人の仕事だし、振り返りは別途時間を取る必要がある。全部自動でやってほしい人には向きません。

あと、1機能を貫通させるまでは効果がまったく出ません。生成された直後の CLAUDE.md は想像で書いた薄いファイルなので、そこで止めると「ドキュメントが増えただけ」で終わります。3 と 4 のステップを飛ばすと、このスキルを使う意味はほぼ無いです。

まとめ

やっていることを一行にすると、CLAUDE.md を書く時間を、実装前から実装後に移しただけです。

事前に想像で書くのをやめて、間違えたところを数えて、2回以上のものだけをルールにする。それだけなんですが、手でやると続かないので、置き場所と手順を固めてスキルにしました。

同じところで何度も同じ指摘をしている自覚がある人には、たぶん効きます。