バイブコーディング時代の文書管理：何を残し、どう読んでもらうか

Thu, 10 Sep 2026 10:00:00 +0900

文書の目的はコミュニケーションです。バイブコーディングは、その対話に参加する主体を増やします。

チョン・ドヒョン - ROBOCO首席コンサルタント

TL;DR

バイブコーディングにも従来の文書化の原則が当てはまります。執筆と整理をエージェントに任せれば、少ない手間で優れた実践の恩恵を得られます。
更新を続ける基準文書と、目的を果たせば役割を終える一時的な文書を区別しましょう。すべての文書を最新化する必要はありません。
文書は短いMarkdownファイルに分け、フォルダごとの索引やルール、スキルでつなぎましょう。必要な作業で見つけて読めることが大切です。
頻繁に素早く確認する内容は箇条書きで、文脈の理解と深いレビューが必要な内容は文章形式で書きましょう。
文書は人と人、人とAI、AIとAIが意図と判断基準を共有する手段です。人は目的を定め、結果を判断することに集中しましょう。

これまで何度も述べてきたように、バイブコーディングにも従来のソフトウェア開発の原則がそのまま当てはまります。問題を定義し、設計します。実装し、検証します。結果をレビューし、改善します。人が行ってもエージェントが行っても、この過程は必要です。変わるのは各段階を担う主体とコストです。

以前書いた「バイブコーディングについての真実、あるいは嘘」でも同じ話をしました。テストや設計、CI/CDといった優れた実践はバイブコーディングでも通用します。「バイブコーディングとエンジニアリング成熟度の向上、どちらが先か？」では、さらに一歩進めました。エージェントは既存の開発体制を活用するだけでなく、その体制を整えることも支援できます。

文書化も同じ原則に従います。良い文書がもたらす恩恵は変わりません。ただし、それを得るために人がかける手間は大きく減ります。コードから使い方を抽出し、変更を反映し、文書を分類する作業はエージェントに任せられます。人が一つひとつ書いていた頃より、はるかに少ない時間と労力で文書を整えられます。

文書管理で最初に問うべきことは二つです。この文書はいつまで有効なのか。そして、誰がどのような目的で読むのか。

1. エージェントにとって文書は次の作業の出発点になる

人が開発するときも文書は重要です。コードだけでは、なぜその選択をしたのか分かりません。納期のために諦めた代案もあります。顧客と合意した例外もあります。実装は現在の動作を示します。文書はその動作を選んだ理由と、守るべき条件を伝えます。

バイブコーディングでは、この役割がさらに重要になります。人は以前の会議や作業をある程度覚えています。エージェントが新しいセッションを始めるとき、過去の会話をすべて引き継ぐとは限りません。長くなった会話が要約されると、重要な条件が抜けることもあります。別のエージェントに仕事を引き継げば、同じ説明が再び必要になります。

例えば、決済リクエストが失敗しても自動では再試行しないと決めたとします。二重決済を防ぐため、まず外部の決済事業者の処理状況を確認する必要があるからです。この文脈が会話にしか残っていなければ、次のエージェントは再試行ロジックの追加を改善案として提案するかもしれません。コードだけを見ると、復旧機能が欠けているように見えるためです。

この制約と理由を文書に残せば、次の作業の出発点が変わります。エージェントは同じ議論を繰り返す必要がありません。レビューする人も、実装が合意した条件を守っているか判断できます。

複数のエージェントが分担して開発するときも同じです。異なる前提で作業すれば、それぞれの実装は正しくてもシステム全体はかみ合いません。共有したAPI契約と完了基準は、このずれを減らします。文書は人とAIの間の説明書であり、AI同士の協業の基準でもあります。

2. すべての文書を更新し続ける必要はない

開発文書はライフサイクルの観点から二種類に分けられます。現在の基準を伝えるために継続して保守する文書があります。特定の時点のコミュニケーションが終われば、役割を終える一時的な文書もあります。

