docs-cleaner

Docs Cleaner

ドキュメントでは同じ問題が繰り返し発生しますが、それぞれに異なる対応が必要です。

内容が古くなります。 ポート、パス、手順、決定事項などが変更されても、ドキュメントには古い情報が残ったままです。この状態は、現場では documentation rot または version drift と呼ばれます。成果物が一つずつ実態と合わなくなり、やがて人々は一式のドキュメントを信頼しなくなります。

増殖します。 同じトピックについて一部は正しいものの、どれも正式な情報源とは言えないファイルが三つも蓄積します。

根本原因は共通しています。事実が、定義された場所より多くの場所に書き記されていたことです。 以下のすべては、この問題の修正に基づいています。

中核原則（両方のモードに適用）

削除の前に、必ず慎重に評価してください。決して無条件に削除しないでください。 削除を提案する前に、各セクション独自の価値を分析します。目標は、情報を失わずに減らすことです。

この原則は、統合だけでなく、このスキルにおける削除に関わるすべての作業に適用されます。ドキュメントのアーカイブ、派生値の削除、相互参照の削除は、いずれも削除であり、まず同じ分析が必要です。「重複しているように見えた」は、その分析にはなりません。

どちらのモードですか？

ユーザーの発言／状況	モード
「Xを変更しました」／差分がある／手順を更新した	1 — 変更後のガバナンス
「どのドキュメントが間違っているか」、「古いコマンドやパスを確認して」	1 — 変更後のガバナンス
「ドキュメントを整理して」、「この件のファイルが多すぎる」、「これらを統合して」	2 — 統合
明確な管理者がいないまま、トピックが複数のファイルに分散している	2 — 統合

どちらのモードでも、以下のドリフトテストを行います。両方に当てはまる場合は、まずモード1を実行してください。事実がすでに古くなっているドキュメントを統合すると、自信をもって誤りを伝えるドキュメントが一つできるだけです。

CLAUDE.md／AGENTS.mdについて： どちらのモードでも、他のドキュメントと同じように扱います。変更後はガバナンスを行い、互いに内容が重複している場合は統合します。別の場所で行うべき作業は、サイズが大きすぎる単一ファイルの再構成です。トップレベルを簡潔に保ちながら、使用頻度の低い詳細を参照資料に移します。これは、daymade-claude-codeのclaude-md-progressive-disclosurerスキルが想定している作業です。問題が正確性や重複ではなく、サイズと階層化にある場合は、そちらを優先してください。利用できない場合でも、モード2でファイルを扱えます。その場合は、価値の分析を手作業で行ってください。

---

ドリフトテスト（両モードの中核）

ドキュメントに値を書き込む前に、また既存の値を残す価値があるか判断するときに、次の質問を順番に問い、最初に該当した時点で止めてください。

1. ここにすでに記録されている詳細、または信頼できる情報源から算出できますか？ → それは派生値です。書き込まないでください。誰かに尋ねられたときに計算します。 例：「6 セクション」「対象となる N 個のグループ」といった数、合計、下にある表の行を要約したステータス、ログの下にすでに記載がある場合の「最終更新日」。

値を削除したら、文に穴を残さず修正してください。「下記の 4 つのチェック項目」は「下記のチェック項目」にします。数字を削除して文法が崩れたままにするのは、修正ではなく別の不具合です。

例外 — 生成されるナビゲーション。 見出しを繰り返す目次はこのテストでは派生値であり、手作業で管理されているものは削除すべきです。ただし、ドキュメントツールチェーンによってビルド時に生成される場合や、プラットフォームでナビゲーションを表示するためにマーカーが必要な場合は、そのまま残してください。そうしたものはオンデマンドで計算されるため、質問 1 の条件に当てはまります。削除する前に、生成ツールが使われているか確認してください。

2. 算出できないものの、同じ事実がほかの場所で正式に定義されていますか？ → それは複製です。その定義へのリンクを貼ってください。値を繰り返し記載しないでください。

3. 派生値でも複製でもなく、特定の時点で何が事実だったかを独立して記録していますか？ → 日付付きの変更、当時の測定値、価格の記録、意思決定など、独立した履歴上の観測値として残してもかまいません。過去の値を現在の値や現在の設定へのリンクに置き換えてはいけません。

変更履歴、事後分析、日付付きメモの中にある記述も含め、個々の主張にこの順序でテストを適用してください。日付が付いていても、ローカルに算出できる合計や比率、複製された要約が質問 1 と 2 の対象外になるわけではありません。独立した出来事、測定値、因果関係の文脈は残したまま、派生値または複製された記述を削除してください。

たとえば、日付付きのアップロード上限の変更は、その時点での変更を記録しています。今日の設定は別の事実です。地域追加の出来事を残しつつ、記録された当時の地域情報から算出できる合計は削除します。その過去の合計を、今日の地域を使って再計算しないでください。

質問 1 と 2 に当てはまらない、唯一無二の履歴上の記録は、ドリフト修正の対象ではありません。その内容の価値については、既存の承認範囲内でモード 2 の分析を行います。ある主張が派生値、複製、独立した観測値のどれに当たるかを証拠から判断できない場合は、未解決のまま残し、問題を報告してください。削除の根拠を推測してはいけません。新たな承認が必要なのは、実行しようとすることがすでに与えられた承認範囲を超える場合だけです。

リンクで解決できるのはケース 2 だけです。 派生値へのリンクは、分類を誤っています。リンク先となる唯一の信頼できるセルが存在しないため、そのリンクはそれ自体が古くなる足場となり、さらに、2 つの場所が一致しているという誤った印象を生みます。

この順序が重要な理由： API ドキュメントのドリフトに対する成熟した答えは、「手作業で複製せず、情報源から生成する」です（OpenAPI／Swagger はまさにこのために存在します）。質問 1 は、同じ考え方を文章に当てはめたものです。数値を正しく保つ最も確実な方法は、その数値を二度書かないことです。

配置場所は例外になりません

事実は、どこに記載されていても事実です。以下はすべて、上記のテストでは本文として扱います。また、監査後も古い値が実際に残っているのは、まさにこうした箇所です。

フロントマター · YAML／JSON メタデータ · 括弧内の補足 · インデックス表の説明列 · チェックボックスの状態 · 本題に入る前の導入的な説明 · ドキュメントをまたぐ脚注 · 表に追加された列 · 文章中に残されたコミットメッセージ風のメモ

事実に該当するもの

