technical-specification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical Specification

技术规范

Create comprehensive technical specifications for software projects.

为软件项目创建全面的技术规范。

Specification Template

规范模板

markdown

undefined

markdown

undefined

Technical Specification: [Feature Name]

Metadata

Status: Draft | In Review | Approved
Author: [Name]
Reviewers: [Names]
Last Updated: [Date]

Status: Draft | In Review | Approved
Author: [Name]
Reviewers: [Names]
Last Updated: [Date]

Executive Summary

[2-3 sentences: What problem does this solve? What's the proposed solution?]

Background & Context

Current pain points
Why now?
Related work

Current pain points
Why now?
Related work

Goals

Primary Goals

[Measurable goal]

[Measurable goal]

Non-Goals

[What this spec explicitly does NOT cover]

[What this spec explicitly does NOT cover]

Functional Requirements

ID	Requirement	Priority
FR-1	[Description]	P0
FR-2	[Description]	P1

ID	Requirement	Priority
FR-1	[Description]	P0
FR-2	[Description]	P1

Non-Functional Requirements

Performance: Response time < 200ms
Scalability: Support 10K concurrent users
Availability: 99.9% uptime
Security: [Requirements]

Performance: Response time < 200ms
Scalability: Support 10K concurrent users
Availability: 99.9% uptime
Security: [Requirements]

Technical Design

Architecture

[Diagram or description]

API Design

POST /api/v1/resource
Request: { "field": "value" }
Response: { "id": "123", "field": "value" }

POST /api/v1/resource
Request: { "field": "value" }
Response: { "id": "123", "field": "value" }

Database Schema

sql

CREATE TABLE resources (
  id UUID PRIMARY KEY,
  field VARCHAR(255)
);

sql

CREATE TABLE resources (
  id UUID PRIMARY KEY,
  field VARCHAR(255)
);

Implementation Plan

Phase	Timeline	Deliverables
1	Week 1-2	Core functionality
2	Week 3	API endpoints
3	Week 4	Testing & docs

Phase	Timeline	Deliverables
1	Week 1-2	Core functionality
2	Week 3	API endpoints
3	Week 4	Testing & docs

Testing Strategy

Unit tests: 80% coverage
Integration tests: API endpoints
E2E tests: Critical flows

Unit tests: 80% coverage
Integration tests: API endpoints
E2E tests: Critical flows

Risks & Mitigations

Risk	Probability	Impact	Mitigation
[Risk]	Medium	High	[Plan]

Risk	Probability	Impact	Mitigation
[Risk]	Medium	High	[Plan]

Success Criteria

All P0 requirements implemented
Tests passing
Performance targets met
Documentation complete

undefined

All P0 requirements implemented
Tests passing
Performance targets met
Documentation complete

undefined

Full Template

完整模板

See references/template.md for a comprehensive copy-paste template including:

Complete metadata section
Success metrics tables
Architecture diagrams
Detailed API design sections
Security threat analysis
Monitoring & observability
Risk assessment matrix
Rollout and rollback plans
Dependencies tracking
Open questions section

请查看 references/template.md 获取可直接复制使用的完整模板，包含：

完整的元数据部分
成功指标表格
架构图
详细API设计章节
安全威胁分析
监控与可观测性
风险评估矩阵
发布与回滚计划
依赖项跟踪
待解决问题板块

Best Practices

最佳实践

Do:

Include measurable acceptance criteria
Add architecture diagrams
Define explicit API contracts
Quantify performance targets
Document risks and mitigations
Get stakeholder review before implementation
Include security considerations
Define rollback procedures

Don't:

Use vague requirements ("fast", "scalable")
Skip non-functional requirements
Ignore security considerations
Leave alternatives unexplored
Omit testing strategy
Forget dependencies and risks

推荐做法：

包含可量化的验收标准
添加架构示意图
定义明确的API契约
量化性能目标
记录风险及对应的缓解方案
实现前获得利益相关方的评审意见
纳入安全考量
定义回滚流程

禁止做法：

使用模糊的需求描述（如「快速」、「可扩展」）
省略非功能性需求
忽略安全相关考量
不对备选方案进行调研
遗漏测试策略
忘记记录依赖项与风险