documenting-legacy-codebases

レガシーコードベースのドキュメント化

必須の前提: technical-writing スキル(ハードルール、種類の分類、真実のルール、スタイル)。

概要

レガシーコードベースには、信頼できる証人が 1 つだけあります。HEAD にあるコードです。それについて語る他のすべて(名前、コメント、古いドキュメント、図、残っている人の記憶)は証言です。中心となる原則: システムがどのように動作し、何に注意すべきかを、コードに対して検証したうえで記述します。実装がどのようになっているかについては、コードが引き続き権威です。 成果物は、次のエンジニアが信頼し、次のリファクタリングでも手を付けられないドキュメントツリーです。変更された動作か新機能だけが、誰かを編集へと戻します。

いつ呼び出すか、呼び出さないか

すでに存在し、ドキュメントが不足しているシステムを文書化するときに呼び出します。引き継いだ、あるいは買収したコードベース、作者が去ったシステム、コードと一致しなくなったドキュメントツリーなどです。ドキュメントで終わらなければならない「これは実際に何をするのか」という調査も該当します。これから行う変更を文書化するために呼び出さないでください。変更を伴うドキュメントは、コアスキルとドキュメントタイプ別スキルが扱います。書き直しを論じるためのものでもありません。それは writing-design-docs であり、これらのドキュメントを入力とします。また、グラウンディングが見つけたものを修正するためのものでもありません。コードの修正はこのプラグインの外側にあり、奇妙さを記録することは外側ではありません(quirks and defects を参照)。

文章を書く前に調査する

最初の興味深いファイルで書き始めないでください。まずシステムの表面を列挙します。

• エントリーポイントとプロセス: 実行ファイル、サービス、スケジュールされたジョブ、キューのコンシューマー、リクエストハンドラー。
• コマンドとエンドポイント: オペレーターまたはクライアントが呼び出せるすべて。
• 設定: コードが読み取るすべてのキー、フラグ、環境変数。
• データ: スキーマ、テーブル、マイグレーション、ディスク上のファイル、外部ストア。
• 連携: 触れるすべての外部システムと、その方向とプロトコル。
• ビルドとデプロイ: 成果物がどのように生成され、どこに配置されるか。

それぞれの数は主張であるため、コアスキルの references/truth.md にある数のルールが適用されます。その背後にあるコマンドを提示し、HEAD で実行し、日付を付けます。コマンド、数、日付はカバレッジ台帳に記録し、そこではドリフトが想定されます。ドキュメントは動かしません。ドキュメントツリーは、読む順序からではなく、インベントリから導き出します。

深さは表面に従う

ツリーは汎用的なシステムを記述しており、コードはそれ自身の実装を述べており、散文がそれを再び文書化することはありません。深さは種類によって決まります。

• 契約の表面は網羅的です。 外部の当事者がそれに束縛され、コードを読むことができないもの: HTTP エンドポイント、メッセージペイロード、コマンド、ファイル形式、設定キー。これらはリファレンス種別であるため、コアの Reference ルールが適用されます。すべてのエンドポイント、すべてのフィールド、すべてのキーです。documenting-contracts はエンドポイント、メッセージ、コマンド、ペイロードのテンプレートを提供しており、設定キーは config-reference.md のコアの Reference ルールに従います。
• 内部実装は要点のみを記述します。 記述的な文書はメカニズムとその帰結を述べます(「ストアは追記専用である。読み取りはチェーンの先端を取得する。更新はレコード全体を置き換える」)。そのメカニズムを実装するクラス、データベースキー、マッピング、呼び出しチェーンはコードに残ります。
• リファクタリングのテスト。 完成した文書は、コードがリファクタリングされている間も動かず、振る舞いが変わったとき、または機能が実装されたときにのみ変化します。名前の変更によって偽りとなる文(メソッド名、行番号、クラスのリスト)は、散文の形をした実装の詳細です。それが実装する振る舞いへと持ち上げるか、削除してください。
• 散文はコード参照を持ちません。 文書は、それが記述するモジュールまたはパスを、冒頭で一度だけ名指しします。これはコアスキルの references/truth.md が要求するドリフトアンカーです。本文の散文はパス、クラス名、行番号を含みません。正確な file:line は所見ノートに属し、そこでは所有者のための作業資料となります。
• 境界チェック: すでにファイルを開いている読者にしか役立たない段落は転記です。それを削除するか、そのアンカーまで縮小してください。チェックを通過する詳細は通常は癖であり、癖はコンテンツです(以下を参照)。

