Back to Details

spec-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

spec-writing

规格文档编写

Purpose

目的

Produce implementation-ready specs from approved intent and known repository constraints.
根据已获批的需求意图和已知的代码仓库约束条件，生成可直接用于开发的规格文档。

Use When

适用场景

  • Business intent is approved and needs a technical spec.
  • Existing specs are incomplete, outdated, or too vague to implement safely.
  • A team needs interfaces, constraints, and validation captured in one place.
  • 业务需求意图已获批，需要转化为技术规格文档时。
  • 现有规格文档不完整、过时，或表述过于模糊，无法安全开展开发工作时。
  • 团队需要将接口、约束条件和验证规则集中记录在一处时。

Do Not Use When

不适用场景

  • The request is still missing key business decisions.
  • The task is already in active implementation and only needs a small local note.
  • 请求仍缺少关键业务决策时。
  • 任务已处于活跃开发阶段，仅需添加少量本地注释时。

Inputs

输入信息

  • Approved intent
  • Shared context
  • Existing contracts and repository constraints
  • 已获批的需求意图
  • 共享上下文信息
  • 现有契约及代码仓库约束条件

Outputs

输出成果

  • Spec draft
  • Assumptions list
  • Test and validation plan
  • 规格文档草稿
  • 假设条件清单
  • 测试与验证计划

Workflow

工作流程

  1. Frame the problem, goals, and scope boundary.
  2. Record the decisions, interfaces, dependencies, and constraints that implementers need.
  3. Separate approved decisions from assumptions or open risks.
  4. Add validation steps and acceptance criteria that match the requested change.
  1. 明确问题、目标及范围边界。
  2. 记录开发人员所需的决策、接口、依赖关系及约束条件。
  3. 将已获批的决策与假设条件或未解决的风险区分开。
  4. 添加与需求变更匹配的验证步骤及验收标准。

Rules

规则

  • Separate decisions from assumptions.
  • Keep acceptance criteria testable.
  • Prefer behavior-level clarity over vague architectural prose.
  • 区分已决策内容与假设内容。
  • 确保验收标准可测试。
  • 优先保证行为层面的清晰性，避免模糊的架构性描述。

Checklist

检查清单

  • Problem and goals are explicit.
  • Interfaces and constraints are documented.
  • Assumptions are separated from decisions.
  • Validation plan and acceptance criteria are present.
  • 问题与目标表述明确。
  • 接口与约束条件已记录在案。
  • 假设内容与已决策内容已区分。
  • 包含验证计划与验收标准。

Non-Negotiable Rules

不可违背规则

  • Do not leave decision-critical ambiguity inside the spec.
  • Do not present assumptions as approved decisions.
  • Do not skip validation planning for changes that affect behavior.
  • 规格文档中不得存在对决策至关重要的模糊表述。
  • 不得将假设条件表述为已获批的决策。
  • 对于影响行为的变更，不得跳过验证计划环节。

References

参考资料

  • specs/CONTRACT.md
  • context/
  • rules/global-rules.md
  • specs/CONTRACT.md
  • context/
  • rules/global-rules.md

Examples

示例

Example Trigger

示例触发场景

Write the implementation-ready spec for the new approval workflow using the approved product intent and current repo context.
结合已获批的产品需求意图和当前代码仓库上下文，编写新审批流程的可落地开发规格文档。

Example Output Shape

示例输出格式

Produce a spec with goals, scope, interfaces, constraints, assumptions, and a concrete test and validation plan.
生成包含目标、范围、接口、约束条件、假设条件，以及具体测试与验证计划的规格文档。