AIに読ませるための引き継ぎ資料を、1.36MBまで育てた。そして先日、そのAI本人に聞いてみたら「私はそれを通読していません」と言われた。
今回は、Claude Code とどうやって開発を進めているかという話と、その方法が抱えていた綻びの話をする。前回（6台のサーバにしか実体がなかった設定ファイルを、GitLabへ集めるまで）で作ったシステムは、この方法で作ったものだ。
やっていることは、昔から何も変わらない
先に手順を書いておく。特別なことは何もしていない。
1. まず「何をやりたいか」だけを話して、設計書を書いてもらう。 前回のGitLab同期システムなら、最初に渡したのはこれくらいの粒度だ——「各ノードの設定ファイルの正本がサーバの中にしかないので、GitLabへ一方向で同期したい」。それだけ。そこから設計書を書いてもらい、章立てで詰めていく。
2. 判断が必要なところは、その場で人間が決める。 設計を進めると、AIが勝手に決めてはいけない分岐が必ず出る。リポジトリはモノレポのままか分割か。中央が取りに行くか各ノードがpushするか。コミットはノード単位か全体で1本か。こういう問いが出たとき、Claude Code はこちらに聞いてくる。私はその場で答える。
3. 決めたことは「決定記録」として設計書に残す。 D-A、D-B、D-C……と決定ごとにIDを振り、何を確定したかを表にしておく。数日後の別セッションで「なぜモノレポなのか」を蒸し返さずに済む。
4. セッションは切れる前提で、引き継ぎ資料を書かせる。 作業は一度で終わらない。今回も設計のセッション、実装のセッション、その続き……と分かれた。区切りごとに、何をやったか・何が確定したか・何が残っているかを書いてもらう。
これは、担当者が代わるときに書く引き継ぎ書と同じだ。決定事項一覧も、基本設計書も、システム開発の現場で昔からあった。相手がAIになっただけで、「明日の自分は他人」という前提は何も変わらない。
プロンプトを工夫するより、確実に速い
最初の頃は指示の書き方を工夫しようとしていた。前提を細かく書き、制約を並べ、出力形式を指定する。だがこれは疲れるわりに、セッションが変わると全部消える。翌日また同じ前提を書き直すことになる。
設計書と引き継ぎ資料をリポジトリに置く方式に変えてから、これが要らなくなった。前提はファイルを読めば分かるので、私が毎回説明しなくていい。リポジトリ直下に CLAUDE.md を置いておくと Claude Code がセッション開始時に自動で読み込むので、新しいセッションで私が最初に打つのは「続きをやりたい」程度の一言で済んでいる。
もうひとつ効いているのは、設計が先にあると実装が翻訳作業になることだ。今回の設計書には「実装規律」という章があり、shell=Falseで固定引数のみ使うこと、LLM呼び出しを一切含まないこと、--dry-runを必ず用意すること、異常があれば全体を中止することが書いてあった。実装フェーズはこれをコードに落とすだけになる。できあがった同期ツールの中にAI呼び出しが一つも無いのは、設計書がそう決めていたからだ。設計は対話で決め、実装は決定論で作る。
ここまでは、うまくいっている話だ。問題はこの先にある。
1.36MBの引き継ぎ資料
先日、引き継ぎ資料を開こうとしたら妙に重かった。行数を数えたら18,794行、1.36MB。中身を見ると、半分以上がソースコードの全文貼り付けだった。
これは書いた当時は正しかった。サーバ上のファイルを保存しておく手段が、引き継ぎ資料の付録しかなかったからだ。だが同期システムができた後は、実体がリポジトリ本体にあるので完全な重複になっていた。役目はとうに終わっていたのに、ファイルだけが残り続けていた。
削除して、日付に依存しないアーキテクチャ説明は別の設計書へ切り出した。1.36MB が 60万バイトになった。整理はついた——と、その時は思っていた。
「私はそれを読んでいません」
整理を終えたあと、ついでに Claude Code へ率直な感想を求めてみた。この作業方法のどこが弱いか、忖度なしで書いてほしい、と。返ってきた第一声がこれだった。
handoverはもう「引き継ぎ資料」ではなく「アーカイブ」です。そして私は読んでいません。正直に言うと、私は毎回grepしているだけで、通読していません。
整理した後でも512KB・1,963行ある。そして CLAUDE.md には、私自身がこう書いていた——「大きいので必要な章だけ検索して読むこと」。
つまり私は、AIに読ませるつもりで書いた資料に、AIへ向けて『全部は読むな』と注意書きを添えていたことになる。その時点で、それはもう引き継ぎ資料ではない。引き継ぎ資料は数分で読み終えられるべきもので、検索して掘り返すものは資料ではなく倉庫だ。
しかも今回 1.36MB を削ったが、再び太るのを止める仕組みは何も入っていない。毎セッション追記され、何も退役しない構造は手つかずのままだ。半年後にまた同じ整理をすることになる。
そして、資料は嘘をついていた
もっと悪い指摘が続いた。記録は現実より遅れる、というものだ。心当たりが二つあった。
ひとつは今回の作業中に起きている。CLAUDE.md に「SSH到達性は整備済み」と書いてあったので、その前提で中央pull方式（ai-coreが各ノードへ取りに行く）の実装に入ろうとした。ところが実機を確認すると、整備済みだったのはこの作業用Windows機から各ノードへの到達性で、ai-core からの鍵認証は一度も作られていなかった。まったくの別物だった。資料は間違ってはいなかったが、読み手が必要としている問いには答えていなかった。
もうひとつは以前の事故だ。引き継ぎ資料に貼ってあったソースコードが実機より古く、それを正本と思って編集を始めたことがある。あやうく稼働中のエンドポイントを削除するところだった。実機の現物と突き合わせて気づいて事なきを得た。
このシリーズでは「計測してから信じる」を何度も書いてきた。ログを見る前に結論を出さない、動いているように見えるものを信用しない、と。その規律を、私はドキュメントにだけ適用していなかった。コードと実機は疑うのに、自分の書いた資料は疑っていなかった。記録は現実の写真ではなく、撮った時点の仮説だ。
どう直すか
指摘を受けて、次にやることが決まった。
引き継ぎ資料に行数の上限を決める。 「現在の状態」と「過去のログ」を別ファイルに割り、前者は200行以内を維持する。今の状態・進行中の案件・次にやること・落とし穴だけを置き、溢れたら過去ログへ落とす。上限を CLAUDE.md に明記しておくのが肝で、上限がないから太る。
ツールにテストを書く。 同期ツールには秘密情報スキャナが入っていて、これは「121ファイルで誤検知ゼロになるまで調整した」正規表現の塊だ。にもかかわらずテストが無い。次に誰かが正規表現を触った瞬間、静かに壊れる。しかも壊れる方向は「秘密情報を見逃す」側だ。
そしてもう一件、この記事を書いている最中に見つかったものがある。ブログ投稿用に作ったツールで、メタディスクリプションをAPI経由で設定する機能を付けていた。だがこれは動かない。Yoast SEO のメタはアンダースコア始まりの保護されたキーで、明示登録されていない限り REST API 側で黙って捨てられる。投稿は成功し、メタだけ入らない。エラーも出ない。
第45回から繰り返し書いてきた「静かな失敗」を、自分の道具に自分で仕込んでいた。送信をやめ、投稿後に「これは手動で入れてください」と表示するよう直した。動かない機能があるくらいなら、無い方がいい。
結局のところ
設計書を書き、判断を人が下し、引き継ぎ資料を残す。この手順自体は効いている。プロンプトの書き方を工夫するより、ずっと確実に速い。人間だけでやっていた頃、こうした文書は「書くのが面倒だが、後で誰かが助かるもの」だった。今は書いた瞬間から自分が助かる。AIがそれを読んで動くからだ。
ただし——読ませたいなら、読める長さでなければならない。今回いちばん堪えたのは、読み手に直接「読んでいない」と言われるまで、自分がそれに気づかなかったことだった。相手がAIでなければ、たぶん誰も正直には言ってくれなかったと思う。