The AI Thinkerの記事を読んで、Claude Codeのフォルダ管理について改めて考え直した記録。プロダクトマネージャー向けの記事だが、主張はエンジニアの自分にもそのまま刺さった。
プロンプトはセッションを良くする、ファイルはその先を良くする
記事の核心はこの一文。
Past the basics, your results in Claude Code stop depending on how well you prompt and start depending on how well you file.
基礎を超えた先では、成果を決めるのはプロンプトの上手さではなく、ファイリングの上手さになる。良いプロンプトは1回のセッションを改善するが、良いファイルはその後の全セッションを改善する、という対比。
これは実感がある。毎回同じ前提を説明し直しているセッションと、CLAUDE.mdやcontext/配下のファイルが前提を代わりに説明してくれているセッションでは、同じタスクでも体感速度がまったく違う。
トピックではなく「変化速度」でフォルダを分ける
記事で一番印象に残ったのは、ファイルの分類軸。「何について書いてあるか」ではなく「どれくらいの速さで変わるか」で分けるという発想だ。
| 変化速度 | 具体例 | 置き場所 |
|---|---|---|
| 数分〜数時間 | チケットやSlackのようなライブデータ | ファイルではなく、外部ツールと直接つなぐMCP（Model Context Protocol）接続に持たせる |
| 数日〜数週間 | 議事録やステータス更新 | ファイル名に日付を入れて「これは当時の事実」と分かるようにする |
| ほぼ変わらない | プロダクトの立ち位置やユーザー像 | context/product.mdのような場所に置いて、毎セッション参照できるようにする |
トピックで分けると、古い真実と今の真実が同じ棚に並んで見分けがつかなくなる。速度で分ければ、古い情報が新しい顔をして紛れ込むことがなくなる、というのが記事の主張だ。LLMの失敗パターンは「古いコンテキストを自信満々に使い回すこと」だから、という理由づけにも納得感があった。
振り返ってみると、Obsidian Vaultの11-Zettelkasten/はすでに近い構造になっていた。Karpathy方式（Andrej Karpathyが提唱した「人間は素材を投げ込むだけ、LLMが整理してwikiに育てる」運用スタイル）を採用したときは「素材と完成品を分ける」くらいの意識だったが、今回の記事を通すと「速度で分けていた」という説明の方がしっくりくる。
| 役割 | フォルダ | 変化速度 |
|---|---|---|
| raw（生の入力） | 00-Inbox/ 01-Fleeting-Notes/ |
速い、人間だけが書く |
| wiki（概念） | 01-Permanent-Notes/ index.md |
遅い、Claudeが整理して書く |
| reports（回答） | 02-Reports/ |
都度生成される出力 |
raw層を人間しか触らない読み取り専用にしているのも、速く変わる素材に遅い層の確からしさを求めないための線引きだった。
CLAUDE.mdは地図であって、マニュアルではない
もう1つ刺さったのが、CLAUDE.mdの役割の話。CLAUDE.mdは毎セッション必ず読み込まれるファイルなので、そこに書いた1行1行がAnthropicの言う「attention budget」を消費する。だから中身を全部詰め込むのではなく、「誰が」「どこに何があるか」「常に守るルール」だけを書いた地図にとどめ、詳細はcontext/配下の各ファイルに逃がして、必要なタスクのときだけ読み込ませる。ドキュメントの目安は200行以内とのこと。
自分のCLAUDE.mdを読み返すきっかけになった。プロジェクトの規約は書いてあっても、「詳細はどのファイルにあるか」への導線が弱い箇所がまだ残っている。今後整理するときは、内容を書き足す前に、地図として残すべきか参照先ファイルへ逃がすべきかを問うようにする。
名詞はファイルに、動詞はスキルに
記事のもう1つの判定基準がこれ。Claudeが「知っておくべきこと」は名詞なのでファイルに、「実行すべきこと」は動詞なのでスキルにする。この2つが逆転すると、事実しか持たないスキルや、実行できない手順書のようなcontextファイルが生まれてしまう、という指摘だった。
.claude/skills/を見返すと、kb-compile（編纂）、kb-report（回答）、kb-lint（棚卸し）はどれも動詞として素直に成立している。一方で、ブログ執筆の「文体の好み」のような、本来ファイルに置くべき名詞的な知識が、まだどこにも定着していないことに気づいた。
修正は一度だけ言う
最後の実践が、個人的に一番効きそうだと感じた部分。Claudeの出力に同じ修正を何度も入れている、という状況そのものが問題だという指摘だ。一度きりの言い間違いは流してよいが、同じ指摘を2回したなら、それはファイルに書くべきタイミング、というシンプルな基準。
記事のワークスペースにはfile-feedbackというスキルがあり、修正が起きるたびに次の4つに振り分けるそうだ。
- 一度きりの言い間違い → 流す
- 抜けていた事実 → 該当するcontextファイルに追記
- 手順の間違い → スキルを修正
- 好みの問題 → preferencesファイルに、理由と適用条件つきで記録
「理由と適用条件つきで記録する」という部分が地味に重要だと思う。理由がなければ、次回また同じ判断で迷うことになる。
Zettelkastenにはkb-lintという棚卸しの仕組みはあっても、「同じ指摘を繰り返さないための記録場所」はまだない。ブログ記事のQAで文体の指摘を毎回同じように受けているなら、それはpreferencesファイル行きの候補だ。
ループエンジニアリングとしての読み方
最初にこの記事を読んだときに考えていたのは、「これはプロダクトマネージャーの整理術の話ではなく、ループエンジニアリングの話だ」ということだった。
Claude Codeに何かを依頼するたびに、前提の再説明・実行・修正というループを回している。フォルダ設計が雑だと、このループの前半（前提の再説明）が毎回重くなる。後半（修正）も、毎回同じ内容の繰り返しになりがちだ。
一方で、変化速度でファイルを分け、地図と詳細を分離すれば話は変わる。修正を一度で記録に変えていけば、同じループでも前提説明と修正のコストはどんどん軽くなっていく。プロンプトを工夫してループ1回の質を上げるのではなく、ファイルを整えてループそのものを速くする。今回の記事が言っていたのは、結局そういうことだった。
次にやることは決めた。ブログ執筆まわりの「文体の好み」を、まずは1つのファイルに書き出すところから始める。
参考