规格
- 作者仓库星标 38
- 许可证 MIT
- 作者仓库 builder-skills
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @kazdenc · MIT
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步:阅读要求
在写作之前,收集输入。没有要求的规范只是猜测。来源 · 从中提取什么 PRD · 问题、目标、功能需求、非功能需求、范围边界 工作故事 · 用户工作流程、验收标准、边缘案例 对话 · 如果两者都不存在,则采访用户以确定系统必须做什么以及为谁做
第 2 步:编写规格
使用这个结构。根据项目调整标题——并非每个部分每次都适用。
# Technical Specification
A tech spec answers **how** we'll build something — without over-prescribing implementation details that engineers should own. It bridges product requirements to engineering execution.
## Step 1: Read the Requirements
Before writing, gather the inputs. A spec without requirements is guesswork.
| Source | What to pull from it |
|--------|---------------------|
| **PRD** | Problem, goals, functional requirements, non-functional requirements, scope boundaries |
| **Job stories** | User workflows, acceptance criteria, edge cases |
| **Conversation** | If neither exists, interview the user to establish what the system must do and for whom |
Flag anything ambiguous. A spec built on vague requirements produces vague engineering.
## Step 2: Write the Spec
Use this structure. Adapt headings to the project — not every section applies every time.
```
# Tech Spec: [Feature / System Name]
## Overview
One paragraph. What this is, why we're building it, and what it connects to.
Link to the PRD or source requirements.
## Technical Approach
The core design decision. How this fits into the existing system.
Keep it to the architecture level — components, their responsibilities,
how they interact. Don't write pseudocode unless it clarifies a tricky algorithm.
## Data Model
New tables, fields, or schema changes. Include:
- Field name, type, constraints
- Relationships to existing models
- Migration notes (new table vs altering existing)
## API Design
Endpoints, methods, request/response shapes.
For each endpoint:
- Method + path
- Request body / params
- Response shape
- Error cases
## Edge Cases
What happens when things go wrong or get weird.
| Case | Behavior | Rationale |
|------|----------|-----------|
| User submits duplicate | Return existing record, don't create new | Prevents data bloat |
| Payload exceeds size limit | Reject with 413, log for monitoring | Protects downstream services |
## Testing Strategy
What gets tested and how.
- Unit tests: which modules, what coverage target
- Integration tests: which workflows end-to-end
- Manual QA: what can't be automated and why
## Migration Plan
Only if changing existing systems. Cover:
- Data migration steps
- Backward compatibility (can old and new coexist during rollout?)
- Rollback procedure
## Rollout Plan
How this gets to users.
- Feature flag strategy
- Phased rollout stages (internal → beta → GA)
- Monitoring and alerting during rollout
- Success/failure criteria for each stage
```
## Decision Log
Every non-obvious choice gets logged. This prevents re-litigating decisions later and helps future engineers understand why things are the way they are.
```
## Decisions
### D-1: [Short description of the decision]
**Options considered:**
1. Option A — [brief description]
2. Option B — [brief description]
3. Option C — [brief description]
**Decision:** Option B
**Rationale:** [Why this option wins. Reference constraints, trade-offs,
or requirements that drove the choice.]
```
Keep decisions numbered (D-1, D-2) so they can be referenced in code comments and PR descriptions.
## Quality Checks
Before delivering the spec, verify:
- **Does it answer "how" without dictating unnecessary "what exactly"?** The spec should constrain the architecture, not micromanage the implementation. Engineers need room to make local decisions.
- **Are edge cases covered?** If you only describe the happy path, the implementation will only handle the happy path.
- **Is the data model complete?** Missing a field or relationship here means a migration later.
- **Do API contracts match the requirements?** Walk each job story through the API. Does the data flow support every acceptance criterion?
- **Is the testing strategy proportional?** Critical paths get thorough tests. Low-risk utilities get basic coverage. Don't spec 100% coverage everywhere.
- **Is the rollout reversible?** If something goes wrong in production, can you roll back without data loss?
## Scope Boundaries
A tech spec is not:
- **A tutorial.** Don't explain how frameworks work. Assume engineering competence.
- **A PRD.** Don't redefine what we're building. Reference the PRD and focus on how.
- **A project plan.** Don't include timelines or task assignments. That's a separate artifact.
## When the Spec Is Done
Ship it with:
1. **Clear status** — Draft, In Review, or Approved
2. **Open questions** — What still needs answers before building starts
3. **Review ask** — Who should review (engineering, security, platform) and what feedback you need
章节与文件索引
按说明文件中的顺序排列。
第 1 步:阅读要求
第 2 步:编写规格
决策日志
质量检查
范围边界
文件/命令 -> request/response · Success/failure
内容校验值 -> 0742b2197f15
当前原文的自动摘译,尚未人工审校。
决策日志
每个不明显的选择都会被记录下来。这可以防止以后重新对决策提出诉讼,并帮助未来的工程师理解事情为什么会是这样。对决策进行编号(D-1、D-2),以便可以在代码注释和 PR 描述中引用它们。
质量检查
在交付规范之前,请验证:它是否回答了“如何”而没有规定不必要的“到底是什么”?规范应该限制架构,而不是对实现进行微观管理。工程师需要空间来做出本地决策。边缘情况是否被覆盖?如果您只描述快乐路径,则实现将只处理快乐路径。数据模型是否完整?这里缺少字段或关系意味着稍后迁移。
范围边界
技术规范不是:教程。不要解释框架如何工作。假设具有工程能力。一个珠三角。不要重新定义我们正在构建的东西。参考 PRD 并重点关注如何实现。一个项目计划。不要包括时间表或任务分配。那是一个单独的工件。