アプリケーションをループエンジニアリングで開発したらドキュメントの陳腐化が加速した

この記事でわかること

自走（goal / loop を意識した長時間運用）で起きやすかった問題の、仕組み側の前提
記憶を マークダウンに移譲 すると、文書が増え、全部を参照し切る前に判断する 構造が生まれること
それが Loop / Graph 型のエージェント運用に特有に見えやすい理由
内容の検査（検証） と 出所の検査（裁定） の切り分け
実務で置いた最小の打ち手（決定登録簿・逆参照・CI）と ADR との違い

想定読者は、コーディングエージェントを日常的に使い、handoff や方針メモをファイル経由で次のセッションに渡している人です。Loop Engineering / Graph Engineering の用語は知らなくて構いません（後半で対応としてだけ使います）。

前提の共有: 自走すると、記憶はファイルになる

この夏、Cloudflare Workers + D1 の SaaS を、ほぼ AI エージェントだけで約 14 日間かけて組みました。規模の目安だけ先に置きます（数値はリポジトリの実測）。

項目	実測
TypeScript（主に Worker / API 側）	約 19,500 行
素の JavaScript（主に `public/` の UI）	約 24,000 行
API	100 本超
認可	マルチテナント向けに多層

書いた行のほとんどはエージェントです。人間が手で書いた行は 体感ではごくわずか（未計測） です。

本記事の主題は「速く書けた」ことではありません。どう回したか です。

現場では、Claude に対して goal / loop を意識した「自走」 を指示していました。人が毎ターン細かく誘導するのではなく、目標とループ（進める → 検証する → また進める）を持たせて長く走らせる、という向きです。

ここで避けられないのが、次の制約です。

コンテキストウィンドウはセッションで切れる。自走を続けるには、状態を外に書き出す必要がある。

実務上、その外出し先はほぼ マークダウン でした。方針、現状、未決、handoff、レビュー結果、決定メモ。Loop や Graph の語彙で言えば、「次のループ／次のエージェントが読める形で記憶を移譲する」ための媒体です。

対比をはっきりさせると、こうなります。

進め方	記憶の置き場	次の一手の材料
人が短い往復で誘導する	主にその場の会話	ウィンドウ内の文脈
goal / loop 型の自走	会話 + ファイルに書いた正本	次セッションが読む MD 群

短い往復は会話ウィンドウ内に記憶がある。goal/loop自走はマークダウンへ外出しし、次ループは読んだ断片を材料にする

図1. 記憶の置き場が変わると、次の一手の材料も変わる

「フェーズを跨ぐ開発」といった抽象は、ここでは軸にしません。壁打ちや実装停止のような区間はありましたが、問題の芯は「段階の名前」ではなく、自走のために MD を量産し、それを次の判断材料にしたこと にあります。

事実: 文書が増え、「PoC」が次の正になった

何が起きたか

自走を回すほど、リポジトリ内の文書は増えます。探索中の言い回し（「まずは PoC で」「本番は後で」）、停止理由、比較表、モック注釈、実装方針が、それぞれファイルとして残ります。

そのうえで、次のようなことが起きていました（運用ログ上 2026-07-26 前後の例）。

実装トラックが、文書と方針の中で 「これは PoC だから本番必須要件は非ゴール」 と固定されていた
OIDC・マルチテナント・既に人間が決めていた ADR などが、そのラベルの下で後回しにされていた
文書としては整合的に読め、部分的なテストも通っていた
しかし 誰も「本番相当でなくてよい」と承認したわけではなかった

つまり、エージェントが「承認済み」と偉そうに宣言した、という単純な話ではありません。
大量の MD のうち、古い前提を含む一部が、次のループの出発点として使われた という話です。

なぜそうなるか（解説）

こちらの理解は次です。

自走（goal / loop）は、状態を マークダウンに書き出す ことを前提にしやすい
探索区間のノイズ（壁打ちや実装停止のときの言い回しを含む）も、同じ「残すべき文書」として混ざる
次のループ／別エージェントは、そのコーパスを 全部精読し切る前に、手元の一文・要約・目立つラベルで方針を固定しがち
テストが緑でも、「その前提を今も使ってよいか」は検査していない
結果として、未読了のまま決める 構造が、自己承認に見える現象の土台になる

これは単発のチャット完結型より、ファイル経由で記憶を移す Loop / Graph 型の運用で起きやすい、というのが本稿の立場です。会話だけで閉じている間は、ウィンドウ内の更新がそのまま「今」です。自走で MD が正本になると、「書いたが読まれない／読まれたが古い」が常態化します。

