Spec 与 Skills：开发范式的此消彼长

在围绕代码生成与自动化开发的工程实践中，团队组织工作的方法正在发生变化。过去很长一段时间，主流做法是把需求写成完整、结构化的规格文档（spec），再用提示词驱动模型按步骤执行；而近期一种更轻量的做法开始流行：把常见任务沉淀为一组组可直接调用的能力（skills），让模型在能力集合中选择与组合。本文对比的正是这两种范式——以规格文档为中心的开发方式与以可调用能力为中心的开发方式，分析它们的含义、共同点、核心差异、适用场景与迁移注意事项。

需要说明的是，本文讨论的是方法论层面的对比，不涉及任何具体厂商的专有接口或产品能力；文中提到的“能力库”“规格文档”“执行入口”等均为通用概念。

一、对比背景：为什么这两种范式值得比较

在模型能力尚不稳定的阶段，开发者需要靠更细的指令、更完整的约束来“兜住”模型的输出。规格文档承担了三个角色：需求描述的载体、执行步骤的约束、验收标准的依据。文档越结构化，模型偏离预期的概率越低。

随着模型在理解长上下文、遵循指令、自主分解任务方面的能力抬升，一部分原本必须写进文档的约束，可以由模型自行推断或补齐。于是团队开始把精力从“把过程写清楚”转向“把能力组织好”：把高频任务封装成边界清晰、输入输出稳定的能力单元，让模型按需调用。规格文档依然存在，但篇幅变短，往往只保留关键要点，随后直接进入开发。

这种转变并不是“文档无用”，而是约束的重心从过程描述转移到了能力供给。理解这一转移，对技术选型和团队协作方式都有直接影响。

二、对象定义：两种范式分别是什么

以规格文档为中心（Spec-centric）：以文档为主要输入，文档描述目标、约束、步骤、边界条件和验收标准，模型依据文档逐步执行。文档质量直接决定执行结果的稳定性，通常需要较完整的结构化撰写。

以可调用能力为中心（Skill-centric）：以能力库为主要输入，把常见任务拆解为若干可复用的能力单元，每个单元有明确的输入、输出、适用条件和失败处理方式；模型作为调度者，根据任务目标选择并组合能力。规格文档退居次要位置，更多承担目标说明与验收定义的职责。

两者并非互斥。实际工程中常见的是混合形态：能力库覆盖高频路径，规格文档处理长尾与例外。

三、相同点：目标与技术逻辑的共性

1. 目标一致：都是为了把非结构化的意图转化为可稳定复现的执行结果，降低模型输出的不确定性。
2. 都依赖边界定义：规格文档通过约束条款定义边界，能力库通过能力单元的输入输出契约定义边界，本质都是缩小模型自由发挥的空间。
3. 都需要验收机制：两种范式都无法完全避免偏差，都需要测试、审查或自动化校验来兜底。
4. 都随模型能力演进：模型能力越强，规格可以越薄、能力可以越抽象；反之则需更细的约束。
5. 都强调可维护性：文档会腐化，能力会过时，两者都需要版本管理与定期清理。

四、核心差异分析

1. 技术架构与依赖重心

规格文档范式依赖的是“描述质量”，系统边界由文档文本界定，执行路径是线性或树状的步骤序列。能力库范式依赖的是“能力契约”，系统边界由能力单元的接口定义界定，执行路径是模型动态编排的组合图。前者更像脚本化流程，后者更像服务化编排。

2. 功能能力与覆盖范围

规格文档擅长表达一次性、非标准、强约束的任务，对例外路径的描述能力强；但文档越长，维护成本越高，模型在长文档中的注意力衰减也越明显。能力库擅长覆盖高频、可标准化、重复出现的任务，复用性好；但对尚未沉淀为新能力的长尾任务，覆盖不足，需要回退到文档描述。

3. 接入方式与改造量

采用规格文档范式，接入成本主要在撰写与评审，开发改造量小，适合快速启动。采用能力库范式，前期需要设计能力边界、定义输入输出、处理失败与降级，接入改造量较大，但边际成本随复用次数下降。

4. 性能与稳定性表现

从通用维度看，能力库把复杂任务拆成短链路调用，单步不确定性更低，稳定性更容易通过单元级校验保障；但编排层引入了选择错误的风险——模型可能选错能力或组合顺序。规格文档范式的风险集中在长文档执行中的偏离累积。两者都不宜用具体数值比较，应结合任务复杂度评估。

