write-adr

このスキルでは、PRD と合わせて、AI 開発エージェントが曖昧さなく機能やアプリケーションを実装するために必要な情報をすべて備えた ADR ドキュメントを 1 つ以上作成します。技術的な決定、判断の根拠、図、データ構造、テスト計画をすべてここで定義し、実装を担当するエージェントがアーキテクチャについて推測する必要がないようにします。

PRD では意図的に扱わない技術的な実装の詳細とテスト戦略は、ここで定義します。

---

プロセス

ステップ 1 — PRD を読む（存在する場合）

docs/PRD.md があるか確認します。見つかった場合は、作業を進める前に最後まで読みます。見つからない場合は、機能またはアプリケーションの説明をユーザーに求めます。具体的には、何をするものか、誰が使うのか、主なフローは何かを確認します。

ステップ 2 — 確認の質問をする（必須 — 最低 5 問）

ADR を作成する前に、焦点を絞った確認の質問を最低 5 つユーザーに尋ねます。回答を得るまでは書き始めないでください。PRD、ユーザー、またはコードベースですでに回答されている話題については、同じ質問を繰り返すのではなく、別の決定事項について、より踏み込んだ質問をします。関連する話題には、次のようなものがあります。

• 使用中、または使用を希望するフレームワーク、言語、ランタイム環境は何ですか？
• すでに決定しているライブラリやツールはありますか？Context7 ID がわかっている場合は、ステップ 3 で記録します。
• デプロイ上の制約はありますか？ローカル開発のみ、Docker、クラウド、サーバーレスなど。
• 永続化の方針はどうなっていますか？使用するデータベースやストレージと、その理由は何ですか？
• 統合する外部 API やサービスはありますか？その制約は何ですか？
• この PoC／MVP で想定するパフォーマンスや規模はどの程度ですか？
• セキュリティ要件はありますか？認証、シークレット管理、データプライバシーなど。
• テスト要件はありますか？ユニットテストのみ、統合テスト、E2E テストなど。TDD を想定していますか？
• コードベースに従う必要がある既存のアーキテクチャパターンはありますか？

作成を始める前に、アーキテクチャに影響する決定事項を解決します。残る前提や未解決の質問は、回答を作り上げずに記録します。

ステップ 3 — 最新の技術ドキュメントを確認する

判断に影響するライブラリ、フレームワーク、SDK については、Context7 CLI（ctx7 または npx ctx7@latest）を優先して使用します。PRD または概要ですでに確認済みの Context7 ID が提示されている場合は、docs <libraryId> "<question>" で直接使用します。それ以外の場合は、まず library <name> "<question>" で ID を解決します。CLI が利用できない場合は、設定済みの Context7 MCP を使用します。どちらも利用できない場合は、公式ドキュメントを参照します。セットアップの詳細については、インストール済みの Context7 スキルに従います。

使用した確認済みの Context7 ID はすべて、ADR の Technology Documentation References テーブルに記録します。これにより、実装エージェントはライブラリを再解決せずに最新のドキュメントを直接取得できます。Context7 ID がない場合は、代わりに公式ドキュメントへのリンクを記録します。ID を捏造しないでください。

ステップ 4 — ADR の構成を決める

複雑さに応じて選びます。

シンプル（単一ファイルを使用）：

• 技術レイヤーが 1 つ、または単純な機能追加
• 統合するコンポーネントが 3 つ未満
• 保存先：docs/ADR/000-[short-description].md

複雑（複数ファイルを含むフォルダーを使用）：

• 複数の異なる技術レイヤー（例：フロントエンド + バックエンド + データベース + AI/LLM）
• 複数の統合ポイントまたは外部サービス
• 領域ごとの担当が必要な大規模なスコープ
• 保存先：
  • docs/ADR/000-main-architecture.md — システム全体、コンポーネントマップ、主要な決定事項
  • docs/ADR/001-[area].md、002-[area].md など — 技術領域ごとに 1 ファイル

ファイル名：ゼロ埋めの番号と、短い kebab-case の説明を使用します。ファイル名に「ADR」を含めないでください。その文脈はフォルダー名で示されます。 例：000-main-architecture.md、001-backend-api.md、002-frontend.md、003-database.md

ステップ 5 — ADR を作成する

以下のテンプレートを使用します。docs/ADR/ に保存します。

---

ルール

• 言語：依頼内容や会話の言語にかかわらず、ADR は常に英語で記述してください。
• コードスニペット禁止：実装コードは含めないでください。実装エージェントは、最新のドキュメントから正確な API の使用方法を確認できます。方法ではなく、内容を説明してください。
• 曖昧な記述の禁止：すべての制約、決定、要件は具体的で検証可能なものにしてください。PRD の受け入れ基準と同じ水準にします。
• 図は必須：該当するすべてのフローについて、アーキテクチャ図、データフロー図、シーケンス図を含めてください。その形式で表現できない場合に限り、その種類の図を省略してください。詳細であるほど望ましいです。
• テストは必須：すべての ADR にテスト戦略を含めてください。TDD は実装エージェントが自己検証するための主要な手段です。
• ドキュメントの参照先：利用可能な場合は Context7 ID を記録してください。それ以外の場合は、公式ドキュメントへのリンクを記録してください。ID を捏造しないでください。
• 目的：このドキュメントと PRD を合わせて、開発エージェントがシステムの全体像を把握できるようにします。実装に影響する決定事項はユーザーと解決し、それ以外の未解決の質問は明示的に記録してください。
• コードを実装しないでください：コードを実装するエージェントに必要な技術的詳細をすべて提供できるよう、アーキテクチャ決定（ADR）の記述に注力してください。

