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

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

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ページの文章形式の文書を使うと説明しました。書き手には手間がかかりますが、読者は重要な問題を理解し、適切な質問をしやすくなるという理由です。³

先ほどの設計案を文章にすると、違いが見えてきます。架空の注文システムを考えてみましょう。注文リクエストが来ると、外部サービスの応答を待ちます。外部サービスが遅くなると、注文の受け付けも遅れます。そこで、受け付けと後続処理を分離しようとしています。ただし、処理完了まで時間差が生まれます。利用者に進行状況を示す必要があります。重複リクエストへの対処も別途必要です。

これでレビュー担当者は、何を検討すればよいか分かります。利用者がその時間差を受け入れられるか判断します。外部サービスへの呼び出しだけを改善する代案はないかと問います。運用が複雑になる代償も考えます。文章がつながることで、検討すべき前提と因果関係が表に出るためです。

文章形式は読むのに時間がかかる場合があります。しかし、文字数だけでコミュニケーションのコストを測ってはいけません。短い箇条書きを理解するために会議を開き、書き手から説明を聞く時間もコストです。必要な文脈を文書に含めれば、読者は一度読む中で判断を進められます。

原因と結果を結びつけて読むことは、後から決定の理由を思い出す助けにもなります。文章形式なら必ず長く記憶に残るという意味ではありません。記憶を助けるのは分量そのものではなく、意味のあるつながりです。同じことを長々と繰り返す文書では、文章形式の利点を生かせません。

人にとって、こうした文章を書くことは負担でした。エージェントを使えば、その負担は大きく減ります。同じ資料を渡し、背景と代案、選択の理由をつなげて説明するよう指示すればよいのです。指示する手間は箇条書きと大きく変わりません。ただし文章が長くなれば、生成時間とトークンは増えます。根拠のない部分を、もっともらしい文章で埋めていないかも確認が必要です。

アーキテクチャ提案書や技術導入の検討書、製品要件の背景説明、障害原因の分析文書には、この形式を勧めます。関係者の判断と合意が必要な文書は、文章形式を基本にしましょう。問題と制約、検討した代案、選択した理由、残る論点をつなげて書きます。短い要約や比較表を補助として添えてもよいでしょう。

TL;DRは箇条書きでも文章形式でも役立ちます。箇条書きでは重要な項目を先に示し、必要な情報を探す時間を減らします。文章形式では問題と結論を先に示し、読者が論旨の流れを追いやすくします。読者は要約を見て、今読むべき文書かどうか判断できます。一度読んだ文書の要点を思い出すときにも役立ちます。

文章形式の文書の冒頭に箇条書きの要約を置いても、本来の目的には反しません。要約は読み始めるための手がかりを与え、本文は判断に必要な文脈と根拠を伝えます。この記事の冒頭にあるTL;DRも同じ役割です。ただしレビューが目的なら、要約だけで検討を終えてはいけません。要約で方向をつかみ、本文で前提と根拠を確認しましょう。

同じデプロイ作業でも、両方の形式を使えます。デプロイ戦略を変える提案書は文章形式で書きます。合意した戦略を実行するチェックリストは箇条書きで書きます。提案書は当時の判断の記録として残します。チェックリストは現在の手順に合わせて更新します。文書の寿命と読む目的をそれぞれ決めれば、管理方法も自然に定まります。

結論

開発で文書化が重要だという話は、新しいものではありません。バイブコーディングでは、その重要性がさらに増します。人は開発の初めに目的と制約、完了基準を定めます。開発の終わりには結果と検証の根拠を読み、意図どおりに作られたか判断します。文書は、人が主導する最初と最後の段階の中心にあります。

私は、実装とテスト、デプロイや反復的な整備まで、ますます多くの実行をエージェントが担うようになると考えています。最終的には、文書を通じて意図を定め、結果を判断すること以外の実行は、エージェントの領域へ移るでしょう。だからといって人の責任まで消えるわけではありません。何を作り、どの結果を受け入れるかは、引き続き人が決めます。

すべての文書を永久に管理しようとしてはいけません。必要なコミュニケーションのために、一時的な文書も積極的に作りましょう。継続して使う知識は現在の基準に移します。頻繁に確認する内容は箇条書きで、深く検討する内容は文章形式で書きます。そして必要なときに見つけて読めるようにつなぎましょう。

文書の目的は、結局コミュニケーションです。ソフトウェア開発は、人と人が理解を合わせる仕事です。そこに人とAI、AIとAIの関係が加わりました。実装を任せる範囲が広がるほど、互いに同じ意図で働けるようにすることが重要になります。