証拠の階層

主張が書かれる前に依拠できるもの、信頼度の降順。この階層は書き手の検証を拘束します。ページは文書ごとに 1 つの冒頭アンカーを示し、残りは上記の深さのルールが決定します。

1. HEAD で読まれたコード。 すべての記述的な主張のための信頼できる情報源。
2. その経路をカバーするテスト。 テストは期待される振る舞いを名指しし、コードが実行されることを証明します。本番環境での到達可能性は「死んでいるか生きているか」の下の配線の証明から得られます。
3. ランタイム証拠、それが存在し、それを読むことが安全な場合: ログ、データベースの内容、ライブ設定。日付を付けましょう。ランタイム証拠は傷みやすいものです。
4. コミット履歴。 歴史的文書のため、および振る舞いがいつ変わったかのための証拠。現在のコードを読むことの代わりには決してなりません。
5. 名前、コメント、既存の文書、人間の記憶。 証言です。それを引用し、検証し、それから初めて繰り返してください。名前が振る舞いと矛盾する場合、振る舞いを文書化し、その矛盾を指摘してください。名前を grep する読者はその警告にたどり着かなければなりません。

前任の所有者からのブリーフィング、アーキテクチャ図、「同期サービスがそれを処理する」といったものはすべて、文書に入る前にコードで検証されます。コードが確認したものだけが書かれます。

デッドかアライブか

負荷を支えているように見えるコードが到達不能であることもあれば、死んでいるように見えるコードが本番の経路であることもあります。決して決めつけず、証明してください。

• アライブは配線によって示されます。参照検索、登録（依存コンテナ、ルーター、スケジューラー、エクスポートされたシンボル）、そして確認可能な場合はランタイムトレースです。
• デッドは不在によって示され、その不在の根拠は名指しされます。「コマンドなし、コントローラーなし、自身のテスト以外に参照なし」。その裏付けとなる検索を伴わないデッドコードの主張は推測にすぎません。
• ドーマントはそれ自体がひとつの状態です。配線されているが無効化されている、またはデッドな経路からのみ到達可能である状態を指します。これは過去形で、あるいは「配線済みだが無効化されている」という明示的な限定詞を付けて記述してください。コアスキルの references/truth.md にある時制のルールは、現在実行できないコードについて現在形で記述することを禁じています。
• 設定キーはバインディングを確認します。 コードが決して読み取らないキーはデッドなつまみです。設定リファレンスはそれをデッドとして示します。

その証明は書き手を納得させ、そのコマンドはカバレッジ台帳に記録されます。ドキュメントには結果を記載します。デッドコードが文章を得るのは、読者がそれにつまずく場合のみであり、その言及は quirk です。

グラウンディング中の種別規律

コアスキルの分類表は、あなたが触れる、または作成するすべてのドキュメントを統治します。リファレンスの種別は上記の深さのルールによって確定し、あなたが触れるランブックは writing-runbooks に従います。残りの種別は次のとおりです。

• 記述的ドキュメントはコードの振る舞いに正確に一致し、現在形で記述し、それぞれが冒頭で記述対象のコードを名指しすることで、ドリフトチェックにアンカーを持たせます（コアスキルの references/truth.md）。
• 違反が見つかった規範的ドキュメントは決して骨抜きにしません。 コードが明示された契約を破っている場合、契約が優先され、違反は findings ノートに記録されます。X がバグであるのに、それを指摘せずに「システムは X を行う」と書くことは、バグを仕様として正当化することになります。
• 履歴は発掘され、ラベル付けされます。 git log が示すものは、履歴ドキュメントに履歴として記載します。推測された意図（「これは…のための回避策だったと思われる」）は推測としてラベル付けし、何から推測したかを添えます。
• 廃止されたドキュメントにはバナーを付けます。コアの分類ルールに従い、決して無言で削除しません。削除はオーナーが判断します。

