Claude Codeの毎回の説明を3層のファイルで廃止

Claude Codeを使い始めた最初の1か月、著者は毎セッション同じプロジェクト情報を繰り返していた。スタック（Next.js App Router、Supabase、Stripe）、テストコマンド、ブランチとPRの流れだ。説明が抜けると、AIはmainに直接pushしようとしたり、「Kit」をツールキットと誤解して妙な変数名を付けたりした。著者の目安は、3回説明したものはチャットではなくファイルに入れる、というものだ。

提案する分割は、何を書くかではなく各ファイルが読まれる頻度に従う。事実と用語は知識Markdownファイルに入れ、必要な時だけ渡す。週1回以上行う手順は.claude/skills配下のSKILL.mdファイルにする。プロジェクト固有でも全プロジェクト共有でもよく、descriptionフィールドが呼び出し条件を兼ねる。毎セッション成り立つルールはプロジェクトルートのCLAUDE.mdに入れる。著者は長い手順をそこに詰め込むとファイルが肥大し効果が薄れると警告する。無関係なタスクでも読まれてしまうからだ。

この助言に切れ味を与えているのは剪定の規律だ。著者はCLAUDE.mdに書かないものを挙げる。長い手順、リンターが強制できるスタイル規則、一度きりの指示、現在の担当者や締め切りなど変化の速い詳細だ。そして何をどこに置くかを判断する3つの質問を用意する。ドリフトもメンテナンスとして扱い、チャットで指示を足すのではなくファイルを直す。そうすることでドキュメントが使うほど良くなる資産になると論じる。