Back to Details

technical-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Specification & Design Documents

技术规格与设计文档

Expert guidance for writing effective technical design documents, RFCs, Architecture Decision Records, and technology evaluation frameworks.
为撰写高效的技术设计文档、RFC、架构决策记录（ADR）及技术评估框架提供专业指导。

Core Philosophy

核心原则

  • Write before code — Design documents prevent costly rework and align teams
  • Living documents — Keep docs updated as the system evolves
  • Clarity over completeness — Simple, direct language reduces cognitive load
  • Diagrams as code — Version-controlled, maintainable architecture diagrams
  • Decisions over descriptions — Document why, not just what
  • 先写文档再编码 — 设计文档可避免高昂的返工成本，确保团队对齐
  • 活文档 — 随着系统演进持续更新文档
  • 清晰优先于完备 — 简洁直接的语言降低认知负担
  • 图表即代码 — 采用版本控制、可维护的架构图表
  • 记录决策而非仅描述 — 重点记录决策原因，而非仅说明内容

Hard Rules (Must Follow)

硬性规则（必须遵守）

These rules are mandatory. Violating them means the skill is not working correctly.
这些规则为强制性要求。违反规则意味着本技能未正常发挥作用。

Alternatives Required

必须包含备选方案

Every design document must include at least 2 alternative solutions.
markdown
❌ FORBIDDEN:
每份设计文档必须至少包含2种备选解决方案。
markdown
❌ 禁止：

Solution

解决方案

We will use PostgreSQL for the database. (No alternatives considered)
✅ REQUIRED:
我们将使用PostgreSQL作为数据库。 （未考虑任何备选方案）
✅ 要求：

Proposed Solution

提议的解决方案

PostgreSQL for primary database.
采用PostgreSQL作为主数据库。

Alternatives Considered

考虑的备选方案

Option A: PostgreSQL (Recommended)

方案A：PostgreSQL（推荐）

Pros: ACID compliance, JSON support, mature ecosystem Cons: Vertical scaling limits Decision: Chosen for reliability and team expertise
优点：ACID合规、支持JSON、成熟生态 缺点：垂直扩容受限 决策：因可靠性和团队技术选型

Option B: MongoDB

方案B：MongoDB

Pros: Horizontal scaling, flexible schema Cons: Eventual consistency, less familiar to team Decision: Rejected due to consistency requirements
优点：水平扩容、灵活 schema 缺点：最终一致性、团队熟悉度低 决策：因一致性要求被否决

Option C: DynamoDB

方案C：DynamoDB

Pros: Serverless, auto-scaling Cons: Vendor lock-in, complex query patterns Decision: Rejected due to query flexibility needs
undefined
优点：无服务器、自动扩容 缺点：厂商锁定、查询模式复杂 决策：因查询灵活性需求被否决
undefined

Diagrams Required

必须包含图表

System designs must include architecture diagrams. No text-only descriptions.
markdown
❌ FORBIDDEN:
"The user sends a request to the API, which talks to the database
and returns a response."

✅ REQUIRED:
Include at least one of:
- C4 Context/Container diagram
- Sequence diagram for key flows
- Data flow diagram

Example (Mermaid):
```mermaid
sequenceDiagram
    Client->>API: POST /orders
    API->>Auth: Validate token
    Auth-->>API: User context
    API->>DB: Create order
    DB-->>API: Order ID
    API-->>Client: 201 Created
undefined
系统设计必须包含架构图表，禁止仅用文字描述。
markdown
❌ 禁止：
"用户向API发送请求，API与数据库交互并返回响应。"

✅ 要求：
至少包含以下一种图表：
- C4上下文/容器图
- 关键流程的序列图
- 数据流图

示例（Mermaid）：
```mermaid
sequenceDiagram
    Client->>API: POST /orders
    API->>Auth: Validate token
    Auth-->>API: User context
    API->>DB: Create order
    DB-->>API: Order ID
    API-->>Client: 201 Created
undefined

Success Metrics Defined

必须定义成功指标

Every design must include measurable success criteria.
markdown
❌ FORBIDDEN:
每份设计必须包含可衡量的成功标准。
markdown
❌ 禁止：

Goals

目标

  • Make the system faster
  • Improve reliability
  • Better user experience
✅ REQUIRED:
  • 提升系统速度
  • 提高可靠性
  • 优化用户体验
✅ 要求：

Success Metrics

成功指标