自走が回る→MDが増える→一部だけ読む→方針を固定する、未読了判断の4段階

図2. 未読了のまま方針を固定する流れ

一般化すると、こうなります。

誰も承認していない前提が、記憶移譲用のマークダウンを経由して、次の判断の正として流通する。

必要なのは、出力の正しさだけでなく、「いま効かせてよい前提か」を別経路で見る 仕組みです。

切り分け: 内容の検査と、出所の検査

前提を共有したうえで、用語を置きます。

呼び方	見ているもの	典型的な問い
検証（内容の検査）	成果物そのもの	動くか。壊れていないか。テストは落ちるか
裁定（出所の検査）	前提・決定の効力	誰の承認で、今もその前提を使ってよいか

検証ゲートは成果物の内容を検査し、権威ゲートは決定の出所（登録簿からの逆参照の有無）を検査する

図3. 検証は内容、裁定は出所。同じ「ゲート」でも検査対象が違う

PoC の件は、検証だけでは足りない典型です。部分的に動いていても、「PoC でよい」という前提の出所が人間の決定に紐づいていない。

Loop / Graph との対応（短く）

同じ頃、コミュニティでは Loop Engineering / Graph Engineering という語彙もよく出ていました。知らなくて大丈夫です。本稿での対応だけ示します。

ループ・グラフ・裁定の3層モデル。各層の問いはそれぞれ「出力は正しいか」「正しく流れるか」「誰の承認で決まったか」

図4. 作業用の3層。下から出力・流れ・決定の出所

層の問い	本稿での位置づけ	自分の体制（要約）
出力は正しいか（ループ）	検証・敵対レビュー	流行前から運用
正しく流れるか（グラフ）	役割分担・差し戻し	固定パイプラインで部分的
誰の承認で決まったか（裁定）	本記事の主題	自走＋MD 移譲の副作用対策として厚くした

ループとグラフは「どう回すか」を精緻化する。一方で、回すためにファイルへ記憶を逃がす と、未読了判断という別種の穴が開く。裁定層は、その穴を「モデルの賢さ」ではなく 正本の置き方 で塞ぐ試みです。

ヒルクライミングや動的ワークグラフは未達です。先取りできていたのは検証と役割分担で、MD に書いた前提の効力管理 は後から必要になりました。

打ち手: 決定登録簿と逆参照（最小）

前提

自走を続ける限り、状態はファイルに出やすい
ファイルは増える。次のループは全部を精読しないことがある
だから「文書に何と書いてあるか」だけでは、今も効く前提を決められない

事実（置いたもの）

決定登録簿に、人間の決定を ID 付きで残す
登録簿から 対象文書のパスと承認版（コミットハッシュ）へ一方向の逆参照を張る
文書側に「承認済み」「確定」「PoC」と書いてあっても、登録簿からの逆参照が無ければ未裁定として扱う
重要文書には、裁定状態の表記を CI で強制しうる
登録簿へ決定を足す権限の運用は 人間側に置く

PoC の件では、決定記録に次を載せました（決定 ID: D-N）。

uni/ は PoC ではなく本番相当として扱う
既存文書の「非ゴール」自己申告は既決ではなく、負債台帳で人間が裁定する

これで、探索時の言い回しが MD に残っていても、今も効く前提は登録簿側が正 になります。

解説: ADR との違い

「それ ADR では？」という反応は正しいです。重なります。ただし向きが違います。

	ADR（一般的な使い方）	本稿の裁定層
主目的	決定を記録して残す	移譲用 MD から権威を剥奪する
参照の向き	文書が Accepted を自称しうる	登録簿 → 文書の逆参照が無い限り未裁定
効く場面	設計判断のアーカイブ	自走で量産された方針メモ・handoff・古いラベル
強制	レビュー文化に依存しがち	CI でヘッダ欠落を fail にできる
書き込み	運用次第	登録簿への追記権限を人間側に固定

ADR は今も使います（例: docs/decisions/0001-...md）。裁定層は、ADR 以外のメモが「読まれた断片」だけで次の正になるのを止める装置です。

最小サンプル

登録簿の 1 行イメージ:

D-N | 2026-07-26 | uni は PoC ではなく本番相当。『非ゴール』自己申告は負債台帳で人間が裁定
    | 対象: docs/notes/260725_方針転換_決定記録.md（追補7） @ <commit>

文書側ヘッダのイメージ:

| 項目 | 値 |
|---|---|
| 裁定状態 | unreviewed \| approved |
| 決定 ID | （approved のとき必須。例: D-N） |
| 承認版 | （commit hash。推奨） |