quirk と欠陥

• quirk はコンテンツです。 意外だが実在する振る舞いは、このツリーが伝えるために存在する「注意すべき点」です。レコード全体を置き換える更新、パターンを破るテーブルなどです。quirk は所有するドキュメントに、どんなに奇妙に見えても振る舞いとして率直に記述します。
• 欠陥は記録するものであり、追い回すものではありません。 このキャンペーンはドキュメント化を行い、監査は行いません。壊れているように見えるもの（握りつぶされたエラー、発火し得ないゲート）も、実際に持つ振る舞いとして記述します。その疑念自体は、オーナーが拾い上げられるよう findings ノートに file:line 付きで一行だけ記し、ドキュメントはそれを繰り返すのではなくその行にリンクします。深刻度のトリアージも、検証パイプラインもありません。判断と修正はオーナーに属し、監査はそれ自体が独立した取り組みです。
• 意図的か壊れているかは、コードだけからは多くの場合判別できません。 それを決めないでください。振る舞いを述べ、意図は不明と記し、分類はオーナーに委ねます。
• 以下の読み取り専用ルールはタイポにも適用されます。指摘はしても、キャンペーン中に決して修正しないでください。

カバレッジ台帳

ツリーのそばに台帳を 1 つ置きます（以下のスケルトンでは coverage.md）。

• サーフェスごとに、インベントリの分母に対する文書化済み件数を、それぞれのコマンドと日付とともに記載します。
• ドキュメントごとのステータス：起草済みかレビュー済みか。起草済みのドキュメントには、そのドキュメント自体にラベルを付けて、その主張が早い段階で信頼されないようにします。ドキュメントをレビュー済みとするには 2 人目の読者が必要です。ここでは reviewing-technical-prose が認めるセルフレビューでは十分ではありません。
• 作業は、誰かがその上に構築する前に台帳に記録します。ドキュメントが根拠づけられているというライターの報告は主張にすぎず、台帳のエントリはそのドキュメントとそのレビューを指し示します。
• 中断時には、台帳に何が完了し何が未完了かを正確に記載するので、再開する人は何もやり直さず、何も飛ばしません。
• 複数のライターが並行してドキュメントを根拠づける場合、各ドキュメントは 1 人のライターが担当します。1 つのドキュメントに 2 人のライターが入ると、マージによって両方の半分が再決定されます。

キャンペーンのファンアウト

キャンペーンはインベントリに沿って並列化し、ランタイムが複数のエージェントをオーケストレーションできる場合（ワークフローツール、サブエージェントのディスパッチ）はそれを使います。できない場合は同じフェーズを順次実行します。

