doc-maintenance

ドキュメントの保守

コードベースと既存ドキュメントを比較して、古くなった記述、抜け漏れ、整理不足を見つけ、体系的に監査、整理、修正します。

実行するタイミング

• 機能ブランチのマージ後、またはリファクタリング完了後
• 依存関係のアップグレード後、または API の変更後
• プロジェクトのドキュメントについて、オンボーディング時に混乱が生じたとき
• 定期メンテナンス（月次またはリリースごと）
• scripts/doc_audit.py を手動で実行し、指摘事項が報告されたとき

ワークフローの概要

Phase 1: Audit       → Run deterministic scan + haiku search agents
Phase 2: Triage      → Classify findings by severity and action type
Phase 3: Remediate   → Dispatch specialized agents to fix/create docs
Phase 4: Quality     → docs-architect reviews all changes

---

フェーズ 1：監査

ステップ 1a — 決定論的なスキャンを実行する

同梱の監査スクリプトを実行し、ベースラインレポートを取得します。

python3 skills/doc-maintenance/scripts/doc_audit.py

スクリプトは、次の項目を網羅する構造化レポートを生成します。

• 壊れた内部リンク（存在しないファイルを指す Markdown の [text](path)）
• 孤立したドキュメント（他のドキュメントや README からリンクされていないファイル）
• 必須の構成の不足（docs/ または manual/ に、想定されるフォルダーやファイルがない）
• コードに対して古くなったドキュメント（参照先のサブツリーが、ドキュメントの最終更新以降に大幅に変更されているもの。絶対的なドキュメントの古さではなく、ドキュメントの最終編集から現在までのコードコミットを Git のログで調べて測定します。これにより、安定したアーキテクチャドキュメントに対するノイズを抑えます）
• 空のファイルまたはスタブファイル（内容が 3 行未満）

機械可読な出力を得るには --json を指定します。プロジェクトルートの検出を上書きするには --root PATH を指定します。

ステップ 1b — 検索エージェントをディスパッチする

決定論的なスキャンの後、より詳細な分析を行うサブエージェントを起動します。 モデルの選択はタスクに合わせて調整します。パターン列挙には haiku、複数ファイルの相関分析と判断には sonnet を使用します。完全なプロンプトテンプレートは references/agent-dispatch.md を参照してください。

エージェント 1 — コードからドキュメントへの網羅性スキャン（subagent_type: "Explore"、model: "haiku"）： コードベースから公開 API、CLI コマンド、設定スキーマ、エクスポートされたモジュールを検索します。 既存のドキュメントと相互参照します（grep で記載の有無を確認）。ドキュメント化されていない項目を報告します。 内側のループはパターン列挙と grep による記載確認なので、haiku で十分です。

エージェント 2 — ドキュメントからコードへの鮮度スキャン（subagent_type: "general-purpose"、 model: "sonnet"、ドキュメントファイルごとにディスパッチ）： 対象範囲の各 Markdown ファイルについて、ファイルの内容とともに sonnet エージェントをディスパッチします。エージェントは (a) 具体的なコード参照（関数名、CLI フラグ、ファイルパス、設定キー、API エンドポイント）をすべて抽出し、 (b) grep／codanna／Read を使って現在のコードと照合し、 (c) 不一致を RENAMED／REMOVED／CHANGED として報告します。鮮度の検証には複数ファイルをまたぐ追跡（ハンドラー → ミドルウェア → 設定）が必要になることが多く、名前変更と削除を区別するには、古い場所がなくなったことを確認するだけでなく、新しい場所を読む必要があるため、sonnet とドキュメントファイルごとのディスパッチが必要です。

エージェント 3 — 構成準拠スキャン（subagent_type: "Explore"、model: "haiku"）： 現在の docs/ と manual/ の構成を、references/folder-structure.md に定められたフォルダー構造と比較します。 不足しているフォルダー、誤った場所にあるファイル、命名規則違反を報告します。 仕様との純粋なパターン照合なので、haiku が適切です。

