docs-updater

Universal Documentation Updater

最新のリリースタグ以降の Git 変更を分析し、それに合わせて更新すべきドキュメントファイルを更新します。

概要

Git の履歴を使ってリリースに関係する変更を特定し、README.md、CHANGELOG.md、関連するドキュメントフォルダーを更新します。明示的なユーザー承認、正確な編集、リポジトリ固有のドキュメント構成を重視したワークフローを維持してください。

使用するタイミング

次のような場合にこのスキルを使用します。

• リリースノートまたは Unreleased の変更履歴を準備するとき
• 機能の実装後に README.md やドキュメントを同期するとき
• PR またはリリースの前に、前回のリリース以降の変更内容を確認するとき

前提条件

開始する前に、次の条件が満たされていることを確認してください。

# Verify we're in a git repository
git rev-parse --git-dir

# Check that git tags exist
git tag --list | head -5

# Verify documentation files exist
test -f README.md || echo "README.md not found"
test -f CHANGELOG.md || echo "CHANGELOG.md not found"

タグが存在しない場合は、比較対象となるリリースタグが少なくとも 1 つ必要であることをユーザーに伝えてください。

手順

フェーズ 1：最終リリースバージョンの検出

目的：比較対象となる最新のリリースバージョンを特定します。

操作：

1. 比較の基準を検出して表示します。

LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

if [ -z "$LATEST_TAG" ]; then
    echo "No git tags found. This skill requires at least one release tag."
    echo "Please create a release tag first (e.g., git tag -a v1.0.0 -m 'Initial release')"
    exit 1
fi

CURRENT_BRANCH=$(git branch --show-current)
VERSION=$(echo "$LATEST_TAG" | sed -E 's/^[^0-9]*([0-9]+\.[0-9]+\.[0-9]+).*/\1/')

echo "Latest release tag: $LATEST_TAG"
echo "Version detected: $VERSION"
echo "Comparing: $LATEST_TAG -> $CURRENT_BRANCH"

フェーズ 2：Git 差分の分析

目的：前回のリリースと現在のブランチの間にあるすべての変更を分析します。

操作：

1. コミット範囲と統計情報を取得します。

# Get commit count between tag and HEAD
COMMIT_COUNT=$(git rev-list --count ${LATEST_TAG}..HEAD 2>/dev/null || echo "0")
echo "Commits since $LATEST_TAG: $COMMIT_COUNT"

# Get file change statistics
git diff --stat ${LATEST_TAG}..HEAD

2. 分析用にコミットメッセージを抽出します。

