Back to Details

spec-coding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

需求跟进（Spec Coding）

Requirements Tracking (Spec Coding)

默认用一份需求 Markdown 维护当前规则、设计要点和验证结果。 先明确需求和验收，再实现并验证，历史交给 Git。
By default, use a single requirements Markdown document to maintain current rules, key design points, and verification results. First clarify requirements and acceptance, then implement and verify; leave history to Git.

流程

Workflow

  1. 发现约定
    • 阅读仓库 
      AGENTS.md
      、需求索引和既有文档结构，沿用已有编号与路径。
    • 没有约定时使用 
      docs/project.md
      和需求(R-xx)。
    • 登记前按模块、接口、配置或业务规则查索引，阅读范围相交的需求及验收标准。
  2. 登记
    • 在索引登记，默认使用单份需求 MD。
    • 细化或纠正同一需求时优先更新原编号；独立需求才新建编号并登记关联。
    • 参考 spec-template.md 和 spec-example.md。
  3. 定稿
    • 写清范围、非目标、验收标准、关键决策和待确认项。
    • 影响实现的待确认项闭环后，状态转为 
      开发中
      ，再修改代码。
  4. 验证先行
    • 为每个验收标准选择足以证明行为的最低成本验证层级。
    • 先建立失败基线或说明现有缺口，再实现到通过。
    • 一个验收标准可由多个用例证明，一个用例也可覆盖多个相关标准。
  5. 实现与收敛
    • 按验证映射实施，完成后更新对应验证项，替换失效结论。
    • 测试环境通过但尚未发布时保持 
      待回归
      。
    • 实际发布后转为 
      已上线
      。
  6. 收尾
    • 入口、涉及范围、关联需求或状态变化时更新索引。
    • 替代已有规则时标注旧条目的替代关系与适用范围，避免两份规则同时有效。
    • 长期仓库规则或权威入口变化时更新 
      AGENTS.md
      。
    • 对照本轮差异检查规则、引用和验证范围，避免遗留旧结论或重复记录。
    • commit message 引用 spec 路径或编号。
  1. Discover conventions
    • Read the repository's 
      AGENTS.md
      , requirements index, and existing document structure, and follow existing numbering and paths.
    • When no conventions exist, use 
      docs/project.md
      and requirement(R-xx).
    • Before registration, search the index by module, interface, configuration, or business rule, and read requirements and acceptance criteria whose scope intersects.
  2. Register
    • Register the requirement in the index; by default, use a single requirement MD.
    • When refining or correcting the same requirement, prefer updating its original ID; create a new ID and record the relationship only for an independent requirement.
    • Refer to spec-template.md and spec-example.md.
  3. Finalize
    • Clearly document the scope, non-goals, acceptance criteria, key decisions, and open questions.
    • Once open questions affecting implementation are resolved, transition the status to 
      开发中
      , and then modify the code.
  4. Verification first
    • For each acceptance criterion, select the lowest-cost verification level sufficient to demonstrate the behavior.
    • First establish a failing baseline or document the existing gap, then implement until it passes.
    • One acceptance criterion may be proven by multiple test cases, and one test case may cover multiple related criteria.
  5. Implementation and convergence
    • Implement according to the verification mapping; when complete, update the corresponding verification items and replace stale conclusions.
    • If it passes in the test environment but has not yet been released, keep the status as 
      待回归
      .
    • After the actual release, transition the status to 
      已上线
      .
  6. Wrap-up
    • Update the index when the entry point, affected scope, related requirements, or status changes.
    • When superseding existing rules, mark the old entry's replacement relationship and applicable scope to avoid having two sets of rules valid at the same time.
    • Update 
      AGENTS.md
      when long-term repository rules or authoritative entry points change.
    • Check the rules, references, and verification scope against the current diff to avoid leaving stale conclusions or duplicate records.
    • Reference the spec path or ID in the commit message.

文档组织

Document Organization