エージェント 4a — ASCII 図の検出（subagent_type: "Explore"、model: "haiku"）： Markdown をスキャンし、罫線描画文字（─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼）、矢印表記 （-->、<--、==>）、またはいくつかのノードを超えるインデント付きのツリー構造を検出します。それぞれについて、 Mermaid への変換候補として、推奨する図の種類とともに報告します。文字を見つけて場所を報告する機械的なパターン検出なので、haiku が適切です。

エージェント 4b — 図の不足に関する判断スキャン（subagent_type: "general-purpose"、 model: "sonnet"、ドキュメントファイルごとにディスパッチ）： 対象範囲の各 Markdown ファイルについて、sonnet エージェントをディスパッチします。エージェントはドキュメントを読み、 図を追加することで理解が実質的に向上する箇所に印を付けます。対象となるのは、順序が重要な複数段階のフロー、名前付きコンポーネント間のアーキテクチャ上の関係、状態遷移、リクエスト／レスポンスのシーケンスです。重要なのは、図が文章よりも価値を加える場合に限って印を付けることです（手順のリストすべてに図が必要なわけではありません）。 haiku は過剰に印を付ける（あらゆるリストを図にできると見なす）か、逆に見落としがちです（暗黙的なフローの説明を見逃す）。このシグナルの信頼性を高めるのは、sonnet の判断です。

エージェント 1、2、3、4a、4b を並行して起動します。ただし、エージェント 2 と 4b は内部でドキュメントファイルごとに ディスパッチするため、実際の呼び出し回数は 5 回ではなく 2 + (2 × N_docfiles) になります。

ステップ 1c — 結果を統合する

スクリプトの出力とエージェントの所見をまとめて、単一の監査レポートを作成します。重複する所見は統合します。 このレポートをフェーズ 2 への入力として使用します。

---

フェーズ 2：トリアージ

各指摘を、以下のアクションカテゴリのいずれかに分類します。

カテゴリ	説明	例
stale	ドキュメントは存在するものの、古いコードや動作を参照している	CLI フラグ名が変更されているのに、ドキュメントには旧名称が記載されている
missing	ドキュメント化すべき項目のドキュメントが存在しない	公開 API エンドポイントのリファレンスドキュメントがない
orphan	ドキュメントは存在するものの、たどり着けない、またはリンクされていない	ガイドファイルがどのインデックスやナビゲーションにも含まれていない
misplaced	ドキュメントは存在するものの、誤ったフォルダーに置かれている	チュートリアルが docs/architecture/ に置かれている
irrelevant	削除された機能を扱っている	削除された機能のガイド
structural	フォルダー構成が規定のレイアウトから逸脱している	docs/security/ フォルダーがない
diagram-convert	ASCII／テキスト図を Mermaid にするべき	アーキテクチャドキュメントに複雑な罫線図がある
diagram-missing	図を追加すると分かりやすくなるセクション	複数ステップのプロセスが文章だけで説明されている

重大度を割り当てます。

• P0 — ユーザー向けドキュメントに事実誤認がある（manual/）
• P1 — 開発者向けドキュメントが存在しないコードを参照している
• P2 — 公開 API または機能のドキュメントがない
• P3 — 構造上／整理上の問題
• P4 — 軽微な古さ、体裁上の問題

---

フェーズ 3：修正

各指摘を適切な専門エージェントに割り当てます。以下に記載されたサブエージェントタイプで Task ツールを使用してください。詳しいプロンプトテンプレートについては、references/agent-dispatch.md を参照してください。

