[DataFlow-CV v2.0.0] 从 SDD 到 Skills：主动约束实践与思考

SDD 的约束模型存在结构性缺陷：spec 是静态文档，约束依赖 Agent 主动阅读并自行对照，执行阶段仍会出现遗漏。本文介绍 DataFlow-CV 从 SDD 到 Skills 的优化实践：spec 维护方法论固化、开发 skill 抽取与 CLAUDE.md 结构优化、PreToolUse hook 主动约束注入，以及插件化分发与工程解耦。

• [Claude Code] Skill/插件开发实践：设计、分发与维护
• [DataFlow-CV v2.0.0] 从 SDD 到 Skills：主动约束实践与思考
• [SDD 方法论]系统化实践指南
• [DataFlow-CV v1.5.0] SDD 实践与思考
• [DataFlow-CV v0.6.2] Vibe Coding 实践与思考
• [译] Specification-Driven Development (SDD)
• [译] Spec-driven development with AI: Get started with a new open source toolkit

项目地址：https://github.com/zjykzj/DataFlow-CV

一、问题：被动约束的局限

在 SDD 范式下，spec 定义「什么是对的」，代码是 spec 的实现。架构硬约束与 Known Gotchas 进一步限定了 Agent 的生成范围。这套机制在大部分场景下有效，但存在结构性缺陷——约束模型是被动的：

被动约束：
  Agent 读 spec → Agent 记在心里 → 写代码时自行对照 → (经常断链)

实际开发中的典型遗漏（对应约束在 spec 中均有明确定义）：

• spec_conversion.md 定义 RLE 编码必须使用 latin1，实现 coco_handler.py 时仍写出 utf-8
• spec_convert.md 要求 converter state 在 finally 块中清理，异常处理路径上遗漏
• spec_cli.md 禁止 CLI 直接 import label handlers，实现时绕过约束

这些遗漏的共性是：约束本身清晰，失败发生在执行环节。spec 是静态文档，Agent 的注意力随上下文增长而稀释，早期读入的约束在长任务后期失效。

优化方向：将约束从「被动参考」升级为「主动执行」——由系统在正确的时机注入正确的约束，而不是依赖 Agent 主动读取并记忆。

二、约束机制的四层架构

优化后的约束体系分为四层，各有明确的职责与加载方式：

层	载体	职责	加载方式
常驻规则	CLAUDE.md	高频硬规则、架构约束、关键实现细节、Known Gotchas	每次会话全量加载
行为契约	specs/	外部格式、评估指标、模块接口的权威定义	按需读取
流程封装	skills	特定工作流的步骤与方法论	按需触发（description 匹配）
时机注入	hooks	特定工具调用发生时强制注入约束	事件驱动

分层原则：高频知识常驻，领域契约按需，流程知识封装，时机敏感约束注入。约束放错层的失败模式有两种：放常驻层浪费上下文，放按需层注入不到时机。

三、Spec 维护方法论

3.1 契约净化

specs 目录早期混杂了非契约内容：变更历史、文件目录树、伪代码实现步骤、迁移指南、Legacy API 对照表等。这类内容稀释了契约的权威性：Agent 在噪声中查找约束，人类在噪声中审查。

净化原则：spec 只回答「什么是对的」。非契约内容按六类删除规则清除。

3.2 两读者模型

spec 有两位读者：Agent 与人类开发者。Agent 需要无歧义的可执行契约；人类需要可快速审查的领域知识。契约越纯粹，两者的效率同时提升——这两类需求并不冲突。

3.3 方法论与契约分离

SDD 通用方法论与工程特有指南不属于行为契约，移出 specs/ 目录：方法论固化在 CLAUDE.md（涵盖分类原则、两读者模型、六类删除、接口 vs 实现检查、边界规则），可复用模板存放于 docs/。

职责边界：spec 定义「什么是对的」，CLAUDE.md 定义「怎么维护」。

3.4 spec-first 硬规则

1. 影响 specs/ 契约的变更，必须先更新 spec 至目标状态，再实现代码
2. 实现完成后执行 conformance check，对照 spec 验证实现
3. commit body 列出受影响的 spec 文件

四、Skill 抽取与 CLAUDE.md 结构优化

4.1 消费模式错配

CLAUDE.md 由系统每次会话全量加载，但早期版本包含大量低频内容：发布流程仅在发布时使用，spec 维护方法仅在修改 spec 时使用。低频流程常驻上下文，占用空间并稀释注意力。

4.2 流程抽取

将流程性内容抽取为 skill，按需加载：

Skill	职责
/commit	commit 格式、Co-Authored-By 尾注、CHANGELOG [Unreleased] 同步
/release	版本号升级、tag、GitHub Release
/spec	spec-first 开发循环、spec 维护方法论
/claude	CLAUDE.md 编写指南（含开发命令文档化）

（早期存在的 /dev skill 已裁撤，通用工具链指引并入 /claude。）

4.3 CLAUDE.md 三类内容

