Dora Pocket

Appearance

架构文档模板 ​

本模板用于生成架构设计文档，适用于系统设计、模块架构、技术选型等场景。遵循 Layer 1 通用规范 + Layer 2 架构文档规范。

文档结构模板 ​

Frontmatter ​

yaml
---
title: '[模块/系统名称] 架构设计'
description: '[系统/模块的完整功能说明和设计目标]'
category: 架构
ai_model: Gemini # 推荐使用 Gemini 进行大上下文分析
---

章节结构 ​

1. 概述 ​

目的: 说明系统的问题域和解决方案概览。

内容要求:

  • 问题域: 描述要解决的核心问题和业务需求
  • 解决方案概述: 简明扼要地说明系统的整体架构思路
  • 关键目标: 列出系统设计的主要目标（性能、可扩展性、可维护性等）

示例结构:

markdown
## 概述

### 问题域

[描述系统要解决的核心问题和业务背景]

### 解决方案

[简要说明整体架构设计思路和核心理念]

### 设计目标

- **[目标1]**: [说明]
- **[目标2]**: [说明]

2. 设计决策 ​

目的: 记录关键的架构决策和设计选择（ADR - Architecture Decision Record）。

内容要求:

  • 使用 ADR 格式记录每个重要决策
  • 包含决策背景、考虑的方案、最终选择和理由
  • 说明决策的影响和后果

ADR 格式:

markdown
## 设计决策

### [决策标题]

**背景**: [为什么需要做这个决策]

**考虑的方案**:

1. **方案A**: [描述] - 优点: [...] / 缺点: [...]
2. **方案B**: [描述] - 优点: [...] / 缺点: [...]

**最终决策**: 选择方案 [A/B]

**理由**: [详细说明选择理由]

**影响**: [说明这个决策对系统的影响]

3. 系统结构 ​

目的: 展示系统的组件组织、模块划分和层次关系。

内容要求:

  • 必须包含架构图 (推荐使用 Mermaid)
  • 说明每个组件/模块的职责
  • 明确组件之间的依赖关系和数据流向
  • 定义关键接口和交互方式

示例结构:

markdown
## 系统结构

### 架构可视化