MetricCurrentTargetMeasurement
API Latency (P95)500ms<200msPrometheus histogram
Availability99.5%99.9%Uptime monitoring
Error Rate2%<0.1%Error tracking
Throughput1K req/s10K req/sLoad testing
undefined
指标当前值目标值测量方式
API延迟（P95）500ms<200msPrometheus直方图
可用性99.5%99.9%在线时间监控
错误率2%<0.1%错误追踪
吞吐量1K 请求/秒10K 请求/秒负载测试
undefined

Risks and Mitigations

必须包含风险与缓解措施

All designs must identify risks and their mitigations.
markdown
❌ FORBIDDEN:
(No risk section, assuming everything will work)

✅ REQUIRED:
所有设计必须识别风险及其缓解方案。
markdown
❌ 禁止：
（无风险章节，假设一切顺利）

✅ 要求：

Risks & Mitigations

风险与缓解措施

RiskSeverityLikelihoodMitigation
Database migration failsHighMediumBackup + rollback plan, test in staging
Third-party API unavailableMediumLowCircuit breaker, fallback cache
Team lacks expertiseMediumMediumPair programming, external review
Scope creepHighHighFixed scope document, change control

---
风险严重程度发生概率缓解方案
数据库迁移失败高中备份+回滚计划，在预发布环境测试
第三方API不可用中低断路器、降级缓存
团队缺乏相关技术中中结对编程、外部评审
范围蔓延高高固定范围文档、变更控制流程

---

When to Use This Skill

何时使用本技能

ScenarioDocument TypeComplexity
New feature designTechnical Design DocMedium-High
System architectureC4 Model DiagramsMedium
Major technical decisionArchitecture Decision Record (ADR)Low-Medium
Cross-team proposalRFC (Request for Comments)Medium-High
Technology evaluationTech Selection MatrixMedium
API contractOpenAPI/AsyncAPI SpecLow-Medium
场景文档类型复杂度
新功能设计技术设计文档中-高
系统架构C4模型图中
重大技术决策架构决策记录（ADR）低-中
跨团队提案RFC（征求意见稿）中-高
技术评估技术选型矩阵中
API契约OpenAPI/AsyncAPI规范低-中

Document Types Overview

文档类型概述

Technical Design Document (TDD)

技术设计文档（TDD）

Purpose: Blueprint for implementing a feature or system Audience: Engineers, technical leads When: Before implementing significant features Sections: Problem, solution, alternatives, risks, timeline
目的：功能或系统实现的蓝图 受众：工程师、技术负责人 适用时机：在实现重要功能之前 章节：问题、解决方案、备选方案、风险、时间线

RFC (Request for Comments)

RFC（征求意见稿）

Purpose: Proposal for discussion and feedback Audience: Cross-functional teams When: Need consensus on technical direction Sections: Problem statement, proposal, trade-offs, open questions
目的：用于讨论和收集反馈的提案 受众：跨职能团队 适用时机：需要就技术方向达成共识时 章节：问题陈述、提案、权衡、开放问题

Architecture Decision Record (ADR)

架构决策记录（ADR）

Purpose: Document a single architectural decision Audience: Current and future engineers When: Any architecturally significant choice Sections: Context, decision, consequences, status
目的：记录单个架构决策 受众：当前及未来的工程师 适用时机：任何具有架构重要性的选择 章节：背景、决策、后果、状态

C4 Model Diagrams

C4模型图

Purpose: Visualize system architecture at multiple zoom levels Audience: Technical and non-technical stakeholders When: Communicating system structure Levels: Context, Container, Component, Code
目的：从多个缩放级别可视化系统架构 受众：技术与非技术干系人 适用时机：沟通系统结构时 层级：上下文、容器、组件、代码

Essential Document Sections

文档核心章节

1. Front Matter

1. 前置信息

markdown
undefined
markdown
undefined

Title: User Authentication System

标题：用户认证系统

Author: Jane Doe Status: Proposed | In Review | Approved | Implemented Created: 2025-12-18 Last Updated: 2025-12-18 Reviewers: @tech-lead, @security-team
undefined
作者：Jane Doe 状态：提议中 | 评审中 | 已批准 | 已实现 创建日期：2025-12-18 最后更新：2025-12-18 评审人：@tech-lead, @security-team
undefined

2. Problem Statement (The "Why")

2. 问题陈述（“为什么”）

markdown
undefined
markdown
undefined

Problem

问题

