update-docs

ドキュメントの更新

変更後のドキュメントを総点検します。見落としやすい知識を適切なドキュメントに記録し、冗長な記述を削り、変更によって生じた可能性のあるずれを解消して、リポジトリ内のドキュメント全体の整合性を保ちます。

使用する場合

• インフラストラクチャ、設定、アーキテクチャ、運用に関する変更の後
• マージ済みの PR、リリースの確定、機能のリリース、バージョンの更新の後で、それらの変更によってドキュメントにずれが生じた可能性がある場合
• ドキュメント、指示ファイル、ランブック、変更履歴、API ドキュメント、ロードマップ、README の更新を依頼された場合
• セッション中に新たな注意点、セットアップ手順の変更、外部から見える動作の変更、サービスの追加が明らかになった場合
• API 契約、機能の範囲、移行手順、リリース／インストール手順が変更された場合
• リポジトリのドキュメントが明らかに不十分で、最小限のドキュメントの整備を提案する価値がある場合

使用しない場合

• ユーザーの承認なしに、ドキュメント一式をゼロから作成する場合
• コードの正確性やセキュリティのレビューの場合は、code-review または security-audit を使用します
• コード品質、不要な記述、保守性の改善の場合は、code-simplification を使用します
• プロンプトの作成や再利用可能なスキルファイルの保守の場合は、prompt-generator または skill-creator を使用します
• 複数の領域にまたがるコードベース全体の監査の場合は、repo-audit を使用します（その中で update-docs が一工程として実行されます）
• Git のコミットメッセージ、PR の説明、リリース告知文、タグ操作の場合は、git を使用します
• ロードマップの優先順位付けとバックログの整理は roadmap スキルの担当です。リリース済みの [planned]／[exploring] 項目の移動はロードマップのモード 2 で行います。明記されたバージョン番号と注目点の説明文はここで扱います

---

AI によるセルフチェック

ドキュメントの更新を提示する前に、以下を確認してください。

• 読者が必要とする内容（セットアップ、外部から見える動作、注意点、判断事項、障害時の挙動）が網羅されており、実装内容を重複して列挙していない
• 古い件数を新たに持ち込んでいない（「N」を使用するか、件数を正確に保っている）
• 内部リンクを確認した（名前の変更や移動後も参照切れがない）
• 関連する指示ファイル間の整合性を維持した（CLAUDE.md を変更した場合、AGENTS.md も同期した）
• 新しい Markdown ファイルを作成する前に、既存のドキュメントを確認した
• リリース、API、ロードマップ、機能のドキュメントは、変更による影響が実際にあった場合にのみ更新した
• すでに解決済みの問題に関する注意点が残っていない
• 非推奨の項目は黙って削除せず、日付と [DEPRECATED] プレフィックスを付けて示した
• 環境変数やランタイム設定を変更した場合、.env.example を更新した
• リポジトリのドキュメントが不十分な場合、最小限の整備を強制せず、提案としてユーザーに提示した
• サイズを確認した（wc -c）。指示ファイルは 40,000 文字未満である
• README／品質を裏付けるセクションに、古い日付、古い件数、過去の実行への参照がないか確認した
• コミット済みと Git で無視されるものの両方を含む、すべてのロードマップファイルを確認した。記載されたバージョン／日付は現在の HEAD または最新のタグと一致している
• 非公開と公開の両方のロードマップがある場合、両方を更新した。公開版にはユーザー向けの注目点のみを、非公開版には内部の詳細を記載した
• ドキュメントとコードの一致：コマンド、フラグ、設定名、スクリーンショット、API の例を、変更後の実装に照らして確認した
• 読者の導線を確認：README、変更履歴、API ドキュメント、ランブック、移行メモは、ユーザーに必要な場合にのみ更新した
• エージェント運用に関する横断的な衛生管理を適用した。references/agent-hygiene.md を参照

基本原則