\`\`\`mermaid
graph TD
A[组件A] --> B[组件B]
A --> C[组件C]
B --> D[核心模块]
C --> D
\`\`\`

### 组件说明

#### [组件名称]

- **职责**: [说明组件的核心功能]
- **依赖**: [列出依赖的其他组件]
- **接口**: [定义对外提供的接口]

4. 技术栈 ​

目的: 说明系统使用的技术和工具，以及选择理由。

内容要求:

  • 列出核心技术栈和依赖库
  • 说明每个技术选择的原因
  • 明确版本要求和兼容性说明
  • 包含外部依赖和开发工具

示例结构:

markdown
## 技术栈

### 核心技术

| 技术/工具  | 版本 | 用途     | 选择理由                 |
| ---------- | ---- | -------- | ------------------------ |
| TypeScript | ^5.0 | 类型系统 | 类型安全，开发体验好     |
| Vitest     | ^1.0 | 单元测试 | 快速，与 Vite 生态集成好 |

### 依赖说明

**核心依赖**:

- `[package-name]`: [用途和选择理由]

**开发依赖**:

- `[dev-package]`: [用途说明]

5. 权衡分析 ​

目的: 说明架构设计中的权衡取舍和已知限制。

内容要求:

  • 优势: 列出当前设计的主要优点
  • 限制: 明确已知的限制和不足
  • 风险: 识别潜在的技术风险
  • 替代方案: 说明未来可能的改进方向

示例结构:

markdown
## 权衡分析

### 优势

- **[优点1]**: [详细说明]
- **[优点2]**: [详细说明]

### 限制与风险

- **[限制1]**: [说明限制及其影响]
- **[风险1]**: [说明风险和缓解措施]

### 未来改进方向

- **[改进方向1]**: [说明改进思路]

AI 生成提示词 ​

以下提示词适用于使用 Gemini 生成架构文档（推荐模型：gemini-2.5-pro）。

角色定义 ​

你是一位经验丰富的系统架构师和技术写作专家，擅长分析复杂系统、提取设计模式并撰写清晰的架构文档。

任务说明 ​

基于提供的代码库、设计文档或技术需求，生成一份完整的架构设计文档，符合以下规范：

  1. 遵循规范:

    • Layer 1 通用文档规范 (Frontmatter、标题结构、语言、链接格式、代码示例、注意事项)
    • Layer 2 架构文档规范 (架构可视化、设计原则、组件关系、技术选型论证)
    • 本模板的 5 个章节结构

  2. 内容要求:

    • 概述章节: 清晰说明问题域、解决方案和设计目标
    • 设计决策章节: 使用 ADR 格式记录至少 2-3 个关键决策
    • 系统结构章节: 必须包含 Mermaid 架构图，说明所有组件及其关系
    • 技术栈章节: 完整列出技术栈并提供选择理由
    • 权衡分析章节: 诚实说明优势、限制和未来改进方向

  3. 质量检查点:

    • 设计决策完整性: 所有重要的架构决策都有 ADR 记录，包含背景、方案对比和选择理由
    • 图表清晰度: Mermaid 图表准确反映系统结构，节点和边的标签清晰易懂
    • 权衡分析深度: 不仅列出优势，更要诚实说明限制和风险，提供缓解措施

输入要求 ​

  • 代码库上下文: 提供项目源码目录结构和关键文件路径
  • 设计文档: 如有已存在的设计说明或技术需求文档
  • 依赖信息: 提供 package.json、tsconfig.json 等配置文件

输出格式 ​

  • 格式: Markdown 文件，包含 YAML frontmatter
  • 语言: 简体中文（代码注释可使用英文）
  • 代码块: 使用三反引号 (```) 包裹，标注语言类型
  • Mermaid 图表: 使用 ```mermaid 代码块

推荐模型 ​

  • 首选: Gemini (gemini-2.5-pro) - 大上下文分析能力强，擅长架构审查和模式识别
  • 备选: Qwen (qwen-coder) - 当 Gemini 不可用时的备选方案

使用示例 ​

bash
# 使用 Gemini 生成架构文档
cd docs/contributing/documentation && gemini -p "
PURPOSE: 生成 [模块名称] 的架构设计文档
TASK:
• 分析模块的组件结构和依赖关系
• 提取关键设计决策和技术选型
• 绘制 Mermaid 架构图
• 说明优势、限制和未来改进方向
MODE: write
CONTEXT: @../../../packages/[module-name]/src/**/* @../../../packages/[module-name]/package.json | Memory: 遵循 Dora Pocket 零依赖原则和 monorepo 组织模式
EXPECTED: 完整的架构文档，包含 5 个章节、Mermaid 图表和 3 个质量检查点的验证
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-architecture.txt) | 遵循 L1+L2 架构文档规范，使用 ADR 格式记录决策 | write=CREATE/MODIFY/DELETE
" --approval-mode yolo

核心指令与规范 ​

  1. 继承规范:

  2. 必需章节:

    • 概述 (问题域、解决方案、设计目标)
    • 设计决策 (ADR 格式)
    • 系统结构 (Mermaid 图 + 组件说明)
    • 技术栈 (依赖列表 + 选择理由)
    • 权衡分析 (优势、限制、风险、未来改进)

  3. Mermaid 图表要求:

    • 使用 graph TD 或 flowchart 展示组件关系
    • 节点标签清晰，边的方向表示依赖或数据流
    • 图表后必须有文字说明

  4. 质量检查要点:

    • 设计决策完整性: 检查所有重要决策是否有 ADR 记录
    • 图表清晰度: 验证 Mermaid 图能正确渲染且易于理解
    • 权衡分析深度: 确保不仅列出优势，更说明限制和风险

相关文档 ​

版本历史 ​

  • v1.0 (2025-11-19): 初始版本，定义架构文档的 5 个章节结构和 AI 生成提示词

基于 MIT 许可证发布

版权所有 © 2024-2025 Esdora