默认使用一份 
docs/xxx需求.md
，不主动建立需求目录或拆分设计、验证、任务文件。 按需保留背景与范围、验收标准、关键设计、待确认项和验证；任务较多时在本文列出。
  • 索引：维护入口、状态、涉及范围与关联需求，不复制正文、测试数量或命令。
  • 接口文档：面向使用方，可独立维护对外契约。
  • 拆分条件：用户明确要求或某部分确需独立维护时才拆分，不以篇幅或轮次为依据。
  • 已有结构：遵循仓库约定，不强制迁移目录；拆分后用链接引用，不重复记录。
By default, use a single 
docs/xxx需求.md
; do not proactively create a requirements directory or split design, verification, and task files. Retain the background and scope, acceptance criteria, key design, open questions, and verification as needed; if there are many tasks, list them in this document.
  • Index: Maintain the entry point, status, affected scope, and related requirements; do not duplicate the body text, test counts, or commands.
  • Interface documentation: Intended for consumers and may independently maintain external contracts.
  • Splitting criteria: Split only when explicitly requested by the user or when a particular section genuinely needs independent maintenance; do not split based on length or the number of iterations.
  • Existing structure: Follow repository conventions and do not force directory migrations; after splitting, use links for references and do not duplicate records.

连续迭代与审阅

Continuous Iteration and Review

  • 局部审阅：每轮说明行为变化、影响范围和未验证项；小改动只展示局部差异。
  • 原位收敛：更新对应规则和验收标准，删除失效描述，不按对话轮次追加章节。
  • 按需同步：按实际影响更新文档，不额外建立变更文件或增加确认环节。
  • 排版隔离：需求变更与纯排版整理分开，避免重排无关内容。
  • Focused review: In each iteration, explain behavior changes, impact scope, and unverified items; for small changes, show only the local diff.
  • Converge in place: Update the corresponding rules and acceptance criteria, remove stale descriptions, and do not append sections by conversation turn.
  • Sync as needed: Update documentation according to the actual impact; do not create additional change files or add confirmation steps.
  • Formatting isolation: Separate requirement changes from formatting-only cleanup to avoid reformatting unrelated content.

核心 spec 要求

Core Spec Requirements

  • 状态：
    规划中 / 开发中 / 待回归 / 已上线
    ，核心 spec 维护状态，索引只展示摘要。
  • 范围与关联
    • 明确本次范围与非目标；有范围交集时，区分重复、依赖、扩展、替代或冲突。
    • 具体关系在本文说明并链接相关需求，替代应明确到验收标准或规则及生效范围。
    • 共享模块不等于冲突，编号先后不代表覆盖；未核实的关系不可写成确定结论。
  • 验收标准
    • 描述可测试的行为，中文条件句使用「当、应、若、则」。
    • 「应」表示需要满足的要求；简单规则直接陈述，不强行套完整条件句。
    • 编号写作需求(R-01)、验收标准(AC-1)，范围写作验收标准(AC-1~AC-4)。
    • 括号和范围连接符使用半角字符，两侧不加空格；保留已有编号和路径。
  • 输入约束：明确格式、数量/长度上限、空值和超限行为。
  • 关键设计：按需在本文记录影响实现或验收的结论与原因。
  • 待确认项与假设
    • 区分阻塞项、默认值和待核实假设，说明依据与验证方式；未解决的规则冲突也列在此处。
    • 阻塞项闭环前不实施依赖它的内容；不依赖该项的已授权工作可继续。
    • 单测不能证明的展示效果或上游口径，单列联调验证缺口。
  • 验证映射
    • 关联验收标准、风险/行为、验证层级及用例/证据，不要求全部对应单元测试。
    • 已有独立验证文件时，spec 只保留覆盖关系和链接，不复制执行结果。
  • 验证结果
    • 默认集中在本文验证节，记录当前结论、范围、版本或改动依据及证据。
    • 更新已有条目，不逐轮追加摘要；移除失效结论，历史交给 Git。
    • 局部验证只证明对应范围，其余改动标明未验证，不沿用旧版本的全量通过结论。
  • Status: 
    规划中 / 开发中 / 待回归 / 已上线
    . The core spec maintains the status, while the index displays only a summary.
  • Scope and relationships
    • Clearly define the current scope and non-goals; when scopes overlap, distinguish duplication, dependency, extension, supersession, and conflict.
    • Explain the specific relationship in this document and link related requirements. A supersession must identify the acceptance criterion or rule and its effective scope.
    • Sharing a module does not imply a conflict, and numbering order does not indicate supersession; unverified relationships must not be stated as definitive conclusions.
  • Acceptance criteria
    • Describe testable behavior. Chinese conditional sentences should use 「当、应、若、则」.
    • 「应」 denotes a requirement that must be met; state simple rules directly without forcing them into a complete conditional sentence.
    • Write IDs as requirement(R-01) and acceptance criterion(AC-1), and write ranges as acceptance criterion(AC-1~AC-4).
    • Use half-width characters for parentheses and range connectors, with no spaces on either side; preserve existing IDs and paths.
  • Input constraints: Specify the format, count/length limits, null values, and behavior when limits are exceeded.
  • Key design: Record conclusions and rationale that affect implementation or acceptance in this document as needed.
  • Open questions and assumptions
    • Distinguish blockers, default values, and assumptions to verify, and explain the basis and verification method; list unresolved rule conflicts here as well.
    • Do not implement dependent content until the blocker is resolved; authorized work that does not depend on it may continue.
    • List integration verification gaps separately for visual effects or upstream semantics that unit tests cannot prove.
  • Verification mapping
    • Map acceptance criteria, risks/behavior, verification levels, and test cases/evidence; do not require every criterion to map to a unit test.
    • When standalone verification files already exist, keep only the coverage relationships and links in the spec, and do not duplicate execution results.
  • Verification results
    • By default, centralize results in this document's verification section, recording the current conclusion, scope, version or change basis, and evidence.
    • Update existing entries rather than appending a summary after each iteration; remove stale conclusions and leave history to Git.
    • Partial verification proves only the corresponding scope. Mark other changes as unverified, and do not carry forward an old version's conclusion that all checks passed.

