Work Documentation

Appearance

Decision Record Creation Guide ​

本ガイドは、システムアーキテクチャや技術選定、設計方針に関する重要な意思決定を記録・追跡するために <root>/docs/decision-records/ 配下に作成する意思決定記録（DR-XXX.md）の記述内容とMarkdownテンプレートを定義するものです。

Rules & Section Guidelines ​

1. 命名規則・番号管理 ​

  • ファイル名: DR-XXX.md の形式で3桁以上の連番により管理します（例: DR-001.md, DR-002.md）。
  • 台帳への登録: ファイルを作成した際は、必ず <root>/docs/decision-records/index.md の一覧テーブルに登録・追記してください。

2. 改訂と新規作成の判断基準 ​

  • 新規DR作成（破壊的変更）: 既存の決定内容を根本から覆す変更や非互換な方針転換（コミットにおける BREAKING CHANGES 相当）を行う場合は、既存DRを上書きせず新規にDRを発番・作成します。
    • 旧DRのステータスは SUPERSEDED に更新し、新DRへのリンクを明記します。
  • 既存DRの改訂（軽微な変更・修正）: 誤字脱字の修正、説明の補足・明確化、関連ドキュメントリンクの追加など、決定方針自体を覆さない軽微な変更・修正の場合は既存DRを改訂できます。
    • 改訂時は、末尾の「更新履歴」セクションに日付と変更内容を記録します。

3. フロントマターとステータス管理 ​

  • 標準項目（name, description, timestamp, ai）に加え、status, review キーを記述します。
  • status の値:
    • PROPOSED: 提案中・議論中
    • ACCEPTED: 承認・採択済み
    • REJECTED: 却下・非採択
    • DEPRECATED: 非推奨・廃止
    • SUPERSEDED: 後続の意思決定により置換済み（DR-YYY により置換等）
  • フロントマター review: result (ACCEPTED | REJECTED), timestamp, reason (REJECTED時の1行理由サマリー。ACCEPTED時は "")
  • ステータス更新: ステータス変更時は、update-document-status スキルを使用してフロントマターおよび台帳（docs/decision-records/index.md）を一括更新すること。

4. 必須セクション構成 ​

  1. コンテキストと背景 (Context & Problem Statement)
    • 意思決定が必要となった背景、解決すべき課題、制約条件を記述します。
  2. 決定事項 (Decision)
    • 採択した方針や技術選定結果を明確に記述します。
  3. 検討した選択肢 (Options Considered)
    • 比較・検討した他の代替案とそのメリット・デメリットを記述します。
  4. 帰結・影響 (Consequences)
    • この決定によって生じるプラス・マイナスの影響やトレードオフ、今後のアクションを記述します。
  5. 関連ドキュメントとのインライン相互リンク必須化
    • この意思決定によって影響を受ける・決定根拠となる設計書や仕様書（architecture.md, design.md, SPEC-XXX.md 等）が存在する場合、 対象記述の直後に ([DR-001](...)) 形式でインラインリンクを記述 するとともに、「帰結・影響」または「関連」セクション内に相互リンクを明記します。
  6. 更新履歴 (Changelog)
    • 初版作成日および改訂時の日付・変更内容を時系列で記述します。

Template ​

以下は意思決定記録（DR-001.md）を作成する際の標準Markdownテンプレートです。

markdown
---
name: DR-001.md
description: <意思決定事項の1行概要>
timestamp: YYYY-MM-DD
ai: ai-coauthored
status: ACCEPTED # PROPOSED | ACCEPTED | REJECTED | DEPRECATED | SUPERSEDED
review:
  result: "" # ACCEPTED | REJECTED
  timestamp: "" # YYYY-MM-DD
  reason: "" # REJECTED時の1行理由サマリー
---

# DR-001: <意思決定タイトル・件名>

## コンテキストと背景

<意思決定が必要となった背景、発生していた問題、技術的/ビジネス的制約条件を記述します。>

## 決定事項

<最終的に採択・決定した方針や技術選定の内容を明確に記述します。>

## 検討した選択肢

### 選択肢 1: <案1の名称 (採択案)>

-   **メリット**: <メリットを記述>
-   **デメリット**: <デメリットを記述>

### 選択肢 2: <案2の名称>

-   **メリット**: <メリットを記述>
-   **デメリット**: <デメリットを記述>

## 帰結・影響

-   **プラスの影響**: <決定によって得られる効果やポジティブな結果>
-   **マイナスの影響 / トレードオフ**: <決定に伴う受容すべきリスクや課題>
-   **関連ドキュメント (必須)**:
    -   [`architecture.md`](../architecture.md)
    -   [`SPEC-001`](../auth/specs/SPEC-001.md)

## 更新履歴

-   YYYY-MM-DD: 初版作成
-   YYYY-MM-DD: <軽微な修正・更新内容を記述>