spec-development
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesespec-development
spec-development
Overview
概述
Research and develop specs through collaborative discussion. Spec-first approach - no jumping to action. Every process gets specced before implementation.
Announce at start: "Using spec-development. What are we speccing?"
When spec is ready: Switch to skill to execute it.
spec-execution通过协作讨论来研究和制定规格文档。采用规格先行的方法——不要直接行动。所有流程在实施前都必须先制定规格文档。
开始时需声明："正在使用spec-development技能。我们要制定什么规格文档？"
**当规格文档就绪后：**切换至技能来执行。
spec-executionCore Principles
核心原则
1. User Decides, Agent Proposes
1. 用户决策，Agent提议
The user has decision-making authority, not the agent. The agent proposes options, provides analysis, and makes recommendations - but the user makes all decisions.
Agent responsibilities:
- Present options with pros/cons
- Make recommendations with rationale
- Ask for confirmation before acting
Tool tip: When presenting options or asking for choices, use structured question tools when available (,AskQuestionor similar). These provide a better UX than plain text options.AskUserQuestion
Never assume a decision on behalf of the user:
- Wrong: "I'll use approach A since it's faster"
- Right: "Two options: A (faster) or B (safer). I recommend A because [reason]. Which do you prefer?"
Even when confident, confirm:
- Wrong: "This is clearly a bug, I'll fix it"
- Right: "This looks like a bug - [description]. Should I fix it?"
拥有决策权的是用户，而非Agent。Agent负责提供选项、分析信息并给出建议，但所有决策由用户做出。
Agent职责：
- 列出选项并说明优缺点
- 给出建议并附上理由
- 行动前需征得用户确认
**工具提示：**当呈现选项或询问选择时，若有结构化提问工具（如、AskQuestion或类似工具）请优先使用。相比纯文本选项，这些工具能提供更好的用户体验。AskUserQuestion
切勿擅自替用户做决策：
- 错误示例："我将采用方案A，因为它更快"
- 正确示例："有两个选项：A（速度更快）或B（更安全）。我推荐A，理由是[具体原因]。您更倾向于哪个？"
即使非常确定，也要确认：
- 错误示例："这明显是个bug，我来修复"
- 正确示例："这看起来是一个bug——[描述详情]。需要我来修复吗？"
2. Discussion by Default
2. 默认进行讨论
When user input is ambiguous, assume they want to discuss, not act.
User says: "the screenshot process needs work"
- Wrong: Start editing the screenshot process
- Right: "What's not working? The steps, the naming, something else?"
User says: "add priority to the table"
- Wrong: Add a Priority column with your best guess
- Right: "How should priority be defined?"
当用户输入模糊不清时，默认认为用户希望先讨论，而非直接行动。
用户表述："截图流程需要改进"
- **错误做法：**直接开始编辑截图流程
- 正确做法："哪里需要改进？是步骤、命名还是其他方面？"
用户表述："给表格添加优先级列"
- **错误做法：**凭猜测添加优先级列
- 正确做法："优先级应该如何定义？"
3. Define Before Use
3. 先定义再使用
Never use vague or undefined terms. If a concept isn't defined, define it first.
Wrong: "High priority = significant market presence"
Right: "How is priority defined? Proposal: High = 3+ sources, Medium = 2, Low = 1"
切勿使用模糊或未定义的术语。若某个概念未被定义，需先对其进行定义。
错误示例："高优先级=显著的市场存在感"
正确示例："优先级该如何定义？提议：高=3个及以上来源，中=2个来源，低=1个来源"
4. Propose, Show, Confirm
4. 提议、展示、确认
Never make changes without showing exactly what will change and getting confirmation.
Pattern:
- State what you propose
- Show the exact change (the actual text/code)
- Ask for confirmation
- Only then execute
在未明确展示具体变更内容并获得确认前，切勿进行任何修改。
流程模式：
- 说明你的提议内容
- 展示具体的变更内容（实际文本/代码）
- 请求用户确认
- 获得确认后再执行
5. One Thing at a Time
5. 一次只处理一件事
Don't bundle multiple changes or questions. Each message should address one thing.
Wrong: "I'll add the template, update the criteria, and fix the naming convention"
Right: "First, let's define the template. Here's what I propose: [show]. Does this work?"
不要将多个变更或问题捆绑在一起。每条消息应仅处理一件事。
错误示例："我将添加模板、更新标准并修复命名规范"
正确示例："首先，我们来定义模板。以下是我的提议：[展示内容]。这样可行吗？"
6. Trace Decisions
6. 记录决策依据
Document why decisions were made, not just what was decided.
In specs, include rationale:
markdown
**Priority criteria:**
- High: 3+ sources
- Medium: 2 sources
- Low: 1 source
> Rationale: Based purely on mention frequency. Simple, concrete, measurable.不仅要记录决策内容，还要记录做出决策的原因。
在规格文档中，需包含决策依据：
markdown
**优先级标准：**
- 高：3个及以上来源
- 中：2个来源
- 低：1个来源
> 决策依据：完全基于提及频率。简单、具体、可衡量。7. Don't Assume, Verify
7. 不要假设，要验证
Never guess or infer. Always research and check.
- Need a command? Check the docs
- API returns data? Check the actual response, don't assume structure
- Build succeeded? Check the output, don't assume
- File exists? Verify, don't assume from context
- User says X is broken? Reproduce before fixing
切勿猜测或推断。始终要进行研究和核实。
- 需要某个命令？查阅文档
- API返回数据？查看实际响应，不要假设结构
- 构建是否成功？查看输出结果，不要假设
- 文件是否存在？进行验证，不要仅凭上下文猜测
- 用户称X功能损坏？先复现问题再修复
8. Cross-Reference, Don't Duplicate
8. 交叉引用，避免重复
Link to existing specs instead of restating. Keep specs DRY.
Wrong: Copy the criteria into every research doc
Right:
> **Spec**: [../README.md](../README.md)链接到现有规格文档，而非重复内容。保持规格文档的DRY（不重复）原则。
**错误做法：**将标准复制到每份研究文档中
正确做法：
> **规格文档**：[../README.md](../README.md)9. Template Everything
9. 所有流程模板化
If a process will repeat, create a template in the spec.
Templates should include:
- Structure with placeholders
- Example of filled-in version
- Where the template lives (which spec doc)
若某个流程会重复出现，需在规格文档中创建对应的模板。
模板应包含：
- 带占位符的结构
- 填写完成后的示例
- 模板所在位置（对应哪个规格文档）
10. Log Everything (With Permission)
10. 所有内容需记录（需获得许可）
Log what's defined, ask about the rest.
Log without asking:
- What the skill explicitly requires (step completion, test results, bugs, status updates)
Ask before logging:
- Any action, decision, or finding not explicitly required
- Investigations, design decisions, context, side discoveries
Pattern:
- Do the work
- Ask: "Should I log [this finding/decision/investigation]?"
- If yes, log it; if no, move on
Wrong: Assume everything should be logged and document without asking
Wrong: Skip logging something potentially valuable without asking
Right: "I checked for similar issues in other files and found none. Should I log this investigation?"
记录已定义的内容，对于其他内容需先询问。
无需询问即可记录：
- 技能明确要求的内容（步骤完成情况、测试结果、bug、状态更新）
记录前需询问：
- 任何未被技能明确要求的操作、决策或发现
- 调查过程、设计决策、背景信息、额外发现
流程模式：
- 完成工作
- 询问："我是否需要记录[该发现/决策/调查过程]？"
- 若用户同意则记录，若不同意则继续下一步
**错误做法：**假设所有内容都需要记录，未经询问就进行文档记录
**错误做法：**未经询问就跳过可能有价值的内容记录
正确做法："我检查了其他文件中是否存在类似问题，未发现相关内容。我需要记录这次调查过程吗？"
Process
流程步骤
Step 1: Create Research File
步骤1：创建研究文档
Every spec development starts with a research file. This captures the discussion, decisions, and rationale that lead to the spec.
Actions:
- Propose a location for the spec folder (naming convention: )
[year]-[month]-[day]-[work-name] - Get user confirmation on location
- Create before any discussion or investigation
research.md
This is blocking - do not proceed until research file exists.
Research file template: assets/research-template.md
所有规格文档的开发都始于研究文档。该文档用于记录制定规格文档过程中的讨论内容、决策结果和决策依据。
操作步骤：
- 提议规格文档文件夹的存储位置（命名规范：）
[年份]-[月份]-[日期]-[工作名称] - 获得用户对存储位置的确认
- 在进行任何讨论或调查前，先创建文档
research.md
此步骤为阻塞式——研究文档创建完成前，不得继续后续步骤。
研究文档模板：assets/research-template.md
Step 2: Research & Discuss
步骤2：研究与讨论
Investigate and discuss until the spec can be written with no ambiguity.
Activities:
- Understand scope - what is this spec for? What processes does it cover?
- Work from concrete examples - start with a real case, then generalize
- Define all terms - every term used must have a clear definition
- Ask clarifying questions:
- "How is [term] defined?"
- "What's the inclusion/exclusion criteria?"
- "Should this be a template?"
- "Where does this get documented?"
- "Is there an existing spec this should reference?"
Update research file immediately after each:
- Finding - something you learned
- Decision - a decision made by the user
- Answer - a question that got resolved
Rules:
- Never batch updates - update immediately after each finding
- Only log decisions after user has made them (agent proposes, user decides)
- Strike through answered questions, add answer reference
进行调查和讨论，直到规格文档可以毫无歧义地被撰写出来。
活动内容：
- 明确范围——该规格文档的用途是什么？涵盖哪些流程？
- 从具体示例入手——先从实际案例开始，再进行归纳总结
- 定义所有术语——使用的每个术语都必须有清晰的定义
- 提出澄清问题：
- "[术语]的定义是什么？"
- "纳入/排除标准是什么？"
- "这需要做成模板吗？"
- "该内容应记录在何处？"
- "是否有可参考的现有规格文档？"
每次完成以下操作后，需立即更新研究文档：
- 发现——你了解到的新信息
- 决策——用户做出的决策
- 答案——已解决的问题
规则：
- 切勿批量更新——每次发现后需立即更新
- 仅在用户做出决策后记录该决策（Agent提议，用户决策）
- 对已解答的问题添加删除线，并附上答案参考
Step 3: Confirm Research Complete
步骤3：确认研究完成
Before writing the spec, explicitly confirm with the user:
"I believe research is complete. We have:
- [summary of key decisions]
- [summary of defined terms]
- [any open questions resolved]
Ready to write the spec?"
Do not proceed to spec writing without user confirmation.
The user decides when research is complete. The agent may propose that research seems sufficient, but only the user can confirm readiness to proceed.
在撰写规格文档前，需明确向用户确认：
"我认为研究已完成。我们已确定：
- [关键决策摘要]
- [已定义术语摘要]
- [所有未解决问题已得到解答]
是否可以开始撰写规格文档？"
未经用户确认，不得开始撰写规格文档。
**研究是否完成由用户决定。**Agent可提议研究已足够充分，但只有用户能确认是否可以进入下一步。
Step 4: Write the Spec
步骤4：撰写规格文档
Create in the same folder as research.
spec.mdSpec template: assets/spec-template.md
Required sections:
- Header (Status, Created, Research link)
- Overview (what + current/target state)
- Scope (In Scope / Out of Scope)
- Steps (with Action, Files, Changes, Verification per step)
- Verification Checklist (overall checks after all steps)
- Execution Plan (mode + rationale)
Optional sections (add as needed):
- Context/Background - domain-specific info
- Testing Plan - manual/automated testing
- Rollback Plan - if changes are risky
在研究文档所在的同一文件夹中创建文档。
spec.md规格文档模板：assets/spec-template.md
必填章节：
- 页眉（状态、创建日期、研究文档链接）
- 概述（用途+当前/目标状态）
- 范围（纳入范围/排除范围）
- 步骤（每个步骤需包含操作、涉及文件、变更内容、验证方式）
- 验证清单（所有步骤完成后的整体检查项）
- 执行计划（模式+理由）
可选章节（按需添加）：
- 背景信息——特定领域的相关信息
- 测试计划——手动/自动化测试方案
- 回滚计划——当变更存在风险时的回滚方案
Step 5: Confirm Spec Complete
步骤5：确认规格文档完成
After all sections are written, ask the user to approve the spec as final:
"The spec is drafted. All sections complete. Is this spec approved and ready for execution?"
The user decides when the spec is ready. Do not consider the spec final or begin execution until the user explicitly approves it.
所有章节撰写完成后，请求用户批准规格文档定稿：
"规格文档已起草完成，所有章节均已完善。该规格文档是否已获批并可执行？"
**规格文档是否就绪由用户决定。**在用户明确批准前，不得将规格文档视为定稿或开始执行。
Execution Plan Requirement
执行计划要求
Every spec must include an execution plan. Before finalizing, propose the execution mode and get user confirmation:
"For execution, I recommend [Direct/Subagents] because [reason]. Does this work?"
If Subagents, also propose: sequential steps, parallel steps, max concurrent.
Recommendation guidelines:
- Default: Direct (especially for coding)
- Subagents only when: many similar items (5+), detailed unambiguous steps, items are independent
The user decides. Agent provides recommendation with rationale; user confirms or chooses differently.
每份规格文档都必须包含执行计划。在定稿前，需提议执行模式并获得用户确认：
"对于执行环节，我推荐[直接执行/子Agent执行]，理由是[具体原因]。这样可行吗？"
若选择子Agent执行，还需提议：步骤执行顺序（串行/并行）、最大并发数。
推荐准则：
- 默认：直接执行（尤其适用于编码工作）
- 仅在以下情况使用子Agent执行：存在大量相似任务（5个及以上）、步骤明确无歧义、任务相互独立
**最终由用户决策。**Agent提供带理由的建议，用户确认或选择其他方案。
When to Switch to Execution
何时切换至执行环节
After the spec is approved, switch to the skill to execute it.
spec-execution| Situation | Action |
|---|---|
| Spec approved and ready | Switch to |
| User wants to start executing | Switch to |
| Gap found during execution | Return here to fill the gap, then back to execution |
规格文档获批后，切换至技能来执行。
spec-execution| 场景 | 操作 |
|---|---|
| 规格文档已获批并就绪 | 切换至 |
| 用户希望开始执行 | 切换至 |
| 执行过程中发现漏洞 | 返回此技能填补漏洞，然后再回到执行环节 |
Anti-Patterns
反模式
Don't do these:
| Anti-Pattern | Instead |
|---|---|
| Jump to editing when user mentions a file | Ask what they want to change |
| Use undefined terms ("market presence") | Define terms first |
| Bundle multiple changes | One change at a time |
| Assume file contents | Read the file |
| Guess at commands | Check documentation |
| Say "I'll do X, Y, and Z" | "First, let's address X. [details]. OK?" |
| Start writing spec without research file | Create research file first |
| Write spec before user confirms research complete | Confirm research complete first |
切勿采取以下做法：
| 反模式 | 正确做法 |
|---|---|
| 用户提及某个文件时直接开始编辑 | 询问用户想要修改的内容 |
| 使用未定义的术语（如"市场存在感"） | 先定义术语 |
| 捆绑多个变更操作 | 一次只处理一个变更 |
| 假设文件内容 | 读取文件实际内容 |
| 猜测命令用法 | 查阅文档 |
| 说"我将做X、Y和Z" | "首先，我们来处理X。[详情]。可以吗？" |
| 未创建研究文档就开始撰写规格文档 | 先创建研究文档 |
| 用户未确认研究完成就开始撰写规格文档 | 先确认研究已完成 |
Checklist
检查清单
Before taking any action:
- Have I created a research file?
- Have I defined all terms I'm using?
- Have I confirmed with user before proceeding to next step?
- Am I doing one thing, not multiple things?
- Have I updated the research file with this finding/decision?
采取任何行动前，请确认：
- 是否已创建研究文档？
- 是否已定义所有使用的术语？
- 进入下一步前是否已获得用户确认？
- 是否在一次只处理一件事，而非多件事？
- 是否已将该发现/决策更新至研究文档？