# Get all commit messages in the range
COMMITS=$(git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%s|%b" --reverse)

# Display commits for review
echo "$COMMITS"

3. 詳細なファイル変更を取得します。

# Get list of changed files
CHANGED_FILES=$(git diff --name-only ${LATEST_TAG}..HEAD)

# Show add/modify/delete status for quick categorization
git diff --name-status ${LATEST_TAG}..HEAD

4. ファイルパスに基づいてコンポーネント領域を特定します。

# Detect which components/areas changed
echo "$CHANGED_FILES" | grep -E "^plugins/" | cut -d'/' -f2 | sort -u

フェーズ 3：ドキュメント構成の調査

目的：プロジェクト内の関連するドキュメントの場所をすべて特定します。

操作：

1. 標準的なドキュメントフォルダーを検索します。

# Check for common documentation locations
DOC_FOLDERS=()

[ -d "docs" ] && DOC_FOLDERS+=("docs/")
[ -d "documentation" ] && DOC_FOLDERS+=("documentation/")
[ -d "doc" ] && DOC_FOLDERS+=("doc/")

# Find plugin-specific docs
for plugin_dir in plugins/*/; do
    if [ -d "${plugin_dir}docs" ]; then
        DOC_FOLDERS+=("${plugin_dir}docs/")
    fi
done

echo "Documentation folders found:"
printf '  - %s\n' "${DOC_FOLDERS[@]}"

2. 既存のドキュメントファイルを特定します。

# Check for standard doc files
DOC_FILES=()

[ -f "README.md" ] && DOC_FILES+=("README.md")
[ -f "CHANGELOG.md" ] && DOC_FILES+=("CHANGELOG.md")
[ -f "CONTRIBUTING.md" ] && DOC_FILES+=("CONTRIBUTING.md")
[ -f "docs/GUIDE.md" ] && DOC_FILES+=("docs/GUIDE.md")

echo "Documentation files found:"
printf '  - %s\n' "${DOC_FILES[@]}"

フェーズ 4：CHANGELOG の更新内容の作成

目的：Keep a Changelog 標準に従って、分類された変更履歴の項目を作成します。

操作：

1. Conventional Commits のセマンティクスに従ってコミットを解析し、Added、Changed、Fixed、Removed、Security などの Keep a Changelog セクションに分類します。

2. 既存の CHANGELOG.md を読み、構成を把握してから、Keep a Changelog 形式に従って新しい項目を作成します。

詳細な bash コマンドと変更履歴のテンプレートについては、references/examples.md を参照してください。

フェーズ 5：README.md の更新

目的：関連する概要レベルの変更をメインの README に反映します。

操作：

1. 現在の README.md を読み、構成を把握します
2. 更新が必要なセクション（機能一覧、スキル／エージェント、セットアップ手順、バージョンの参照）を特定します
3. Edit ツールを使って更新を適用します。構成とトーンを維持し、バージョン番号を更新します

フェーズ 6：ドキュメントフォルダーの更新

目的：変更を docs/ フォルダー内の関連ドキュメントに反映します。

操作：

1. 見つかった各ドキュメントフォルダーについて、変更されたコードに言及しているファイルがないか確認します
2. 変更されたファイルと関連するドキュメントを対応付けます
3. 更新内容を作成します。新機能のドキュメント追加、API リファレンスの更新、古くなった例の修正を行います

詳細な調査パターンと更新方法については、references/examples.md を参照してください。

フェーズ 7：変更内容のレビュー

目的：変更を適用する前に、更新する内容をユーザーに提示します。

操作：

1. 提案する変更の概要を提示します。

## Proposed Documentation Updates

### Version Information
- Previous release: $LATEST_TAG
- Current branch: $CURRENT_BRANCH
- Commits analyzed: $COMMIT_COUNT

### Files to Update
- [ ] CHANGELOG.md - Add new version section with categorized changes
- [ ] README.md - Update [specific sections]
- [ ] docs/[specific files] - Update documentation

### Summary of Changes
**Added**: N new features
**Changed**: N modifications
**Fixed**: N bug fixes
**Breaking**: N breaking changes

2. AskUserQuestion を使ってユーザーに確認します。

• 更新するファイルを確認します
• 変更が必要な項目があるか尋ねます
• 続行する承認を得ます

フェーズ 8：ドキュメントの更新を適用

目的：承認された更新を書き込み、正しく反映されたことを確認します。

操作：

1. CHANGELOG.md を更新します。

# Read current changelog
CURRENT_CHANGELOG=$(cat CHANGELOG.md)

# Prepend new section
cat > CHANGELOG.md << 'EOF'
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
[New content goes here]

[Rest of existing changelog]
EOF

2. Edit ツールを使って README.md を更新します。

• 特定のセクションを対象に編集します
• 全体の構成を維持します
• 該当する場合はバージョン番号を更新します

3. ドキュメントファイルを更新します。

# For each documentation file that needs updates
# Use Edit tool to make precise changes

4. 適用した変更を検証します。

# Confirm key files still exist after editing
test -f CHANGELOG.md && echo "CHANGELOG.md present"
test -f README.md && echo "README.md present"

# Review the scope of markdown changes
git diff --stat -- '*.md'

# Spot-check the actual content written
git diff -- '*.md' | sed -n '1,240p'

5. リポジトリにドキュメントまたは Markdown の検証コマンドがすでに定義されている場合は、終了前に実行します。

例

例1：機能開発後の更新

ユーザーのリクエスト：「追加した新機能のドキュメントを更新してください」

出力：

• 最新のタグ：v2.4.1 → 現在のブランチ：develop
• 5件のコミットを分析しました
• 新しい Spring Boot Actuator スキルの CHANGELOG エントリを生成しました
• README.md のスキル一覧を更新しました

例2：リリースドキュメントの準備

ユーザーのリクエスト：「v2.5.0 リリースのドキュメントを準備してください」

出力：

• v2.4.1 以降の47件のコミットを分析しました
• 15件の機能、8件の修正、3件の破壊的変更を検出しました
• CHANGELOG.md の [2.5.0] セクション全体を生成しました
• README.md とプラグインのドキュメントを更新しました

例3：差分同期

ユーザーのリクエスト：「ドキュメントを同期してください。いくつか変更を加えました」

出力：

• 2件のコミットを分析しました
• github-issue-workflow スキルの変更に関する、対象を絞った CHANGELOG の更新
• README やプラグインのドキュメントの更新は不要です

詳細なセッション記録とトラブルシューティングについては、references/examples.md を参照してください。

ベストプラクティス

1. 書き込む前にプレビューし、書き込み後に確認する：まず計画を提示し、編集後に最終的な差分を確認します
2. Keep a Changelog に従う：一貫した変更履歴の書式を維持します
3. 適切に分類する：正しいカテゴリ（Added、Changed、Fixed など）を使用します
4. 具体的に記述する：変更履歴のエントリにはプラグイン名やコンポーネント名を含めます
5. 構成を維持する：既存のドキュメントの構成とスタイルを維持します
6. コミットを参照する：追跡に役立つ場合は、コミットハッシュを含めます
7. 破壊的変更に対処する：移行に関する注記を添えて、破壊的変更を明確に示します
8. バージョン参照を更新する：ドキュメント全体でバージョン番号の一貫性を保ちます

制約と警告

1. Git タグが必要です：このスキルは、リポジトリにリリースタグが1つ以上ある場合にのみ機能します
2. 読み取り専用の分析：スキルは変更を分析しますが、書き込み前に確認を求めます
3. 手動でのレビューが必要です：生成された変更履歴のエントリは、正確性を確認してください
4. Conventional Commits：Conventional Commits 形式を使用するプロジェクトで最も効果を発揮します
5. タグは作成しません：このスキルはドキュメントを更新しますが、リリースタグは作成しません
6. 自動コミットはありません：ドキュメントの変更は準備されますが、自動的にはコミットされません
7. プロジェクト固有のパターン：プロジェクトによっては、準拠すべき独自の変更履歴形式がある場合があります
8. ファイルパス：クロスプラットフォーム互換性のため、すべてのファイルパスでスラッシュ（Unix 形式）を使用します