インストールガイドやAPI仕様書、現在のアーキテクチャの説明、運用手順は前者です。読者は、今適用できる基準として読みます。実行コマンドが変わればインストールガイドも変える必要があります。障害対応の手順が変われば運用文書も更新します。関連コードを変更する作業の完了条件に、文書の更新を含めるとよいでしょう。

特定のバグの調査メモ、一度のデプロイに向けた作業計画、レビュー依頼の説明、次のセッションへの引き継ぎ文書は後者です。作業中は内容を補えます。しかし作業終了後も、現在の状態に合わせて書き直し続ける理由はありません。その時点の状況を伝えられたなら、目的は達成されています。

一時的という言葉は、すぐ削除せよという意味ではありません。議事録や意思決定記録は、後から当時の判断を確認する資料になります。こうした記録は過去の文脈を保存する必要があります。決定が変わったら、古い記録を今日の結論で上書きせず、新しい決定とつなげればよいのです。記録の保存と内容の最新化は別の仕事です。

この区別がなければ、すべての文書が保守対象になります。機能を一つ変えるたびに、過去の計画書や調査メモまで修正します。人は時間を使い、エージェントはトークンを使います。その結果、文書を作るほど仕事が増えるという結論に至ります。説明が必要な場面でも、文書を作らなくなってしまいます。

文書を作るときは、用途と有効範囲を併記しましょう。現在の基準なのか、特定の作業の記録なのかを明示します。一時的な文書には日付と対象作業、完了状況を残します。作業が終わったら進行中の作業の索引から外し、保管先へつなぎます。次のエージェントが過去の計画を現在の指示として読まないようにするためです。

一時的な文書から、長く使える知識が生まれることもあります。バグ調査で見つかった制約は運用ガイドに反映します。レビューで合意したルールは開発指針に移します。必要な知識だけを現在の基準に取り込み、調査メモは記録として残します。こうすれば、コミュニケーションに必要な文書を負担なく作れます。

3. 文書は作業中に見つけて読める必要がある

文書を保存しただけで、エージェントが自動的に活用するわけではありません。どの作業で何を読むべきかをつなぐ必要があります。以前書いた「バイブコーディングのトークン管理戦略」でも、必要な文書を選んで読む構造を重視しました。Anthropicも、ファイルパスのような軽量な参照を保持し、必要なときに内容を読み込む方法を説明しています。¹

エージェントが参照する開発文書は、Markdownを基本にするとよいでしょう。見出しと段落、リンクで構造を示せます。検索や部分的な修正も簡単です。コードと同じリポジトリに置けば、変更履歴も一緒に管理できます。

一つの文書は、可能なら300行以下に保ちましょう。これはすべてのツールに共通する技術的制限ではなく、実務上の目安です。行数が同じでもトークン数は異なります。数字を満たすために文章を一行に詰め込んでも意味はありません。一つの文書で一つの主題を扱い、長くなれば主題ごとに分けるという意味です。レビューに必要な論理まで分断してはいけません。

フォルダも用途別に分けましょう。例えば、現在使うガイドは docs/guides/ に置きます。進行中の作業文書は docs/tasks/、完了した作業の記録は docs/archive/ に置きます。各フォルダの README.md には短い説明と主要文書へのリンクを載せます。人がフォルダを開いたときも、どこから読めばよいか分かる必要があります。

エージェント向けの入口も必要です。使うツールに合わせ、AGENTS.md や CLAUDE.md に共通ルールと文書のパスを書きましょう。リンクを並べるだけでなく、いつ読むかも明示します。決済機能を修正するときは、決済契約と重複処理の方針を先に確認するように書く、といった形です。両方のファイルを使うなら、共通ルールの基準を一つに定め、内容の食い違いを防ぎましょう。

