文書の置き場所は、中身の種類で決める

僕の開発用のフォルダには、AIに読ませるための文書がたくさんある。コーディングしてくれているClaude Code（以降Code）と一緒に作ってきたものだ。システムの設計、AIへの指示、作業の記録。Codeとの会話は1回ずつ区切られていて（この1回をセッションと呼ぶ）、Codeは前の回のことを覚えていない。だから次の回のCodeは、こういう文書を読んで続きを始める。

困っていたのは、何がどこにあるのかよく分からないことだった。Codeに調べてもらうと、文書の置き場所が2つあった。1つは、docs（ドキュメント）という名前のフォルダ。もう1つは、HO（ハンドオーバー。セッションの終わりに残す引き継ぎメモ）を入れているフォルダの中に作られた、topicsというフォルダ。どっちに何を書くかの決まりは、外から見えない、とCodeは言った。

Codeにフォルダの片付けを頼んだ日、この2つの中身を、ファイル1本ずつ確かめていった。

「必読」と書いた文書は、毎回は読まれていなかった

まず、docsとは何なのかをCodeに聞いた。Codeは中のファイルを全部読んで、ほぼ全部の冒頭に「提案中」「確定」のような状態が書いてあり、決まるたびに上書きされている、と教えてくれた。これから作るシステムや、今動いているシステムの仕様書だった。

僕と設計を相談した結果をここにまとめているのか、作る前に読むものなのか、と聞くと、Codeはどっちもその通りだと答えて、こう説明してくれた。設計の相談をしたセッションからは、文書が2つできる。HOには、その回に何が起きたかを、経緯や理由も含めて書き足していく。仕様書には、決まった答えだけを書く。古い答えは上書きされて消える。

ただ、作る前に仕様書を読む、という決まりはどこにも無かった。CLAUDE.mdという、Codeが起動するたびに最初に読むルールのファイル（僕は憲法と呼んでいる）も、docsには一言も触れていない。

Code「docsは『これが正しい版』ということになってるのに、そこを読みに行く決まりがどこにも無い状態です。読まれるかどうかは、セッションごとの運。」

topicsの方は、問題がもっとはっきりしていた。中身は、何回ものセッションをまたいで使う知識のまとめ。そのうちのいくつかには、冒頭に「必読: はい（全セッションで読むこと）」と書いてある。

こんなものを毎回読んでいたら、すごい量のトークン（AIが文章を数える単位）を使っているんじゃないか、とCodeに聞いた。Codeはtopicsの量を測ってから、先に結論を言った。今、そのトークンは使っていない。topicsは、起動の時に自動では読み込まれないからだ。このセッションのCodeも、1本も読まずに作業を始めていた。

Code「今の状態は『高い』んじゃなくて、『無料だけど効いてない』。」

じゃあ、topicsは1本も使われていないのか、と聞くと、Codeが調べ直してくれた。HOを書くサブエージェント（Codeが作業を分けて任せる、別のAI）の定義が、topicsのうち5本を「更新しろ」と指している。更新するには読むしかないので、その5本は実際には読まれていた。ただし、「必読」の通りに毎回読まれているものは、1本も無かった。

topicsには、作業の手順や決まりを書いたファイルも何本かあった。そっちは、中の決まりがいつの間にか、使う時に必ず読み込まれるファイルの方へ移っていた。起動するたびに読まれる憲法や、動く時に読まれるサブエージェントの定義だ。実際に効いているのは向こうで、topicsに残っていたのは、役目を終えた写しだった。

原本から抜き出したまとめだけが、古いまま残っていた

topicsの中に、設計の決定を集めた1本があった。Codeとの会話は、同時にいくつか開いておける。ちょうど、別の会話のCodeがそのファイルに書き足していたので、僕も中を見てみた。古い内容と新しい内容が混ざっている気がして、これは誰も読んでいないんじゃないかと思った。それで、例えば会話の記憶を整理する仕組みの全体を知りたい時、Codeはどこを読んでいるのか、と聞いた。

