用途
该技能是 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,包含模块契约、数据格式与集成规格。
核心步骤
- 读取上下文文件:读取 LLD.md、SRS_Draft.md 与 tech_stack.md,记录每个文件的绝对路径;任一必需文件缺失即停止并报告缺口。
- 从 LLD 提取模块契约:对每个模块提取模块名(取自类图标识符)、公共接口(含类型的方法签名与返回类型)、前置条件、后置条件、异常(错误条件与异常类型)。
- 定义数据格式规格:为模块间交换或经 API 暴露的数据实体定义 JSON schema(字段名、类型、必填/可选、约束)、数据库列类型与精度(如金额用 DECIMAL(19,4))、枚举取值及定义。
- 定义集成规格:为 LLD 与 SRS 3.1 节识别的集成点定义 API 契约,包括端点路径、HTTP 方法、内容类型、请求 schema 与校验规则、响应 schema 与状态码、鉴权要求与限流。
- 定义配置参数:参数名、数据类型、默认值、有效范围、环境变量映射(如 DB_HOST)、配置文件格式与位置。
- 定义依赖矩阵:源模块、目标模块、依赖类型(编译期、运行期、可选),并将双向依赖标记为设计问题。
- 生成实施说明:推荐设计模式(如 Repository、Strategy、Observer)、源自非功能需求的性能考量、源自 SRS 3.5 节的安全考量。
- 带追溯性地写出输出:写入 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、需要产出可评审交接物的开发阶段,供实现团队、评审者与测试阶段使用。限制:需要明确的项目证据与决策授权;必需输入缺失时不应继续,不得臆造范围、阈值、集成或负责人;不接受以通用模板替代项目来源映射,也不得在无授权时变更仓库或生产状态。