1. Quick Reference：高频硬规则（排序约定、零交叉依赖、spec-first、commit 规范）
2. 架构与关键实现细节：每次编码所需的知识
3. 配置与指针：AI 模型配置、版本号位置、skill 引用

4.4 可移植性设计

skill 使用 placeholder 变量（{{AI_MODEL_NAME}}、{{REPO_URL}} 等）替代硬编码，工程特有配置留在 CLAUDE.md。职责划分：skill 定义「怎么做」，CLAUDE.md 定义「这个工程用什么参数做」。同一 skill 可跨工程复用。

五、Hook：时机触发的主动注入

skill 由 Agent 主动调用，存在「不调用」的失败模式。hook 补足这一点。

PreToolUse hook：当工具调用匹配 Edit|Write 且目标为 specs/ 目录时，在工具执行前注入 spec-first 方法论提醒。Agent 无需记忆「修改 spec 前应加载方法论」——触碰 spec 文件时，系统自动注入。

被动约束：
  Agent 读 spec → Agent 记在心里 → 写代码时自行对照 → (经常断链)

主动约束：
  编辑 specs/ → PreToolUse hook 注入方法论 → 先改 spec 再写代码
  提交代码 → /commit skill 强制格式 + CHANGELOG 同步
  发布版本 → /release skill 按检查清单执行

现状边界

• hook 的注入粒度是方法论级（提醒 spec-first 流程），未实现具体约束级（如按文件路径注入 RLE 编码规则）
• 细粒度约束通过 CLAUDE.md 全量常驻实现：41 条 Known Gotchas 每次会话加载；DeepSeek V4.0 的 1M 上下文使全量加载不再受限
• 原设想的按文件触发 Rules 未落地——「常驻内存」在 1M 上下文下以更低复杂度达到同等效果

六、插件化分发与工程解耦

skills 沉淀的是通用开发工作流，不属于特定工程。留在仓库内会产生两个问题：新工程需要复制，skill 更新后所有工程需要同步。

分发方案：

仓库内 skills → maestro 插件（claude-skills marketplace 分发）
                     /maestro:commit  /maestro:release  /maestro:spec  /maestro:claude

设计原则：插件是可选加速器，不是开发前提。

• 工程规则自足：CLAUDE.md 不依赖外部 skill，开发命令直接列于其中
• 仓库不提交 .claude/settings.json，不自动注册插件
• 无插件可正常开发；安装插件后获得 hook 与 skill 加速

6.1 两类插件

插件	类型	读者
maestro	开发工作流类	开发者
dataflow	知识参考类	库使用者

dataflow 插件（/dataflow:dataflow-cv）打包 CLI/API 参考、canonical 示例与 known gotchas，使 AI Agent 在使用库时获得准确知识——工程知识从开发者文档扩展为使用者可消费的技能。

6.2 版本联动

post-release checklist：发布改变 CLI/API 表面时，同步 /dataflow:dataflow-cv 的最低版本要求。插件与工程之间建立版本联动。

七、收益与代价

7.1 收益

1. 纪律自动化：CHANGELOG 由 /commit 在提交时自动维护，版本发布由 /release 按清单执行。文档同步从人工纪律转为系统流程。
2. 约束时机化：hook 使 spec-first 从自觉变为强制；41 条 Gotchas 全量常驻，不依赖 Agent 在长任务后期仍记得读取。
3. 可移植：skills 以插件形式跨工程复用，方法论沉淀从项目级上升为工具链级。
4. 仓库自包含：新 clone、换模型、换 Agent 均不被个人工具链绑架。

7.2 代价

1. skill 本身也是活文档：需要持续维护；插件与工程之间多了一层一致性要求（post-release checklist 即为此存在）。
2. 机制复杂度上升：四层机制各有触发时机，新增约束时需判断归属层级，放错层的成本见第二节。
3. 注入粒度有限：细粒度约束仍依赖全量常驻的 Gotchas 与 Agent 的注意力，这是当前机制与理想状态的差距。

八、工程数据

指标	v1.5.0	v2.0.0
测试数	418	561
代码覆盖率	76%（3986 statements）	80%（5462 statements）
Known Gotchas	26 条（平铺）	41 条（按主题分类 + [!]/[*] 严重度分级）
架构硬约束	5 条	10 条
模块数	4（Convert/Visualize/Evaluate + Label）	5（+ Analyse）
specs 目录	14 个文件（含两份方法论文档）	18 个文件（15 个契约 spec + 3 个 index，方法论移出）

版本节奏：v1.6.0 → v2.0.0，64 天，8 个版本。

九、结语

约束机制优化的验证与修正：

• 验证：skill 封装流程有效；hook 时机注入有效；「常驻内存」在 1M 上下文下可替代细粒度 rules
• 修正：skills 应独立于工程分发，成为工具链资产
• 待解决：细粒度约束的主动注入；多 Agent 协作（spec 作为协作协议的系统化实践）

写的真棒！！！哈哈哈，当然了我指的是Claude Code + DeepSeek-V4.0-PRO。DataFlow-CV v2.0.0 已覆盖日常数据处理的主要场景，后续将持续维护与优化。