Current State: Users authenticate via legacy session cookies, no MFA support. Impact: 23% of security incidents related to compromised credentials. Constraint: Must support 10K concurrent users, <200ms login latency. Goal: Implement secure, scalable authentication with MFA and OAuth support.
undefined
当前状态：用户通过传统会话Cookie认证，不支持MFA。 影响：23%的安全事件与凭证泄露相关。 约束：必须支持10K并发用户，登录延迟<200ms。 目标：实现支持MFA和OAuth的安全、可扩展认证系统。
undefined

3. Proposed Solution (The "What")

3. 提议的解决方案（“是什么”）

markdown
undefined
markdown
undefined

Solution

解决方案

Implement JWT-based authentication with:
  • Access tokens (15min TTL) + Refresh tokens (7 day TTL)
  • TOTP-based MFA (Google Authenticator compatible)
  • OAuth 2.0 providers (Google, GitHub)
  • Redis for token blacklist and session management
实现基于JWT的认证系统，包含：
  • 访问令牌（15分钟有效期）+ 刷新令牌（7天有效期）
  • 基于TOTP的MFA（兼容Google Authenticator）
  • OAuth 2.0提供商（Google、GitHub）
  • Redis用于令牌黑名单和会话管理

High-Level Design

高层设计

[Include C4 Container diagram here]
[此处插入C4容器图]

Data Flow

数据流

  1. User submits credentials → Auth Service validates
  2. Auth Service generates JWT pair, stores refresh token in Redis
  3. Client includes access token in Authorization header
  4. API Gateway validates token, extracts user context
  5. On expiry, client exchanges refresh token for new access token
undefined
  1. 用户提交凭证 → 认证服务验证
  2. 认证服务生成JWT令牌对，将刷新令牌存储到Redis
  3. 客户端在Authorization头中携带访问令牌
  4. API网关验证令牌，提取用户上下文
  5. 令牌过期时，客户端使用刷新令牌换取新的访问令牌
undefined

4. Alternatives Considered

4. 考虑的备选方案

markdown
undefined
markdown
undefined

Alternatives

备选方案

Option A: Session-based authentication

方案A：基于会话的认证

Pros: Simpler implementation, server-side revocation Cons: Doesn't scale horizontally, higher latency Decision: Rejected - doesn't meet scalability requirements
优点：实现更简单，支持服务端吊销 缺点：无法水平扩容，延迟较高 决策：否决 - 不满足扩容要求

Option B: Auth0 (3rd party)

方案B：Auth0（第三方服务）

Pros: Battle-tested, feature-complete Cons: $500/month cost, vendor lock-in Decision: Deferred - revisit if team velocity insufficient
undefined
优点：久经考验，功能完备 缺点：每月500美元成本，厂商锁定 决策：延后 - 若团队交付速度不足时再重新评估
undefined

5. Risk Assessment

5. 风险评估

markdown
undefined
markdown
undefined

Risks & Mitigations

风险与缓解措施

RiskSeverityLikelihoodMitigation
JWT secret leakCriticalLowRotate secrets quarterly, use HSM
Token theft (XSS)HighMediumHttpOnly cookies, CSP headers
Redis downtimeHighLowFallback to stateless validation
Clock skew issuesMediumMediumUse 
nbf
claim, allow 5min tolerance
undefined
风险严重程度发生概率缓解方案
JWT密钥泄露关键低每季度轮换密钥，使用HSM
令牌被盗（XSS）高中HttpOnly Cookie，CSP头
Redis宕机高低回退到无状态验证
时钟偏差问题中中使用
nbf
声明，允许5分钟容错
undefined

6. Implementation Plan

6. 实施计划

markdown
undefined
markdown
undefined

Work Breakdown

工作分解

Phase 1: Core Authentication (Week 1-2)

阶段1：核心认证（第1-2周）

  • JWT generation/validation service
  • Password hashing (bcrypt)
  • User repository interface
  • Unit tests + integration tests
  • JWT生成/验证服务
  • 密码哈希（bcrypt）
  • 用户仓库接口
  • 单元测试 + 集成测试

Phase 2: MFA (Week 3)

阶段2：MFA（第3周）

  • TOTP secret generation
  • QR code generation
  • Verification endpoint
  • Backup codes
  • TOTP密钥生成
  • QR码生成
  • 验证端点
  • 备用码

Phase 3: OAuth (Week 4)