時間とともに変化し、どこかに信頼できる定義があるものはすべて該当します。数値、 ステータス、所有権、関係、分類、ルール、判断の根拠、日付、件数などです。 ビジネスルールも該当します。「すべての見積もりは財務責任者を経由する」というルールは一度定義し、 下流の各ドキュメントで繰り返すのではなく、参照します。

---

モード 1 — 変更後のガバナンス

以下を順番に実行します。この順序が重要です。何が信頼できる情報源なのかを確立する前に派生ドキュメントを 修正すると、作業が単に増えるだけです。

1. リポジトリではなく、変更内容から範囲を定めます。 この変更で変わった事実を列挙します。このポート、このパス、この手順名、 このデフォルト値などです。このリストが作業の範囲を定めます。リストの範囲は限定しますが、各項目の検索範囲は 限定しません。事実の目立たないコピーは、変更対象にならなかったファイルにこそ存在するため、手順 5 では各事実をリポジトリ全体で検索します。禁止されているのは別のことです。無関係な問題を探すためにファイルを開くことです。範囲を定めない総ざらいは、ドキュメント作業をレビュー不能なリファクタリングに変えてしまいます。

2. 影響を受ける各事実の信頼できる情報源（SSOT）を特定します。 このポート／パス／手順に言及しているのではなく、定義しているファイルはどれでしょうか。まずそれを更新します。それ以降のものは、すべてそのファイルを参照するか、そこから派生します。

手順が Skill エントリからリファレンスへ移動する場合は、それを利用する CLAUDE.md / AGENTS.md のポインターもこの範囲に含めます。 delivery-entry replay を使って、移動先が実際の手順の目的地であることを踏まえ、変更前と修正後のナビゲーションを確認します。到達できるだけでは、その移動先が必要な手順を引き続き定義していることの証明にはなりません。

「定義している」かどうかを判断する実務的な基準は、現実を変えるにはどこを変更しなければならないかです。デプロイ時に実際に読み込まれるファイル、コードが読み込むスキーマ、人が手順どおりに実行するランブックなどが該当します。別のことを説明しながら値を繰り返すファイルは、その値に言及しているだけです。宣言的に見えるファイルが 2 つある場合は、次の順で優先します。人だけが読むファイルより機械が読み込むファイル、記述対象により近いファイル、他のドキュメントからすでに参照されているファイルです。そのうえで、どれを選び、どの根拠に基づいたのかをレポートに記載します。手順 2 で他のすべてをそこに紐づけると、恣意的な選択が恒久化してしまうため、最初に開いたファイルがたまたまそうだったという事故ではなく、明示した判断にする必要があります。

3. 確立された意図と承認に基づき、実装の不一致を解消します。 コード、スクリプト、設定、観察された実行結果は、現在の動作を示す証拠として扱い、意図された動作を自動的に決定する権威としては扱いません。要件、信頼できる情報源、またはテストによって意図された動作が確立されており、ユーザーが対象範囲内の実装修正をすでに承認している場合は、まず実装を修正して検証し、その後でドキュメントを実装に合わせて更新します。その修正は、タスクですでに承認されている事実とファイルの範囲内にとどめます。

意図された動作が曖昧な場合、または実装の変更がまだ承認されていない場合は、不一致を報告し、不足している判断または承認を得てからコードを編集します。望ましいだけの動作をドキュメントに記載したり、ドキュメントの確認作業をひそかに実装プロジェクトへ変えたりしないでください。

4. 編集前に、影響を受ける各ドキュメントの扱いを決めます。

ドキュメントの状態	対応
引き続き実用可能で、特定の事実だけが古くなっている	更新
前提がもはや成り立たない	アーカイブ／廃止

前提が失われたドキュメントにパッチを当てないでください。内部的には整合していても全体として誤ったものになり、明らかに古いファイルより見つけにくくなります。本文中に「このセクションは置き換えられました」という注記を残すのも、第三の選択肢ではありません。保守担当者向けの記録を読者の導線に置くべきではありません。読者にはそれを理解するための背景がなく、混乱するだけです。外へ移してください。 「アーカイブ」とは、読者の目に触れる場所から外しつつ、履歴には残すことです。 具体的には、プロジェクトですでに使われている規約（_archive/、archive/、deprecated/ など）を探して、それに従ってください。該当するものがなければ、そのファイルと同じ階層に _archive/ を作成します。どちらの場合も、履歴が引き継がれるように git mv で移動し、すべての参照元を付け替えるか削除してください。完全に削除してはいけません。 また、読者がまだ見つけられる場所にファイルを残したまま、フロントマターに status: deprecated を追加するだけで済ませてはいけません。廃止されたドキュメントが読者の目に触れる場所に残っているなら、今も読まれています。

同じ理由から、Phase 4 のステップ 3 で合意が必要なのと同様に、自分が作成していないものをアーカイブする前に確認してください。確認せずに実行する必要があり、確認できない場合：ドキュメントには手を加えず、廃止が必要なものとして報告してください。 代わりに修正するのもやめてください。前提が崩れたドキュメントは、事実を更新すると、誤解を招く度合いが増すだけです。

5. 変更する事実のコピーをすべて見つけてから、変更してください。 これは省略されがちなステップで、よくある失敗が起きるのもここです。目につく箇所は更新しても、ひっそり残った 3 つの箇所は更新されません。正確なコマンドについては、以下の 検証 を参照してください。

最もリスクが高いのは、項目の番号を振り直したり、項目を途中に挿入したりすることです。変更するのは 1 つの事実ではなく、相互に参照し合う情報のまとまりだからです。本文中の「ステップ 7 を参照してください」という記述、関連ファイル内の相互参照、そして最も厄介な、数を文に埋め込んだ表現（「以下の 4 つの確認項目」など）があります。最後の表現には検索対象となる数字が含まれないため、ステップ番号で検索しても見つかりません。

この作業に機械的な一括検索手段はなく、あるかのように扱うべきではありません。 代表的な 2 つの検索範囲を実測しましたが、どちらも失敗します。

• リポジトリ全体で数を表す語を検索する → 実際のドキュメントリポジトリでは 224,330 行／約 550 MB（単一プロジェクトディレクトリに範囲を絞っても 17.7 MB）。誰も実行しません。確実に無視される指示は、指示がないより悪いものです。
• 対象に言及しているファイルだけで数を表す語を検索する → 範囲は限定されますが、重要な点で的外れです。数を文に埋め込んだ表現は、まさに対象を別名、翻訳、代名詞、または単独のリンクで指し、タイトルでは言及しない表現です。「以下の 4 つの確認項目」、「预检有四个检查」のようなものです。実際に測定したところ、古い数を含むファイルで、対象名やファイル名を検索しても一致は ゼロ でした。この絞り込み方法では、目的の対象ほど見つかりにくくなります。