5. 安全与合规

能力库的权限控制更细粒度：每个能力单元可以独立设定访问范围、数据隔离级别与审计埋点，便于最小权限原则落地。规格文档范式的权限通常绑定在执行主体上，粒度较粗。对于涉及敏感数据的场景，能力化拆分在合规审计上更有优势。

6. 运维成本

规格文档的运维主要是文档更新与一致性维护，成本随文档数量线性增长。能力库的运维包括能力注册、版本兼容、依赖管理、失败重试与监控告警，复杂度更高，但可通过平台化手段摊薄。

7. 成本结构

规格文档范式的人力成本集中在撰写与评审，资源成本较低；能力库范式的前期设计与平台建设投入较高，长期看复用降低了单任务成本，但需要持续投入维护。选型时应评估任务复用率：复用率低时，能力化投入难以回收。

8. 使用边界

规格文档范式不适合高频重复且规则稳定的任务，属于重复劳动；能力库范式不适合需求频繁变化、边界尚不清晰的任务，过早能力化会导致接口频繁破坏性变更。

五、对比表格

维度	规格文档为中心	可调用能力为中心
主要输入	结构化文档	能力库与能力契约
执行路径	步骤序列，线性或树状	模型动态编排的组合图
约束重心	过程描述	能力边界与输入输出契约
复用性	较低，偏一次性	较高，高频任务可沉淀
前期投入	低	较高
长期维护	文档一致性维护	能力版本与依赖管理
权限粒度	较粗	较细，可按能力单元控制
长尾任务支持	强	弱，需回退文档
主要风险	长文档执行偏离累积	能力选择与编排错误
适用任务特征	非标准、强约束、变化快	高频、可标准化、规则稳定

六、典型场景选择

• 需求频繁变化、尚在探索期的项目：更适合以规格文档为主，先跑通再沉淀，避免过早固化能力接口。
• 高频重复、规则稳定的工程任务：更适合能力化，把校验、构建、数据整理等动作封装为能力单元，降低重复描述成本。
• 多人协作、权限敏感的企业应用：能力库的细粒度权限与审计更易满足合规要求，但需配套能力治理机制。
• 长尾定制、一次性交付：规格文档更直接，能力化投入难以回收。
• 混合场景：以能力库覆盖主干流程，用精简规格文档处理例外分支，是较为务实的组合方式。

七、选型建议

判断的关键不在于哪种范式更先进，而在于三个条件：任务复用率、需求稳定性、团队治理能力。复用率高且规则稳定，能力化的投入可以摊薄；需求变化快，文档的灵活性更有价值；团队若缺乏能力版本管理与监控手段，过早能力化会带来编排错误与兼容性风险。条件化表达应是：“在高频重复场景下可优先考虑能力化”“在探索期项目上可优先保留规格文档的完整度”。

八、迁移与使用注意事项

从文档范式迁移到能力范式，需要注意以下几点：

1. 接口稳定性：能力契约一旦对外，破坏性变更成本高，建议先内部试用再固化。
2. 编排错误兜底：模型选择能力可能出错，需要失败重试、降级路径与人工复核机制。
3. 兼容与版本：能力库需要版本策略，避免调用方与实现方不同步。
4. 数据与权限：能力拆分后权限边界更细，需重新梳理数据流向与审计埋点。
5. 回退能力：保留规格文档通道，用于能力未覆盖的长尾任务，避免形成单点依赖。
6. 渐进迁移：按任务复用率排序，先迁移高频稳定任务，逐步扩大范围。

示意性伪代码（通用示例，不含任何专有工具名）：

# 能力化编排示意
task = parse_intent(user_input)
candidates = capability_registry.match(task)
plan = planner.compose(candidates)   # 模型选择与排序
for step in plan:
    result = step.invoke(context)
    if result.failed:
        fallback_to_spec_document(task)  # 回退到文档描述路径

九、总结

规格文档与可调用能力并非替代关系，而是约束重心在模型能力提升后的重新分配。文档负责目标与例外，能力负责高频与稳定；前者胜在灵活与低门槛，后者胜在复用与细粒度治理。选型的核心是评估任务复用率、需求稳定性与团队治理成熟度，并保留双向回退通道，让开发方式随模型能力一起演进，而不是一次性押注某一种范式。