ドキュメント自動更新
概要
このスキルは、実装完了後に関連するドキュメントファイルを自動的に検出し、コードの変更内容に基づいて更新します。README.md、CLAUDE.md/AGENTS.md/GEMINI.md などのエージェント設定ファイル、docs/ 配下のマークダウンファイルなど、プロジェクトのドキュメント全体を対象とします。
重要: 各プロジェクトには独自のドキュメント構造やスタイルがあります。このスキルは既存のフォーマット、トーン、用語を尊重し、最小限の変更で実装との整合性を保つことを優先します。
いつ使うか
以下のタイミングでこのスキルを使用してください：
- •新機能を実装した後、README やドキュメントに反映したい時
- •API や関数のシグネチャを変更し、ドキュメントと整合性を取りたい時
- •コミット前にドキュメントと実装の同期を確認したい時
- •ユーザーが「ドキュメントを更新して」「docs を最新化」とリクエストした時
- •リファクタリング後、影響を受けるドキュメントを更新したい時
いつ使うべきでないか
以下の状況ではこのスキルを使用しないでください：
- •設計段階での仕様書作成（実装前のドキュメント作成）
- •コード内のコメントやdocstring の更新（コードレビュースキルで対応）
- •API仕様書の自動生成（Swagger/OpenAPI など専門ツールを使用）
- •変更履歴（CHANGELOG.md）の生成（commit履歴ベースの専門スキルを使用）
- •ブログ記事やマーケティング資料の作成
更新手順
1. 変更内容の把握
まず、どのようなコード変更があったかを把握します。
引数が指定されている場合：
- •ファイルパスが指定された場合：そのファイルに関連するドキュメントを更新
- •特定のトピック（例: "API", "インストール"）が指定された場合：そのセクションに関連するドキュメントを更新
引数が指定されていない場合：
git diff --name-only
を実行して、最近変更されたファイルを特定します。変更がない場合は、カレントディレクトリ全体を対象とします。
次に、変更内容の詳細を把握：
git diff
で変更内容を確認し、追加された関数、変更されたAPI、削除された機能などを特定します。
注意: このスキルは読み取り専用の git コマンド（git diff, git status, git log）のみを使用します。git commit や git push などの書き込み操作は実行しません。
2. ドキュメントファイルの検出
以下のコマンドでプロジェクト内のドキュメントファイルを検出します：
# README 系ファイル find . -iname "README*.md" -o -iname "readme*.md" # エージェント設定ファイル（各ツール固有の命名） find . -name "CLAUDE.md" -o -name "AGENTS.md" -o -name "GEMINI.md" -o -name ".clauderc" # docs ディレクトリ配下 find . -path "*/docs/*.md" -o -path "*/documentation/*.md" # その他の一般的なドキュメント find . -name "CONTRIBUTING.md" -o -name "ARCHITECTURE.md" -o -name "API.md"
検出したドキュメントファイルを以下の優先度で分類：
- •High: README.md（プロジェクトルート）
- •Medium: CLAUDE.md/AGENTS.md/GEMINI.md などのエージェント設定、docs/配下の主要ファイル
- •Low: サブディレクトリの README、参考資料
3. 影響範囲の特定
変更されたコードとドキュメントの関連性を分析します。
関連性判定の基準
- •関数・クラス名の言及: ドキュメント内にコードで変更された関数名やクラス名が記載されているか
- •ファイルパスの言及: ドキュメント内に変更されたファイルのパスが記載されているか
- •概念的な関連: 変更内容がドキュメントのセクション（例: "インストール"、"使い方"）に該当するか
具体的には、Grep ツールを使用して以下を検索：
# 例：新しく追加された関数 `processData` がドキュメントに記載されているか Grep pattern=processData, path=., glob=*.md
関連性が高いドキュメントを優先的に更新対象とします。
4. ドキュメントの読み込みと理解
各対象ドキュメントに対して以下を実行：
- •Read ツールでファイル全体を読み込む
- •ドキュメントの構造とスタイルを理解する
- •見出し構造（
#,##,###）とその一貫性 - •セクション分け（Installation, Usage, API Reference など）
- •コードブロックの有無と内容、使用されているコードフェンスの言語指定
- •既存の文体（です・ます調 vs である調、命令形 vs 説明形）
- •用語の統一（例: "ユーザー" vs "利用者"、"関数" vs "メソッド"）
- •リスト形式の統一（
-vs*、番号付きリストのスタイル）
- •見出し構造（
- •変更が必要な箇所を特定する
- •古くなった情報（削除された機能の説明、変更前のAPI例）
- •不足している情報（新機能の説明、追加されたオプション）
- •誤った情報（変更されたパラメータ、更新された戻り値）
5. ドキュメントの更新
以下の原則に従ってドキュメントを更新します：
更新の原則
a. 正確性を最優先
- •コードの実装と完全に一致する内容にする
- •曖昧な表現を避け、具体的に記述する
- •古い情報を残さない
b. 一貫性の維持（最優先）
- •既存のドキュメントのトーンやスタイルを絶対に維持する
- •既存の用語をそのまま使用する（例: 既存が "ユーザー" なら "利用者" に変えない）
- •フォーマットの統一（コードブロック、リスト形式、見出しレベルなど既存に合わせる）
- •絵文字の使用：既存ドキュメントで使われていれば使用、なければ追加しない
- •箇条書きの記号：既存が
-なら-、*なら*を使う
c. 読者を意識（既存のトーンに合わせる）
- •README.md: 初めてプロジェクトを見る人向け（簡潔でわかりやすく、既存のフレンドリーさまたはフォーマルさを維持）
- •API.md: 開発者向け（技術的詳細を含む、既存の説明の詳細度に合わせる）
- •CLAUDE.md/AGENTS.md/GEMINI.md: AI エージェント向け（明確な指示形式、既存の命令形スタイルを踏襲）
d. 最小限の変更
- •変更が必要な箇所のみを更新する
- •全面的な書き直しは避ける（意図しない情報の削除を防ぐ）
- •変更箇所が明確になるよう、セクション単位で更新する
更新内容の種類
新機能の追加
## 新機能: データ処理
新しく追加された `processData` 関数を使用して、大量のデータを効率的に処理できます。
### 使い方
\`\`\`javascript
import { processData } from './processor';
const result = await processData(inputData, {
batchSize: 100,
parallel: true
});
\`\`\`
### パラメータ
- `inputData` (Array): 処理対象のデータ配列
- `options` (Object): 処理オプション
- `batchSize` (number): バッチサイズ（デフォルト: 50）
- `parallel` (boolean): 並列処理を有効化（デフォルト: false）
既存機能の変更
- •古い API 例を新しいものに差し替え
- •変更されたパラメータや戻り値を更新
- •非推奨（deprecated）の機能には明記する
削除された機能
- •該当セクションを削除
- •代替手段がある場合は移行ガイドを追加
インストール・セットアップの変更
- •依存関係の追加・削除を反映
- •設定手順の変更を更新
- •環境要件の変更を明記
6. 更新内容の検証
ドキュメント更新後、以下を確認します：
内容の正確性
- • コード例が実際に動作するか（可能であれば実行確認）
- • 関数名、パラメータ名が実装と一致しているか
- • リンクが正しく機能しているか
構造の一貫性
- • 見出しレベルが適切か
- • リストや表のフォーマットが統一されているか
- • Markdown 記法が正しいか
読みやすさ
- • 文章が自然で理解しやすいか
- • 専門用語に説明が添えられているか
- • コードブロックに言語指定があるか（```javascript など）
7. 更新サマリーの生成
以下の形式で更新内容のサマリーを生成します：
# ドキュメント更新サマリー 更新日時: [YYYY-MM-DD HH:MM:SS] ## 更新されたファイル ### README.md - **セクション**: インストール - **変更内容**: 新しい依存パッケージ `@types/node` を追加 - **理由**: TypeScript サポートの追加に伴う更新 ### docs/api.md - **セクション**: データ処理 API - **変更内容**: `processData` 関数の説明を追加 - **理由**: 新機能の実装 ### AGENTS.md - **セクション**: スキル一覧 - **変更内容**: `update-docs` スキルの説明を追加 - **理由**: 新スキルの追加 ## 変更統計 - 更新ファイル数: 3 - 追加行数: 42 - 削除行数: 8 ## 検証結果 - [x] コード例の動作確認 - [x] リンクの検証 - [x] Markdown フォーマットの検証 ## 推奨事項 - `docs/api.md` に使用例をさらに追加することを推奨 - README.md の "クイックスタート" セクションも更新を検討
特殊なドキュメントの扱い
README.md
- •バッジ（Badges）: CI/CD のステータスバッジなどは慎重に扱う
- •クイックスタート: 最もシンプルな使用例を提示する
- •目次（TOC）: 自動生成されている場合は手動更新しない
CLAUDE.md / AGENTS.md / GEMINI.md（エージェント設定ファイル）
- •ツール固有の命名: プロジェクトで使われているファイル名を尊重（CLAUDE.md、AGENTS.md、GEMINI.md など）
- •スキル定義: YAML フォーマットやフロントマターを崩さない
- •指示形式: 既存の命令形スタイルを維持する（"〜してください"、"〜すること"、"〜せよ" など）
- •トリガー条件: "いつ使うか" が明確に記載されているか確認
- •セクション構造: 既存のセクション分け（例: "開発ガイドライン"、"スキル使用ルール" など）を崩さない
API ドキュメント
- •型情報: TypeScript、Python の型ヒントなどを正確に記述
- •エラーケース: 例外やエラーレスポンスも記載する
- •サンプルコード: 最新の実装で動作する例を提供
CHANGELOG.md
- •このスキルでは更新しない（変更履歴は別のスキルで管理）
- •既存の CHANGELOG がある場合は触れない
エッジケースと注意事項
複数言語のドキュメント
プロジェクトに複数言語のドキュメント（README.md, README.ja.md など）がある場合：
- •すべての言語版を同期して更新する
- •翻訳の質を保つため、機械翻訳ではなく内容を適切に翻訳する
自動生成されたドキュメント
以下のような自動生成ドキュメントには注意：
- •JSDoc/TypeDoc で生成された API ドキュメント → 手動更新しない
- •Swagger/OpenAPI 仕様書 → ソースから再生成
- •コメントから生成された README → ソースコメントを更新
ファイルの先頭に <!-- This file is auto-generated --> のようなコメントがあれば、手動更新を避けます。
Git管理されていないドキュメント
.gitignore に含まれるドキュメントや、ビルド成果物としてのドキュメントは更新対象外とします。
カスタマイズとプロジェクト固有の規約
このスキルは既存のドキュメントスタイルを自動的に検出して尊重しますが、プロジェクト固有のドキュメント規約がある場合は、更新実行前にそれらを明示してください。
自動検出される項目
- •文体（です・ます調 vs である調）
- •箇条書き記号（
-vs*） - •用語の統一パターン
- •コードブロックの言語指定スタイル
- •絵文字の使用有無
明示すべきカスタムルールの例
- •「このプロジェクトではドキュメントに絵文字を積極的に使用する方針です」
- •「API ドキュメントは OpenAPI 形式で記述し、手動更新しないでください」
- •「README.md の "Features" セクションは常にアルファベット順にソートしてください」
- •「CLAUDE.md では命令形（"〜すること"）を使用し、"〜してください" は使わない」
- •「コードブロックには必ず言語名を指定する（```python など）」
更新後のアクション
ドキュメント更新後、以下のアクションを推奨します：
- •差分確認:
git diffでドキュメントの変更内容を確認 - •レビュー: 更新内容が意図通りか目視確認
- •コミット: 実装とドキュメントを同じコミットに含める、または別コミットとして分ける
- •CI/CD: ドキュメントのリンク切れチェックや Markdown linter を実行（設定されている場合）
このスキルにより、実装とドキュメントの整合性を保ち、プロジェクトの保守性を高めることができます。