阶段3：OAuth（第4周）

  • Google OAuth integration
  • GitHub OAuth integration
  • Account linking flow
  • Google OAuth集成
  • GitHub OAuth集成
  • 账号关联流程

Success Metrics

成功指标

  • 100% test coverage for auth logic
  • <100ms token validation latency
  • Zero security vulnerabilities in audit
undefined
  • 认证逻辑测试覆盖率100%
  • 令牌验证延迟<100ms
  • 审计中无安全漏洞
undefined

7. Open Questions

7. 开放问题

markdown
undefined
markdown
undefined

Open Questions

开放问题

  1. Token storage: Should refresh tokens be in httpOnly cookie or localStorage?
    • Recommendation: Cookie (XSS protection), need CSRF mitigation
  2. MFA enforcement: Opt-in or mandatory for all users?
    • Requires: Product team decision
  3. Session limits: Should we limit concurrent sessions per user?
    • Impact: Redis storage requirements, UX complexity

---
  1. 令牌存储：刷新令牌应存储在HttpOnly Cookie还是localStorage中？
    • 建议：Cookie（防XSS），需CSRF缓解措施
  2. MFA强制要求：用户可选开启还是强制所有用户开启？
    • 需：产品团队决策
  3. 会话限制：是否限制每个用户的并发会话数？
    • 影响：Redis存储需求、UX复杂度

---

Best Practices

最佳实践

Clarity & Language

清晰度与语言

markdown
✅ DO:
- Use simple, direct language
- Define acronyms on first use
- Include diagrams for complex flows
- Use tables for comparisons
- Provide concrete examples

❌ DON'T:
- Use jargon without explanation
- Write walls of text
- Assume prior knowledge
- Skip the "why" behind decisions
- Create docs that become stale
markdown
✅ 建议：
- 使用简洁直接的语言
- 首次出现时定义缩写
- 为复杂流程添加图表
- 使用表格进行对比
- 提供具体示例

❌ 禁止：
- 使用未解释的行话
- 撰写大段文字
- 假设读者具备前置知识
- 省略决策背后的“为什么”
- 创建会过时的文档

Diagrams

图表

Mermaid (Simple flows)
mermaid
sequenceDiagram
    Client->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User data
    API->>Redis: Store session
    API-->>Client: JWT token
PlantUML with C4 (Architecture)
plantuml
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

System_Boundary(c1, "Auth System") {
    Container(api, "API Gateway", "Node.js", "Routes requests")
    Container(auth, "Auth Service", "Go", "Handles authentication")
    ContainerDb(redis, "Redis", "Cache", "Sessions & tokens")
}

Person(user, "User")
user -> api : Login request
api -> auth : Validate
auth -> redis : Store token
@enduml
Mermaid（简单流程）
mermaid
sequenceDiagram
    Client->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User data
    API->>Redis: Store session
    API-->>Client: JWT token
PlantUML + C4（架构图）
plantuml
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

System_Boundary(c1, "Auth System") {
    Container(api, "API Gateway", "Node.js", "Routes requests")
    Container(auth, "Auth Service", "Go", "Handles authentication")
    ContainerDb(redis, "Redis", "Cache", "Sessions & tokens")
}

Person(user, "User")
user -> api : Login request
api -> auth : Validate
auth -> redis : Store token
@enduml

Structure & Templates

结构与模板

Use consistent templates across your organization:
  • Technical Design Doc → 
    templates/design-doc-template.md
  • ADR → 
    templates/adr-template.md
  • Technology evaluation → 
    reference/tech-selection.md
在组织内使用统一模板：
  • 技术设计文档 → 
    templates/design-doc-template.md
  • ADR → 
    templates/adr-template.md
  • 技术评估 → 
    reference/tech-selection.md

Version Control

版本控制

bash
undefined
bash
undefined

Store docs with code

与代码一同存储文档

docs/ ├── architecture/ │ ├── ADRs/ │ │ ├── 001-database-selection.md │ │ └── 002-api-authentication.md │ └── diagrams/ │ └── c4-system-context.puml ├── design/ │ └── auth-system-design.md └── rfcs/ └── 2025-01-user-authentication.md

---
docs/ ├── architecture/ │ ├── ADRs/ │ │ ├── 001-database-selection.md │ │ └── 002-api-authentication.md │ └── diagrams/ │ └── c4-system-context.puml ├── design/ │ └── auth-system-design.md └── rfcs/ └── 2025-01-user-authentication.md

---

