sc-readme

ドキュメント自動更新スキル

Git の変更に基づいてドキュメントをインテリジェントに保守します。相互参照の検証、古さの報告、重要な更新に対する複数モデルのコンセンサスに対応しています。

クイックスタート

# Update README based on current branch changes
/sc:readme

# Multi-document review and update (all project docs)
/sc:readme --scope all

# Target specific documentation
/sc:readme --scope api-docs

# Preview changes without writing
/sc:readme --preview

# Analyze N recent commits instead of branch diff
/sc:readme --commits 20

# Force PAL consensus for all updates
/sc:readme --consensus

# Compare against different base branch
/sc:readme --base develop

# Staleness report only (no changes)
/sc:readme --report-only

動作の流れ

1. DISCOVER - git diff または git log を実行して変更されたファイルを特定します
2. ANALYZE - 変更されたファイルを読み込み、種類（API、設定、依存関係、機能）ごとに分類します
3. MAP - 信頼できる情報源のマッピングを使い、変更されたファイルと影響を受けるドキュメントを対応付けます
4. VALIDATE - すべてのドキュメントにわたって相互参照の一貫性を確認します
5. PLAN - 更新が必要なセクションを特定し、古さのレポートを生成します
6. GENERATE - Edit ツールを使ってドキュメントのセクションを更新します
7. VERIFY - PAL codereview で最終的なドキュメントを確認します

フラグ

フラグ	型	デフォルト	説明
--base	string	main	比較対象のベースブランチ
--preview	bool	false	書き込まずに変更をプレビューします
--consensus	bool	false	すべての更新で PAL のコンセンサスを強制します
--scope	string	readme	対象：readme、all、または任意のドキュメントパス
--commits	int	-	ブランチ差分の代わりに、直近の N 件のコミットを分析します
--report-only	bool	false	変更を加えずに古さのレポートを生成します
--cross-ref	bool	true	相互参照の検証を有効にします

使用する Git コマンド

# Branch diff mode (default)
git diff main...HEAD --name-status
git diff main...HEAD
git log main...HEAD --oneline

# Commit mode (--commits N)
git log --oneline -N --name-only --pretty=format: | sort -u | grep -v '^$'
git log --oneline -N

変更カテゴリ

カテゴリ	ファイルパターン	影響を受けるドキュメント
API	*.py、*.ts、*.js（新しいエクスポートを含む）	README、API ドキュメント
依存関係	package.json、requirements.txt、pyproject.toml	README、インストール
設定	.env*、*.config.*、settings.*	README、設定ドキュメント
機能	新しいモジュール、重要な追加	README、機能ドキュメント
データベース	models/、migrations/	データベースドキュメント、README
フロントエンド	src/components/、src/pages/	フロントエンドドキュメント、README
インフラストラクチャ	docker-compose*、Dockerfile、CI 設定	DevOps ドキュメント、README

複数ドキュメントモード（--scope all）

--scope all を使用すると、プロジェクト内のすべてのドキュメントファイルを検出して検証します。

ドキュメントの検出

ドキュメントファイルを自動検出します。

# Find all markdown docs (excluding node_modules, .venv, etc.)
find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/dist/*"

一般的なドキュメントのパターン：

ドキュメントファイル	用途
README.md	プロジェクトの主要ドキュメント
CLAUDE.md	Claude Code の指示
CONTRIBUTING.md	貢献ガイドライン
docs/*.md	詳細なドキュメント
frontend/README.md	フロントエンド固有のドキュメント
api/README.md	API ドキュメント

信頼できる情報源のマッピング

コードの変更を、影響を受けるドキュメントに対応付けます。

コードパターン	影響を受けるドキュメント
src/api/**、app/routers/**	README、API ドキュメント
src/models/**、app/models/**	README、データベースドキュメント
src/components/**、frontend/src/**	README、フロントエンドドキュメント
migrations/**	データベースドキュメント
.env.example	README、環境変数への参照があるすべてのドキュメント
tests/**	README（テスト構成のセクション）

相互参照の検証

--cross-ref が有効な場合（デフォルト）、ドキュメント間の一貫性を確認します。

• README に記載された API ルートが、実際のルートハンドラーと一致している
• 環境変数がすべてのドキュメントと .env.example で一致している
• ドキュメント内で参照されているファイルパスが実際に存在する（Glob 経由）
• コンポーネント名がすべてのドキュメントで一貫している
• ドキュメントに記載されたコマンドの構文が正しい

古さのレポート

## Documentation Staleness Report

**Commits Analyzed**: 20 | **Docs Scanned**: 6 | **Issues Found**: 3

### README.md
**Status**: STALE
**Affected by**: src/api/users.py, src/models/user.py

- [ ] API Routes table missing new `/users/bulk` endpoint
- [ ] Environment variables section missing `BULK_IMPORT_LIMIT`

### docs/DATABASE.md
**Status**: UP-TO-DATE
No changes needed.

### frontend/README.md
**Status**: STALE
**Affected by**: src/components/UserProfile.tsx

- [ ] Component list missing UserProfile

更新順序

依存関係に従ってドキュメントを処理します。

1. まず README.md（主要な参照元）
2. 次に CLAUDE.md（README との一貫性を保つ必要があります）
3. その後、その他のドキュメント（信頼できる情報源として README を参照）

MCP 統合

PAL MCP

# Consensus for API/breaking changes
mcp__pal__consensus(
    models=[{"model": "gpt-5.2", "stance": "for"}, {"model": "gemini-3-pro", "stance": "against"}],
    step="Evaluate: Does this documentation update accurately reflect the code changes?",
    relevant_files=["/README.md", "/src/changed_file.py"]
)

# Review final documentation
mcp__pal__codereview(
    review_type="quick",
    step="Review documentation accuracy and cross-reference consistency",
    relevant_files=["/README.md", "/docs/API.md"]
)

ツールの連携

• Bash - Git コマンド（git diff、git log）
• Read - ドキュメントファイル、変更されたソースファイル
• Edit - ドキュメントのセクションをその場で更新
• Glob - ファイルパスの検証、ドキュメントの検索
• Grep - 相互参照の確認、パターンの検証

例

README を1つ更新

/sc:readme
# 1. git diff main...HEAD --name-status
# 2. Read README.md + changed files
# 3. Identify sections needing updates
# 4. PAL consensus if API changes detected
# 5. Update README.md

複数のドキュメントをレビュー

/sc:readme --scope all --commits 20
# 1. git log --oneline -20 for change context
# 2. Discover all .md documentation files
# 3. Map changes to affected docs
# 4. Cross-reference validation
# 5. Generate staleness report
# 6. Update all affected docs

古さのレポートのみ

/sc:readme --report-only --scope all
# Generates report without making changes

プレビューモード

/sc:readme --preview
# Same analysis, but output proposed changes instead of writing

ガードレール

1. 変更前にドキュメントをバックアップしてください
2. ユーザーの確認なしにセクションを削除しないでください
3. 互換性を損なう変更には合意が必要です
4. コード変更に関係のないカスタムコンテンツを保持してください
5. 順番に処理してください。まず README、その後に関連ドキュメントを処理します
6. ドキュメントで定められた範囲内の .md ファイルのみを変更してください
7. git checkout を使った Git によるロールバックを常に利用できます

関連スキル

• /sc:git - Git 操作
• /sc:document - 一般的なドキュメント生成
• /sc:pr-check - PR 前の検証