AI主導開発前提でのGithub Issueとdocs/以下の棲み分け v0.1

docs-rules.ja.md

---
id: docs-rules
title: docs/ ディレクトリ運用ルール
status: stable
owner: platform-team
tags: [guidelines, docs, rules]
updated: 2025-08-23
lang: ja
ai:
  summary: "docs/ 配下のディレクトリ構造・命名規則・テンプレート・Issue連携のルールを定義したガイドライン"
  index: true
---

docs/ ディレクトリ運用ルール

本ドキュメントは、docs/ 配下の構造と使い分けを確定ルールとして定義したものです。
人間もAIも、このルールに従ってドキュメントを配置・更新してください。

1. GitHub Issue と docs の棲み分け

• GitHub Issue

  • バグ報告、顧客要望、質問、議論の入口
  • 一過性の情報や顧客固有の内容はここに残す
  • ラベル付与 (type:bug, type:feature, needs-docs など) を必須とする

• docs/

  • 再利用される知識・設計・手順・方針
  • 結論や恒久的に参照されるべき情報のみを配置
  • needs-docs が付いた Issue をクローズする際は必ず docs を更新する

2. ディレクトリ構造（固定）

docs/
00-overview/         # 全体像・用語集・FAQ・このルール文書
10-concepts/         # 設計思想・原則・ベストプラクティス
20-architecture/     # システム構成・依存関係・データフロー
30-specs/            # API / スキーマ / イベント定義
40-design-decisions/ # RFCとADR（提案と決定の記録）
50-runbooks/         # 運用手順（障害対応・定常タスク）
60-guides/           # How-to / チュートリアル（目的達成ガイド）
70-security/         # セキュリティ・コンプライアンス文書
80-changelog/        # リリースノート・更新履歴
_shared/             # 図・共通スニペット
_index/              # 自動生成の索引ページ

3. 配置ルール（カテゴリごとの基準）

• 00-overview/

  • 本ルール文書、用語集、FAQ、組織/サービスの全体説明

• 10-concepts/

  • 「なぜ・何を」レベルの原則や思想
  • 例: ドメインモデルの基本概念、設計方針

• 20-architecture/

  • システム構成図、データフロー、依存関係
  • 例: サービス間の通信図、クラウド構成図

• 30-specs/

  • API仕様、DBスキーマ、イベント定義
  • 変更時は必ずここを更新

• 40-design-decisions/

  • RFC = 大きな提案や設計案（Issueから昇格）
  • ADR = RFC/議論の結論を簡潔に残したもの
  • 提案と結論を同居させる（歴史を追いやすくするため）

• 50-runbooks/

  • 障害対応や定常作業の具体手順
  • 「誰でもすぐ対応できる」形式にする

• 60-guides/

  • How-to やチュートリアル（開発者やユーザー向け）
  • 例: 新しい環境のセットアップ方法、機能利用ガイド

• 70-security/

  • 一過性でないセキュリティ方針・規範
  • 例: 脅威モデル、暗号化ポリシー、アクセス制御モデル
  • インシデント対応の基本方針はここ、具体手順は runbooks/ に

• 80-changelog/

  • リリースノート、重要な更新履歴

• _shared/

  • 共通の画像・図表・スニペットコード

• _index/

  • CI により自動生成されるタグ・Owner・ステータス・更新日の索引ページ
  • 手動編集は禁止

4. ファイル命名規則

• 基本形式: kebab-case.md
  • 例: db-failover-runbook.ja.md, session-store-redis.adr.md
• 日付が必要な場合:
  • RFC, ADR, Changelog には必ず日付を付ける
  • 形式: YYYY-MM-DD-短い説明.md
  • 例:
    • 2025-08-23-rfc-search-migration.md
    • 2025-08-23-adr-elasticsearch-choice.md
    • 2025-08-23-release-v1.2.0.md
• 多言語対応:
  • README.ja.md, README.en.md の形式
  • 例: onboarding-guide.ja.md, onboarding-guide.en.md

5. Frontmatter の必須項目

すべての Markdown 文書は以下の Frontmatter を持つこと。

---
id: 一意のID（変更不可）
title: 文書タイトル
status: draft | review | stable | deprecated
owner: チーム名または責任者
tags: [キーワード1, キーワード2]
updated: YYYY-MM-DD
lang: ja | en
ai:
  summary: "AIが即座に理解できる要約（1–3文）"
  index: true
---

6. RFC と ADR の書き分け

• RFC

  • 大きな変更提案や設計案をまとめる
  • 複数の選択肢や代替案を明示
  • 状態: draft または review

• ADR

  • RFCの結論を簡潔に記録
  • 「いつ・なぜ・どう決めたか」を残す
  • 状態: stable または deprecated

両者は docs/40-design-decisions/ に配置する。

---

7. セキュリティ文書の扱い

• 70-security/ に置くもの

  • 脅威モデル
  • 認証・認可ポリシー
  • 暗号化方針
  • 秘密情報の扱いルール
  • セキュリティレビュー手順
  • インシデント対応方針（Runbookへのリンクを付ける）

• Issueにのみ残すもの

  • 個別の脆弱性報告
  • 顧客固有のセキュリティ要件

---

8. 自動チェックとインデックス

• CIで以下を実行する：

  • Frontmatter 必須フィールド検証
  • 相互リンク（Issue ↔ docs）のチェック
  • needs-docs が付いた Issue が docs 更新なしに閉じられていないか確認
  • _index/ の再生成（タグ・Owner・ステータス・更新日別）

9. ディレクトリ分割ルール

• 各カテゴリのファイル数が 50を超えたらサブディレクトリ導入を検討

  • 例: 50-runbooks/incident/, 50-runbooks/operations/
  • 例: 30-specs/api/, 30-specs/db/

• サブディレクトリを切っても idは変更しない（永続リンク担保）

10. Changelog の特別ルール

• ファイル名は必ず日付付き: YYYY-MM-DD-release-vX.Y.Z.md

• 内容は以下を必須とする:

  • 新機能
  • 修正
  • 非互換変更

• 80-changelog/README.ja.md に最新リリースへのリンクを追記する

11. 人とAIの使い分け

• 人間は Issueだけ書けばよい。結論を docs に昇格するのはエンジニア/PMの責務
• AIは docs を優先的に参照し、Issueは補助的に使う
• AIが docs を生成する場合、本ルールに従って配置・Frontmatterを自動付与する

結論

• Issue = 窓口と議論
• docs = 長期資産
• RFC = 提案、ADR = 結論
• セキュリティは再利用可能な知識だけdocsに残す
• AIはこのルールを基準に必ず正しい場所に配置する
• 命名規則・日付ルール・テンプレートを厳守する