Traceability & Maintenance

可追溯性与维护

Link Requirements to Decisions

需求与决策关联

markdown
undefined
markdown
undefined

Requirements Traceability

需求可追溯性

RequirementDesign ElementImplementationTests
REQ-001: MFA supportAuth Service TOTP module
auth/totp.go
auth/totp_test.go
REQ-002: OAuth loginOAuth provider adapter
auth/oauth.go
auth/oauth_test.go
REQ-003: <100ms latencyRedis token cache
middleware/jwt.go
benchmark/auth_bench.go
undefined
需求设计元素实现测试
REQ-001: MFA支持认证服务TOTP模块
auth/totp.go
auth/totp_test.go
REQ-002: OAuth登录OAuth提供商适配器
auth/oauth.go
auth/oauth_test.go
REQ-003: <100ms延迟Redis令牌缓存
middleware/jwt.go
benchmark/auth_bench.go
undefined

Document Lifecycle

文档生命周期

markdown
undefined
markdown
undefined

Document Status

文档状态

  • Proposed: Initial draft, seeking feedback
  • In Review: Under review by stakeholders
  • Approved: Accepted, ready for implementation
  • Implemented: Fully implemented
  • Deprecated: No longer valid, superseded by ADR-XXX
undefined
  • 提议中：初始草稿，寻求反馈
  • 评审中：正在由干系人评审
  • 已批准：已通过，可开始实现
  • 已实现：完全实现
  • 已废弃：不再有效，被ADR-XXX取代
undefined

Review Process

评审流程

Before implementation:
  1. Author writes design doc
  2. Share with team for async review (2-3 days)
  3. Schedule 30-45min readout meeting
  4. Address feedback, update doc
  5. Get sign-off from tech lead + security (if needed)
After implementation:
  • Review doc 1 month post-launch
  • Update with actual learnings
  • Document what changed and why
实现前：
  1. 作者撰写设计文档
  2. 分享给团队进行异步评审（2-3天）
  3. 安排30-45分钟的宣讲会议
  4. 处理反馈，更新文档
  5. 获得技术负责人+安全团队（如有需要）的签字确认
实现后：
  • 上线1个月后评审文档
  • 更新实际经验总结
  • 记录变更内容及原因

Anti-Patterns to Avoid

需避免的反模式

markdown
❌ Design as justification
   - Don't write docs after implementation to justify decisions
   - Write BEFORE to think through design

❌ Too much detail
   - Don't document every function and variable
   - Focus on system-level design, not line-by-line code

❌ Spec-first waterfall
   - Don't spend months on perfect design
   - Write enough to start, iterate as you learn

❌ Stale documentation
   - Don't let docs drift from reality
   - Update or delete outdated docs

❌ No alternatives analysis
   - Don't present only one solution
   - Show you considered trade-offs

❌ Missing success criteria
   - Don't forget to define "done"
   - Include measurable success metrics
markdown
❌ 事后补文档用于合理化
   - 不要在实现后才写文档来证明决策合理性
   - 应在实现前撰写，梳理设计思路

❌ 过度细节
   - 不要记录每个函数和变量
   - 聚焦系统级设计，而非逐行代码

❌ 先规格后开发的瀑布模式
   - 不要花费数月时间追求完美设计
   - 撰写足够内容即可启动，边实践边迭代

❌ 过时文档
   - 不要让文档与实际情况脱节
   - 更新或删除过时文档

❌ 无备选方案分析
   - 不要只呈现一种解决方案
   - 展示你已考虑过权衡

❌ 缺失成功标准
   - 不要忘记定义“完成”的标准
   - 包含可衡量的成功指标

Checklist

检查清单

Before Writing

撰写前

  • Understood the problem and constraints
  • Identified stakeholders and reviewers
  • Selected appropriate document type
  • Gathered context (existing systems, data, metrics)
  • 理解问题与约束
  • 确定干系人与评审人
  • 选择合适的文档类型
  • 收集上下文信息（现有系统、数据、指标）

During Writing

撰写中

  • Clear problem statement with impact
  • Proposed solution with diagrams
  • Alternatives considered with trade-offs
  • Risk assessment with mitigations
  • Success criteria defined
  • Work breakdown with timeline
  • Open questions documented
  • 清晰的问题陈述及影响
  • 带图表的提议解决方案
  • 包含权衡分析的备选方案
  • 带缓解措施的风险评估
  • 定义的成功标准
  • 带时间线的工作分解
  • 记录的开放问题