Codeが調べると、混ざっているのは僕が感じた通りだった。そのファイルには、Warm-Aという言葉が51箇所出てくる。会話の記憶を整理する仕組みの、部品の1つの名前で、後で仕組みを作り直した時に廃止している。なのに、作り直す前に書かれた節のいくつかは、何の注記も無く、Warm-Aを今も動いている部品として説明していた。

原因は、読まれていないことよりも、書き方の方にあった。このファイルは、HOを書くサブエージェントが毎回末尾に書き足して育てていた。サブエージェントへの指示は「すでにある内容と重複しないか確かめる」だけで、前の内容と食い違っていないかは確かめないことになっていた。

Code「末尾に足せば仕事が終わる作りなので、前を読み返して直す理由がどこにもない。」

しかもこのまとめは、HOと仕様書から抜き出したもので、元の情報はそっちにある。記憶の仕組みの全体を知りたい時はどこを読むのか、という僕の問いの答えもここで出た。Codeが読んでいるのは仕様書の方で、topicsのまとめではなかった。Codeによると、まとめは古くなっても直されないので、元の文書よりどんどん悪くなっていく。

Codeは、同じWarm-Aが仕様書・HO・topicsのまとめの3つでどう書かれているかを並べてくれた。仕様書では、もう「廃止」になっている。HOには、当時は動いていたと書いてあるが、日付の付いた記録なので嘘にはならない。

Code「HOは最初から『当時の話』として書いてあるので古くならない。仕様書は上書きだから、いつも今の話。topicsだけが、日付の無い今の話として古い内容を書いてる。」

AIに読ませる文書は、仕様書・指示書・記録の3種類

ここから先、ファイルを動かすのは全部Codeに任せることにした。その上で、僕からこう提案した。docsの中身は全部仕様書なのだから、名前を仕様書（spec）のフォルダに変える。複数形のspecsにするかどうかは、Codeに任せた。空いたdocsという名前で、今度は本当に記録（ドキュメント）を入れるフォルダを作り直す。そこには、topicsにあった1本だけを入れる。僕のAIが同じ失敗を形を変えて何度も繰り返した事例を、並べてまとめた記録だ。Codeが、他に代わりが無いと言っていた1本だ。topicsの残りは、使わなくなったファイルを置く物置きのフォルダへ移す。

Codeは、それだと困るものがあると言った。一番大きいのは、topicsの中にある、月に1回自動で動く点検の手順書だ。点検というのは、作ったシステムが今の実態とずれていないかを、AIが調べる仕組みだ。点検役のAIは、毎回この手順書を読んで動く。物置きに入れると、次の月の点検が黙って失敗する。

僕はその手順書の中を見て、これは仕様書というより、AIへの指示書（システムプロンプト）なんじゃないかと思った。Codeが自分の記憶をどう書くかをまとめた別の1本は、タイトルに「仕様」と書いてあった。でも、そもそも仕様書とシステムプロンプトは何が違うのか。仕様書は、作る前の計画書みたいなものじゃないのか。この辺りがいい加減だから、ぐちゃぐちゃになっているんじゃないか。ちゃんと決めておきたい、とCodeに言った。

Codeは、仕様書を作る前の計画書と見るのはほぼ合っている、ただ決め手になるのは何について書いているかだ、と言って、3種類の違いを表にまとめてくれた。

種類	何を書くか	読む人	いつ読まれるか	直し方
仕様書（spec）	モノ。これから作る・今動いているシステムの構造	作る人	作る前	上書き
指示書（prompt）	振る舞い。AIがどう動くか	AI	動く時に、機械が読み込む	上書き
記録（document）	起きた事実。何が分かったか	人とAI	判断する時	書き足す

Code「仕様書と指示書は、どちらも『〜すること』と書くから混ざる。でも、書いている対象が違います。」

