Claude-Code-Workflow/docs/skills/templates/architecture-doc.md

Architecture Doc Template

用途: 架构文档模板，用于 spec-generator Phase 4 输出

模板

_index.md 模板

# Architecture - Index

> **Product**: {Product Name}
> **Generated**: {YYYY-MM-DD}
> **Session**: {session-id}

## Overview

架构概述（2-3 段）

## Architecture Principles

1. **Principle 1**: Description
2. **Principle 2**: Description
3. **Principle 3**: Description

## System Architecture

### High-Level Architecture

```plaintext
┌─────────────────────────────────────────────────┐
│                   Frontend                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │  Web UI  │  │  Mobile  │  │   API    │      │
│  └──────────┘  └──────────┘  └──────────┘      │
└─────────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│                  Backend Layer                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ Gateway  │  │ Services │  │  Events  │      │
│  └──────────┘  └──────────┘  └──────────┘      │
└─────────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│                  Data Layer                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  | Database │  │   Cache  │  │  Storage │      │
│  └──────────┘  └──────────┘  └──────────┘      │
└─────────────────────────────────────────────────┘

Components

Component	Responsibility	Technology
Component 1	描述	技术栈
Component 2	描述	技术栈
Component 3	描述	技术栈

Technology Stack

Frontend

Layer	Technology	Rationale
Framework	{framework}	选择理由
State	{state lib}	选择理由
UI	{ui lib}	选择理由

Backend

Layer	Technology	Rationale
Runtime	{runtime}	选择理由
Framework	{framework}	选择理由
Database	{database}	选择理由

Architecture Decisions

详见各 ADR 文档：

• ADR-001-{title}
• ADR-002-{title}

Requirements Traceability

Requirement	ADR	Component
REQ-001	ADR-001	Service A
REQ-002	ADR-002	Service B

Change Log

Version	Date	Changes
1.0.0	YYYY-MM-DD	Initial version

---

### ADR-*.md 模板

```markdown
# ADR-{NNN}: {Decision Title}

> **Status**: {Accepted|Deprecated|Superseded}
> **Date**: {YYYY-MM-DD}
> **Decision Type**: {Technical|Process|Architecture}

## Context

描述背景和问题：
- 当前状况
- 需要解决的问题
- 约束条件

## Decision

**决策内容**: 一句话概括

详细说明决策内容

### Options Considered

| Option | Pros | Cons | Selected |
|--------|------|------|----------|
| Option 1 | 优点 | 缺点 | No |
| Option 2 | 优点 | 缺点 | **Yes** |
| Option 3 | 优点 | 缺点 | No |

### Rationale

选择此方案的原因：
1. Reason 1
2. Reason 2
3. Reason 3

## Consequences

### Positive

- Benefit 1
- Benefit 2

### Negative

- Risk 1
- Risk 2

### Mitigation

如何缓解负面影响

## Related Requirements

| Requirement | Relation |
|-------------|----------|
| REQ-001 | Enables |
| NFR-PERF-001 | Addresses |

## Alternatives Considered

1. Alternative 1: Description - Rejected because...
2. Alternative 2: Description - Rejected because...

## References

- [Related Doc](path)
- [External Reference](url)

使用说明

1. 触发: spec-generator Phase 4
2. 输入: Phase 3 Requirements (PRD)
3. 输出: architecture/ 目录，包含 _index.md 和所有 ADR 文件
4. 验证: 确保追溯链接有效

---

示例

简化示例 - ADR-001.md

# ADR-001: Use Operational Transformation for Real-Time Sync

> **Status**: Accepted
> **Date**: 2026-03-01
> **Decision Type**: Technical

## Context

实时协作平台需要支持多用户同时编辑同一文档。
- 简单的"最后写入胜出"策略会导致数据丢失
- 需要自动解决编辑冲突
- 网络延迟和离线编辑需要支持

## Decision

**决策内容**: 使用 Operational Transformation (OT) 算法实现实时同步

OT 通过转换操作序列来解决冲突，确保最终一致性。

### Options Considered

| Option | Pros | Cons | Selected |
|--------|------|------|----------|
| Last Write Wins | 简单 | 数据丢失 | No |
| OT (Yjs) | 成熟方案 | 复杂度高 | **Yes** |
| CRDT | 理论优雅 | 性能开销 | No |

### Rationale

1. **成熟度**: Yjs 是成熟的 OT 实现，被广泛应用
2. **性能**: OT 比 CRDT 性能更好，适合文档编辑场景
3. **社区**: 活跃的社区支持和丰富的集成

## Consequences

### Positive

- 自动解决冲突，无需用户干预
- 支持离线编辑，重连后自动同步
- 低延迟，良好的用户体验

### Negative

- 实现复杂，学习曲线陡峭
- 需要维护操作历史，内存开销

### Mitigation

- 使用成熟的 Yjs 库，降低实现复杂度
- 实现历史压缩策略，控制内存使用

## Related Requirements

| Requirement | Relation |
|-------------|----------|
| REQ-001 | Enables |
| NFR-PERF-001 | Addresses |