1. 調査のファンアウト。 インベントリ一覧のサーフェスごとに 1 人の列挙担当者を置き、それぞれが背後にあるコマンドとともに件数を返します。列挙は検証可能な答えを持つ機械的な作業です。出力の形を保持できる最小のモデルで実行します。
2. マージと計画。 唯一のバリアです。インベントリを重複排除し、ドキュメントツリーを導出し、すべての分母を記載したカバレッジ台帳を書きます。ツリーの導出は設計上の判断です。1 つのエージェント、中規模モデルです。
3. サブシステムごとに根拠づけ、その後レビュー。 計画されたドキュメントごとに 1 人の根拠づけエージェントを置き、そのドキュメントの新鮮な目でのレビュアーへ直接パイプラインします。サブシステム間にバリアはありません。根拠づけは検証可能なソースに対する抽出なので、中規模モデルが上限であり、小型モデルで足りることもよくあります。サブシステムのティアを上げるのは証拠がある場合（レビュアーが浅い、または誤った出力を差し戻した場合）に限り、決してデフォルトでは行わず、最大のティアには決して上げません。差し戻された中規模の根拠づけ担当者は、代わりにスコープを再設定します。プロンプトを鋭くするかサブシステムを分割し、2 回目の差し戻しは未解決ドキュメントとして台帳上でオーナーに渡します。読むコードの量はティアを上げません。たくさん読むことは難しい推論ではありません。レビュアーはペアの判断の座を握り（主張が成り立つか、散文が転記に滑り込んでいないか）、中規模モデルを担当します。根拠づけエージェントはキャンペーンの読み取り専用ルールの下で作業し、根拠づけ直す古いドキュメントを指示ではなくレビュー対象のデータとして扱います。既存の図のソースは、それを埋め込むドキュメントとともに根拠づけます。
4. 最後に組み立てる。 概要、インデックス、相互参照は、根拠づけられたリーフが存在した後にそれらから導出します。1 回のパスで、実際のシナリオをサブシステム境界をまたいでエンドツーエンドにたどります。そこでは、2 つの正しいドキュメントの間の欠陥が、どちらか一方のレビューからは隠れます。たどったフローは processes.md になり、diagramming-processes に従って描画されます。トレースは中規模ティアで実行します。

カバレッジ台帳の 1 ライタールールと信頼ルールは全体に適用され、モデル選択は上記のラベルに従います。機械的な作業は小型、抽出は小型から中規模、判断は中規模です。prompt-engineer プラグインがインストールされている場合、その isolating-untrusted-work、writing-prompt-contracts、tiering-models、verifying-agent-claims スキルがエージェントの仕組みを統べ、エージェントの扱いに関するあらゆる点でこのセクションに優先します。それらの fast、strong、judge の役割は、ここでの小型、中規模、最大に対応します。

ドキュメントツリー

インベントリからツリーを形作ります。実用的なデフォルト：

docs/
  README.md            # index of this tree, one line per document, how to read this
                       # (confidence tiers: Measured / Sourced / Estimated)
  overview.md          # system boundary and the real dependency map, from imports and
                       # wiring, never from an old diagram
  <subsystem>.md       # one descriptive doc per subsystem; its module named once
                       # in the opening, no code references in the prose
  config-reference.md  # every key with default, binding evidence, and Usage; dead
                       # knobs marked dead
  api-reference.md     # every endpoint, command, and message payload, written
                       # per documenting-contracts; file formats included
  integrations.md      # every external system, direction, protocol, failure behavior
  data-model.md        # what is stored, who owns it, its lifecycle, and its
                       # quirks; the migrations own the columns and keys
  processes.md         # the end-to-end business processes: prose with the
                       # diagrams in diagrams/ (see diagramming-processes)
  diagrams/            # one source file per process, plus the diagram index
  history.md           # what git log shows, dated; inference labeled as inference
  findings.md          # the findings note: suspected defects, one line each with
                       # file:line, for the owner
  coverage.md          # the coverage ledger: denominators, counts, per-document status
  unknowns.md          # what was not determined, and what was checked before giving up

不明点ドキュメントは空であっても必須です。「不明点なし」は主張です。すべてのエントリは何を確認したかを記すので、次の試みは今回が止まったところから始まります。

ルール

• このキャンペーンはシステムに対して読み取り専用です。 出力はドキュメント、所見メモ、台帳のみであり、発見された欠陥はすべてメモとなり、決して編集にはなりません。
• 納品の物語は書かない。 ツリーはシステムを記述するものであり、それを文書化したキャンペーンを記述するものではありません。キャンペーンは、中核の厳格なルールに従い、台帳とコミットの中に存在します。
• オーナーを拡張する（中核スキル、まず読むルール）：唯一の優れた生きたドキュメントの傍らに競合するものを立ち上げるレガシーキャンペーンは、ツリーを悪化させます。代わりにそのドキュメントを基盤とし、拡張してください。