---

ADR-000 テンプレート — メインアーキテクチャ（または単一 ADR）

# ADR: [Product / Feature Name] — Main Architecture

**Date:** [today]
**Status:** Accepted
**PRD:** [link to docs/PRD.md if exists]

---

## 1. Overview

What is being built. What problem it solves. How this ADR relates to the PRD.

---

## 2. Technology Documentation References

Libraries, frameworks, and SDKs relevant to the decisions below. Record each verified Context7 ID so implementing agents can fetch current docs directly without searching again; use an official documentation link when no ID is available.

| Library | Context7 ID or official docs | Used for |
|---|---|---|
| [Library name] | `/org/repo` | [purpose] |

---

## 3. System Architecture

### Architecture pattern
[e.g., monolith, monorepo, microservices, SPA + REST API, etc.]

### Repository structure
Describe the repo layout: folders, modules, build artifacts, how frontend and backend relate.

### Technology stack
List each layer with the chosen technology and one-sentence justification.

| Layer | Technology | Reason |
|---|---|---|
| Backend | | |
| Frontend | | |
| Database | | |
| AI/LLM | | |
| ... | | |

---

## 4. Module Structure & Dependencies

List all modules/packages/services. For each:
- What it is responsible for
- What it depends on
- What depends on it

Describe the dependency direction explicitly. No circular dependencies.

---

## 5. Data Models

Describe each entity/model conceptually:
- Name and purpose
- Key fields and their types (conceptual, not schema code)
- Relationships to other models
- Persistence (where it is stored, how long)

---

## 6. API / Interface Contracts

For each endpoint or interface boundary:
- Name / path
- Input (fields, types, constraints)
- Output (fields, types)
- Error cases
- Notes (auth required, rate limit, streaming, etc.)

No code. Conceptual contracts only.

---

## 7. Environment Variables

All required environment variables the application needs to run.

| Variable | Purpose | Required | Example value |
|---|---|---|---|
| | | Yes/No | |

---

## 8. Technical Decisions

One record per significant decision. Use the format below.

### [short title]
**Status:** Accepted | Proposed | Superseded
**Date:** [today]
**Context:** Why this decision was needed. What problem or constraint triggered it. (2-3 sentences)
**Decision:** What was decided. Brief reasoning — why this option over others.
**Rejected alternatives:**
- [Alternative A]: [1-2 sentences why rejected]
- [Alternative B]: [1-2 sentences why rejected]
**Consequences:**
- (+) [positive consequence]
- (-) [negative consequence or trade-off]
**Review trigger:** [Specific condition that would require revisiting this decision. E.g., "If concurrent sessions exceed 100/day", "If we add authentication", "If we move to production"]

---

## 9. Diagrams

### 9.1 Architecture / Component Diagram
[Mermaid diagram showing components and their relationships]

```mermaid
...
```

### 9.2 Data Flow Diagram
[Mermaid diagram showing how data moves through the system]

```mermaid
...
```

### 9.3 Sequence Diagrams
One diagram per main flow. Cover: happy path, error path, and any async/streaming flows.

#### [Flow name — e.g., Form submission and AI analysis]
```mermaid
sequenceDiagram
...
```

#### [Flow name — e.g., Session resume]
```mermaid
sequenceDiagram
...
```

---

## 10. Testing Strategy

### Philosophy
Describe the testing approach. TDD is recommended — tests should be written before or alongside implementation and serve as the agent's primary self-validation mechanism.

### Test layers

| Layer | Type | Scope | Tools |
|---|---|---|---|
| Unit | | | |
| Integration | | | |
| E2E | | | |

### Key test scenarios

List the most important scenarios to cover. For each:
- Scenario name
- What is being tested
- Input conditions
- Expected output / behavior
- Edge cases to cover

Include both happy path and failure/edge cases.

### Technical acceptance criteria

Measurable, verifiable criteria that confirm the implementation is correct from a technical standpoint (complement the business ACs in the PRD).

- TAC-01: [concrete, testable statement]
- TAC-02: ...

---

詳細 ADR テンプレート（ADR-001 以降）

複雑なプロジェクトでは、技術領域ごとにこのテンプレートを使用してください。

# ADR-[NNN]: [Technical Area Name]

**Date:** [today]
**Status:** Accepted
**Relates to:** `docs/ADR/000-main-architecture.md`

---

## 1. Scope

What technical area this ADR covers. What it does NOT cover (leave to other ADRs).

---

## 2. Technology Documentation References

Libraries specific to this area, with verified Context7 IDs or official documentation links.

| Library | Context7 ID or official docs | Used for |
|---|---|---|

---

## 3. Component Design

Describe the internal design of this area:
- Layers / classes / services and their responsibilities
- Key interfaces and contracts between them
- State management (if any)

---

## 4. Data Structures

Models, DTOs, request/response shapes specific to this area. Conceptual descriptions, no code.

---

## 5. Interface Contracts

Endpoints, events, or method signatures this area exposes or consumes. Input/output/error for each.

---

## 6. Technical Decisions

[Same ADR record format as in the main architecture template]

---

## 7. Diagrams

### Component / Class Diagram
```mermaid
...
```

### Sequence Diagrams
```mermaid
sequenceDiagram
...
```

---

## 8. Testing Strategy

### Test scenarios for this area

| Scenario | Type | Input | Expected output | Edge cases |
|---|---|---|---|---|

### Technical acceptance criteria

- TAC-[NNN]-01: [concrete, testable statement]