Back to Details

add-functional-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Add Functional Spec

添加Functional Spec

Always use the skill 
load-plain-reference
to retrieve the ***plain syntax rules — but only if you haven't done so yet.
始终使用
load-plain-reference
技能来获取plain语法规则——但仅当你尚未获取过时才需要这么做。

Workflow

工作流程

  1. Identify the target 
    .plain
    file.     If ambiguous, ask the user.
  2. Read the entire file to understand existing definitions, implementation reqs, and all current functional specs (including those in 
    requires
    modules).
  3. Draft the functional spec following the rules below.
  4. Analyze complexity — use the 
    analyze-if-func-spec-too-complex
    skill to verify the drafted spec implies ≤ 200 LOC. If too complex, use the 
    break-down-func-spec
    skill to split it, then repeat from step 3 for each resulting spec.
  5. Check for conflicts with every existing functional spec — this is critical. Run 
    analyze-func-specs
    once with the new spec plus all existing specs (in the file and in any 
    requires
    chain) as a single batch. The batched analyzer returns every conflicting pair in one call — do not invoke a pair-by-pair analyzer. For each conflicting pair it reports, run 
    resolve-spec-conflict
    on that pair; re-run 
    analyze-func-specs
    over the touched set after each resolution until the verdict is 
    COMPATIBLE
    .
  6. Append the spec to the end of the 
    ***functional specs***
    section (specs are chronological; new ones go last).
  7. Read the file again to confirm correct placement and syntax.
  1. 确定目标
    .plain
    文件    。如果存在歧义，请询问用户。
  2. 读取整个文件，以理解现有定义、实现要求以及所有当前的functional specs（包括
    requires
    模块中的规范）。
  3. 起草功能规范，遵循以下规则。
  4. 分析复杂度——使用
    analyze-if-func-spec-too-complex
    技能验证起草的规范对应的代码变更行数≤200 LOC。如果过于复杂，使用
    break-down-func-spec
    技能将其拆分，然后针对每个拆分后的规范重复步骤3。
  5. 检查冲突——这一点至关重要，需与所有现有functional specs进行冲突检查。将新规范与所有现有规范（文件中以及任何
    requires
    链中的规范）作为一个批次，一次性调用
    analyze-func-specs
    。批量分析器会在一次调用中返回所有冲突对——不要调用逐对分析器。对于报告的每个冲突对，对该对运行
    resolve-spec-conflict
    ；每次解决后，重新对相关集合运行
    analyze-func-specs
    ，直到结果为
    COMPATIBLE
    。
  6. 将规范追加到
    ***functional specs***
    部分的末尾    （规范按时间顺序排列；新规范放在最后）。
  7. 再次读取文件，确认放置位置和语法正确。

Rules

规则

Complexity Limit

复杂度限制

Each functional spec must imply a maximum of 200 changed lines of code. If the requirement is too large, use the 
break-down-func-spec
skill to split it into multiple smaller, independent specs. Do not include LOC estimates in the spec text.
每个functional spec对应的代码变更行数最多为200行。如果需求过大，使用
break-down-func-spec
技能将其拆分为多个更小、独立的规范。不要在规范文本中包含LOC估算。

Chronological Ordering

时间顺序

Specs are rendered incrementally, top to bottom. The renderer has no knowledge of future specs — only previously rendered specs are in context. This means:
  • A new spec can reference behavior defined by earlier specs.
  • A new spec cannot assume anything about specs that come after it.
  • Place the new spec at the correct position if it must come before a future spec; otherwise append at the end.
规范从上到下逐步呈现。渲染器不了解未来的规范——只有之前呈现的规范在上下文范围内。这意味着：
  • 新规范可以引用早期规范定义的行为。
  • 新规范不能假设任何后续规范的内容。
  • 如果新规范必须放在某个后续规范之前，则将其放在正确的位置；否则追加到末尾。

Language Agnosticism

语言无关性

Write in terms of behavior, concepts, and domain logic — not implementation constructs. Avoid language-specific types, generics syntax, framework annotations, or other constructs tied to a particular language or framework. General technical terms (null values, JSON types, HTTP status codes) are fine. Language-specific guidance belongs in 
***implementation reqs***
.
以行为、概念和领域逻辑的术语来编写，而非实现结构。避免特定语言的类型、泛型语法、框架注解或其他与特定语言或框架相关的结构。通用技术术语（空值、JSON类型、HTTP状态码）是可以的。特定语言的指导内容应放在
***implementation reqs***
中。

