Version Control for Docs

概要

このスキルは、Gitを活用してドキュメントの変更管理、レビューフロー、リリース管理を効率的に行うためのプラクティスを提供します。

Documentation as Codeの原則に基づき、ドキュメントをコードと同様にバージョン管理し、変更の追跡、レビュー、デプロイを自動化します。

主要な価値:

• 変更履歴の完全な追跡
• 効率的なレビュープロセス
• リリース管理の自動化
• コードとドキュメントの同期

対象ユーザー:

• 仕様書を作成するエージェント（.claude/agents/spec-writer.md）
• ドキュメントエンジニア
• DevOpsエンジニア

リソース構造

version-control-for-docs/
├── SKILL.md                                    # 本ファイル（概要と原則）
├── resources/
│   ├── git-diff-guide.md                      # Git Diff活用ガイド
│   ├── commit-conventions.md                  # コミットメッセージ規約
│   ├── review-workflow.md                     # レビューワークフロー設計
│   ├── branch-strategy.md                     # ドキュメント用ブランチ戦略
│   └── changelog-generation.md                # CHANGELOG自動生成
├── scripts/
│   └── generate-changelog.mjs                 # CHANGELOG生成スクリプト
└── templates/
    ├── pr-template.md                         # ドキュメントPRテンプレート
    └── changelog-template.md                  # CHANGELOGテンプレート

コマンドリファレンス

リソース読み取り

# Git Diff活用ガイド
cat .claude/skills/version-control-for-docs/resources/git-diff-guide.md

# コミットメッセージ規約
cat .claude/skills/version-control-for-docs/resources/commit-conventions.md

# レビューワークフロー設計
cat .claude/skills/version-control-for-docs/resources/review-workflow.md

# ドキュメント用ブランチ戦略
cat .claude/skills/version-control-for-docs/resources/branch-strategy.md

# CHANGELOG自動生成
cat .claude/skills/version-control-for-docs/resources/changelog-generation.md

スクリプト実行

# CHANGELOG生成（TypeScript）
node .claude/skills/version-control-for-docs/scripts/generate-changelog.mjs <version>

テンプレート参照

# ドキュメントPRテンプレート
cat .claude/skills/version-control-for-docs/templates/pr-template.md

# CHANGELOGテンプレート
cat .claude/skills/version-control-for-docs/templates/changelog-template.md

いつ使うか

シナリオ1: 変更追跡システムの導入

状況: ドキュメントの変更履歴を正確に追跡したい

適用条件:

• 誰が何をいつ変更したか把握したい
• 過去バージョンへのロールバックが必要
• 変更理由の記録が重要

推奨アプローチ: Git管理、コミット規約の徹底

シナリオ2: レビュープロセスの確立

状況: ドキュメント変更のレビュー体制を構築したい

適用条件:

• 公開前に品質チェックが必要
• 複数のレビュアーの承認が必要
• レビューコメントの追跡が重要

推奨アプローチ: PRベースレビュー、承認ワークフロー

シナリオ3: リリース管理の自動化

状況: ドキュメントのリリースプロセスを効率化したい

適用条件:

• 定期的なドキュメントリリースがある
• CHANGELOGの自動生成が必要
• バージョン管理が重要

推奨アプローチ: セマンティックバージョニング、自動CHANGELOG

前提条件

必要な知識

• Gitの基本操作（commit, branch, merge, diff）
• PR/MRの概念
• Markdownの基本

必要なツール

• Bash: Gitコマンドの実行
• Read: 変更ファイルの確認
• Write: ドキュメントの作成・更新

環境要件

• Gitリポジトリ
• GitHub/GitLab等のホスティングサービス（レビュー用）

ワークフロー

Phase 1: バージョン管理基盤の構築

目的: ドキュメントのGit管理体制を確立する

ステップ:

1. ディレクトリ構造の設計:

   • ドキュメント専用ディレクトリ
   • バージョン別の整理（必要に応じて）
   • 関連リソース（画像等）の配置

2. Git設定:

   • .gitignoreの設定
   • 大容量ファイルの扱い（Git LFS等）
   • フックの設定（pre-commit等）

3. 初期コミット:

   • 既存ドキュメントの整理
   • 意味のあるコミット単位
   • コミットメッセージ規約の適用

判断基準:

• ディレクトリ構造が設計されているか？
• Git設定が完了しているか？
• 初期コミットが完了しているか？

リソース: resources/branch-strategy.md

Phase 2: コミット規約の策定

目的: 一貫性のあるコミットメッセージを実現する

ステップ:

1. コミットタイプの定義:

   • docs: ドキュメント追加・更新
   • fix: ドキュメントの誤り修正
   • style: フォーマット、スタイル変更
   • refactor: 構造の再編成
   • chore: ビルド、ツール関連

