documentation-sync

Documentation Sync

コード変更に伴い、関連ドキュメントが同期されているかを検証するスキル。

中核は、プロジェクトに依存しない次の汎用手順である。

1. git diff で変更ファイルを特定し、変更カテゴリに分類する
2. カテゴリごとにドキュメント同期の要否を判定する
3. 自動生成ドキュメントを再生成する
4. リンク切れをチェックする
5. 結果を表形式レポートで出力する

具体的なパスマッピング・生成コマンド・分類軸はプロジェクトごとに異なる。このスキルは判定の骨格だけを定め、プロジェクト固有の対応関係は各プロジェクトのマッピング表を正とする。

---

プロジェクト既定の優先（最初に確認する）

手順を始める前に、対象プロジェクトの CLAUDE.md / AGENTS.md（または契約ドキュメント）に「コードパス → ドキュメントパス」のマッピング表・同期ルール・自動生成コマンドが定義されていないかを確認する。

• 定義がある場合: プロジェクト側の定義を常に優先する。このスキルの後述の例示は、手順の当てはめ方を示す参考でしかない。分類軸・生成コマンド・ドキュメント配置がプロジェクト側と衝突する場合は、プロジェクト側の CLAUDE.md / AGENTS.md のマッピング表が正となる。
• 定義がない場合: このスキルの汎用手順に沿って分類軸・生成コマンド・ドキュメント配置を推定し、推定した前提を報告に明示したうえで進める。

以降の l-shift / food-article-seo の記述は、パスマッピングの多様性を示す例示であり、いずれかのプロジェクトの正規ルールとして参照してはならない。プロジェクトのマッピング表がこれらと異なるなら、迷わずプロジェクト側に従う。

---

1. 変更ファイルの特定と分類

# base ブランチからの差分ファイル一覧
git diff --name-only <base-branch>...HEAD

変更ファイルを、ドキュメント同期の観点でカテゴリに分類する。カテゴリとファイルパターンの対応はプロジェクトのマッピング表を正とする。マッピング表がない場合の汎用的な分類軸は次のとおり。

カテゴリ	判定の観点	必要なドキュメント同期
スキーマ / DB 変更	永続化構造・型・マイグレーションの変更	自動生成リファレンスの再生成
公開 API 変更	パッケージ / モジュールの公開面・シグネチャの変更	対応する仕様書・API ドキュメントの確認
新機能追加	新しい振る舞い・エンドポイント・ツールの追加	要件・設計ドキュメントの新規作成 / 更新
設計変更	アーキテクチャ・境界・責務の変更	設計ドキュメント・決定記録の整合性確認

例（分類軸はプロジェクトごとに異なることの確認用）:

