AI時代の開発に最適化されたリポジトリドキュメント構成のスターターキット
Note
叩き台としての側面が強いので、プロジェクトの実情に合わせて適宜カスタマイズすることを推奨。
mcpやコード、CI/CDなどでこれらを制御できることが理想だが前提としてプロジェクトに対してこれらの情報を人間が言語化して整備できている必要があるという思想のもと作成した。
当初の仮説: AI専用のドキュメント（.ai/）が必要
結論: すべてのドキュメントを docs/ に統一し、人間とAIが同じ情報源を参照
理由:
- AI向けコンテキストは専用ツール（GitHub Copilot, Claude Desktop）の設定で管理可能
- AI向けと思われた情報は、実は人間にも必要な設計情報
- 情報の分断はメンテナンスコストを増大
問題: API仕様やDB設計をMarkdownで手書きすると、コードと二重管理になる
解決策: Single Source of Truth（SSOT）の原則
- コードで表現できるもの: コードを唯一の情報源とし、ドキュメントは自動生成
- コードで表現できないもの: 設計の意図・判断理由のみを手書き
実装例:
- API仕様: API定義ファイル → ドキュメント生成ツール
- DB設計: モデル定義 → ER図生成
- インフラ: IaCコード → 構成図生成
問題: フロントエンド、バックエンド、インフラが別リポジトリの場合、ドキュメントをどこに配置すべきか
解決策: リポジトリの責務に応じた配置
| リポジトリ | 配置するドキュメント |
|---|---|
project-docs |
機能仕様、システム全体構成、ADR、運用手順 |
project-ui |
UI設計、フロントエンド実装ガイド |
project-api |
API/DB設計、バックエンドAPI実装ガイド |
project-workers |
バッチ/ワークフロー設計、実装ガイド(UI,API,IaC以外のケースと考えて良い) |
project-infrastructure |
インフラ設計、デプロイ・運用手順 |
詳細: guides/multi-repo-strategy.md
問題: 新機能追加・改修が継続的に行われる中で、ドキュメントをどう管理するか
解決策: 機能ベースのドキュメント構成
- features/: 機能ごとにディレクトリを作成し、独立して管理
- ユーザーストーリー: 各機能のoverview.mdで管理
- システムマニュアル: specifications.mdがそのまま利用可能
上記の課題を解決し、以下を実現するドキュメント構成テンプレート:
- 人間とAIが同じ情報を参照
- コードとドキュメントの冗長性を排除
- マルチリポジトリ環境に対応
- ビジネス契約書との適切な分離
このテンプレートの役割:
- 重要な観点の抜け漏れ防止: 検討すべき項目を網羅的にリストアップ
- 曖昧な箇所の明示化: 設計判断が必要な箇所をプレースホルダーで示す
- 設計判断の記録: 「何を選んだか」「なぜ選んだか」を記録する構造を提供
テンプレートの抽象度:
- ❌ 具体的な技術名・手法名は記載しない（例: JWT、SQLインジェクション、TLS 1.2）
- ✅ 検討すべき観点のみを記載（例: 認証方式、入力検証、通信暗号化）
- ✅ プレースホルダー
[...]でチームが記入すべき箇所を明示
使い方:
- テンプレートの項目を確認
- 各項目について設計判断を行う
- プレースホルダーに具体的な内容を記入
- 不要な項目は削除、必要な項目は追加
定義: 情報の源泉が明確で唯一のものはそれを使用する
適用:
- API仕様: API定義ファイル
- DB設計: モデル定義 + マイグレーションファイル
- インフラ構成: IaCコード
手書きのドキュメント/コメントに記載すべきもの:
- 設計の意図
- 選択理由
- トレードオフ
- ビジネスルール
定義: 各リポジトリはその責務に関するドキュメントのみを持つ
例:
- API リポジトリ: API設計、DB設計を記載
- UI リポジトリ: UI設計、コンポーネント設計を記載
- Workers リポジトリ: バッチ/ワークフロー設計を記載
- インフラリポジトリ: インフラ設計を記載
- 全体統括リポジトリ: システム全体構成、リポジトリ間連携を記載
- 一般にはコンフルなどが該当するがあえてリポジトリとして管理し、サブモジュールなどで活用しても良い
定義: 手作業で維持できるものは自動化する
実装:
- スクリプトやOSS: ドキュメント自動生成
- CI/CD: PRマージ時の自動生成・デプロイ
- Pre-commit hooks: ドキュメント更新忘れの防止
定義: ドキュメントの詳細度はフェーズに応じて段階的に充実
フェーズ別の記載内容:
| フェーズ | 記載するドキュメント |
|---|---|
| 設計 | アーキテクチャ、設計方針 |
| 実装 | 実装ガイド（学習型） |
| 運用 | 運用手順、トラブルシューティング（学習型） |
学習型ドキュメント: 実装を通じて徐々に充実させる
micro-adr.md: Micro ADR（軽量なアーキテクチャ決定記録）- 実装時の判断とその理由を記録
- 代替案と選択理由
- トレードオフの記録
templates/
├── project-docs/ # プロジェクト全体統括用
├── backend-api/ # バックエンドAPIリポジトリ用
├── workers/ # ワーカーリポジトリ用
├── frontend/ # フロントエンドリポジトリ用
└── infrastructure/ # インフラリポジトリ用
docs/
├── features/ # 機能ごとのドキュメント
│ ├── user-authentication/
│ │ ├── overview.md # 機能概要・ユーザーストーリー
│ │ ├── specifications.md # 機能仕様（システムマニュアル）
│ │ └── api-contracts.md # リポジトリ間API契約
│ ├── payment-processing/
│ └── notification-system/
│
├── architecture/
│ ├── system-overview.md # システム全体構成
│ ├── decisions/ # ADR（重要な技術選定）
│ │ ├── 001-use-microservices.md
│ │ ├── 002-database-selection.md
│ │ └── README.md
│ └── cross-cutting-concerns.md # 横断的関心事
│
├── glossary.md # ドメイン用語集（ユビキタス言語）
│
└── operations/
├── release-process.md # リリースフロー
└── runbook.md # 運用手順
設計思想:
- 機能ベース: 新機能追加時は
features/配下に新ディレクトリを追加 - Git管理: 変更履歴はGitで追跡（changelog不要）
- ユーザー視点: 各機能のspecifications.mdがシステムマニュアルとして機能
docs/
├── design/
│ ├── README.md # 設計書の読み方
│ ├── architecture.md # API層アーキテクチャ
│ ├── database.md # DB設計（意図のみ）
│ ├── domain-model.md # ドメインモデル
│ └── security.md # セキュリティ設計
│
├── implementation/
│ ├── coding-guidelines.md # コーディング規約
│ └── micro-adr.md # 実装判断ガイド
│
├── testing/
│ └── test-guide.md # テストガイド
│
└── development/
├── setup.md # 環境構築
└── local-development.md # ローカル開発
重要: docs/design/README.md で自動生成ドキュメントとの関係を明示
docs/
├── design/
│ ├── README.md # 設計書の読み方
│ ├── architecture.md # ワーカーアーキテクチャ
│ ├── workflow-design.md # ワークフロー設計
│ └── scheduling.md # スケジューリング設計
│
├── implementation/
│ ├── coding-guidelines.md # コーディング規約
│ └── micro-adr.md # 実装判断ガイド
│
├── testing/
│ └── test-guide.md # テストガイド
│
└── development/
├── setup.md # 環境構築
└── local-development.md # ローカル開発
docs/
├── design/
│ ├── README.md # 設計書の読み方
│ ├── ui-architecture.md # UI層アーキテクチャ
│ ├── component-design.md # コンポーネント設計
│ └── state-management.md # 状態管理設計
│
├── implementation/
│ ├── coding-guidelines.md
│ └── micro-adr.md
│
└── development/
└── setup.md
docs/
├── design/
│ ├── README.md
│ ├── network-design.md # ネットワーク設計
│ ├── security-design.md # セキュリティ設計
│ └── cost-estimation.md # コスト見積
│
├── operations/
│ ├── deployment.md # デプロイ手順
│ ├── disaster-recovery.md # DR計画
│ └── monitoring.md # 監視設定
│
└── development/
└── setup.md
# バックエンドAPIリポジトリの場合
cd your-api-repo
cp -r /path/to/repo-docs-starter/templates/backend-api/docs ./docsnpx degit japanese-wolf/repo-docs-starter/templates/backend-api your-api-repocd existing-repo
# docsディレクトリのみ追加
cp -r /path/to/repo-docs-starter/templates/backend-api/docs ./docs
# 既存ドキュメントとマージ
# 必要に応じて手動で統合各テンプレートファイルの [...] プレースホルダーを実際の情報に置き換え:
[PROJECT_NAME]→ 実際のプロジェクト名[REPOSITORY_URL]→ GitHubリポジトリURL[技術名]→ 使用技術
ドキュメントを更新した上で、各リポジトリへの配置かサブモジュールなどを使用してAIエージェントに対するコンテキストや制約として使用する。