SuperAPI AI 工具集

01-technical-specification

编程与开发

查看项目

更新于 10-16 07:09

技能介绍

用途

该技能是 Phase 04(开发制品)中的第一个技能,用于把 Phase 03 的低级设计(LLD)模块分解与 SRS 需求,转化为「可实施的技术规格说明书」(Technical Specification),供开发人员将设计落实为代码。文档面向实现,强调契约驱动,遵循 IEEE 1016-2009 与 ISO/IEC/IEEE 29148:2018(取代 IEEE 830-1998)。

何时使用

  • Phase 03 完成且 LLD.md 已存在于 projects/<ProjectName>/<phase>/<document>/,包含模块分解与类图。
  • SRS_Draft.md 已存在于 projects/<ProjectName>/<phase>/<document>/,用于需求追溯。
  • tech_stack.md 已存在于 projects/<ProjectName>/_context/,用于技术栈相关的实现细节。

输入

文件 位置 必需 用途
LLD.md projects/<ProjectName>/<phase>/<document>/LLD.md 是 模块分解、类图、需形式化为契约的算法
SRS_Draft.md projects/<ProjectName>/<phase>/<document>/SRS_Draft.md 是 用于追溯与接口约束的功能需求
tech_stack.md projects/<ProjectName>/_context/tech_stack.md 是 技术选型、运行时版本、框架相关实现细节

若任一必需文件缺失,技能应停止执行并报告缺口。

输出

  • Technical_Specification.md,位于 projects/<ProjectName>/<phase>/<document>/Technical_Specification.md,包含模块契约、数据格式与集成规格。

核心步骤

  1. 读取上下文文件:读取 LLD.md、SRS_Draft.md 与 tech_stack.md,记录每个文件的绝对路径;任一必需文件缺失即停止并报告缺口。
  2. 从 LLD 提取模块契约:对每个模块提取模块名(取自类图标识符)、公共接口(含类型的方法签名与返回类型)、前置条件、后置条件、异常(错误条件与异常类型)。
  3. 定义数据格式规格:为模块间交换或经 API 暴露的数据实体定义 JSON schema(字段名、类型、必填/可选、约束)、数据库列类型与精度(如金额用 DECIMAL(19,4))、枚举取值及定义。
  4. 定义集成规格:为 LLD 与 SRS 3.1 节识别的集成点定义 API 契约,包括端点路径、HTTP 方法、内容类型、请求 schema 与校验规则、响应 schema 与状态码、鉴权要求与限流。
  5. 定义配置参数:参数名、数据类型、默认值、有效范围、环境变量映射(如 DB_HOST)、配置文件格式与位置。
  6. 定义依赖矩阵:源模块、目标模块、依赖类型(编译期、运行期、可选),并将双向依赖标记为设计问题。
  7. 生成实施说明:推荐设计模式(如 Repository、Strategy、Observer)、源自非功能需求的性能考量、源自 SRS 3.5 节的安全考量。
  8. 带追溯性地写出输出:写入 Technical_Specification.md,包含把每个模块契约映射到 LLD 模块与来源 SRS 需求 ID 的追溯表,并记录模块契约、数据 schema 与集成规格的总数。

输出结构

生成的文档按顺序包含:文档头(项目名、日期、版本、标准)、1. 引言与范围、2. 模块契约、3. 数据格式规格、4. 集成规格、5. 配置参数、6. 依赖矩阵、7. 实施说明、8. 追溯矩阵、附录 A:术语表。

能力与权限边界

最低能力为读取与搜索已授权的项目来源;执行是可选的,且仅限于非破坏性验证。评估与规划默认只读;仅当请求明确授权时,才创建或编辑指定项目文档。生产变更、发布、破坏性操作、花费、外部沟通或认证声明,均需单独且明确的授权。密钥、租户数据、事件证据与财务记录按最小权限处理。

降级模式

若文件、执行、网络、渲染、环境访问、字体或当前证据不可用,返回最窄可用的草稿加缺口登记,把受影响的检查标注为「未评估」,保留预期的验收判据,并说明谁必须提供或验证缺失证据。不可将无法执行的检查转为通过。

决策规则

  • 证据完整且授权明确:依据已批准的 LLD 与 SRS 选择契约细节,产出完整制品。
  • 缺少必需来源或批准:停止受影响分支,记录缺口、负责人与解除阻塞条件,避免臆造需求或未授权操作。
  • 多来源证据冲突:保留两种主张,识别有控制权的负责人,并请求书面决策,避免静默选择方便但错误的来源。
  • 检查无法在现有环境运行:保留判据并标注未评估,要求后续执行证据。

质量标准

每一节都应基于具名的项目来源、决策、测量结果或负责的负责人;为每条需求或过程给出可复现的确定性判据;在交接时保留假设、排除项、降级检查、残余风险与豁免;运行仓库反 AI 空话门禁,移除填充内容,核验具名标准与依赖,保留有目的的领域细节。

反模式

  • 直接套用通用模板而不映射项目来源。修正:把每节关联到已批准的需求、配置、风险或负责人。
  • 仅因「常见做法」而选择阈值。修正:从需求、测量基线、风险决策或当前可验证来源推导。
  • 把不可访问或未执行的检查报告为通过。修正:标注未评估,保留判据,指明验证者。
  • 未划边界就混入相邻的 coding-guidelines 关注点。修正:交叉引用其输出并保持所有权明确。
  • 遗漏失败、回滚、空状态、安全、租户或升级行为。修正:为每种适用情形指定触发条件、安全动作、验证与负责人。
  • 在起草指导时变更仓库、环境、租户、账本或外部系统。修正:在明确变更内容与授权前保持只读。
  • 仅凭文字声称合规、认证、就绪或发布。修正:要求来源可归属的证据与具名的验收决策。

常见陷阱

  • 模块契约缺少前置条件:每个公共方法都应显式声明输入约束。
  • JSON schema 缺少必填/可选标记:每个字段都应声明是否必填。
  • 集成规格缺少错误响应:每个 API 契约都应记录错误状态码与载荷。
  • 配置参数缺少默认值:每个参数都应有文档化默认值或被标记为必填。

验证清单

  • Technical_Specification.md 已存在于指定路径且八个章节均填充。
  • 每个 LLD 模块都有对应契约,含公共接口、前置条件与后置条件。
  • 数据格式规格包含带类型字段与约束的 JSON schema。
  • 集成规格记录请求/响应 schema 与状态码。
  • 配置参数列出默认值与有效范围。
  • 依赖矩阵标记任何循环依赖。
  • 追溯表把每个模块契约映射到 LLD 模块与 SRS 需求 ID。

集成关系

上游:Phase 03(02-low-level-design)提供 LLD.md 模块分解与类图;Phase 02(需求工程)提供 SRS_Draft.md 用于需求追溯。下游:02-coding-guidelines 依据模块契约指导编码模式;Phase 05(测试)使用模块契约与集成规格派生测试。

标准与资源

标准:IEEE 1016-2009(软件设计描述);ISO/IEC/IEEE 29148:2018(需求工程)。资源:logic.prompt(包含分步技术规格生成逻辑的可执行提示)与 README.md(快速开始指南),均在需要其模板、逻辑或细节时加载。

适用场景与限制

适用于已具备 LLD 与 SRS、需要产出可评审交接物的开发阶段,供实现团队、评审者与测试阶段使用。限制:需要明确的项目证据与决策授权;必需输入缺失时不应继续,不得臆造范围、阈值、集成或负责人;不接受以通用模板替代项目来源映射,也不得在无授权时变更仓库或生产状态。