そこで、代わりに次の手順を実行し、対象外となるものも報告してください。

1. 番号を振り直したファイルを、最初から最後まで読みます。 古い自己参照の多くは、このファイル内にあります。

2. ファイル一覧を作成してから、その一覧内で数を表す語を検索します。 Mode 1 のこれ以前の手順では、この一覧は作成されていません。参照の更新 にある、参照元の検索を使おうとしないでください。これは Mode 2 の手順で、別の問い（「このファイルを参照していたものは何か」であって、「この対象について述べているものは何か」ではない）に答えるものです。ここで作成してください。

   ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || { echo "not in a git repo — pass the docs root explicitly" >&2; exit 1; }
   rg -l -F "<the subject's name>" "$ROOT" --no-ignore --hidden -g '!.git'
   

   これにより対象を明示的に記載しているファイルがわかります。明示的に記載していないファイルについては、ステップ 3 で確認します。対象は少数なので、リストを xargs に渡すのではなく、ファイル名を直接指定してください。リストが空の場合、GNU xargs は検索コマンドにパスを渡さずに実行するため、代わりにカレントディレクトリが検索されます。これは範囲が違うのに、出力があるように見えてしまいます。

   rg -n -i -H \
     -e '\b(one|two|three|four|five|six|seven|eight|nine|ten|both) [a-z]+\b' \
     -e '[一二三四五六七八九十两](个|条|步|项|点)' -e '[0-9]+(个|条|步|项|点)' \
     -e '\b[0-9]+ [a-z]+\b' \
     path/to/one.md path/to/two.md
   

   2 つの細かな点があります。どちらも実測に基づいています。ファイルが 1 つだけ指定された場合に rg がファイル名を省略するため、-H を付けます。また、ここでの答えとして必要なのは「どのファイルか」だけです。さらに、このパターンでは名詞のリストではなく、その後に続く任意の単語を対象にしています。リストにはプロジェクトで使われている名詞（「4 つのゲート」、「3 つのレーン」など）が含まれない可能性があり、見落としても気づけないためです。数個のファイルを検索する際、余分な結果は大した問題ではありませんが、該当行の見落としは問題です。

3. 対象の別名を自分で列挙して検索し、見つかったものの中で数を表す語を検索します。 この作業を代わりに行えるツールはありません。 次に、何を確認したかを述べてください: 「番号を振り直したファイルを読み、名前でそれを参照している N 個のファイルで count という単語を検索しました。他の名前でそれを参照している散文は機械的にカバーされていません。」 この一文は、上の 2 つの失敗のどちらかを暗に意味する緑のチェックマークより価値があります。

6. 途中で出会った派生値はクリーンアップする — ただし、すでに編集していたファイル内でのみ。 開いているファイル内の古い件数を削除するのは衛生管理であり、スコープクリープではありません。さらに探すために無関係なファイルを開くのはスコープクリープです。この境界が、これをレビュー可能な変更に保つのです。

7. 行ったことを報告する — What to report の下の構成に従ってください。

---

モード 2 — 統合

価値のある内容をすべて保持しながら、冗長なドキュメントを統合します。このモードのすべての削除は、上記の 中核原則 に従います。

フェーズ 1: 発見

1. そのトピックを扱っているすべてのドキュメントファイルを特定し、検索する前に、検索した範囲（ディレクトリ、スイート、1 つのプロジェクト）を明示してください — モード 1 のステップ 1 が使うのと同じ範囲限定ルールです。「ドキュメント」だけを与えられて範囲を指定されなかった 2 つのエージェントは、異なるファイルセットを統合します。その範囲内でのトピックキーワードの一括検索が通常の方法です — -F に注意してください。C++、.NET、v1.0.0 のようなトピック用語はリテラルであり、パターンとしてはほとんどすべてに一致してしまうからです: rg -l -i -F -e '<topic term>' -e '<synonym>' <boundary> --no-ignore --hidden -g '!.git' このリストが統合全体の範囲を定めるため、ゴミのようなリストはゴミのような分析を意味します。
2. ファイル全体の総行数を数える — ステップ 1 のリストに対して wc -l
3. 内容の重複をマッピングする: 各ファイルの各見出しについて、同じ領域を扱っている他のファイルを記録します。成果物は、見出し → それを同様に扱っているファイルの表です。複数のファイルに現れるセクションが統合の候補です。このステップでは 重複のみ を判断します — 保持するか削除するかは判断しません。一意のセクションであっても、重複とは無関係な理由（自明、時代遅れ、副産物）でフェーズ 2 において削除されることがあります。したがって、これは 「ここには、一意のセクションを冗長として削除することを正当化するものは何もない」 と読むべきであり、「一意とはそれが生き残ることを意味する」 と読むべきではありません。

フェーズ 2：価値分析

各ドキュメントについて、セクションごとの表を作成します。

セクション	行数	価値	理由
API リファレンス	25	維持	独自のエンドポイントドキュメント
セットアップ手順	40	簡潔化	冗長ですが不可欠です
環境変数の表	30	削除	正式な情報源である README.md の表と重複しています

削除の例では、正本となる重複情報を示しています。履歴に関する主張にも同じ順序でドリフトテストを適用します。過去の出来事と現在の設定は、必ずしも同じ事実ではありません。

• 維持 — 独自性があり、不可欠で、頻繁に参照されるもの

• 簡潔化 — 価値はあるものの冗長なもの

• 削除 — 重複、一度限り、自明、または古くなったもの

