Loading...
Loading...
Compare original and translation side by side
Expert guidance for writing effective technical design documents, RFCs, Architecture Decision Records, and technology evaluation frameworks.
为撰写高效的技术设计文档、RFC、架构决策记录（ADR）及技术评估框架提供专业指导。
These rules are mandatory. Violating them means the skill is not working correctly.
这些规则为强制性要求。违反规则意味着本技能未正常发挥作用。
❌ FORBIDDEN:❌ 禁止：undefinedundefined❌ 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 Createdundefined❌ 禁止：
"用户向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 Createdundefined❌ FORBIDDEN:❌ 禁止：| Metric | Current | Target | Measurement |
|---|---|---|---|
| API Latency (P95) | 500ms | <200ms | Prometheus histogram |
| Availability | 99.5% | 99.9% | Uptime monitoring |
| Error Rate | 2% | <0.1% | Error tracking |
| Throughput | 1K req/s | 10K req/s | Load testing |
undefined| 指标 | 当前值 | 目标值 | 测量方式 |
|---|---|---|---|
| API延迟（P95） | 500ms | <200ms | Prometheus直方图 |
| 可用性 | 99.5% | 99.9% | 在线时间监控 |
| 错误率 | 2% | <0.1% | 错误追踪 |
| 吞吐量 | 1K 请求/秒 | 10K 请求/秒 | 负载测试 |
undefined❌ FORBIDDEN:
(No risk section, assuming everything will work)
✅ REQUIRED:❌ 禁止：
（无风险章节，假设一切顺利）
✅ 要求：| Risk | Severity | Likelihood | Mitigation |
|---|---|---|---|
| Database migration fails | High | Medium | Backup + rollback plan, test in staging |
| Third-party API unavailable | Medium | Low | Circuit breaker, fallback cache |
| Team lacks expertise | Medium | Medium | Pair programming, external review |
| Scope creep | High | High | Fixed scope document, change control |
---| 风险 | 严重程度 | 发生概率 | 缓解方案 |
|---|---|---|---|
| 数据库迁移失败 | 高 | 中 | 备份+回滚计划，在预发布环境测试 |
| 第三方API不可用 | 中 | 低 | 断路器、降级缓存 |
| 团队缺乏相关技术 | 中 | 中 | 结对编程、外部评审 |
| 范围蔓延 | 高 | 高 | 固定范围文档、变更控制流程 |
---| Scenario | Document Type | Complexity |
|---|---|---|
| New feature design | Technical Design Doc | Medium-High |
| System architecture | C4 Model Diagrams | Medium |
| Major technical decision | Architecture Decision Record (ADR) | Low-Medium |
| Cross-team proposal | RFC (Request for Comments) | Medium-High |
| Technology evaluation | Tech Selection Matrix | Medium |
| API contract | OpenAPI/AsyncAPI Spec | Low-Medium |
| 场景 | 文档类型 | 复杂度 |
|---|---|---|
| 新功能设计 | 技术设计文档 | 中-高 |
| 系统架构 | C4模型图 | 中 |
| 重大技术决策 | 架构决策记录（ADR） | 低-中 |
| 跨团队提案 | RFC（征求意见稿） | 中-高 |
| 技术评估 | 技术选型矩阵 | 中 |
| API契约 | OpenAPI/AsyncAPI规范 | 低-中 |
undefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefinedundefined| Risk | Severity | Likelihood | Mitigation |
|---|---|---|---|
| JWT secret leak | Critical | Low | Rotate secrets quarterly, use HSM |
| Token theft (XSS) | High | Medium | HttpOnly cookies, CSP headers |
| Redis downtime | High | Low | Fallback to stateless validation |
| Clock skew issues | Medium | Medium | Use |
undefined| 风险 | 严重程度 | 发生概率 | 缓解方案 |
|---|---|---|---|
| JWT密钥泄露 | 关键 | 低 | 每季度轮换密钥，使用HSM |
| 令牌被盗（XSS） | 高 | 中 | HttpOnly Cookie，CSP头 |
| Redis宕机 | 高 | 低 | 回退到无状态验证 |
| 时钟偏差问题 | 中 | 中 | 使用 |
undefinedundefinedundefinedundefinedundefinedundefinedundefined
---
---✅ 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✅ 建议：
- 使用简洁直接的语言
- 首次出现时定义缩写
- 为复杂流程添加图表
- 使用表格进行对比
- 提供具体示例
❌ 禁止：
- 使用未解释的行话
- 撰写大段文字
- 假设读者具备前置知识
- 省略决策背后的“为什么”
- 创建会过时的文档sequenceDiagram
Client->>API: POST /login
API->>DB: Validate credentials
DB-->>API: User data
API->>Redis: Store session
API-->>Client: JWT token@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
@endumlsequenceDiagram
Client->>API: POST /login
API->>DB: Validate credentials
DB-->>API: User data
API->>Redis: Store session
API-->>Client: JWT token@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
@endumltemplates/design-doc-template.mdtemplates/adr-template.mdreference/tech-selection.mdtemplates/design-doc-template.mdtemplates/adr-template.mdreference/tech-selection.mdundefinedundefined
---
---undefinedundefined| Requirement | Design Element | Implementation | Tests |
|---|---|---|---|
| REQ-001: MFA support | Auth Service TOTP module | | |
| REQ-002: OAuth login | OAuth provider adapter | | |
| REQ-003: <100ms latency | Redis token cache | | |
undefined| 需求 | 设计元素 | 实现 | 测试 |
|---|---|---|---|
| REQ-001: MFA支持 | 认证服务TOTP模块 | | |
| REQ-002: OAuth登录 | OAuth提供商适配器 | | |
| REQ-003: <100ms延迟 | Redis令牌缓存 | | |
undefinedundefinedundefinedundefinedundefined❌ 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❌ 事后补文档用于合理化
- 不要在实现后才写文档来证明决策合理性
- 应在实现前撰写，梳理设计思路
❌ 过度细节
- 不要记录每个函数和变量
- 聚焦系统级设计，而非逐行代码
❌ 先规格后开发的瀑布模式
- 不要花费数月时间追求完美设计
- 撰写足够内容即可启动，边实践边迭代
❌ 过时文档
- 不要让文档与实际情况脱节
- 更新或删除过时文档
❌ 无备选方案分析
- 不要只呈现一种解决方案
- 展示你已考虑过权衡
❌ 缺失成功标准
- 不要忘记定义“完成”的标准
- 包含可衡量的成功指标┌─────────────────────────────────────────────────────────────┐
│ 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. 开放问题（哪些内容不明确？） │
├─────────────────────────────────────────────────────────────┤
│ 最佳实践 │
│ ├── 实现前先写文档 │
│ ├── 为复杂流程使用图表 │
│ ├── 语言简洁直接 │
│ ├── 展示权衡，而非仅解决方案 │
│ ├── 定义成功标准 │
│ └── 随系统演进更新文档 │
└─────────────────────────────────────────────────────────────┘