SpecArtisan｜让 Coding Agent 从”理解需求”走到”证明实现”

在 AI 辅助开发中，需求理解偏差往往不会在生成第一行代码时就暴露。例如一个音乐播放器，很快就能画出播放按钮和进度条，但真正播放时可能出现各种问题：按钮已变成暂停图标但声音未响；歌曲加载失败但进度条仍在走；切换歌曲后页面仍显示上一首歌词。等到联调时才发现，需求、设计、代码和报告各说各话，很难定位偏差是从哪一步开始的。

SpecArtisan 就是为了解决这个偏差而设计的。它不负责把 Prompt 写得更长，而是把原始需求转换成一份可追踪、可验证的设计契约，让 Coding Agent 在动手之前先明确：需要修改哪些模块，正常路径怎么走，异常从哪里分叉，用户最终看到什么，以及用什么证据证明代码没有跑偏。

一、从一句需求到完整契约：让遗漏在编码前暴露

很多团队都有这种感受：需求明明写了不少，交给 Coding Agent 后，总有一些细节像从纸缝里掉了出去。“点击播放后更新界面”被压缩成一次 play() 调用，“加载失败恢复播放按钮”被收进一句“失败时友好处理”里。第一版代码看起来完整，真正重要的状态变化却没有留下来。

SpecArtisan 做的第一件事，就是把这些容易丢失的信息拆开。

它不让 Agent 只写一段自然语言总结，而是要求需求进入模块、API、端到端用例、异常分支、UI 行为和验收检查点，每一项都有稳定 ID，可继续追踪到实现文件与测试。

以音乐播放器为例：用户点击播放按钮后开始播放选中的歌曲；播放成功后按钮切换为暂停图标，进度条跟随歌曲更新；加载失败时恢复播放图标、进度条停止，并提示“播放失败，请重试”。

如果设计里只有一行“点击按钮 → 调用 play()”，它无法说明按钮什么时候切换，也没有约束加载失败后的播放器状态。代码即使让进度条提前运行，也很难被这份规格判错。SpecArtisan 会把关键结果展开为一份契约（节选）：

*可左右滑动查看

到这里，需求不再只是“调用播放器”。播放状态、进度计时器、按钮图标和失败反馈都成了契约，按钮提前切换、失败后进度仍在走，都会成为可以定位的偏差。“看起来能播”不再是验收答案。

同样的规则也用在异常场景上：权限不足、空状态、重复操作、并发冲突和技术失败都要成为明确分支，不能藏在备注里等实现者临场判断。

在一次内部复盘中，我们把 56 条早期实践问题放在一起看，首轮遗漏、精确值丢失和异常分支消失反复出现。问题并不在于 Agent 没读到那段文字，而是读完以后，没有一个稳定结构要求它把每项承诺留下来。而 SpecArtisan 先把承诺留下来。

二、从“写清楚”到“能够判错”：让 PASS 有证据

把契约写进 YAML 只是第一步。如果没有检查，一份结构化文档照样可能过期、漏项，甚至和代码一起错得很整齐。

SpecArtisan 的第二件事，是让规格进入门禁。

机械验证器会检查必填结构、ID 唯一性、引用解析、模块依赖环、UI 组件类型、影响文件和追踪关系。这类问题没有必要交给模型自由判断：引用不存在就报错，依赖成环就阻断，UI 操作没有登记就不能继续。真正涉及行为的部分，再交给语义与 Hoare 检查。

回到音乐播放器的例子——播放、暂停和加载失败不能只靠几个互不相干的布尔值拼起来，它们需要形成一组可以核对的状态转换：

点击播放，IDLE / PAUSED / ERROR 进入 LOADING；

加载成功进入 PLAYING 且计时器运行；

暂停时保留当前位置；

加载失败进入 ERROR，计时器停止，播放图标恢复。

验证时，报告需要先找到真实代码入口和状态映射，再沿着调用链逐步说明：

点击事件调用了哪个播放方法，音频引擎的成功回调在哪里把状态改成 PLAYING，加载失败后谁停止了进度计时器；

代码里出现一个 play() 方法，不等于音乐已经开始播放；

映射不到真实入口，就标记 MAPPING_BLOCKED；

证据链没有闭合，就给出 UNKNOWN；

找到反例，则明确标为 VIOLATED。

这几个词看起来没有 PASS 漂亮，却更有价值。

一轮完整流程会留下四类核心产物：设计契约（specartisan.yaml）、需求覆盖报告、结构与语义检查报告、契约与代码的推理证据报告。

产品、设计、开发和测试看到的不再是各自手里的一段描述，大家可以围绕同一条契约讨论：这项要求有没有进入设计，代码是否真的承载了它，缺少的究竟是实现，还是证据。

这就是 SpecArtisan 带来的核心改变：把散落在 PRD、原型、代码和个人经验里的判断集中起来，通过结构化契约保留原始承诺，通过机械规则拦住低级漂移，再用可回查的推理过程解释代码为什么成立。

需要说明的是，SpecArtisan 仍是一套半形式化方法。它不会替代编译、自动化测试和真机验收，也不会凭一份 YAML 自动理解所有原有工程。我们保留这条边界，因为可靠的工具首先要知道自己还没有证明什么。

即刻体验：给 Coding Agent 一份不能糊弄过去的设计

将仓库 .github/skills 中的 Skill 加载到常用 IDE 或 CLI，即可让 Agent 按 SpecArtisan 的流程工作。第一次尝试，不必选择庞大的系统重构，像音乐播放器这样包含播放、暂停、加载失败和状态切换的小功能就够了。

看看 Agent 的回答会不会从“代码已经写完”，变成“每一项承诺，我都能指出它落在了哪里”。

代码可以生成，设计不能靠猜。

如果您想了解更多 AI 辅助开发应用工具，欢迎扫码入群，了解开箱即用的 HarmonyOS 应用开发专属 AI Agent 工具。

点击??【】跳转到开源仓链接，了解更多 SpecArtisans 相关信息