• アーカイブ — 前提がすでに消滅したドキュメント全体（中止されたシステムの設計メモや、廃止されたサービスの事後分析など）。修正すべき古い現状情報でも、削除すべき重複コンテンツでもありません。このカテゴリがないと、「後継に置き換えられた」と「記録として残すべき」が同じドキュメントを正反対の方向へ引っ張り、最後に読んだ意見が勝ってしまいます。

  稼働中のドキュメント内にある、前提が消滅したセクションも、一段下のレベルで同じ問題です。ただし、アーカイブの対象にはなりません。アーカイブはドキュメント全体に適用されるものとして定義されています。そのセクションは、理由を「前提の消滅」とする削除として扱い、自分だけで判断せず、フェーズ 3 の計画に明記してください。「中止された移行に関する Kafka 移行セクション」は、オーナーが「実際にはまだ参照しています」と答える可能性のある、まさにその種の判断です。

  **アーカイブという判定により、そのドキュメントはこの統合の対象から外れます。**フェーズ 3 やフェーズ 4 には進みません。統合するものも、簡潔化するものもないためです。モード 1 のアーカイブ手順、つまり モード 1 — 変更後のガバナンス にある「『アーカイブ』とは、読者の目には触れないようにしつつ、履歴には残すこと」という段落に従って処理し、報告書にはその処理を行ったことを記載して、残りの統合を続けてください。フェーズ 3 の行数計画にも含めないでください。元の状態のまま残るため、その行数を「削減」として数えると、実際には達成していない削減を計上することになります。

作業を進めながらすべての行にドリフトテストを適用し、次の両方向でカテゴリの判定を上書きしてください。

• 他の情報から算出できる値を言い換えているだけのセクションは、どれほど読みやすく書かれていても削除です（質問 1）。
• 履歴セクションでも、主張ごとに質問 1 と 2 を適用します。ローカルで算出できる集計値や、コピーされた言い換えは削除できます。独立した個別の観測事項は、質問 3 に基づいて残せる場合があります。独自の歴史的事実の削除を提案する場合は、価値分析に明記し、既存の承認に従ってください。古いことや「一度限りの記録」であることだけを理由に削除してはいけません。

詳細な基準：references/value_analysis_template.md。

フェーズ 3：統合計画

実際の数値を使って目標の構成を提案し、合意を得てください。フェーズ 4 で削除を始める前に承認を得るよう求められているのは、この計画です。

