Use Git for Documentation Management

コンテキスト

技術ドキュメントの管理方法は、チームの生産性と知識共有の効率に大きな影響を与える。従来、多くの組織ではConfluenceやNotionなどのWikiベースのドキュメント管理ツールを使用してきたが、以下の課題が存在している。

ドキュメントの変更履歴の追跡が困難
コードとドキュメントの同期が取れない
レビュープロセスが確立されていない
AIツールやIDEからのアクセスが制限的
エクスポート・移行が困難で、ベンダーロックインのリスクがある

また、AI駆動開発の普及により、ドキュメントがAIツールからアクセス可能であることが重要になっている。AI開発支援ツールは、コードベースと同じリポジトリ内のドキュメントを参照して、プロジェクト固有のコンテキストに基づいた支援を提供できる。

決定事項

技術ドキュメントの管理にGitを使用する。ADRは中央集約型のこのリポジトリで管理し、各プロダクト固有のDesign Documentはそれぞれのプロダクトリポジトリで管理する。

選択肢

選択肢1: Git管理（採用案）

利点:
- バージョン管理が完全で、変更履歴が明確
- コードと同じワークフローでレビュー可能（Pull Request）
- AIツールがリポジトリ内のドキュメントに直接アクセス可能
- Markdownベースでプレーンテキスト、移行が容易
- オフラインでの編集・閲覧が可能
- 検索・grep・sedなどのテキスト処理ツールが使用可能
- コードとドキュメントの同期が保たれる
欠点:
- 非技術者にとって学習コストが高い
- リアルタイムコラボレーション機能がない
- 画像や図表の管理がやや煩雑
- WYSIWYGエディタがない

選択肢2: Confluence

利点:
- 豊富なWYSIWYGエディタ
- 非技術者でも使いやすい
- 検索機能が充実
- Jiraとの統合
欠点:
- バージョン管理が弱い
- レビュープロセスが確立しづらい
- AIツールからのアクセスが困難
- エクスポート時にフォーマットが崩れる
- 有料ライセンスが必要

選択肢3: Notion

利点:
- 直感的なUI
- データベース機能
- リアルタイムコラボレーション
- 柔軟なページ構造
欠点:
- APIアクセスが限定的
- バージョン管理が不十分
- 大規模な技術ドキュメントには不向き
- パフォーマンスの問題
- ベンダーロックイン

選択肢4: GitHub Wiki

利点:
- GitHubとの統合
- Markdownサポート
- 基本的なバージョン管理
欠点:
- 機能が限定的
- Pull Requestによるレビューができない
- ローカル編集が煩雑
- 構造化が困難

結果

この決定による影響を記述する。

ポジティブな影響:
- ドキュメントの品質向上（レビュープロセスによる）
- AI開発支援ツールの効果的な活用
- ドキュメントとコードの一貫性向上
- 移行・バックアップが容易
- 開発者にとって馴染みのあるワークフロー
ネガティブな影響:
- 非技術者の参加障壁が高くなる
- 初期セットアップの手間
- リアルタイムコラボレーションの欠如
リスク:
- 非技術者からのドキュメント貢献が減少する可能性
- 画像やダイアグラムの管理が複雑になる
- ドキュメントサイトの構築・ホスティングが必要

実装ガイドライン

ディレクトリ構造

# ADRリポジトリ（中央集約）
architecture-decision-records/
├── src/content/docs/
│   ├── common/          # 共通技術のADR
│   └── products/        # プロダクト固有のADR

# プロダクトリポジトリ
product-repo/
├── docs/
│   ├── design/          # Design Documents
│   ├── api/             # API仕様書
│   └── guides/          # 開発ガイド
└── CLAUDE.md            # AI向けコンテキスト

Markdownガイドライン

ファイル名はkebab-caseを使用
画像はdocs/images/に配置
相対パスでリンク
フロントマターでメタデータ管理

AI活用のベストプラクティス

# CLAUDE.md や README.md に含める内容
- プロジェクトの概要と目的
- 主要な技術スタック
- ディレクトリ構造の説明
- 重要な設計決定へのリンク
- 開発規約とコーディングスタイル