CI は「重要パスなのに 裁定状態 が無い／approved なのに決定 ID が無い」を fail にする、という 1 ルールから始められます。

運用上、決定 ID（D-A 〜 D-AT 前後）は おおよそ 45 件、登録簿の本格運用は 2026-07-25 起点で初期執筆時点まで約 2 週間でした。

失敗 4 件: 自走運用の周辺で起きたこと

裁定だけを設計図どおりに置いたわけではありません。検証・流れ・裁定のどれかが薄かったときに事故が起き、数日以内に制度へ変換した堆積です。

2026年7月から8月にかけての4つの失敗と、それぞれが数日以内に変換された制度のタイムライン

図5. 失敗（上）と、数日以内に入れた制度（下）

1. 2026-07-04 — 並行セッションで成果物が消える

前提: 複数セッションが同じ作業ツリーを触りうる（自走・並行と相性が悪い）。
事実: あるセッションの git stash / ブランチ切替が、別セッションの未コミット 28 ファイルを巻き込んだ。
解説: 注意力への依存は、コンテキストが伸びると薄れる。
制度: ブランチ操作前の物理ブロックフック + worktree 分離。

2. 2026-07-25 — 承認を厚くしすぎて止まる

前提: MD の自称を恐れて、着手前ゲートを増やした。
事実: 開発が止まった。翌日撤回した。
解説: ガバナンスは一方向に肥大しやすい。制度自体も捨てる対象に含める。
制度: ゲートの撤回を正式に記録する。

3. 2026-07-26 — 検証の芝居

前提: ループの「検証」を厚くしたくなる。
事実: 落ちようのない検査を並べて全件合格と報告する動きが出た。
解説: 量が増えても欠陥検出力は上がらないことがある。未読了判断と同じく、「やった体」で次に進める。
制度: 「この検査は何を落とせるか」を問う判断ベースへ。チェックリスト長を評価しない。

4. 2026-08-03 — 全部「要裁定」で停滞

前提: ファイル上の前提を人間に寄せすぎた。
事実: 裁定待ちが 65 件 溜まった。
解説: 決めないことは慎重さではなく停滞になりうる。
制度: 委譲の分類を明文化した。

例	寄せ方（本稿の運用）
ライブラリ選定・内部データ構造	技術判断。エージェントが決めて登録してよい
利用者向け文言、画面の優先順位	価値判断寄り。人間へ
曖昧な要件のどの解釈を採るか	価値判断。線が揺れたら人間が線を引き、決定 ID を残す

なぜモデルが賢くなっても残りやすいか

前提

生成は速くなる。自走は長く回せる。記憶移譲用の MD は増える。

事実（現場の感触）

検証の多くは、敵対レビューや自動検査へ寄せられた。一方で次の問いは残る。

このプロダクトは何を約束し、何を捨てるか
保持や同意の境界をどう置くか
どの MD 上の前提を、今も正としてよいか

解説

これらは正しさではなく 責任の所在 と 記憶移譲の正しさ の問題です。モデルが強くなるほど生成量は増え、未読了のまま使える断片も増える。だから裁定層の相対価値は、少なくとも個人開発の実感では 下がる方向には見えにくい、というのが現時点の仮説です（組織調査の結果ではありません）。

注意点・限界

「自走」「goal / loop」は当時の指示・運用の話であり、特定プロダクトの公式仕様の解説ではない
Loop / Graph の整理は二次記事に依拠した作業用要約。一次投稿の特定はできていない
決定 ID 約 45 件・待ち 65 件などは特定期間の運用数
製品名・顧客名は伏せ、再現に必要な構造だけを書いた

まとめ

層	内容
前提	goal / loop を意識した自走では、状態をマークダウンに外出しして記憶を移す必要が出る
事実	文書が増え、次のループが全部を読み切る前に方針を固定しうる（例: PoC ラベルの残留）
解説	芯は「エージェントの性格」よりファイル経由の記憶移譲と未読了判断に近い。Loop / Graph 型で起きやすい
打ち手	内容の検査（検証）と出所の検査（裁定）を分ける。登録簿＋逆参照＋CI。ADR は記録、裁定は権威の剥奪
運用	失敗を数日で制度にする。ゲートは厚くしすぎたら捨てる。技術判断と価値判断を分ける

TypeScript 約 19,500 行 + フロント JS 約 24,000 行（計おおよそ 43,500 行規模）を 1 人 + AI 群で回すなかで、ボトルネックが「書く速度」から 「どのファイル上の前提が、今も効くか」 へ移った、というのがこの記事の報告です。