Before: 726 lines (3 files, high redundancy)
After:  ~100 lines (1 file + a pointer from the project's main doc)
Value preserved: pending — established by the preservation check after execution

変更前後の行数は、提案する構成を示す数値です。「保持された内容の割合」はそうではありません。計画の段階で割合を示すと、削除する側が自分の削除に問題はなかったと主張することになります。これは、このスキルが取り除こうとしている自己証明の形です。

この値はフェーズ 4 の手順 7 の後に記入します。また、パーセンテージではありません。パーセンテージを出すには、分母を作り出さなければならないからです。明示した分母に対する件数として示します。たとえば、「手順 1 のインベントリにある 34 項目すべてが残った」、または *「34 項目中 31 項目」*とし、抜けた項目とそれぞれの移動先を明記します。

分母に含めるのは、Keep と Condense の項目だけです。 手順 1 のインベントリは、意図的に Delete セクションの項目も対象としています。それらの項目は、統合後のファイルに含まれないことが想定されています。これらまで分母に含めると、そもそも「すべて残った」という結果を出せなくなり、達成不可能な目標は人が目指さなくなります。Delete セクションの項目は、独立した行で説明します。*「さらに、Delete セクションから 6 項目。それぞれ、複製した内容の残存先、または削除する理由を明記」とします。2 つの数値で、2 つの問いに答え、どちらも他方に隠れません。判定結果だけでなく分母も書いてください。「確認した項目はすべて残った」*は、1 項目でも 34 項目でも真になるため、文書の行方ではなく、確認の徹底度しか示しません。すべてに満たない場合は、報告すべき発見事項です。決して数値を切り上げてはならず、報告をよく見せるために自分の統合作業を取り消す理由にもなりません。

フェーズ 4：実行

git で元に戻せるとしても、読者の側から見れば、誰かのドキュメントを削除することは取り消せません。手順 3 の前にフェーズ 3 の計画を提示し、合意を得てください。 フェーズ 3 で「提案」としているのには理由があります。コア原則が定めるのは分析の慎重さであって、作業を実行する権限の有無ではありません。無人で実行していて確認できない場合は、手順 1～2 を行い、停止して、削除する予定だった内容を報告してください。

1. 統合ドキュメントを 1 行でも書く前に、保持の根拠を抽出してください。 この順序が、確認に意味を持たせます。書き換え後に主張のリストを書くと、たまたま引き継いだ内容のリストになり、必ず書き換え結果と一致してしまいます。書き換え前に作れば、書き換え後に満たすべき仕様になります。

   何がそれを担保するのか、正直に考えてください。完成した成果物だけでは、先に書かれたリストと後から作られたリストを見分けられません。つまり、これはゲートではなく慣例です。利用できる唯一の実効性を持たせてください。手順 2 を始める前に、レポートか一時ファイルにリストを出力します。 書き換え前に文書化されたリストなら、それと照らし合わせて確認できます。書き換え後に現れたリストは、結果を書き写したものと区別できません。

   単位はセクションごとでもカテゴリごとでもなく、重要な項目ごとに 1 件です。 どこまで細分化するかは判断に委ねられ、慎重なエージェント 2 つでも異なる件数になるでしょう。それは許容できます。許容できないのは、大まかにまとめたときにどの条項が欠落するかです。そのため、数え方にかかわらず、次の 2 つはそれぞれ独立した項目にしてください。

   • 結果を示す条項。 「再試行する前にロールバックする」は指示です。「半端に適用されたマイグレーションで再試行すると events テーブルが破損し、自動で修復する方法はない」は、その指示に従うべき理由です。大まかなリストでは指示だけが残り、その結果に関する部分が落ちます。ざっと読むだけで見落とされるのは、まさにその部分です。
   • 症状 → 原因の対応関係。 「デプロイ手順で 401 が発生した場合、原因はトークンの期限切れであり、アカウントの誤りではない」は、「トークンの有効期限は 90 日ごとに切れる」から再導出できません。これはトラブルシューティングの情報です。1 行で済むため、真っ先に消えてしまいます。 この2つは最低限であり、重要なことのすべてではありません。 ここに挙げているのは、粗いリストから最も確実に抜け落ちる節だからであり、これら以外の節なら問題ないという意味ではありません。見落とされやすく、手作業で確認する価値のあるものが3つあります。順序の制約（「ワーカーを再起動する前にマイグレーションを適用する」――結果が明記されていないため、最初のルールでは拾えません）、適用範囲を限定する条件（「これはstagingクラスターにのみ適用される」）、文章に埋め込まれたしきい値（「最大5回までバックオフする」）。それぞれ1つの節に収まり、読み手の行動を変えますが、どれも目立つ形では示されません。

   Deleteとマークされたものも含め、すべてのセクションに目を通し、元の資料から次の内容を書き出してください。

   • Keep → 各項目について、特徴的な原文を1行ずつ（各注意点、各制約、各スニペットを記載します。注意点が3つあるセクションなら、1行ではなく3行必要です）
   • Condense → 重要な主張をすべて記載します。すべての制約、数値、条件、警告が対象です
   • 重複として削除 → その中の項目と、それぞれについて残すコピーの場所。 ここは最も省略されやすく、最悪の失敗を見つける工程です。フェーズ1では見出しを基準に重複を対応付けるため、見出しを見て重複と判断されたセクションに、ほかのファイルにはない注意点が1つ含まれていることがあります。項目一覧を作らなければ、その注意点は以降の確認すべてで見えなくなります。そもそも一覧に載っていないため、ステップ7では「すべての項目が引き継がれた」と報告され、それが文字どおりの意味になります。
   • ほかの理由で削除 → その中の項目と、それぞれを削除する理由。理由を言える削除は判断ですが、理由を言えない削除は、まだ気づいていない事故です。
   • 上記すべて → URLはすべて原文のまま記載します

   この一覧でできることと、できないこと。 これは想起の失敗、つまり引き継ぐつもりだったものを引き継げなかったケースを見つけます。判断の失敗は見つけられません。フェーズ2で何かを重要でないと判断した場合、それは一覧に載らず、ステップ7はそれがなくても問題なく通ります。この見落としは実在し、この手順では埋められません。 フェーズ3の計画は人間に渡されますが、含まれるのは移行先の構成と行数であり、この一覧ではありません。そのため、判断を誤った項目も検出できません。これは成果物の形を確認するものであり、何が取り込まれたかを確認するものではありません。ステップ7を通過したことを、価値あるものが何も失われなかった証拠として報告しないでください。報告できるのは、特定したすべての項目が引き継がれたことを確認した、という事実だけです。判断もレビューしてほしい場合、その項目一覧を作成者以外に見せるしかありません。

   続ける前に、妥当性を確認してください。項目数は元の資料の分量に見合っていますか？ 3ページの運用手順書から項目が4つしか出てこないなら、読み飛ばしています。薄い一覧こそ、後でそのまま確認を通過してしまう一覧です。

2. その一覧の項目をすべて含めて、統合ドキュメントを作成する

3. 重複するソースファイルを削除する

4. それらへの参照をすべて更新する（CLAUDE.md／プロジェクトのメインドキュメント、README、インポート）

5. メインドキュメントまたはREADMEに、新しい場所へのポインターを残してください。なければ作成します。統合すると内容は、まだ参照先がない場所に移ります。この工程がなければ、作業者以外には見つけられません。

6. リンク切れがないことを確認する（下記の参照の更新を参照してください。ファイル名だけをgrepしても不十分です）

7. 完了とする前に、ステップ1の一覧を使って、下記の保持チェックを実行してください。 これはこのフェーズの必須条件であり、省略可能な付録ではありません。 手順 1 を飛ばし、ソースが Git で追跡されていた場合でも、復元できます — ただし、どの ref を使うかに注意してください。削除がコミットされる前は、内容は git show HEAD:<path> にあります。コミットされた後は、そのパスは HEAD に存在しないため、 git show HEAD~1:<path>（または削除前のコミット）が必要です。パスは リポジトリのルートからの相対パスなので、サブディレクトリからは git show HEAD:./<path> を使います。間違った形式はどちらも fatal: path ... does not exist というエラーになるため、すぐにわかります。絶対に してはいけないのは、統合ファイルから期待する文字列を取り出すことです — そうすると、そのファイル自体を基準に測ることになります。

---

検証

ドキュメントのチェックは、文字どおり一致させます（事実には正規表現エンジンがワイルドカードとして 解釈する文字が含まれます — パターンとして検索すると、v1.0.0 は v1X0X0 にも一致し、[2026-08-13] は無効な文字範囲としてエラーになります）。また、 連続して一致させます（2 行にまたがる事実は 1 つの事実であり、2 つではありません）。

ripgrep なら、どちらも実現できます。-F は文字どおりに一致させ、-U は複数行にまたがる一致を可能にします。

文字どおりのコマンド例を提示する前に、記載されたシェルと環境で、記述どおりの安全なスニペットを隔離したフィクスチャに対して実行してください。受け付けるフラグ、フラグの優先順位、結果、終了ステータスを、実装または CLI の仕様と照合します。破壊的な操作、外部への送信、本番環境の変更、または認証情報を含む例を、稼働中のターゲットに対して実行してはいけません。そのような例では、コードまたはヘルプ出力からフラグと優先順位を検証し、エンドツーエンドで検証していない動作を明記してください。

必ず明示的なパスを渡してください。 これは文体上の好みではありません。パス引数がなく、標準入力が非対話型の場合 — エージェントのシェルではその状態です — rg はファイルではなく 標準入力 を検索します。どちらの症状が起きるかは標準入力の状態によって異なり、どちらも確認されています。

• 標準入力が閉じている、またはパイプを読み終えている → 終了コード 1、出力なし。これは「その文字列はどこにも現れない」とバイト単位で同一なので、誤りが問題なく通ったように見えます。4 つのファイルにその文字列が含まれていたディレクトリで、パスを省略した形式は何も報告しませんでした。
• 標準入力が継承され、EOF に到達しない → コマンドは何かに終了させられるまでハングします。検索が原因不明のままハングする場合、ファイルシステムが遅いと結論づける前に、パス引数が欠けていないか確認してください。

ディレクトリを検索するすべての検索には、次の理由から 2 つのフラグが必要です。このチェックを信頼できるものにする条件で詳しく説明しているように、rg はデフォルトで VCS によって無視されるファイルと隠しファイルをスキップします。また、ドキュメント化されたコマンドが多数ある .github/ は隠しディレクトリです。これらのフラグを付けない検索では、ドキュメントの厳密な部分集合しか調べられません（実測値では、6 ファイルではなく 4 ファイルでした）。ファイルを明示的に指定する検索では不要です — rg は無視や隠しファイルのルールに関係なく、指定されたパスを読み取ります — そのため、このファイルの後半にある項目ごとのチェックでは省略しています。

検索ルートは一度だけ設定し、黙って範囲が狭まるのではなく、明確に失敗するようにします。

ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || { echo "not in a git repo — set ROOT to the docs root by hand" >&2; exit 1; }

ここで || echo . と書いてはいけません。. への暗黙のフォールバックは、たまたま現在いるディレクトリを検索範囲にし、しかも終了コード 0 を返します — その結果、「リポジトリ全体」は気づかないうちに「このサブツリー」に変わり、1 つ上の階層にある事実が存在しないと報告されます（実測済み）。リポジトリ内にいない場合は、手動で ROOT にドキュメントのルートを設定してください。重要なのは、自分で選んだことです。

# Every copy of a fact, before you change it. Path and both flags are load-bearing.
rg -U -F "the exact fact string" "$ROOT" --no-ignore --hidden -g '!.git'

# Per-file counts — the artifact you paste into your report.
rg -U -F --count-matches "the exact fact string" "$ROOT" --no-ignore --hidden -g '!.git'

# Multi-line facts: the newline has to be a real newline. In bash/zsh that means $'...';
# "\n" inside double quotes is a literal backslash-n and matches nothing (measured).
rg -U -F $'first line of the fact\nsecond line of it' "$ROOT" --no-ignore --hidden -g '!.git'

--no-ignore を有効にしたら、-g '!.git' は省略できません。これを付けないと、検索結果には .git/COMMIT_EDITMSG や .git/logs/HEAD が、残存コピーとして表示されます — これらは変更内容を 説明するコミットメッセージです。これらを「クリーンアップ」することはできないため、これらを数えるチェックでは、件数の不一致を見過ごす癖がつき、本当に対処すべき不一致に対するチェックの役割が損なわれます。--no-ignore は node_modules/ などのベンダー提供ツリーも検索対象に戻すため、存在する場合は同じように除外してください。

検索する前に期待する件数を書き留めてください。検索した後ではありません。 出力を見てから決めた件数は、誤りになりえません。どのファイルにその値が残るべきか、どのファイルには残るべきでないかを示してから、次を実行します。

rg -U -F --count-matches "the old value" "$ROOT" --no-ignore --hidden -g '!.git'
rg -U -F --count-matches "the new value" "$ROOT" --no-ignore --hidden -g '!.git'

各結果を集合の等価性として双方向でリストと比較してください。存在するはずのないファイルが存在すれば残留物であり、リストにあるはずのファイルが存在しなければ、同様に失敗です。--count-matches は一致件数ゼロのファイルを出力から完全に省略するため、新しい値を受け取るはずだったドキュメントが黙ってそうならなかった場合、クリーンな実行とまったく同じに見えます。

このチェックを誠実なものにするポイント:

• 古い値が常にゼロになるとは限りません。 変更履歴のエントリ、意思決定ログ、あるいは「<日付>時点ではこれは X だった」という文は履歴を記録するものであり、正当に古い値を保持します(ドリフトテストの質問3)。カウントをゼロにするためにそれらを削除すると、チェックを満たすために監査証跡を破壊することになります。歴史的なファイルを事前に挙げておいてください。そのリスト以外のものはすべて残留物です。
• --no-ignore --hidden は意図的なものであり、両者は同じフラグではありません。 デフォルトでは rg は VCS で無視されたファイルと隠しファイルの両方をスキップします。--no-ignore は最初のグループのみを復元します。--hidden がなければ、検索は依然として .github/ を決して開きません。そこにはコントリビューションガイド、課題テンプレート、そして文書化されたコマンドでいっぱいのワークフローが存在します(実測: --hidden を追加すると、サンプル検索が4ファイルから6ファイルになりました)。それらのディレクトリが見えない収束ゲートは、生き残った古いコピーの上でグリーンになります。それらを含めて、重要でないと仮定するのではなく、追加のヒットを判断してください。

ゼロを信頼する前にキャリブレーションを行ってください — どのツールを使ったとしても。 何も返さない検索には2つの原因があります。事実が消えたか、コマンドが間違っているかです。それらは同じに見えます。「残存コピーなし」と報告する前に、存在するとわかっている文字列に対して同じ形のコマンドを実行してください。それも何も返さなければ、壊れているのは計器であり、ドキュメントではありません。これは上記のパスなし rg の失敗に対する直接の解毒剤であり、1行のコストで済みます。

ripgrep がない場合

git grep -nF "fact" -- . はどの git リポジトリでも動作し、プラットフォーム間で単一の実装です(grep とは異なり、その再帰およびシンボリックリンクの動作は BSD、GNU、およびドロップイン置換品の間で異なります)。これには以下の制限があり、すべて実測済みで、すべてエラーではなく自信に満ちた誤った答えを生み出します:

追跡されているファイルのみを検索します。 モード2で書いたばかりの統合ドキュメントは新規で未追跡です — そのため git grep を通じて実行された保存チェックはその内容が欠落していると報告し、あなたは決して失われなかったものを「復元」します。まず git add するか、そのファイルを直接読んでください。

複数行の文字列に対する -F は、黙って各行を独立にマッチングするように劣化します。 2行の事実のうち1行目のみを保持したファイルでもヒットとして報告されます — そのため損失のある移動が「内容はまだそこにある」と認定され、これこそが保存チェックが捕まえるために存在する唯一のエラーです。grep と git grep の両方に当てはまります。

どちらのツールも利用できない場合、Python が動作する場所ならどこでも連続チェックを実行できます:

python3 -c 'import sys, pathlib
# .rstrip("\n") matters: your editor adds a trailing newline to needle.txt, and a fact
# sitting at a file'"'"'s end has none — without the strip, that copy is silently missed.
needle = pathlib.Path(sys.argv[1]).read_text(encoding="utf-8").rstrip("\n")
for f in sys.argv[2:]:
    n = pathlib.Path(f).read_text(encoding="utf-8").count(needle)
    if n: print(f, n)' needle.txt doc1.md doc2.md

移動または削除したファイルへの参照を更新する

エントリーを分割した場合やセクション名を変更した場合は、 配信エントリーのリプレイで、対象範囲を限定した古いアンカーの確認と、修正後のエントリーの検証を行えます。本文中のセクションへの参照は、実際の見出しと照らし合わせて確認してください。リンクチェッカーが成功しても、リンクとして解析されなかった本文中の記述は検証されません。

ファイル名だけを検索すると、参照元リンクの一部は見つかりますが、残りは見落とされ、それでも「検証済み」と報告されます。ファイルの参照形式は一つではありません。

BASE=old-doc            # filename without extension
rg -n -F -e "$BASE.md" -e "[[$BASE" -e "($BASE" -e "/$BASE" "$ROOT" --no-ignore --hidden -g '!.git'

これで、Markdownリンク、Wiki形式の [[old-doc]]、パスのみの記述、インポートを確認できます。ただし、次のことは行われません。

• ファイルのディレクトリ階層が変わると、相対パスは壊れます。 1階層からの ../guide.md は、別の階層では ../../guide.md になります。ファイル名をgrepすれば行は見つかりますが、パスが引き続き解決されるかどうかは、リンクごとに別途確認が必要です。

• 「リンク切れがないことの検証」には2つの方向があり、Phase 4で必要なのはそのうち1つだけです。 受信方向 — 「削除したものを、まだ何かが参照しているか？」 — は統合によって壊れる可能性があり、上記の検索で確認できます。こちらを実施してください。これがこのステップで実際に求められることです。

  送信方向 — 「これらのファイル内のすべてのリンクが引き続き解決されるか？」 — はドキュメント全般のQA作業であり、ここで独自に作るものではありません。実際のリンクチェッカーを使用してください。

  lychee --offline --root-dir "$PWD" docs/   # local paths only, no network
  lychee docs/                               # also checks external URLs (slow, fails for unrelated reasons)
  

ドキュメントでルート相対リンク（/docs/x.md — mkdocs、Docusaurus、GitHub Pagesで一般的な形式）を使っている場合、--root-dir は必須です。指定しないと、lycheeはそのようなリンクをすべてエラーとして報告します。これは、下の段落で避けるよう述べている誤検知と同じです。アンカー（x.md#section）は、--include-fragments を追加しない限り検証されません。

0 Total は合格を意味しません。信頼する前に動作を確認してください。 計測結果（lychee 0.24.2）：存在しないパスでは明確に失敗し、終了コード1を返します。一方、存在するもののMarkdownを含まないディレクトリでは、🔍 0 Total … ✅ 0 OK 🚫 0 Errors と表示して終了コード0で終了します。これは問題のない実行と同じ結果です。ディレクトリを1階層上または下に指定すると、何も確認していないのに緑色のチェックが表示されます。Total の数を確認してください。0の場合は、ファイルに本当にリンクが含まれていないことを確認するか、検索場所が間違っていないかを確認してください。（リンクがすべてインラインコードまたはフェンス付きコードブロック内にあるファイルは、lycheeがどちらも正しくスキップするため、正当に0になります。）

lychee（brew install lychee / cargo install lychee）は、シェルのパイプラインでは扱えないMarkdownリンク形式に対応しています。山括弧付きリンク [x](<my file.md>)、タイトル付きリンク [x](y.md "Title")、入れ子の括弧、参照形式の [x][ref]、フェンス付きコードブロック内のリンクなどは、いずれも正規表現と test -e を組み合わせた方法では、両方向の確認で問題を起こします。実際のリンク切れを黙って見落としたり、有効なリンクを誤ってエラーとして報告したりするためです。リンクチェッカーを利用できない場合は、独自実装で代用せず、送信方向の確認を実施していないと記載してください。

チェッカーが検証するのは、解析対象となったリンクとフラグメントだけです。見出し、アンカー、自動リンクの処理規則は、想定する閲覧環境と異なる場合があります。たとえば、異体字セレクター（VS16）を含む絵文字の見出しや、句読点の隣にあるメールアドレスでは、閲覧環境のパーマリンクや mailto: のリンク先が機能していても、チェッカーでエラーになることがあります。これらはパーサー互換性の例であり、汎用的に使える見出しスラッグのアルゴリズムではありません。

リンク切れとの報告を受けて修正または変更する前に、想定する閲覧環境で実際のMarkdownを確認してください。レンダリングされた見出しやパーマリンクをたどるか、メールアドレスの実際の mailto: リンク先を確認します。リンク先が存在しない、または一致しないことを確認できた場合は、実際のリンク切れとして分類してください。閲覧環境で機能するリンク先がチェッカーでエラーになる場合は、パーサーの互換性問題として分類してください。その閲覧環境で確認できない場合は、チェッカーの結果から推測せず、閲覧時の解決可否を未検証のままにしてください。互換性のために修正する場合は、表示ラベルと連絡先の識別情報を維持したうえで、チェッカーの結果と実際の閲覧環境でのリンク先の両方を検証してください。診断を黙らせるためだけに、有用なエントリーを削除したり、意図されたリンク先を変更したりしないでください。

保持の確認（モード 2）

このチェックの古い形式は、「必須の手順を保持した」「注意点を保持した」といった、チェックを付ける項目のリストでした。それらを削除した本人がチェックを付けるので、失敗することはありません。自己評価を証拠に置き換えましょう。具体的な項目をそれぞれ挙げ、現在どこにあるかを示してください。後述のカテゴリは、探し漏れを防ぐためのチェックリストであり、証拠を数える単位ではありません。

Phase 4 のステップ 1 で作成したリストを使ってください。書き換え前に、重要な項目ごとに 1 件ずつ記載したものです。（そのステップを飛ばしましたか？ Phase 4 のステップ 7 に、git からソースを復元する方法と使用する ref が記載されています。）絶対にしてはいけないのは、統合ファイルから想定される文字列を取得することです。それでは、ファイルが自分自身と一致することしか証明できません。

方法は処置に応じて異なり、誤った方法を使うと削除の誤報が生じます。 Keep とマークされたセクションは一字一句そのまま残す必要があります。一方、Condense とマークされたセクションは書き換えることが想定されていたため、古い文をそのまま検索しても何も見つからないのが正しい結果です。これは内容の損失ではなく、要約が機能しているということです。

処置	保持されたことを示す方法
Keep、そのまま引き継いだ場合	保存した項目ごとに：rg -U -F "<saved distinctive line>" <consolidated file> → ヒットする
Keep、別のセクションと統合した場合 — 統合が書き換え前に記録されていた場合に限る（Phase 3 の計画またはステップ 1 のインベントリ）	完全一致検索では見つかりません。同じ制約を異なる言葉で述べた 2 つのセクションを統合すると、3 つ目の表現が生まれます。それが Mode 2 の目的です。以下の Condense の方法を使ってください。検索を成功させるために元の文を再び貼り付けないでください。それでは、削除しようとしていた重複を復活させることになります。

どちらの行を適用するかは、書き換え前に決めます。チェック時に決めるのではありません。 このセクションを統合する予定だったと示す計画またはインベントリの行を指せない場合は、上の行が適用され、見つからなければ不合格です。これは単なる事務処理ではありません。検索に失敗したエージェントに、どの行で評価するかを選ばせると、厳格な完全一致の関門が緩いものになり、しかも何かを検出した場合に限って緩くなります。見逃される失敗は統合ではありません。通常の Keep セクションが書き換え中にひそかに言い換えられ、結果として条件節が落とされているのに、「統合」と再分類され、緩い方法で弱められた文がヒットするケースです。 | Condense | 保存した主張ごとに（各制約、数値、条件、警告）：統合ファイル内でそれを担っている行を引用してください。指し示せない主張は、文章量にかかわらず削除されています。 | | Delete | 保存した項目ごとに：残っているコピーの場所、またはコピーがない場合は削除する理由を示してください。「重複しているように見えた」は理由になりません。何が記載されていたかを明示してください。 |

以下のカテゴリは想起を促すものであり、単位ではありません。見落とした種類に気づくためのもので、それぞれについて、上の表にある項目ごとの証拠を示す必要があります。カテゴリにチェックを付けても、項目ごとの証拠にはなりません。

カテゴリ（Keep と Condense の両方に適用）	提示する証拠
必須の手順（セットアップ、設定）	上記の処置に対応する行に従う
重要な制約と注意点	同様に、注意点ごとに 1 件ずつ示す — 要約で最もよく抜け落ちる、重要な主張です
トラブルシューティングのガイダンス	同様
技術的負債／ロードマップ項目	同様
外部リンクと参照先	Keep または Condense セクションから保存した各 URL が、新しいファイルに一字一句そのまま存在すること（文字列の存在を確認するものであり、HTTP リクエストではありません）。要約しても URL はそのまま残ります。残っていなければ削除されています。「より短い URL」はありません。Delete セクションから保存した URL については、代わりに Delete の行に従ってください。リンクが残っている場所、または削除する理由を示してください。この行を成功させるために統合ファイルへ URL を再び貼り付けないでください。それでは、削除すると決めた内容を復活させることになります
デバッグのヒントとコードスニペット	同様。要約したセクション内であっても、コードは一字一句そのままでなければなりません
一致が見つかっても、その文字列がファイル内にあることを示すだけで、正しい場所にあることまでは証明できません。 ステージング環境のみの警告が「Production」という見出しの下に置かれていたり、制約が適用範囲を定める条件節の外に移動されていたりしても、このチェックには合格しながら、現在は誤った内容を伝えている可能性があります。項目の意味が置かれた場所に依存する場合は、一致した箇所で止めず、その前後の行も確認してください。これは、情報を損なう複数行の移動が「まだ存在する」と認定されてしまうのと同じ理由です。

一致を見つけられない項目は、保持されていません。削除されています。それが正しい判断だった可能性はありますが、チェックマークの中に含めるのではなく、削除として報告してください。

削除ゼロという結果も正当です。 価値分析の結果、すべてのセクションに残す価値があるなら、「統合するものはありません」と報告して終了してください。行数の削減は目標ではありません。報告する数字を作るために何かを削除するエージェントは、目的そのものを取り違えています。

---

報告する内容

次の各項目を明示してください。どれかに触れないと、特に言うことがないという意味に受け取られますが、実際にそうであることはまれです。

1. 見つかった不整合 — 何と何が食い違っていたか
2. 使用した正本 — 各事実を定義するファイルとしてどれを扱ったか、また宣言的に見えるものが複数あった場合、どの根拠で選んだか
3. 変更したファイルとその理由 — ファイルごとに1行
4. 削除した派生値と重複参照 — それぞれどこにあり、残す価値のある事実ではなく派生値と判断した理由
5. 検索の証拠 — 実行したコマンドとその件数。これにより、上記の主張を断言ではなく検証可能なものにします。これは「出力成果物」に記載されているものと同じ成果物です。どちらの一覧も別々のレポートではなく、1つのレポートを指しています。
6. 修正した手順 — 手順を変更した場合は、最初から最後まで
7. 未解決の事項 — 変更していない例外、対象範囲外の古い箇所、解消できなかったリスク

モード2では、このレポートに価値分析表と変更前後の指標も含めます。

抜け落ちやすいのはポイント4ですが、影響が積み重なるのもこの項目です。削除した派生値を明記すれば、それを復活させるべきでない理由を読者に伝えられます。

---

反アンチパターン

パターン	問題	代わりに行うこと
無差別な削除	情報が失われます	まずセクションごとに価値分析を行います
すべてを残す	削減できません	価値基準を厳格に適用します
複数の正本	将来的な不一致が避けられません	正本を1か所に定め、他の場所からはリンクします
孤立した参照	リンク切れになります	内容を移動したら、すべての参照を更新します
派生値を残す	気付かれないまま古くなり、警告も出ません	ドリフトテストの質問1 — 書かないでください
派生値にリンクする	それ自体も古くなる足場に加え、2つが一致しているという誤った安心感を与えます	同じです。値そのものを存在させないでください
前提が成り立たなくなったドキュメントを修正する	内部では一貫していても、全体として誤っています	アーカイブします（手順4の処置）
目につく箇所だけを更新する	見えにくいコピーが残り、後で矛盾します	編集前に検索します（手順5）
未実装の要望を文書化する	初日からドキュメントと実態が食い違います	手順3に従います。確立済みで、すでに承認された動作だけを修正し、それ以外は不一致として報告します
範囲を定めない「ついでの」一括修正	差分をレビューできなくなり、本当の変更が埋もれます	範囲を限定して整理します（手順6）

---

出力成果物

作業が成功すると、次の成果物が得られます。

1. 修正済みのドキュメント — 各事実について、正本が1か所に定められています
2. 価値分析（モード2） — セクションごとの判断理由
3. 変更前後の指標（モード2） — 削減した行数と、保持された価値
4. 検索の証拠 — 実行したコマンドとその件数。これにより主張を検証できます
5. 更新済みの参照 — メインドキュメントまたは README に新しい場所へのポインターがあり、移動した内容へのすべてのポインターが解決できます

次のステップ

ドキュメントの整合性が取れたら、次に取り組むのは自然な流れとして以下のとおりです。

Docs are now consistent — [N] files updated, [M] derived values removed.

Options:
A) Convert the recurring parts into a project rule — if the same drift keeps
   recurring, the fix is a rule in the project's main doc, not another cleanup pass
B) Render or publish the result — if these docs have a build/publish step
C) Nothing further — the docs are the deliverable