与测试 skill 的边界

Boundaries with the Testing Skill

本 skill 管理验收标准与证据的对应关系，不规定具体测试实现。
Spring 项目涉及测试设计、实现或评审时：
  • 技能可用：使用 
    spring-testing
    选择测试层级和实现方式。
  • 技能不可用：遵循仓库既有测试约定。
两个 skill 独立触发，普通 spec 任务不自动加载测试专项知识。
This skill manages the mapping between acceptance criteria and evidence; it does not prescribe specific test implementations.
For Spring projects involving test design, implementation, or review:
  • Skill available: Use 
    spring-testing
    to select the testing level and implementation approach.
  • Skill unavailable: Follow the repository's existing testing conventions.
The two skills trigger independently; ordinary spec tasks do not automatically load specialized testing knowledge.

中文 Markdown

Chinese Markdown

中文行文与源码换行遵循同包的 cn-writing。
Chinese prose and source-code line breaks follow cn-writing from the same package.

约束

Constraints

  • 按风险建档：是否新建 spec 取决于风险、协作和回归面，不以改动行数判断。
  • 先更新规则：需求变更先改核心 spec 和对应验证映射，再改代码。
  • 跨仓库同步：在核心 spec 记录需求落点、传播范围和同步状态。
  • 环境说明：构建与部署步骤放 runbook，
    AGENTS.md
    保留必要约束、入口及链接。
  • 入口约定：不强制创建或复制兼容文件，遵循仓库 
    AGENTS.md
    /
    CLAUDE.md
    的单源策略。
  • Create documentation based on risk: Whether to create a new spec depends on the risk, collaboration, and regression surface, rather than the number of changed lines.
  • Update rules first: For requirement changes, update the core spec and corresponding verification mapping before modifying the code.
  • Cross-repository synchronization: Record the requirement landing points, propagation scope, and synchronization status in the core spec.
  • Environment guidance: Put build and deployment steps in the runbook; retain necessary constraints, entry points, and links in 
    AGENTS.md
    .
  • Entry-point conventions: Do not require creating or copying compatibility files; follow the repository's single-source strategy in 
    AGENTS.md
    /
    CLAUDE.md
    .