Before Publishing

发布前

  • Spell check and grammar review
  • All diagrams render correctly
  • Links are valid
  • Acronyms defined
  • Code examples are tested
  • Requested reviewers identified
  • 拼写和语法检查
  • 所有图表渲染正确
  • 链接有效
  • 缩写已定义
  • 代码示例已测试
  • 确定了请求的评审人

After Implementation

实现后

  • Document updated with learnings
  • Status changed to "Implemented"
  • Related ADRs created for key decisions
  • Runbook/operational docs created if needed
  • 文档已更新经验总结
  • 状态改为“已实现”
  • 为关键决策创建了相关ADR
  • 如有需要，创建了运行手册/操作文档

Quick Reference Card

快速参考卡

┌─────────────────────────────────────────────────────────────┐
│           TECHNICAL DOCUMENT QUICK GUIDE                    │
├─────────────────────────────────────────────────────────────┤
│  Document Type Selection                                    │
│  ├── New feature → Technical Design Doc (TDD)               │
│  ├── Architecture → C4 Diagrams + System Design Doc         │
│  ├── Single decision → Architecture Decision Record (ADR)   │
│  ├── Cross-team proposal → Request for Comments (RFC)       │
│  └── Technology choice → Tech Evaluation Matrix             │
├─────────────────────────────────────────────────────────────┤
│  Essential Sections (TDD)                                   │
│  ├── 1. Problem Statement (Why?)                            │
│  ├── 2. Proposed Solution (What?)                           │
│  ├── 3. Alternatives Considered (Why not X?)                │
│  ├── 4. Risk Assessment (What could go wrong?)              │
│  ├── 5. Implementation Plan (How & When?)                   │
│  ├── 6. Success Metrics (How to measure?)                   │
│  └── 7. Open Questions (What's unclear?)                    │
├─────────────────────────────────────────────────────────────┤
│  Best Practices                                             │
│  ├── Write BEFORE implementation                            │
│  ├── Use diagrams for complex flows                         │
│  ├── Keep language simple and direct                        │
│  ├── Show trade-offs, not just solutions                    │
│  ├── Define success criteria                                │
│  └── Update docs as system evolves                          │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│           技术文档快速指南                                  │
├─────────────────────────────────────────────────────────────┤
│  文档类型选择                                              │
│  ├── 新功能 → 技术设计文档（TDD）                          │
│  ├── 架构 → C4图 + 系统设计文档                            │
│  ├── 单个决策 → 架构决策记录（ADR）                        │
│  ├── 跨团队提案 → 征求意见稿（RFC）                        │
│  └── 技术选型 → 技术评估矩阵                              │
├─────────────────────────────────────────────────────────────┤
│  技术设计文档核心章节                                      │
│  ├── 1. 问题陈述（为什么？）                               │
│  ├── 2. 提议的解决方案（是什么？）                         │
│  ├── 3. 考虑的备选方案（为什么不选X？）                    │
│  ├── 4. 风险评估（可能出什么问题？）                       │
│  ├── 5. 实施计划（如何做？何时做？）                       │
│  ├── 6. 成功指标（如何衡量？）                             │
│  └── 7. 开放问题（哪些内容不明确？）                       │
├─────────────────────────────────────────────────────────────┤
│  最佳实践                                                  │
│  ├── 实现前先写文档                                        │
│  ├── 为复杂流程使用图表                                    │
│  ├── 语言简洁直接                                          │
│  ├── 展示权衡，而非仅解决方案                              │
│  ├── 定义成功标准                                          │
│  └── 随系统演进更新文档                                    │
└─────────────────────────────────────────────────────────────┘

See Also

另请参阅

  • reference/design-doc.md — Technical design document guide
  • reference/adr.md — Architecture Decision Records
  • reference/c4-model.md — C4 architecture diagrams
  • reference/tech-selection.md — Technology evaluation matrix
  • templates/design-doc-template.md — TDD template
  • templates/adr-template.md — ADR template
  • reference/design-doc.md — 技术设计文档指南
  • reference/adr.md — 架构决策记录
  • reference/c4-model.md — C4架构图
  • reference/tech-selection.md — 技术评估矩阵
  • templates/design-doc-template.md — 技术设计文档模板
  • templates/adr-template.md — ADR模板

Sources

参考来源

Research based on 2025 best practices from:
基于2025年最佳实践的研究，来源包括：