doc-sync

Files (4)

• README.md
• README_ja.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# doc-sync

## 目的

リポジトリ内のドキュメントが実装からズレていく問題を解消するSkill。
ドキュメントを読み、コードと突き合わせて**古い記述・抜け落ちた変更**を検出し、
**実装に沿った内容に更新**する。

## Arguments

- `--dry-run`: 検出のみ行い、ファイルは更新しない(差分プレビュー)
- `<path>`: 対象を絞り込むパス(任意。例: `docs/` や `README.md`。指定しない場合はリポジトリ全体)
- `language`: 更新時の文章言語(任意。指定しない場合は**既存ドキュメントの言語**を維持する)

例:

- `/doc-sync` → リポジトリ全体を一括自動更新
- `/doc-sync --dry-run` → 差分検出のみ、更新はしない
- `/doc-sync docs/api/` → 特定ディレクトリのみ自動更新
- `/doc-sync README.md --dry-run` → 単一ファイルの差分プレビュー

## 対象ドキュメント

以下4種類を対象にする。

| 種別               | 検出パターン                                                         |
| ------------------ | -------------------------------------------------------------------- |
| Markdown           | `*.md`(`README.md`, `CLAUDE.md`, `docs/**/*.md` など)                |
| docstring/コメント | コード内の関数・クラスのdocstring、ファイル冒頭のheaderコメント      |
| OpenAPI/Swagger    | `openapi.{yaml,yml,json}`, `swagger.{yaml,yml,json}`                 |
| 設定ファイル例     | `.env.example`, `*.example.{yaml,toml,json,ini}`, `config.example.*` |

`node_modules/`, `.git/`, `dist/`, `build/`, `vendor/`, `.venv/`, `.mjun/` は常に除外する。`.mjun/` 配下のspec・steering・実験計画はコードに先行する意図文書または専用skillが管理する文書であり、doc-syncが実装へ合わせて書き換えてはならない。

## 作業手順

### 1. ドキュメント探索

対象パス(引数指定があればそれ、なければカレントディレクトリ)から、上記4種別のドキュメントを列挙する。
具体的な探索手段(Glob, Grep, `find`, `rg` など)は問わない — 効率の良い方法で網羅すること。

探索のポイント:

- **除外パス**を必ず守る(`node_modules/`, `.git/`, `dist/`, `build/`, `vendor/`, `.venv/`, `.mjun/`)
- docstring/コメントは全件スキャンせず、**最近変更があったコードファイルを起点**にする方が効率的(git logで直近のコード変更を眺めるなど)
- リポジトリが大きい場合は、ドキュメントが集中するパス(`README.md`, `docs/`, `CLAUDE.md` など)を先に処理する

対象ドキュメントが1件も見つからない場合は「対象ドキュメントなし」と報告して終了する。

### 2. 乖離検出

各ドキュメントについて、**実装と照合して古い記述**を見つける。
よくある乖離パターン:

| パターン                  | 例                                                     |
| ------------------------- | ------------------------------------------------------ |
| 関数・クラス名の変更      | docには`fooBar()`、コードは`foo_bar()`または削除済み   |
| シグネチャの変更          | doc記載の引数と実装の引数が異なる                      |
| ファイル/ディレクトリ移動 | doc記載のパスにファイルが存在しない                    |
| CLIフラグ・コマンド変更   | doc記載の`--old-flag`がCLIに存在しない                 |
| API endpointの変更        | OpenAPIの`/api/v1/foo`が実装には無い、または逆         |
| 設定キーの変更            | `.env.example`に古いキーが残っている                   |
| 削除済み機能の残存記述    | docに「機能X」の説明があるがコードには無い             |
| 新機能の未記載            | コードに「機能Y」があるがdocに記載が無い               |
| 古いバージョン/依存関係   | docの「Python 3.9以上」が`pyproject.toml`では3.11以上  |
| 古いインストール手順      | doc記載の手順が現在の`package.json`/`Makefile`と不一致 |

照合方法のヒント:

- ファイルパス・関数名がdocに出てきたら、**実際にそのファイル・関数が存在するか**コード側で確認する
- CLIフラグなら、CLIエントリポイント(argparse/clapなど)の定義と照合する
- 設定キーなら、設定ファイルを実際に読み込むコードを見つけ、参照されているキーを抽出する

具体的にどのtool(Read/Grep/Glob/Bash等)で確認するかはAIに任せる。

**注意**: 文体・言い回しの好みは乖離ではない。**事実が間違っている箇所のみ**を対象にする。

### 3. 乖離リストの整理

検出した乖離を以下の形式でユーザーに提示する。
**ファイル単位 → セクション単位**で階層化する。

```text
検出した乖離:

1. README.md
   - "## インストール" セクション
       現状: `npm install foo-cli`
       実装: `package.json`の`name`は`bar-cli`に変更されている
   - "## 使い方" セクション
       現状: `--old-flag`オプションの説明
       実装: `src/cli.ts`では`--new-flag`に改名されている

2. docs/api.md
   - "## ユーザー作成" セクション
       現状: POST `/api/v1/users`、必須フィールドは`name, email`
       実装: `src/routes/users.ts`では`name, email, role`が必須
```

### 4. 更新の適用

`--dry-run` が指定されていない限り、検出した全ての乖離をEditで書き換える。
適用時は以下のセーフティを守る:

- **元の文体・言語**は維持する(既存docが日本語なら日本語のまま、英語なら英語のまま)
- **無関係な書き換え**(typo修正、スタイル変更、節構成の改変)は行わない
- **判断に迷う乖離**(実装の意図が不明確、複数の解釈がある)は更新せずスキップし、最後に「スキップ一覧」として報告する
- 既存セクションの**範囲を最小限**にして書き換える(隣接セクションを巻き込まない)
- Markdownのヘッダレベル・箇条書きスタイル・コードブロック言語指定は元に揃える
- docstringはそのファイルが採用しているスタイル(Google/NumPy/reStructuredText等)に合わせる
- 表は表のまま、リストはリストのまま更新する(不必要に形式を変えない)

`--dry-run` が指定された場合はEdit / Writeを一切呼ばず、検出した乖離リストと「もし更新するならどう書き換えるか」のbefore/afterだけを報告する。

### 5. 結果の報告

更新後、以下を要約して表示する。

```text

From mjun0812/skills, MIT.

More from mjun0812/skills