同じ事実が2か所にあると、必ずずれる — AIと長く回すための正本の設計

業務ハーネスを2つの現場で運用している。ひとつは事業本部の予実管理で約30本・1万行、もうひとつは新設拠点の運営で12本・6,000行。どちらもClaude Codeと対話しながら1本ずつ書いたものだ。

半年ほど回してみて、効き方を決めているのはスクリプトの出来ではなかった、というのが正直な実感である。効いているのは、情報をどこに置くかを先に決めたことだった。

原則はひとつしかない。同じ事実が2か所にあると、必ずずれる。

実際にずれた話

新設拠点の立ち上げで、鍵管理簿がこうなっていた。

同じ名前で中身の違うファイルが2つあり、ポータルが古い方を指していた。

誰も悪意はない。誰かが手元にコピーを取り、そちらを更新し、リンクだけが元のままだった。それだけのことだが、鍵の割り当ては物理的な結果を伴う。番号が二重になった鍵を実際に貼ってしまえば、直すコストは跳ね上がる。結局、1冊に統合するところから始めた。

自動化を進めるほど、この種のずれは危険になる。人が手で更新していれば「あれ、こっちが古いな」と気づくが、スクリプトは黙って古い方を正しく更新し続ける。ハーネスの速度は、間違った正本に対しても等しく発揮される。

置き場ごとに、持つものと「持たないもの」を決める

そこで、置き場ごとに正本を1つずつ決めた。実際に運用している割り当てはこうなっている。

この表で実務的に効いているのは、右の列だ。

「何を持つか」だけを決めても、ずれは止まらない。人は迷ったとき、目の前で開いているものに書く。だから「ここには置かない」を明示しておかないと、恒久ルールがHANDOFFに紛れ込み、進行中の議論がドライブの台帳のコメント欄に溜まっていく。

とくに docs/ の行は意図的だ。ここは素材と下書きの置き場であって、確定情報の正本にはしない。現地に出してよい確定情報はポータルに移す。この一線が無いと、現場は「どのファイルを見ればいいのか」を毎回人に聞くことになる。

ドキュメントを3層に分ける

もうひとつ、ドキュメント側も3層に固定した。

3つに分ける理由は、読み手と更新頻度が違うからだ。仕様はコードを変えたときに変わる。手順は運用が変わったときに変わる。経緯は毎回追記されるが、上書きされることはない。混ぜると、どれも更新されなくなる。

そして、これがClaude Codeで長く回すための本体になっている。

失敗と判断を毎回HANDOFFに書き戻しているので、次のセッションが同じ穴を踏まない。新しいセッションはHANDOFFを読ませてから始めるだけでよく、「前回どこまでやったか」「なぜこの実装になっているか」を説明し直す必要がない。

実際、予実管理側の74コミットのうち30件超がドキュメントのみのコミットだった。当初は「コードを書いていない日」に見えて落ち着かなかったが、いまはこれを成果物として数えている。記録が薄い週は、翌週のセッションが確実に遅くなる。

踏んだ穴は、次のセッションに渡す

HANDOFFに書き戻しているのは、判断だけではない。相手システムの都合も全部残している。これは調べないと分からず、しかも次に必ずまた当たるからだ。

実際に残っている例を挙げる。

• 同一APIでも、エンドポイントごとに命名規則が違う（片方は snake_case、もう片方は camelCase。逆にすると必須項目エラーで落ちる)
• Pythonの標準HTTPクライアントだとCDNに403で弾かれるが、curl なら同じリクエストが通る
• 認証ヘッダの種類を間違えると401。正しくても別要因で403
• 外部共有チャネルは下書きの作成までしかできず、送信は人の操作が要る
• 法人向けECの支払方法は「請求書払い」で、稟議に「クレジット」と書くと差し戻される
• グループウェアの予定表だけを見て空きと判断しない。実体は別のカレンダー側にあり、空でも埋まっていることがある

こういうものは、公式ドキュメントを読んでも書いていない。一度踏んだ人の手元にしか無い知識であり、だからこそ書き戻す価値がある。AIにコードを書かせる速度が上がるほど、ボトルネックは「相手システムの実際の挙動を知っているか」に移っていく。

「言った/言わない」も、正本の問題だった

正本を決める話は、ドキュメントだけの話ではなかった。

現地への連絡について、送る前に文案をファイルに書いてから送る運用に変えた。その場で打って送るのをやめただけだが、9日間で59本の文案がリポジトリに残った。結果として「いつ何を伝えたか」が引けるようになり、言った/言わないが構造的に消えた。

これも同じ原則の適用だ。チャットの履歴とファイルの両方に事実があると、検索性も保存期間も違うのでずれる。送信内容の正本はファイル側と決め、チャットは配信手段として扱う。

副次的な効果として、送る前に一度ファイルに落とすと、文面が明らかに良くなった。その場で打つと、どうしても前提の共有を飛ばす。

実装する順番

もし同じことを始めるなら、順番はこうなる。

1. 置き場を数え上げる。 いま同じ事実が何か所にあるかを、まず一覧にする。だいたい想像より多い
2. 各置き場に「持たないもの」を書く。 持つものより先にこちらを決める
3. 重複しているものを1つに統合する。 リンクの張り替えまでやる。ここを省くと元に戻る
4. HANDOFFを作り、判断を書き戻し始める。 最初の1週間で効果は出ないが、1か月後のセッション速度が変わる
5. その後でハーネスを書く。 正本が決まっていないうちに自動化すると、間違った場所を高速に更新する仕組みができあがる

順番を逆にしたくなるのは分かる。スクリプトを書く方が手応えがあるからだ。ただ、ツールより効いているのはおそらくこちらだった、というのが2つの現場を回してみた結論である。

情報設計の現状整理から入るべきか、先に1本ハーネスを作って感触を掴むべきかは、組織の状況によって変わる。各論はご相談の場でお伝えできる。