• l-shift では prisma/schema.prisma / prisma/migrations/ が「DB 変更」、packages/*/index.ts が「公開 API 変更」、app/routes/ が「新機能追加」に対応する（正規ルールは l-shift の AGENTS.md / wiki/ を参照する）。
• food-article-seo では src/mastra/agents/（または LLM 呼び出し実装）が docs/agents/、src/mastra/tools/ が docs/tools/ に対応する。1 コードパスが複数ドキュメントパスへ写像される点が l-shift と異なる。

同じ「同期判定」でも、コードパスとドキュメントパスの対応は上記のように大きく異なる。だからこそ、分類の当てはめは常にプロジェクトのマッピング表を起点にする。

---

2. カテゴリ別ドキュメント同期判定

分類した各カテゴリについて、対応ドキュメントが変更に追随しているかを判定する。

# 変更されたコード領域を特定
git diff --name-only <base-branch>...HEAD -- <code-path-glob>

# 対応するドキュメント領域が同一差分内で更新されているか
git diff --name-only <base-branch>...HEAD -- <doc-path-glob>

判定の観点（汎用）:

• 公開 API / 機能変更: 対応する仕様書・API ドキュメントが同じ変更範囲で更新されているか。実装とドキュメントの記述が矛盾していないか。
• 新機能追加: 新機能に対応する要件・設計ドキュメントが作成されているか。
• 設計変更: アーキテクチャドキュメント・決定記録が最新の実装と矛盾していないか。既存の実装パターン集が古くなっていないか。
• 自動生成対象: 手動編集禁止の自動生成リファレンスに手が入っていないか（手動編集は次節の再生成で上書きされ得るため事故になる）。

判定に使うコードパス／ドキュメントパスの対応は、プロジェクトの CLAUDE.md / AGENTS.md のマッピング表に従う。

例: l-shift では packages/employment/ の変更に対し wiki/requirements/ 内の雇用関連仕様書を確認する、という対応が wiki/ 側で規定される（この対応関係自体は l-shift 固有であり、他プロジェクトへ流用しない）。

---

3. 自動生成ドキュメントの再生成

スキーマや公開面から機械生成されるドキュメントは、対応するコードが変わったら再生成する。生成コマンドと出力先はプロジェクトが定義するものを使う。

汎用手順:

1. プロジェクトの CLAUDE.md / AGENTS.md / package.json から、自動生成コマンドと出力先を特定する。
2. 対応するコードカテゴリに変更があれば生成コマンドを実行する。
3. 生成物の差分が変更内容と整合しているかを確認する。
4. 生成物（自動生成リファレンス）を手動編集していないことを確認する。

例（生成コマンドはプロジェクトごとに異なることの確認用）:

• l-shift では DB 設計ドキュメントの再生成に pnpm db:docs を使い、出力先は tbls のドキュメントディレクトリ（.tbls.yml の docPath で設定）である。新規テーブル追加時は .tbls.yml の viewpoints / tables セクション更新も伴う。これらのコマンド名・設定ファイル名・出力先はすべて l-shift 固有であり、正規手順は l-shift 側のドキュメントを参照する。
• 生成コマンドを持たないプロジェクトでは、この節はスキップし、ドキュメントは手動同期の対象として扱う。

自動生成コマンド（pnpm db:docs のような）や設定ファイル（.tbls.yml のような）を、このスキルの記述からそのまま他プロジェクトへ持ち込まない。必ずプロジェクト側で定義されたものを使う。

---

4. リンク切れチェック

ドキュメント間の内部リンクと、CLAUDE.md / AGENTS.md からドキュメントへの参照が切れていないかを確認する。ドキュメントルート（例: docs/・wiki/ など）はプロジェクトに合わせて置き換える。

# ドキュメント内のマークダウンリンクのリンク先だけを抽出し、存在確認する
DOC_ROOT="<docs-dir>"   # 例: docs/ や wiki/。プロジェクトに合わせる
rg -o --no-filename '\[[^]]+\]\([^)]+\)' "$DOC_ROOT" \
  | sed -E 's/.*\(([^)]+)\).*/\1/' \
  | while read -r link; do
      # 外部 URL とアンカーのみは除外
      case "$link" in
        http://*|https://*|'#'*) continue ;;
      esac
      # ルート相対・ドキュメント相対の両方で存在を確認
      if [ ! -f "$DOC_ROOT/$link" ] && [ ! -f "$link" ]; then
        echo "BROKEN: $link"
      fi
    done

# CLAUDE.md / AGENTS.md が参照するドキュメントパスを抽出して存在確認する
rg -o --no-filename '`[^`]*\.md`' CLAUDE.md AGENTS.md 2>/dev/null \
  | tr -d '`' | sort -u \
  | while read -r ref; do
      [ -f "$ref" ] || echo "BROKEN ref: $ref"
    done

内部リンクの検出は、file:line:match 形式ではなくリンク文字列のみを取り出してから存在確認する（パスに : が混ざって誤判定するのを避ける）。

---

5. 出力フォーマット（表形式レポート）

判定結果を表形式で報告する。「要対応」と「確認済み（問題なし）」を分けて示す。

## ドキュメント同期チェック結果

### サマリー

- 変更ファイル数: N 件
- ドキュメント更新必要: N 件
- リンク切れ: N 件
- 適用したマッピング元: <プロジェクトの CLAUDE.md / AGENTS.md のマッピング表 | このスキルの汎用推定>

### 要対応

| 種別 | 対象 | 必要なアクション |
| --- | --- | --- |
| 自動生成再生成 | `<生成物パス>` | プロジェクト定義の生成コマンドを実行 |
| 仕様書更新 | `<doc-path>` | 変更内容を反映 |
| リンク切れ | `<doc-path>:<line>` | リンク先を修正 |

### 確認済み（問題なし）

- <対応済みのドキュメント領域>
- CLAUDE.md / AGENTS.md との参照整合 OK

レポート冒頭で「どのマッピング表に基づいて判定したか」を必ず明示する。プロジェクトのマッピング表に基づいたのか、マッピング表がなく汎用推定に基づいたのかで、判定の信頼度が変わるためである。