読者が行動するために必要なことを、実際に読むファイルに記載してください。 読者に必要な場合は、セットアップ、外部から見える動作、必要なデフォルト値を説明し、実装内容の一覧を重複して記載しないでください。注意点、判断事項、障害時の挙動、回避策、暗黙の依存関係、リリースに関わる変更点、そして「理解するのに 30 分かかったこと」を記録してください。

プラクティス

• プロジェクトに生成ツールがすでに用意されている場合は、生成された API／スキーマのドキュメントを優先します。
• 後からの検証を容易にするため、例は最小限にしつつ、実行できるものにします。
• 動作の変更、非推奨化、移行手順、ロールバックに関する注意点は、ユーザーが確認する場所に記載します。
• 古くなった手順は、矛盾する注記を追加するのではなく削除します。
• 変更履歴の項目はユーザー向けにし、内部実装に関する不要な情報は避けます。

ワークフロー

監査のみモード： repo-audit から呼び出された場合、またはドキュメントの報告や確認を依頼された場合は、関連するステップ 1～7 を確認します。これには、関連ファイルの構成や不整合も含まれます。編集は行わず、コミットのステップ 8 は省略します。確認対象は、依頼された変更の影響を受けるドキュメントに限定します。非公開の設定や無関係なロードマップを自動的に一括確認の対象にはしません。

このチェックリストをコピーして、進捗を記録してください。

• 1. 変更を特定する（1.5 ロードマップの鮮度、1.6 根拠情報の鮮度）
• 2. ドキュメントへの影響を分類する
• 3. リポジトリのドキュメントが不足している、または内容が薄すぎないか確認する
• 4. 影響を受けるドキュメントを更新する（監査のみモードでは、更新が必要な内容を報告する）
• 5. 内部リンクを確認する。リンク切れがあれば修正し、ステップ 5 に戻る
• 6. 指示ファイルの肥大化を監査する
• 7. 関連する指示ファイルを同期する
• 8. ドキュメントの変更をコミットする

1. 変更内容を特定する

git diff と会話の文脈を確認し、変更された内容を把握します。

# Uncommitted changes
git diff --name-only