Codeは例を挙げた。記憶の仕組みの部品として僕が作っているAIの仕様書は、そのAIというモノの図面。点検の手順書は、点検役のAIがどう動くかを決めている。タイトルに「仕様」とあった1本も、中に、Codeの記憶を書く係のサブエージェントに渡す書き方の見本が入っていて、指示書の方だった。

この表に当てはめると、さっきのtopicsのまとめが古くなった理由も分かる。あのまとめは、仕様書のように日付の無い今の話として書かれていたのに、直し方は記録と同じで、書き足すだけだった。

種類が分かれば、置き場所も決まる

Codeは、種類によって壊れ方が違う、とも言った。

Code「指示書は、置き場所を間違えると壊れる。仕様書と記録は、読まれなくなるだけ。」

指示書は、AIが動く時に、決まった場所から機械が読み込む。ファイルをそこから動かすと、読み込めなくなって止まる。さっきの、月1回の点検が黙って失敗する話がまさにそれで、Codeは「あの手順書が指示書だから起きる事故です」と言った。

仕様書と記録は、要る時に人やAIが探して読む。置き場所を間違えても何かが止まるわけではなく、ただ読まれなくなる。「必読」と書いてあっても毎回は読まれていなかったtopicsのまとめが、こっちだった。冒頭の、作る前に読む決まりが無かったdocsの仕様書も同じだ。

だから置き場所は、種類ごとに決めればいい。Codeの案では、指示書はCodeの設定フォルダ（AIの係や、定期の作業の定義が入っている所）、仕様書はspecs、記録はdocsに置く。こうして並べると、散らかっていた原因も見えてきた。

Code「今のぐちゃぐちゃの正体はこれです。指示書が、引き継ぎメモのフォルダのtopicsに置かれてる。人が探して読む文書の棚に、機械が読み込む指示書が混ざってる。」

人も読む指示書は、見える場所に置く

では、点検の手順書は本来どこに置くべきなのか、とCodeに聞いた。Codeが挙げたのは、点検役への指示がすでに入っている、さっきのCodeの設定フォルダだった。手順書がtopicsにあったのは、作った当時ほかに置ける棚が無かったからで、Codeはtopicsのことを「分類じゃなくて、余り物の置き場だった」と言った。

でも、そのフォルダは名前が点で始まる隠しフォルダで、僕は隠しファイルを画面に出さない設定にしている。そこに置くと、僕には見えなくなる。僕が読む必要が無いならそれでいいけど、見えなくても関係ないのか、とCodeに聞いた。

Codeは、関係あると答えた。この手順書のうち、点検で何を基準に良し悪しを決めるかの部分は、僕の価値観をそのまま書いたものだ。何を点検するかを決めるのも僕だ。Codeと僕が一緒に持っているファイルを、僕から見えない所に置くのは間違いだ、と。さっきの表では、指示書を読むのはAIだけとしていた。でもこの手順書は、僕も読む。Codeは、決まりをこう直した。

Code「読む人が機械だけの指示書は、動かす仕組みの側へ。人も読む指示書は、見える場所へ。」

置き場所は、projects（アプリごとのフォルダを並べている所）の下に点検用のフォルダを作るのはどうか、と僕が聞いて、そこに決まった。過去の点検の報告書も引き継ぎメモのフォルダにあったので、一緒に移せば、手順書と報告書が一か所にまとまる。点検の結果が引き継ぎメモのフォルダに入っているのも、確かにおかしな話だった。

Codeが全部動かし終えると、docsはspecsという名前に変わった。topicsの中身は、点検の手順書が点検用のフォルダへ、失敗の事例の記録が新しいdocsへ、どこからも参照されていなかった昔の調べ物の1本が調べ物を集めたフォルダへ、残りは物置きへと分かれた。中身の種類で行き先を決めていったら、余り物の置き場だったtopicsには、何も残らなかった。