write-adr

这项技能会创建一份或多份 ADR 文档，与 PRD 一起为 AI 开发 Agent 提供实现功能或应用所需的全部信息，避免产生歧义。此处会定义所有技术决策、推理过程、图表、数据结构和测试计划，让负责实现的 Agent 无需猜测架构。

PRD 中有意排除的技术实现细节和测试策略应在此处说明。

---

流程

步骤 1 — 阅读 PRD（如果存在）

检查 docs/PRD.md。如果找到，请在继续之前完整阅读。如果未找到，请让用户提供功能或应用的说明：它的用途、使用者以及主要流程。

步骤 2 — 提出澄清问题（必须 — 至少 5 个）

撰写任何 ADR 之前，至少向用户提出 5 个有针对性的澄清问题。在获得回答之前不要开始撰写。如果 PRD、用户或代码库已经回答了某个主题，请针对其他决策提出更深入的问题，而不是重复提问。相关主题包括：

• 正在使用或倾向使用哪些框架、语言和运行环境？
• 是否已决定使用特定库或工具？如果已知其 Context7 ID，请记录下来以供步骤 3 使用。
• 部署约束有哪些——仅限本地开发、Docker、云端还是无服务器？
• 持久化策略是什么——使用哪种数据库或存储，原因是什么？
• 是否要集成外部 API 或服务？它们有哪些约束？
• 此 PoC/MVP 对性能或规模有何预期？
• 是否有安全要求（身份验证、密钥管理、数据隐私）？
• 有哪些测试要求——仅单元测试、集成测试还是端到端测试？是否要求采用 TDD？
• 代码库中是否有必须遵循的现有架构模式？

撰写前，先确定会影响架构的决策。记录其余假设或待解决问题，不要自行编造答案。

步骤 3 — 查阅当前技术文档

对于会影响决策的库、框架和 SDK，优先使用 Context7 CLI（ctx7 或 npx ctx7@latest）。如果 PRD 或需求说明中已提供经过验证的 Context7 ID，请直接使用 docs <libraryId> "<question>"；否则，先用 library <name> "<question>" 解析。如果 CLI 不可用，则使用已配置的 Context7 MCP；如果两者都不可用，则查阅官方文档。有关设置详情，请遵循已安装的 Context7 技能说明。

将 ADR 中使用的每个经过验证的 Context7 ID 记录在 Technology Documentation References 表格中，以便负责实现的 Agent 直接获取最新文档，无需再次解析库。如果没有可用的 Context7 ID，请改为记录官方文档链接。不要编造 ID。

步骤 4 — 确定 ADR 结构

根据复杂度进行选择：

简单（使用单个文件）：

• 单个技术层，或直接的功能增补
• 集成组件少于 3 个
• 保存为：docs/ADR/000-[short-description].md

复杂（使用包含多个文件的文件夹）：

• 包含多个不同的技术层（例如，前端 + 后端 + 数据库 + AI/LLM）
• 存在多个集成点或外部服务
• 范围较大，需要按领域划分职责
• 保存为：
  • docs/ADR/000-main-architecture.md — 整体系统、组件图和主要决策
  • docs/ADR/001-[area].md、002-[area].md 等 — 每个技术领域各一个文件

文件命名：使用零填充编号 + 简短的 kebab-case 描述。文件名中不要包含 “ADR”——文件夹已说明其上下文。 示例：000-main-architecture.md、001-backend-api.md、002-frontend.md、003-database.md

步骤 5 — 编写 ADR

使用下方模板。保存到 docs/ADR/。

---

规则

• 语言：无论简述或对话使用何种语言，ADR 始终使用英文撰写。
• 不包含代码片段：不要包含实现代码。实施 Agent 可以从最新文档中获取准确的 API 用法。描述做什么，而不是怎么做。
• 避免含糊表述：每项约束、决策或要求都必须具体且可验证，达到与 PRD 中验收标准相同的要求。
• 图表为必需项：在适用时，为所有流程包含架构图、数据流图和时序图。只有在某类图确实无法表达时，才可省略。细节越丰富越好。
• 测试为必需项：每份 ADR 都必须包含测试策略。TDD 是实施 Agent 进行自我验证的主要工具。
• 文档参考：如果有 Context7 ID，请记录；否则记录官方文档链接。不要编造 ID。
• 目的：本文档与 PRD 一起，必须让开发者 Agent 清楚了解系统。与用户一起解决会影响实现的决策；明确记录其他尚待解决的问题。
• 不要实现代码：专注于描述架构决策（ADR），为负责实现代码的 Agent 提供所有技术细节。

---

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]