Back to Details

spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec

规范

When to use

使用场景

  • A task has decisions the agent would otherwise make alone
  • Invariants, contracts, schemas, or error behavior need to be preserved
  • Requirements, boundaries, or success criteria are unclear
  • The change touches multiple files, components, interfaces, or data shapes
Skip this skill for tiny, decision-complete changes. Prompt the agent directly.
  • 任务存在Agent原本会独自做出的决策
  • 需要保留不变量、契约、模式或错误行为
  • 需求、边界或成功标准不明确
  • 变更涉及多个文件、组件、接口或数据结构
对于微小的、决策明确的变更，无需使用此技能，直接向Agent发起请求即可。

Process

流程

  1. Use the first argument as the feature name and everything after it as the request.
  2. Read the task and relevant code first so the spec fits the project as it exists.
  3. Choose the lightest useful output:
    • no spec: say the work is prompt-ready
    • short spec: return one concise instruction in chat
    • full spec: write 
      docs/<feature-name>/spec.md
  4. For a full spec, include:
    • What
    • Context
    • Requirements
    • Design
    • Decisions
    • Invariants, when relevant
    • Error Behavior, when relevant
    • Testing Strategy
    • Out of Scope
  5. Keep it brief. Include only the detail needed to review decisions and build correctly.
  1. 将第一个参数用作功能名称，其余内容作为请求内容。
  2. 先阅读任务和相关代码，确保规范符合项目当前的实际情况。
  3. 选择最适用的轻量化输出：
    • 无需规范：说明工作已准备好直接发起请求
    • 简短规范：在对话中返回一条简洁的指令
    • 完整规范：编写
      docs/<feature-name>/spec.md
  4. 完整规范需包含：
    • 内容概述（What）
    • 背景上下文（Context）
    • 需求说明（Requirements）
    • 设计方案（Design）
    • 决策说明（Decisions）
    • 相关不变量（Invariants，如有需要）
    • 错误行为处理（Error Behavior，如有需要）
    • 测试策略（Testing Strategy）
    • 范围外内容（Out of Scope）
  5. 保持内容简洁，仅包含审查决策和正确构建所需的细节。

Verification

验证标准

  • The output weight matches the task's decision weight
  • Requirements are specific and testable
  • Decisions the agent would otherwise make are explicit
  • Invariants say what must not break and how to check it
  • Error behavior is covered where it matters
  • The design matches existing project patterns
  • Assumptions are marked instead of hidden
  • 输出的详细程度与任务的决策复杂度匹配
  • 需求具体且可测试
  • Agent原本会自行做出的决策已明确说明
  • 不变量明确了哪些内容不能被破坏以及检查方式
  • 重要场景下的错误行为已覆盖
  • 设计方案符合项目现有模式
  • 假设已明确标注，而非隐藏

Rules

规则

  • Make the smallest safe change to the system description that fully solves the problem.
  • If two reasonable implementations would behave differently, specify the default.
  • Call out interface, schema, config, CLI, or file-format changes explicitly.
  • Document public success shapes and important error shapes for external interfaces.
  • Include failure paths where they matter instead of leaving them implicit.
  • Do not write a greenfield design if the codebase already has patterns to follow.
  • Skip the spec for tiny, self-contained changes with obvious behavior.
  • If the request is missing a decision that would materially change the build, ask.
  • If the spec starts getting long, split the task instead of expanding the document.
  • Compress wording aggressively without dropping behavior, constraints, names, or examples that carry meaning.
  • 对系统描述做出最小且安全的变更，以完全解决问题。
  • 如果两种合理的实现会产生不同行为，需指定默认方案。
  • 明确指出接口、模式、配置、CLI或文件格式的变更。
  • 为外部接口记录公开的成功数据结构和重要错误数据结构。
  • 重要场景下需包含失败路径，而非隐含处理。
  • 如果代码库已有可遵循的模式，请勿从零开始设计。
  • 对于微小、独立且行为明确的变更，无需编写规范。
  • 如果请求缺少会实质性影响构建的决策，需主动询问。
  • 如果规范篇幅过长，应拆分任务而非扩展文档。
  • 在不丢失行为、约束、名称或有意义示例的前提下，尽可能精简措辞。