governance

ガバナンス文書

ガバナンス文書を作成、管理します。アーキテクチャ上の決定には ADR、要件の変更には CR を使用します。

文書の選択

必要な内容	文書	ガイド
技術上またはアーキテクチャ上の決定	ADR	reference/adr-guide.md
要件またはスコープの変更	CR	reference/cr-guide.md

ガバナンス参照の境界

ガバナンス識別子（CR-、ADR-、FR-、NFR-、AC- の各プレフィックスに数字が続く形式）は、docs/ 配下のガバナンス文書群と、コミットメッセージ、ブランチ名、プルリクエストの説明などの Git メタデータに記載します。ソースコード、テスト名、ユーザー向けドキュメントには記載してはなりません。実装とガバナンス文書を関連付けるには、コミットメッセージに識別子を記載し、コードには動作そのものを記述します。パターンの定義、許可・禁止される範囲、その理由について詳しくは、reference/cr-guide.md#governance-reference-boundary を参照してください。

ADR ワークフロー

ドキュメントのみのタスクです。 ADR の作成はドキュメントのみのタスクです。コードのコンパイル、テストの実行、リンティングは必要ありません。

Architecture Decision Record を作成する際は、このチェックリストを使用してください。

- [ ] Read the template: templates/ADR.md
- [ ] Check docs/adr/ for the next available number
- [ ] Capture current branch (`git rev-parse --abbrev-ref HEAD`) and commit (`git rev-parse --short HEAD`)
- [ ] Create file: docs/adr/ADR-NNNN-{short-title}.md
- [ ] Fill in all required sections (including source-branch and source-commit in frontmatter)
- [ ] Set status to "proposed"

テンプレートのフロントマター： 作成する ADR には、その決定内容を反映した独自の name と description を記載し、テンプレートのメタデータは含めません。テンプレートの name と description はテンプレート自体を説明するものなので、置き換えてください。コピーするテンプレートのメタデータはほかにありません。

厳守する要件：

• ファイル名：ADR-NNNN-{title}.md（4 桁の番号、小文字、ハイフン）
• 初期ステータス：proposed
• 保存場所：プロジェクトの docs/adr/ フォルダー

状況に応じて調整可能：

• 代替案セクションの詳細度
• 記載する結果の数
• 図の掲載（複雑な決定では推奨）

CR ワークフロー

ドキュメントのみのタスクです。 CR の作成はドキュメントのみのタスクです。コードのコンパイル、テストの実行、リンティングは必要ありません。

Change Request を作成する際は、このチェックリストを使用してください。

- [ ] Read the template: templates/CR.md
- [ ] Check docs/cr/ for the next available number
- [ ] Capture current branch (`git rev-parse --abbrev-ref HEAD`) and commit (`git rev-parse --short HEAD`)
- [ ] Create file: docs/cr/CR-NNNN-{short-title}.md
- [ ] Fill in all required sections (including source-branch and source-commit in frontmatter)
- [ ] Write acceptance criteria in Gherkin format
- [ ] Decide whether the change has a user surface: fill in the Model-Based Testing section if it does, remove the section if it does not
- [ ] Set status to "proposed"

テンプレートのフロントマター： 作成する CR には、その変更要求を反映した独自の name と description を記載し、テンプレートのメタデータは含めません。テンプレートの name と description はテンプレート自体を説明するものなので、置き換えてください。コピーするテンプレートのメタデータはほかにありません。

厳守する要件：

• ファイル名：CR-NNNN-{title}.md（4 桁の番号、小文字、ハイフン）
• 初期ステータス：proposed
• 保存場所：プロジェクトの docs/cr/ フォルダー
• 受け入れ基準：Gherkin 形式（Given-When-Then）
• 要件キーワード：RFC 2119（MUST、SHOULD、MAY）

状況に応じて調整可能：

• 文書の長さ（複雑な変更では最低 250 行）
• 図の数
• 影響評価の詳細度
• モデルベーステストのセクションの有無（ユーザーサーフェステストに基づいて判断）

作成済み CR の実装

CR の作成後は、reference/cr-implementation-workflow.md に記載された、特定のプロジェクトに依存しないエージェントチームのワークフローを利用できます。このワークフローでは、レビューから段階的な実装、最終化、検証、不足箇所の修正、ドキュメントの作成までを進めます。ホストプロジェクト独自のビルド、リンティング、テストの規約に従います。

テンプレート

• ADR：templates/ADR.md
• CR：templates/CR.md

リファレンスガイド

ライフサイクル、ベストプラクティス、例について詳しくは、以下を参照してください。

• ADR ガイド：reference/adr-guide.md
• CR ガイド：reference/cr-guide.md
• CR 実装ワークフロー：reference/cr-implementation-workflow.md — 既存の CR を実装するためのエージェントチームのワークフロー

コミットメッセージの形式

ガバナンス文書のコミットは人間の責任です。コミットする準備ができたら、次の形式を使用してください。

• ADR: docs(adr): add ADR-NNNN {title}
• CR: docs(cr): add CR-NNNN {title}