2. メッセージ形式:

   • 件名：50文字以内、命令形
   • 本文：何を、なぜ変更したか
   • フッター：関連Issue、Breaking Changes

3. 検証の自動化:

   • commitlintの導入
   • pre-commitフックの設定

判断基準:

• コミットタイプが定義されているか？
• メッセージ形式が明確か？
• 自動検証が設定されているか？

リソース: resources/commit-conventions.md

Phase 3: レビューワークフローの構築

目的: 効率的で確実なレビュープロセスを確立する

ステップ:

1. PRテンプレートの作成:

   • 変更概要
   • 変更理由
   • レビュー観点
   • チェックリスト

2. レビュー基準の設定:

   • 必須レビュアー
   • 承認条件
   • 自動チェック項目

3. レビュープロセスの定義:

   • ブランチ作成 → 変更 → PR作成
   • レビュー → フィードバック → 修正
   • 承認 → マージ → 公開

判断基準:

• PRテンプレートが用意されているか？
• レビュー基準が明確か？
• プロセスが定義されているか？

リソース: resources/review-workflow.md

Phase 4: 変更履歴と差分管理

目的: 変更の可視化と追跡を効率化する

ステップ:

1. Git Diffの活用:

   • 差分の確認方法
   • 視覚的な差分ツール
   • ワード単位の差分

2. CHANGELOG管理:

   • セマンティックバージョニング
   • 自動生成ルール
   • 手動追記のガイドライン

3. リリースノートの作成:

   • ユーザー向け変更サマリ
   • Breaking Changesの強調
   • 移行ガイド（必要な場合）

判断基準:

• 差分確認方法が整備されているか？
• CHANGELOG管理が自動化されているか？
• リリースプロセスが定義されているか？

リソース: resources/git-diff-guide.md, resources/changelog-generation.md

ベストプラクティス

すべきこと

1. アトミックコミット:

   • 1コミット = 1つの論理的変更
   • 複数の無関係な変更を混ぜない
   • ロールバックしやすい単位

2. 意味のあるコミットメッセージ:

   • 何を変更したか明確に
   • なぜ変更したか説明
   • 関連Issue/PRへのリンク

3. 定期的な同期:

   • 頻繁なプル（最新取得）
   • 早めのコンフリクト解消
   • 長期ブランチの回避

避けるべきこと

1. 巨大なコミット:

   • 100ファイル以上の変更
   • 「大量更新」のようなメッセージ
   • レビュー困難な変更量

2. 直接mainへのプッシュ:

   • レビューなしの変更
   • 保護ブランチの設定なし
   • 承認プロセスの迂回

3. 履歴の改ざん:

   • 共有ブランチでのrebase
   • force pushの乱用
   • コミットの削除

トラブルシューティング

問題1: マージコンフリクトが頻発

症状: 同じファイルで頻繁にコンフリクト

原因:

• 同じ箇所を複数人が編集
• ブランチが長期化

解決策:

1. 作業範囲の明確な分担
2. こまめなマージ/リベース
3. モジュール化による競合回避

問題2: コミット履歴が混乱

症状: 履歴が追いにくい、変更理由が不明

原因:

• コミットメッセージが不適切
• 粒度が不均一

解決策:

1. コミット規約の導入
2. commitlintによる強制
3. squashマージの活用

問題3: レビューが滞る

症状: PRが長期間放置される

原因:

• レビュー担当が不明確
• PRが大きすぎる

解決策:

1. 明確なレビュアー指定
2. PRサイズの制限
3. 自動リマインダーの設定

関連スキル

• .claude/skills/technical-documentation-standards/SKILL.md (.claude/skills/technical-documentation-standards/SKILL.md): 技術文書化標準
• .claude/skills/documentation-architecture/SKILL.md (.claude/skills/documentation-architecture/SKILL.md): ドキュメント構造設計

メトリクス

コミット品質

測定方法: 規約準拠コミット数 / 総コミット数 目標: 100%

レビュー時間

測定方法: PR作成からマージまでの平均時間 目標: <24時間（ドキュメントPR）

マージコンフリクト率

測定方法: コンフリクトを含むPR数 / 総PR数 目標: <10%

変更履歴

バージョン	日付	変更内容
1.0.0	2025-11-25	初版作成 - Git Diff、コミット規約、レビューワークフロー

使用上の注意

このスキルが得意なこと

• ドキュメントのバージョン管理設計
• コミット規約の策定
• レビューワークフローの構築
• CHANGELOG生成の自動化

このスキルが行わないこと

• 文書の具体的なコンテンツ作成
• Git自体の詳細な操作説明
• 実際のGitコマンドの実行

参考文献

• Conventional Commits: https://www.conventionalcommits.org/
• Keep a Changelog: https://keepachangelog.com/
• Git Documentation: https://git-scm.com/doc
• 『Pro Git』 Scott Chacon & Ben Straub著