ドキュメントの種類	サブエージェントタイプ	対象の場所
API リファレンスドキュメント	reference-builder	docs/reference/ または docs/api/
アーキテクチャドキュメント	technical-writer	docs/architecture/
開発者向けガイド（スタイル、ローカル開発、ワークフロー）	technical-writer	docs/development/
テストドキュメント	technical-writer	docs/testing/
セキュリティドキュメント	technical-writer	docs/security/
ユーザー向けチュートリアル	learning-guide	manual/tutorials/
ユーザー向けハウツーガイド	learning-guide	manual/guides/
ユーザー向けスタートガイド	learning-guide	manual/getting-started/
計画と提案	technical-writer	docs/plans/
ASCII 図の変換	mermaid-expert	既存ドキュメント内
文章で説明されているセクションへの図の追加	mermaid-expert	既存ドキュメント内

並列での割り当て： 互いに独立した修正タスクをまとめ、同時に割り当てます。あるドキュメントが別のドキュメントに依存する場合（たとえば、チュートリアルからリンクする API リファレンスが先に必要な場合）に限り、順番に実行します。1 回のバッチで最大 4 つの修正エージェントを割り当てます。

既存ドキュメントの更新： エージェントに現在のファイル内容と、修正対象となる具体的な指摘を提供します。最小限かつ対象を絞った編集を行うよう指示します。

新規ドキュメントの作成： 関連するソースコード、対象ファイルのパス、フォルダー構成の仕様をエージェントに提供し、命名規則に従うよう指示します。

---

フェーズ 4：品質ゲート

すべての修正エージェントの作業完了後、変更全体をレビューする docs-architect エージェントを 1 つ割り当てます。品質ゲートでは、以下を確認します。

1. 正確性 — ドキュメントは現在のコードと一致しているか？
2. 網羅性 — すべての公開インターフェースが網羅されているか？
3. 構成 — フォルダー構成は規定のレイアウトに一致しているか？
4. 相互参照 — すべての内部リンクが有効か？
5. 一貫性 — トーン、書式、見出しレベルは統一されているか？
6. 孤立したドキュメントがないこと — 新規ドキュメントはすべて、インデックスまたは親ドキュメントからリンクされているか？

品質ゲートに合格しなかった場合は、指摘された問題についてフェーズ 3 に戻ります。ユーザーへのエスカレーション前に、修正ループを最大 2 回行います。

---

フォルダー構成

規定のフォルダーレイアウトは references/folder-structure.md で定義されています。概要：

docs/ — 内部向け／開発者向けドキュメント

docs/
├── architecture/    — System design, ADRs, component diagrams
├── development/     — Developer guides: style, local setup, issue tracking
├── plans/           — Proposals, RFCs, roadmaps
├── reviews/         — Code review records, audit reports
├── testing/         — Test strategy, coverage reports, test plans
├── reports/         — Generated reports, metrics, analysis
├── security/        — Security policies, threat models, audit findings
├── api/             — Internal API docs (OpenAPI specs, gRPC protos)
├── reference/       — CLI reference, config reference, manpages
├── ideas/           — Exploratory notes, spikes, brainstorms
└── archive/         — Deprecated docs preserved for history

manual/ — ユーザー向けドキュメント（プロジェクトのルート）

manual/
├── getting-started/ — Installation, quickstart, first steps
├── guides/          — How-to guides for common tasks
├── tutorials/       — Step-by-step learning paths
├── reference/       — User-facing command/config reference
└── troubleshooting/ — FAQ, common errors, known issues

README.md — プロジェクトのルート

メインの README は正確性を監査しますが、再構成はしません。README に関する指摘は、手動での修正が必要な古い項目／不足項目として報告されます。

---

アンチパターン

• 説明されている機能が本当に削除されたことを確認せずに、ドキュメントを削除しないでください
• 内部の相互参照をすべて更新せずに、ドキュメントを再編成しないでください
• フォルダー構成を埋めるためだけにスタブファイルを作成しないでください。実際の内容があるドキュメントのみを作成してください
• docs/ と manual/ の間で内容を重複させないでください。代わりにリンクしてください
• ユーザー向けドキュメントを docs/ に移動したり、開発者向けドキュメントを manual/ に移動したりしないでください