technical-spec

技术规范与设计文档

编写有效技术设计文档、RFC、架构决策记录和技术评估框架的专家指南。

核心理念

• 先写文档，再写代码 — 设计文档可避免高昂的返工成本，并帮助团队达成共识
• 持续更新文档 — 随着系统演进，及时更新文档
• 清晰胜过面面俱到 — 简单直接的语言可减轻认知负担
• 以代码形式编写图表 — 架构图应纳入版本控制并便于维护
• 记录决策，而非仅作描述 — 记录为什么这样做，而不只是做了什么

---

强制规则（必须遵守）

以下规则必须遵守。违反规则意味着此技能未能正常发挥作用。

必须列出备选方案

每份设计文档都必须至少包含 2 个备选方案。

❌ FORBIDDEN:
## Solution
We will use PostgreSQL for the database.
(No alternatives considered)

✅ REQUIRED:
## Proposed Solution
PostgreSQL for primary database.

## Alternatives Considered

### Option A: PostgreSQL (Recommended)
**Pros**: ACID compliance, JSON support, mature ecosystem
**Cons**: Vertical scaling limits
**Decision**: Chosen for reliability and team expertise

### Option B: MongoDB
**Pros**: Horizontal scaling, flexible schema
**Cons**: Eventual consistency, less familiar to team
**Decision**: Rejected due to consistency requirements

### Option C: DynamoDB
**Pros**: Serverless, auto-scaling
**Cons**: Vendor lock-in, complex query patterns
**Decision**: Rejected due to query flexibility needs

必须提供图表

系统设计必须包含架构图。不得仅用文字描述。

❌ 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

### Success Metrics Defined

**Every design must include measurable success criteria.**

```markdown
❌ FORBIDDEN:
## Goals
- Make the system faster
- Improve reliability
- Better user experience

✅ REQUIRED:
## Success Metrics

| 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 |

风险与缓解措施

所有设计都必须指出风险及相应的缓解措施。

❌ FORBIDDEN:
(No risk section, assuming everything will work)

✅ REQUIRED:
## Risks & Mitigations

| 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 |

---

何时使用此技能

场景	文档类型	复杂度
新功能设计	技术设计文档	中-高
系统架构	C4 模型图	中
重大技术决策	架构决策记录（ADR）	低-中
跨团队提案	RFC（征求意见稿）	中-高
技术评估	技术选型矩阵	中
API 契约	OpenAPI/AsyncAPI 规范	低-中

---

文档类型概览

技术设计文档（TDD）

目的：为功能或系统的实现提供蓝图 受众：工程师、技术负责人 适用时机：实现重要功能之前 章节：问题、解决方案、备选方案、风险、时间线

RFC（征求意见稿）

目的：供讨论和反馈的提案 受众：跨职能团队 适用时机：需要就技术方向达成共识时 章节：问题陈述、提案、权衡、待解答问题

架构决策记录（ADR）

目的：记录一项架构决策 受众：当前及未来的工程师 适用时机：作出任何具有重要架构意义的选择时 章节：背景、决策、后果、状态

C4 模型图

目的：以多个缩放层级展示系统架构 受众：技术及非技术相关方 适用时机：传达系统结构时 层级：上下文、容器、组件、代码

---

文档必备章节

1. 前置信息

# 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

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

## 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.

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

## 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

### High-Level Design

[Include C4 Container diagram here]

### 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

4. 已考虑的备选方案

## Alternatives

### Option A: Session-based authentication
**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)
**Pros**: Battle-tested, feature-complete
**Cons**: $500/month cost, vendor lock-in
**Decision**: Deferred - revisit if team velocity insufficient

5. 风险评估

## Risks & Mitigations

| 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 `nbf` claim, allow 5min tolerance |

6. 实施计划

## Work Breakdown

### Phase 1: Core Authentication (Week 1-2)
- [ ] JWT generation/validation service
- [ ] Password hashing (bcrypt)
- [ ] User repository interface
- [ ] Unit tests + integration tests

### Phase 2: MFA (Week 3)
- [ ] TOTP secret generation
- [ ] QR code generation
- [ ] Verification endpoint
- [ ] Backup codes

### Phase 3: OAuth (Week 4)
- [ ] Google OAuth integration
- [ ] GitHub OAuth integration
- [ ] Account linking flow

### Success Metrics
- 100% test coverage for auth logic
- <100ms token validation latency
- Zero security vulnerabilities in audit

7. 待解答问题

## 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

---

最佳实践

清晰度与语言

✅ 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

图表

Mermaid（简单流程）

sequenceDiagram
    Client->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User data
    API->>Redis: Store session
    API-->>Client: JWT token

使用 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

结构与模板

在组织内使用统一的模板：

• 技术设计文档 → templates/design-doc-template.md
• ADR → templates/adr-template.md
• 技术评估 → reference/tech-selection.md

版本控制

# 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

---

可追溯性与维护

将需求关联至决策

## Requirements Traceability

| Requirement | Design Element | Implementation | Tests |
|-------------|---------------|----------------|-------|
| REQ-001: MFA support | Auth Service TOTP module | `auth/totp.go` | `auth/totp_test.go` |
| REQ-002: OAuth login | OAuth provider adapter | `auth/oauth.go` | `auth/oauth_test.go` |
| REQ-003: <100ms latency | Redis token cache | `middleware/jwt.go` | `benchmark/auth_bench.go` |

文档生命周期

## 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

审查流程

实施之前：

1. 作者编写设计文档
2. 分享给团队进行异步审查（2-3 天）
3. 安排 30-45 分钟的讲解会议
4. 处理反馈并更新文档
5. 获得技术负责人和安全团队的批准（如有需要）

实施之后：

• 在上线 1 个月后审查文档
• 根据实际经验更新文档
• 记录变更内容及原因

---

应避免的反模式

❌ 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

---

检查清单

撰写前

• 已理解问题和约束条件
• 已确定相关方和评审人员
• 已选择合适的文档类型
• 已收集背景信息（现有系统、数据、指标）

撰写期间

• 清晰阐述问题及其影响
• 提出解决方案并附上图表
• 考虑备选方案及其权衡
• 评估风险并制定缓解措施
• 明确成功标准
• 制定工作分解和时间表
• 记录未解决的问题

发布前

• 检查拼写和语法
• 确保所有图表均能正确渲染
• 确保链接有效
• 定义缩写词
• 测试代码示例
• 确定需要邀请的评审人员

实施后

• 根据经验教训更新文档
• 将状态更改为“已实施”
• 为关键决策创建相关 ADR
• 如有需要，创建运行手册／运维文档

---

扩展参考

为保持此技能简洁，从 ## Quick Reference Card 开始的详细内容已移至 reference/extended.md。如果任务需要其中移出的示例、命令目录、检查清单、平台详情或实施模板，请加载该参考文档。