# Compare against the roadmap's stated version, falling back to last tag, falling back to last 10
ROADMAP_VER=$(grep -hoE 'Current:?\s*v?[0-9]+\.[0-9]+\.[0-9]+' ROADMAP.md docs/ROADMAP.md 2>/dev/null | head -1 | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+')
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
RANGE="${ROADMAP_VER:-${LAST_TAG}}..HEAD"
git log --oneline "$RANGE" 2>/dev/null || git log --oneline -10

次の変更がないか確認します：設定、インフラストラクチャ、サービスのデプロイ、スクリプト、CI ワークフロー、ネットワーク／IP 割り当て、サービスのバージョン、および運用に関するその他すべて。

1.5. ロードマップの鮮度確認

ロードマップは、コード、タグ、コミット履歴ですでに証明されている事実を繰り返すため、最も不整合が生じやすいドキュメントです。リポジトリにロードマップがある場合は必ずこの確認を行います。対象には、コミット済みのファイルと gitignore 対象のファイルの両方が含まれます。見つからない場合、このステップでは何も行いません。ROADMAP.md がないことはエラーではありません。

references/roadmap-freshness.md のスクリプトを実行します。このスクリプトは、ロードマップファイルをすべて検出して（追跡対象と gitignore 対象の両方）、各ファイルの Current／Updated／Version ヘッダーを解析し、記載されたバージョンが最新タグより古い場合、ヘッダーの日付より後にリリースが行われている場合、またはヘッダーの日付が HEAD より14暦日以上前の場合に ROADMAP DRIFT を報告します。不整合があれば、ステップ 2 の RANGE を広げます。このリファレンスには、ロードマップ本文内の古い Scanned／as of 日付を確認する補助的なチェックも記載されています。これらは個別の所見として報告します。

更新内容をでっち上げないでください。ユーザーは手動で更新するか判断できるよう、古くなっていることの指摘を求めています。架空のデータを作成しないでください。

1.6. 根拠情報の鮮度確認

README ファイルに記載された「品質の根拠」は、気付かないうちに古くなることがよくあります。たとえば、古いベンチマークの日付、古い実行 ID、古いスキル数やテスト数、古いリリースバージョン、「最新の実行」といった、リポジトリの状態に合わなくなった主張などです。README、CHANGELOG、リリースドキュメント、プロジェクト状況ドキュメント、または根拠／品質／状況に関する記述を含むドキュメントを変更する場合は、必ずこの確認を行います。

# Find brittle evidence claims in tracked docs.
DOCS=$(git ls-files '*.md' 'docs/**/*.md' 2>/dev/null)
if [[ -n "$DOCS" ]]; then
  printf '%s\n' "$DOCS" | while IFS= read -r doc; do
    git grep -n -E '([0-9]{4}-[0-9]{2}-[0-9]{2}|[0-9]+/[0-9]+|quality evidence|benchmark|latest (run|score|evidence|benchmark)|current (run|score|evidence|gates|version)|score[: ]|passed (for|in|on))' -- "$doc" 2>/dev/null || true
  done
fi
# Any claimed count ("N plugins", "N endpoints", "N tests") is only as good as the inventory
# that proves it. Recount from the repo's own source of truth before repeating the number:
#   git ls-files '<the tracked glob the claim describes>' | wc -l
# Do the same for scores, run IDs, and benchmark dates: re-read the artifact that stores them.

根拠を示す各記述について、同じセッション内でそれぞれの成果物を再確認します。たとえば、リポジトリのインベントリから件数を確認し、その記録ファイルからスコアや実行 ID を確認し、元になったレポートから日付を確認します。以前のセッションや、確認対象の記述を含むドキュメントから、根拠をそのまま再掲してはいけません。

古くなった根拠の記述が見つかった場合は、元の成果物を参照して更新するか、変動しやすい件数を使わない表現に書き換えます。適切な例：「公開スキルコレクションに対する現在のリポジトリのゲートはすべて合格しています。」注意が必要な例：「現在、42 個すべてのスキルでゲートに合格しています」――同じ実行で件数を確認していない場合。

2. ドキュメントへの影響を分類する

変更内容を更新対象のドキュメントに対応付けます。一般的な指示ファイル名は、CLAUDE.md、AGENTS.md、GEMINI.md、CODEX.md です。プロジェクトのドキュメント構成に合わせて調整してください。

変更の種類	更新が必要と思われるドキュメント
インフラ仕様の新規追加・変更	プロジェクトの指示ファイル（AGENTS.md または同等のファイル）、インベントリドキュメント
サービスまたはアプリの新規デプロイ	プロジェクトの指示ファイル、デプロイドキュメント
IP／ポート／エンドポイントの変更	プロジェクトの指示ファイル、ネットワークインベントリ
バージョンの更新（ランタイム、依存関係、イメージ）	プロジェクトの指示ファイル
新たに判明した注意点	プロジェクトの指示ファイル
運用手順の実施	ランブックまたはデプロイチェックリスト（デプロイサイクルのどの段階で手順を実施するかを記載）
新しいシークレットまたは認証情報	シークレットインベントリ
CI/CD ワークフローの変更	プロジェクトの指示ファイル、パイプラインドキュメント
Docker／Compose の変更	プロジェクトの指示ファイル、デプロイドキュメント
Proxmox／LXC の変更	プロジェクトの指示ファイル、インベントリドキュメント
Rust クレート／ツールチェーンの変更	プロジェクトの指示ファイル、README.md（ビルドの前提条件）
アーキテクチャ上の決定	重要な場合は ADR（後述を参照）、それ以外は指示ファイルに短い箇条書きを追加
新規または変更された環境変数、設定キー、ランタイム設定	.env.example、README.md（セットアップのセクション）
新しい依存関係またはセットアップ手順	README.md（利用開始／前提条件）
API エンドポイントまたは契約の変更	API.md、README.md（API のセクション）、エンドポイントのドキュメント、該当する場合は OpenAPI 仕様
機能の追加、削除、または実質的な変更	README.md、機能ドキュメント（FEATURES.md、FEATURESET.md、docs/features/*.md）、変更履歴
マージされた PR にユーザー向けの影響がある	変更履歴、ロードマップ／ステータスドキュメント、リリースノート、影響を受ける機能／API／セットアップのドキュメント
バージョン更新／新しいリリースの公開	CHANGELOG.md、リリースノート、README.md、インストール／アップグレードのドキュメント、バッジ、パッケージマネージャーの手順
リリース公開またはバージョン更新（ロードマップ側）	ROADMAP.md のヘッダー（Current／Updated）、リリース済みハイライトのセクション、ステータスドキュメント
前回のロードマップ更新以降に複数の機能をリリース	ROADMAP.md のリリース済みハイライトの説明と現在の状況の概要（項目のステータス更新はロードマップモード 2 で行います）
Git で無視される非公開ロードマップとコミット済みの公開ロードマップが両方ある	両方を更新します。非公開版には詳細な内部情報を記載し、公開版にはユーザー向けの概要を記載します
戦略または順序の変更	ROADMAP.md、ステータスドキュメント、マイルストーンドキュメント

ADR を作成する場合： 複数のコンポーネントに影響する決定、今後の選択肢を制約する決定、または以前の決定を覆す決定は、専用のアーキテクチャ決定記録として残す価値があります。「Z のために X から Y に切り替えた」のような一行で済む内容なら、プロジェクトの指示ファイルに短い箇条書きを追加すれば十分です。

注意点の配置の目安：

• 一行で済む注意点（例：「VIP は k8s のトラフィックを拒否するため、直接 IP を使用する」）→ プロジェクトの指示ファイルに箇条書きで追加します。
• 複数の手順が必要な作業（例：「証明書のローテーションには、ドレイン、置き換え、再読み込みの順で実施が必要」）→ 専用のランブックセクションに記載します。
• デプロイ前後に行う時間依存の操作（例：「Redis FLUSHALL は、デプロイ後かつトラフィックを戻す前に実行する必要がある」）→ セクション内に埋もれさせず、ランブックの冒頭にチェックリストを設けます。

3. リポジトリのドキュメントが不足している、または内容が薄すぎるか確認する

リポジトリに有用なドキュメントがない場合、または最小限の README.md しかない場合は、編集を始める前に、それを個別の所見として扱います。

「内容が薄すぎる」例：

• docs/ ディレクトリがなく、ひな形の README.md 以外に継続的に管理されている Markdown ファイルがない
• プロジェクト名だけが記載され、セットアップ、使い方、API、機能の概要がない README.md
• 変更のたびにドキュメントとの不整合が繰り返し生じているが、記録するのに適した場所がない

対応方法：

• 最小限のドキュメント整備を、ユーザーが断れる提案として提示します
• 提案は小規模かつ具体的にします。例：README.md、CHANGELOG.md、API.md、ROADMAP.md、docs/adr/
• リポジトリの種類に合わせて提案し、機械的に汎用のドキュメントツリーを提案しないでください
• ユーザーが断った場合は、既存のドキュメントを最大限活用して作業を続け、その制約を記録します

してはいけないこと：

• ドキュメント一式を自動的に新規作成しないでください
• 最小限のドキュメント整備の提案を理由に、通常のドキュメント保守を妨げないでください

4. 該当するドキュメントを更新する

該当するドキュメントは、それぞれ先に読み、その後、対象を絞って編集します。

追加する内容：

• コードからは分かりにくい注意点（例：「VIP は k8s のトラフィックを拒否するため、直接 IP を使用する」）
• コンポーネント間の暗黙の依存関係（例：「SealedSecret の更新後に Pod を再起動する必要がある」）
• 障害の発生パターンとその症状（例：「PLEG が unhealthy = コンテナランタイムがフリーズしている」）
• 既知の問題に対する回避策
• 運用上の制約（例：「serial: 1 が必須。削除すると、すべてのノードが同時に更新される」）
• 運用上のタイミング — 手順をデプロイのどの段階で実行する必要があるかを明記します（例：「Redis FLUSHALL は、新しいイメージのデプロイ後、トラフィックを戻す前に実行する必要がある」）
• IP、ポート、ホスト名が変わった場合の接続文字列とサービスエンドポイント
• 決定事項とその理由
• ユーザー向け機能の追加、削除、注意事項を、読者が想定するドキュメントに記載します
• リリースに関わる変更点：バージョンのアップグレード、アップグレード時の注意、破壊的変更、移行に関する案内
• API.md、エンドポイントのドキュメント、またはリポジトリの標準的な API ドキュメントにおける API の動作変更

ドキュメントがまだない場合：

• ユーザーから明示的な依頼がない限り、ドキュメント一式をゼロから作成しないでください
• ドキュメントが不足しているリポジトリでは、最小限のドキュメント整備を提案してください
• この注意点や運用メモのきっかけとなった内容を、プロジェクトの指示ファイル（CLAUDE.md、AGENTS.md、または同等のファイル）に最小限記載してください
• プロジェクトに指示ファイルがまったくない場合は、その旨をユーザーに伝え、重要な注意点を含むファイルの作成を提案してください。作成を待たずに作業を続けてください

追加してはいけない内容：

• セットアップや正しい使用にあたって、想定読者が知る必要のない実装上のデフォルト設定
• 読者の作業に関係のない、一般的なフレームワークやプラットフォームの詳細
• 上流のドキュメントにすでに記載されている情報
• 一時的な状態（進行中の作業、すでに完了した一度限りの移行手順）
• 冗長な説明 — 注意点は1項目につき1行とし、修正方法が分かりにくい場合にのみ詳しく説明します

5. 内部リンクを確認する

ドキュメントの編集後、内部参照が引き続き解決できることを確認します。

該当ドキュメントには、リポジトリにある Markdown／リンクチェッカーを優先して使用してください。存在しない場合は、次の限定的なインラインリンクチェックを使用します。これは各ソースドキュメントを基準にパスを解決しますが、見出しアンカー、参照形式のリンク、入れ子になった Markdown 構文は検証しません。確認対象のドキュメントパスを明示的に渡してください。

python3 - README.md docs/guide.md <<'PYLINK'
from pathlib import Path
from urllib.parse import unquote, urlsplit
import re, sys
failed = False
for name in sys.argv[1:]:
    source = Path(name)
    for raw in re.findall(r'\[[^\]]*\]\(([^()]+)\)', source.read_text()):
        destination = raw.strip().split(' "', 1)[0].strip('<>')
        url = urlsplit(destination)
        if url.scheme or url.netloc or not url.path:
            continue
        if url.path.startswith('/'):
            print(f"SITE-ROOT LINK: {source}: {raw}; validate against site configuration")
            continue
        target = source.parent / unquote(url.path)
        if not target.exists():
            print(f"BROKEN LINK: {source}: {raw}")
            failed = True
sys.exit(1 if failed else 0)
PYLINK

BROKEN LINK をすべて修正し、チェックが終了コード 0 で終了するまで再実行してください。ファイルを移動した場合は、参照元も検索してください。未対応のリンク形式は、検証済みではなく未確認として報告してください。

6. プロジェクトの指示ファイルの肥大化を監査する

更新後、プロジェクト共通の指示ファイルを批判的に見直します。

削除または簡潔にする場合：

• 問題点が修正され、該当しなくなった場合（解決済みと記してから、次のセッションで削除します）
• 情報がランブックに記載された場合（リンクに置き換えます）
• セクションがソースにある内容を言い換えている場合（例：コンテナーイメージのタグをすべて列挙している）
• 複数の箇条書きが同じ内容を異なる表現で説明している場合
• 移行や一度きりの手順が完全に完了し、今後繰り返されない場合
• Renovate／CI が自動的に最新に保つバージョン番号

残す場合：

• ドキュメントがなければ、再発見に 15 分以上かかる場合
• 単一のファイルからは把握できない、複数コンポーネント間の連携に関する情報である場合
• コードを読んで予想する内容に反している場合
• 実際の障害をきっかけに生まれた「X をしてはいけない」という警告である場合

サイズの目安：

• 共通の指示ファイル：ツールがより大きなサイズを許容する場合でも、40,000 文字未満、500 行未満を目指します。超える場合は、詳細なセクションを docs/ に移し、リンクします。
• 個別のセクション：30 行を超える場合は、専用ドキュメントへの分割を検討します。
• 編集後にサイズを確認します：wc -c CLAUDE.md AGENTS.md 2>/dev/null

7. 関連する指示ファイルを同期する

プロジェクトで複数の指示ファイル（例：AGENTS.md とツール固有のバリエーション）を管理している場合は、更新後に内容を揃えてください。

編集前に、関連ファイルがシンボリックリンク、インポート用スタブ、生成ファイル、独立したドキュメントのどれにあたるかを確認します。正規ファイルへのシンボリックリンクであれば、そのソースだけを一度編集します。同じファイルへのコピーは不要です。インポート用スタブは維持します。生成される関連ファイルの場合は、ソースの断片を編集して、リポジトリのジェネレーターを実行します。独立したファイルの場合は、対応する共通ガイダンスだけを更新し、対象固有のセクションは維持します。同期の近道として独立した関連ファイル全体を上書きせず、変更後の差分を確認してください。

既定では、指示ファイルは通常 gitignore の対象です。 プロジェクトが意図的に追跡している場合を除きます。コミットする前に .gitignore と既存の履歴を確認してください。

8. ドキュメントの変更をコミットする

編集前に、ステージ済みの状態と作業ツリーの初期状態を記録します。タスクで変更したパスとハンク（公開する予定の新規ドキュメントを含む）の一覧を作成します。無視対象／非公開のファイルはローカルに残します。確認済みのタスク変更だけを、明示的なパス指定またはパッチ単位のステージングでステージします。

コミット前に、ステージ済みの差分全体を確認し、初期のインデックスと比較します。無関係な変更がすでにステージされていた場合はそれを維持し、ユーザーが隔離方法を許可していない限り、タスクの編集はコミットせずに残します。他の人のインデックスをリセットしたり、変更のある Markdown ファイルをすべてステージしたり、ドキュメントが一部変更されたという理由だけでインデックス全体をコミットしたりしないでください。コミットが依頼の範囲内である場合に限り、リポジトリのコミット手順に従います。

クイックリファレンス：ファイルの場所

ファイル	目的	コミット対象？
README.md	リポジトリの概要、セットアップ、インストール、使用方法	はい
CHANGELOG.md	リリース向けの履歴と破壊的変更	通常ははい
API.md	人が読める API の概要と契約に関する注記	通常ははい
ROADMAP.md	公開または非公開の計画／ステータスを示す情報	プロジェクトによります
FEATURES.md / FEATURESET.md	ユーザー向け機能の一覧	プロジェクトによります
その他の *.md ドキュメント	リリースノート、ステータス文書、移行メモ、アーキテクチャ文書	プロジェクトによります
AGENTS.md	ツール間で共通するプロジェクト指示	プロジェクトによります（.gitignore を確認）
ツール固有の指示ファイル	プロジェクトで管理している場合の、特定のエージェント／ツール向けの関連指示	プロジェクトによります（.gitignore を確認）
docs/	プロジェクトのドキュメント（一覧、ランブック、ADR、移行メモ、リリース文書）	はい

非推奨機能の取り扱い

セッション中に機能、サービス、API が非推奨になった場合：

• ドキュメントの項目は残し、[DEPRECATED] の接頭辞と日付を付けます。すぐに削除しないでください。
• 置き換え先を追加し、同じセクションに記載して、読者が両方を確認できるようにします。
• まずリポジトリおよびユーザーが明示した廃止ポリシーに従います。 項目を削除する前に、リリース、公開日、経過期間の条件を確認してください。参照元がないことを理由に、約束した猶予期間を短縮することはできません。
• ポリシーがない場合に限り、非推奨の公開後、完了したリリースサイクルを 2 回分、項目を残します。その後、参照元を確認し、依然として必要な移行ガイダンスを残してから削除します。リリースまたは公開日の証拠を確認できない場合は、項目を残し、未確認の事項を報告します。
• 破壊的変更は独立した箇条書きにし、何が壊れるのか、何に置き換わるのか、必要な移行手順を記載します。

出力要件

要件の全文は references/output-contract.md を参照してください。

• スキル名： UPDATE-DOCS
• 成果物の分類： audits
• モード： 常時適用。すべての実行で、references/output-contract.md の報告サイズと証拠に関するルールが適用されます。
• 成果物のパス： docs/local/audits/update-docs/<YYYY-MM-DD>-<slug>.md
• 重要度の尺度： P0 | P1 | P2 | P3 | info（共通要件を参照）。

関連スキル

• repo-audit - code-review、code-simplification、security-audit、update-docs を並行して実行します。Update-docs は 4 つのパスのうちの 1 つです。
• git - コミットメッセージの規約と PR の説明に使用します。Update-docs はプロジェクトのドキュメントファイルを対象とし、git はバージョン管理操作を対象とします。

参照ファイル

• references/roadmap-freshness.md - ロードマップのずれを検出するスクリプトと、別経路での日付確認について説明しています。ステップ 1.5 で実行してください。
• references/agent-hygiene.md - 返答前に適用する横断的なチェック（生成済み）
• references/output-contract.md - すべての実行に適用するレポート形式（生成済み）

---

よくある間違い

• 何でも文書化すること：実装項目の一覧を繰り返すのは避けてください。読者が製品を正しく設定または使用するために必要な場合は、デフォルト値を記載します。
• 古い品質の証拠：「最新の実行結果」、「現在のスコア」、「39/39 skills」などの README の記述は、同じセッション内にソースの成果物と照合してください。
• 放置された注意事項：3 か月前に修正されたバグに関する注意事項はノイズです。定期的に整理してください。
• マージのたびにドキュメントが必要だと思い込むこと：マージ済みの PR は有力な手がかりですが、自動的にドキュメント更新が必要になるわけではありません。実際にずれがあるか確認してください。
• README 以外の対象を忘れること：API の変更は API.md に、リリースによる差分は CHANGELOG.md に、機能のずれは機能ドキュメントに記載します。
• 移行について過剰に文書化すること：移行が完了し、検証されたら、1 行にまとめて段階的な手順を削除します。
• 非推奨のドキュメントを早く削除しすぎること：リポジトリおよびユーザーが明示したポリシーに従ってください。参照元がないことは、猶予期間を無視する理由にはなりません。廃止条件がどちらにも定められていない場合に限り、上記の「完了したリリースサイクルを 2 回分」という代替ルールを使用します。
• ロードマップのヘッダー確認を省略すること：HEAD が v0.43 のときにロードマップの Current: v0.27 と記載されていれば、ずれの兆候として最も明白です。ロードマップを更新する必要があるか判断する前に、必ずヘッダーを解析して比較してください。
• gitignore 対象のロードマップを対象外として扱うこと：プライベートなロードマップは公開の場で誰も指摘しないため、最もずれが生じやすいものです。追跡対象のロードマップだけでなく、find コマンドが見つけたすべてのロードマップを対象に、鮮度チェックを実行してください。

---

ルール

• デフォルトではなく差分を記録してください。 何が変わったのか、何が壊れたのか、今後のセッションで何を把握しておく必要があるのかを記録してください。
• マージ済みの PR やリリースは、ドキュメントのずれを示す兆候として扱い、保証とはみなさないでください。 編集前に、影響がありそうか確認してください。
• 最も近くて便利なドキュメントではなく、適切な既存ドキュメントを選んでください。 API の変更は API ドキュメントに、リリースによる差分は変更履歴に、計画の変更はロードマップやステータスのドキュメントに記載してください。
• 問題のないドキュメントを、スタイルだけを理由に書き直さないでください。 編集は実務上の価値がある内容に限定してください。