繰り返す作業はスキルでつなぐと便利です。デプロイスキルは運用手順とデプロイの確認文書を読むように構成します。API変更スキルは契約文書を確認し、変更後に仕様書も更新するように構成します。文書が実際の作業手順の中で使われるようになります。

参照する文書が数百を超えると、索引をたどるだけでも負担になりかねません。その場合はLLM Wikiを導入する方法もあります。Karpathyが提案したLLM Wikiは、原資料とは別に、LLMが相互につながったMarkdownのWikiを作成・更新する方式です。² プロジェクトに適用すれば、散在する資料の概念と関係を整理できます。要約から原文に戻れるよう、出典も残す必要があります。導入の基準は文書数そのものよりも、同じ文脈を繰り返し探して組み合わせる負担です。

この構造を、人がファイルごとに手作業で整える必要はありません。既存の文書を用途別に分類し、長い文書を分割し、フォルダごとに索引を作るようエージェントに指示すればよいのです。その後の更新も作業ルールに組み込めます。人は何を現在の基準とするか判断し、結果を確認します。反復的な整理の手間を減らしつつ、誤った内容が基準として定着しないようにしましょう。

4. 頻繁に確認する文書は箇条書きで書く

文書をどう保存し、つなぐかが決まったら、内容をどう伝えるかを決めます。大きく分けて、箇条書きと文章形式があります。Markdownは両方を扱えます。文書の寿命と表現形式も、それぞれ別の選択です。

特に指示をしなければ、エージェントは箇条書きや表を積極的に使うことがよくあります。箇条書きは短時間で全体を見渡すのに向いています。必要な項目を探しやすく、抜け漏れも確認しやすくなります。

デプロイのチェックリストやコマンド集、環境変数の説明、APIフィールドの仕様がよい例です。こうした文書は頻繁に開き、特定の情報を素早く確認します。デプロイ直前に必要なのは実行順序と成功条件です。合意済みの手順を実行するたびに、長い背景説明を読み直す必要はありません。

一方、判断の根拠まで検討するなら、項目だけでは足りないことがあります。設計案に性能改善、コスト削減、拡張性の確保と書かれているとします。一目で把握できます。しかし何がどの程度遅いのかは分かりません。どのコストを減らすのかも不明です。拡張性を得るために何を諦めるのかも見えません。

読者はもっともらしい項目を読んで、理解したと感じるかもしれません。しかし判断に必要な文脈は、書き手の頭の中に残っています。レビューが始まると、項目ごとに説明を求めることになります。同じ文書を何度読んでも、省略された根拠は現れません。

項目同士の関係が見えなければ、後から判断の過程を思い出すことも難しくなります。何をすることにしたかは覚えていても、なぜそうしたかを忘れがちです。箇条書きは素早い確認に強みがあります。深いレビューでは、背景と根拠を説明する文章も必要です。

5. 深くレビューする文書は文章形式で書く

文章形式は、問題と条件、代案と結論を文でつなぎます。読者はその流れを追いながら、自分の考えを整理します。書き手は結論に進む前に、足りない説明を補う必要があります。

以前書いた「認知負債 - バイブコーディング時代の新しい負債管理法」でも、二つの形式を比較しました。セッションストレージをRedisへ移すという同じ決定を、箇条書きと文章形式のADRでそれぞれ示しました。箇条書きの例は、選択と根拠を短く列挙しました。文章形式の例は、ボトルネックの背景と代案を除外した理由、選んだ設計の失敗条件までつなげました。その違いによって、読者は決定の根拠を問い直せるようになりました。具体的な比較は、同記事の「第三に、叙述型の文書」の節を参照してください。

Amazonは、こうした文書を好む企業としてよく知られています。Andy Jassyは2024年の株主宛書簡で、本文が最大6ページの文章形式の文書を使うと説明しました。書き手には手間がかかりますが、読者は重要な問題を理解し、適切な質問をしやすくなるという理由です。³

Documentation on ROBOCO