No Conflicts

无冲突

The new spec must not contradict any existing functional spec. Conflicting specs are the most costly outcome. Before adding, review all existing specs and verify the new one is compatible. Use 
analyze-func-specs
to check the new spec against every existing spec in one batched call — it lists every conflicting pair, so a pair-by-pair analyzer is not needed. If ambiguity exists, add explicit detail to eliminate any conflicting interpretation. For each conflicting pair the batched analyzer reports, use the 
resolve-spec-conflict
skill to diagnose and fix it before proceeding.
新规范不得与任何现有functional spec相矛盾。冲突的规范是代价最高的结果。添加前，查看所有现有规范并验证新规范的兼容性。使用
analyze-func-specs
一次性批量调用来检查新规范与所有现有规范的冲突——它会列出所有冲突对，因此不需要逐对分析器。如果存在歧义，添加明确的细节以消除任何冲突性解释。对于批量分析器报告的每个冲突对，在继续之前使用
resolve-spec-conflict
技能进行诊断和修复。

Disambiguation

消除歧义

Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation. If a single line is not enough to fully disambiguate the behavior, use nested sub-bullets to add detail. Nested lines clarify the parent spec; they do not introduce separate functionality. Even with nested detail, the spec must still imply ≤ 200 LOC.
plain
- :User: should be able to send a :Message: to a :Conversation:.
  - A :Message: must have non-empty content.
  - The :Message: is appended to the end of the :Conversation:.
  - All :Participant: members of the :Conversation: can see the new :Message:.
每个functional spec必须明确无误——渲染器应该只有一种合理的解释。如果单行内容不足以完全明确行为，使用嵌套子项目符号添加细节。嵌套行用于澄清父规范；它们不会引入单独的功能。即使有嵌套细节，规范对应的代码变更行数仍必须≤200 LOC。
plain
- :User: should be able to send a :Message: to a :Conversation:.
  - A :Message: must have non-empty content.
  - The :Message: is appended to the end of the :Conversation:.
  - All :Participant: members of the :Conversation: can see the new :Message:.

Deterministic Interface

确定性接口

Specs must be detailed enough that a developer can use the built software without reading the generated code. All external interfaces must be explicit — REST endpoint paths and HTTP methods, CLI command names and arguments, file formats, message schemas, etc. Never leave interface details up to the renderer's discretion.
规范必须足够详细，以便开发人员无需阅读生成的代码即可使用构建的软件。所有外部接口都必须明确——REST端点路径和HTTP方法、CLI命令名称和参数、文件格式、消息模式等。绝不能让接口细节由渲染器自行决定。

Encapsulation

封装

Functionality must be self-contained in the spec text. 
requires
modules only import functional specs, so do not rely on implementation reqs to convey behavior — they won't be visible in downstream modules.
功能必须在规范文本中自包含。
requires
模块仅导入functional specs，因此不要依赖implementation reqs来传达行为——它们在下游模块中不可见。

Acceptance Tests

验收测试

If the functional spec needs verification, use the 
add-acceptance-test
skill to add acceptance tests after inserting the spec.
如果functional spec需要验证，在插入规范后使用
add-acceptance-test
技能添加验收测试。

Validation Checklist

验证清单

  • Spec implies ≤ 200 lines of code changes
  • No conflict with any existing functional spec
  • Written in language-agnostic terms (no language/framework specifics)
  • All external interfaces are explicit (endpoint paths, methods, CLI args, formats, etc.)
  • All referenced 
    :Concepts:
    are defined in 
    ***definitions***
  • Sentences are short, clear, and unambiguous
  • No redundancy with existing specs
  • Placed in correct chronological position (usually at the end)
  • 规范对应的代码变更行数≤200行
  • 与任何现有functional spec无冲突
  • 以语言无关的术语编写（无特定语言/框架内容）
  • 所有外部接口均明确（端点路径、方法、CLI参数、格式等）
  • 所有引用的
    :Concepts:
    均在
    ***definitions***
    中定义
  • 句子简短、清晰且明确无误
  • 与现有规范无冗余
  • 放置在正确的时间顺序位置（通常在末尾）