sync-readme

README 同期スキル

プロジェクトの実態を読み取り、ルート README.md を最新の状態に同期する。

対象セクション

以下のセクションを順にチェック・更新する。$ARGUMENTS で特定セクションが指定された場合はそのセクションのみ対象とする。

1. ディレクトリ構成 — ツリー図
2. 開発環境 — ツール一覧テーブル
3. セットアップ — インストール手順・コマンド
4. 使用方法 — スクリプトコマンド
5. Claude Code Skills — スキル一覧テーブル

手順

Step 1: プロジェクトの実態を収集

以下の情報を並列で収集する:

1. ディレクトリ構成: Glob でワークスペースパッケージのディレクトリを列挙する
2. 依存パッケージ: 各パッケージの package.json を読み込み、主要な依存を把握する
3. スクリプト: ルート package.json の scripts フィールドを読み込む
4. ワークスペース: pnpm-workspace.yaml を読み込む
5. スキル一覧: .claude/skills/ 配下の SKILL.md を Glob で列挙し、各スキルの frontmatter（name, description）を読み込む

Step 2: 現在の README.md を読み込む

ルートの README.md を読み込み、各セクションの現状を把握する。

Step 3: ディレクトリ構成の同期

実際のディレクトリ構成と README の plaintext コードブロック内のツリー図を比較する。

チェック項目:

• ワークスペースに登録されているパッケージがすべてツリー図に含まれているか
• 各パッケージ内の主要サブディレクトリ（lib/, bin/, agent/, src/, docs/ など）が反映されているか
• 削除されたパッケージやディレクトリがツリー図に残っていないか
• コメント（# 説明テキスト）がパッケージの実態と一致しているか

差分があった場合: ツリー図を更新する。ツリー図の記法・インデントスタイルは既存のフォーマットを維持する。

Step 4: 開発環境テーブルの同期

各パッケージの package.json の dependencies / devDependencies から主要ツールを抽出し、README の開発環境テーブルと比較する。

主要ツール判定基準:

• フレームワーク・ライブラリ（express, hono, langchain, aws-cdk-lib, docusaurus 等）
• ビルドツール・バンドラ（esbuild, rspack, swc 等）
• リンター・フォーマッター（biome, eslint, prettier 等）
• テストフレームワーク（vitest, jest 等）
• CLI ツール（tsx, secretlint, husky 等）

以下は主要ツールとして含めない:

• @types/* パッケージ
• 内部ユーティリティ（@smithy/* 等の間接依存）
• TypeScript 本体（言語自体であり開発ツールとは別カテゴリ）

チェック項目:

• 新しく追加されたツールがテーブルに含まれているか
• 削除されたツールがテーブルに残っていないか
• カテゴリ列（共通 / パッケージ名）が正しいか

差分があった場合: テーブルを更新する。カテゴリの並び順は「共通 → 各パッケージ（アルファベット順）」とする。

Step 5: セットアップ手順の同期

ルート package.json の scripts と、README のセットアップセクションを比較する。

チェック項目:

• scripts に存在するセットアップ系コマンド（*:install 等）が README に記載されているか
• README に記載されているコマンドが実際に scripts に存在するか
• コマンドの説明が実態と一致しているか

差分があった場合: セットアップ手順を更新する。

Step 6: 使用方法セクションの同期

ルート package.json の scripts と、README の使用方法セクションを比較する。

チェック項目:

• 主要な開発用コマンド（dev:*, build:*, cdk:* 等）が README に記載されているか
• README に記載されているコマンドが実際に scripts に存在するか

差分があった場合: 使用方法セクションを更新する。新しいコマンドカテゴリがある場合はサブセクションを追加する。

Step 7: Claude Code Skills テーブルの同期

.claude/skills/ 配下のスキル定義と、README の Skills テーブルを比較する。

チェック項目:

• 新しく追加されたスキルがテーブルに含まれているか
• 削除されたスキルがテーブルに残っていないか
• 各スキルの説明が SKILL.md の description と一致しているか
• コマンド例が argument-hint と一致しているか

差分があった場合: テーブルを更新する。

Step 8: 差分の報告と適用

すべてのチェックが完了したら、検出した差分を一覧表示してユーザーに確認する。

差分がない場合: README は最新の状態であることを報告して終了する。

差分がある場合: 差分の一覧を表示し、Edit ツールで修正を適用する。

修正時のルール

• 既存の文体・トーンを維持する
• Markdown のフォーマット（見出しレベル、テーブル記法、コードブロック）を崩さない
• 情報の並び順はカテゴリ別・アルファベット順を原則とする
• 不確実な情報は追加しない。ツールの公式 URL が不明な場合はリンクなしで記載する
• セクション自体の追加・削除が必要な場合はユーザーに確認を取る

出力

同期完了後、以下の形式でサマリーを出力する:

## README 同期結果サマリー

### 更新したセクション
- [ セクション名: 変更内容 ]
- ...

### 変更なしのセクション
- [ セクション名 ]: 最新の状態 ✅

### ユーザーへの確認事項（ある場合）
- [ 確認事項 ]