mcpField
A
add-functional-spec

add-functional-spec

github.com/plainlang开发8038 次安装今天更新
代码仓库

关于 add-functional-spec

add-functional-spec 用于在 .plain 模块中编写一条功能规格，并指导复杂度、冲突、清晰度、顺序及可选一致性测试检查。

主要功能

  1. 01起草并精简规格
  2. 02检查复杂度限制
  3. 03批量分析冲突
  4. 04明确外部接口
  5. 05添加一致性测试

适用场景

  1. 01添加一项功能需求
  2. 02检查规格与现有行为的冲突
  3. 03为规格准备测试场景

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/plainlang/plain-forge --skill add-functional-spec

安装后在 Claude Code 中输入/add-functional-spec确认已加载。

详细介绍

原文在翻译后有更新，译文可能不是最新。

添加功能规格

始终使用技能 load-plain-reference 获取纯文本语法规则——但仅在你尚未获取这些规则时使用。

工作流

  1. 确定目标 .plain 文件。 如果无法确定，请询问用户。
  2. 通读整个文件，了解现有定义、实现要求和所有当前功能规格（包括 requires 模块中的规格）。
  3. 起草功能规格，遵循以下规则，然后对草稿应用 concise-specs.md 中的审查流程——在进行任何其他检查之前，将措辞精简到不遗漏任何事实的最简形式。
  4. 分析复杂度——使用 analyze-if-func-spec-too-complex 技能，验证起草的规格意味着 ≤ 200 行代码。如果过于复杂，使用 break-down-func-spec 技能拆分，然后从第 3 步开始，对每个拆分后的规格重复流程。
  5. 检查冲突，涵盖所有现有功能规格——这一步至关重要。将新规格与所有现有规格（文件内及任何 requires 链中的规格）作为一个批次，仅运行一次 analyze-func-specs。批量分析器会在一次调用中返回所有冲突的规格对——不要逐对调用分析器。对于其报告的每个冲突对，运行 resolve-spec-conflict 处理该对；每次解决冲突后，对已处理的规格集重新运行 analyze-func-specs，直到判定结果为 COMPATIBLE。
  6. 将规格追加到 ***functional specs*** 部分的末尾（规格按时间顺序排列；新规格放在最后）。
  7. 再次阅读文件，确认位置和语法正确。

规则

复杂度限制

每个功能规格意味着最多 200 行代码变更。如果需求过大，使用 break-down-func-spec 技能将其拆分为多个较小且相互独立的规格。不要在规格文本中包含代码行数估算。

时间顺序

规格按从上到下的顺序逐步渲染。渲染器不了解未来的规格——上下文中只有之前渲染的规格。这意味着：

  • 新规格可以引用之前规格定义的行为。
  • 新规格不能假设后续规格包含任何内容。
  • 如果新规格必须位于某个未来规格之前，请将其放在正确的位置；否则追加到末尾。
语言无关性

描述行为、概念和领域逻辑，而非实现构造。避免使用特定语言的类型、泛型语法、框架注解或其他与特定语言或框架绑定的构造。通用技术术语（空值、JSON 类型、HTTP 状态码等）可以使用。特定语言的指导应放在 ***implementation reqs*** 中。

不得冲突

新规格不得与任何现有功能规格矛盾。冲突规格是代价最高的结果。添加前，请审查所有现有规格并确认新规格与之兼容。使用 analyze-func-specs 在一次批量调用中检查新规格与所有现有规格——它会列出所有冲突对，因此无需逐对调用分析器。如果存在歧义，请添加明确细节，消除任何相互冲突的解读。对于批量分析器报告的每个冲突对，使用 resolve-spec-conflict 技能诊断并修复，然后再继续。

消除歧义

每个功能规格都必须明确无歧义——渲染器只能有一种合理的解读。如果单行内容不足以完全明确行为，请使用嵌套子弹点补充细节。嵌套行用于阐明父规格，不会引入独立功能。即使有嵌套细节，规格仍须意味着 ≤ 200 行代码。

***functional specs***

- A :User: can 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:.
确定性接口

规格必须足够详细，让开发者无需阅读生成的代码即可使用构建完成的软件。所有外部接口都必须明确——REST 端点路径和 HTTP 方法、CLI 命令名称和参数、文件格式、消息架构等。绝不能将接口细节留给渲染器自行决定。

封装

功能必须在规范文本中自成一体。requires 模块只导入功能规范，因此不要依赖实现需求来传达行为，因为下游模块看不到这些内容。

验收测试

如果需要验证功能规范，请在插入规范后使用 add-acceptance-test 技能添加验收测试。

验证清单

  • 规范预计导致的代码变更不超过 200 行
  • 不与任何现有功能规范冲突
  • 使用与语言无关的术语编写（不涉及特定语言或框架）
  • 明确所有外部接口（端点路径、方法、CLI 参数、格式等）
  • 所有引用的 :Concepts: 均在 ***definitions*** 中定义
  • 句子简短、清晰且明确
  • 按 concise-specs.md 的要求精简：不包含显而易见的内容、理由、无法验证的形容词或模棱两可的措辞，通篇使用简单词语
  • 不与现有规范重复
  • 放置在正确的时间顺序位置（通常在末尾）

评论

支持 Markdown