Skill 创建笔记：AI 编程时代，如何为 Agent 写一份不会偏离需求的 Spec
日期：2026-05-15
用户：xc（OpenHarmony 鸿蒙化适配工程师）
Agent：Hermes / MiniMax-M2.7 & DeepSeek-V4-Pro
产物：spec skill v1.2.1
一、需求背景与目标
背景
在用 Agent 做 Vibe Coding 时，最怕的是 Agent "自由发挥"——你随口说"帮我写个登录页面"，它今天这样实现、明天那样实现，模块边界越来越乱。没有 Spec 的 Agent 就像没有地图的司机，每次都得重新认路。
Vibe Coding 需要 Spec 吗？需要。但不能是传统的几十页 PRD——那和 Vibe Coding 的快节奏天然冲突。Spec 需要轻、结构化、Adaptive——既能给 Agent 边界，又不拖慢迭代速度。
目标
- 在 Hermes Agent 中创建一个
specskill，让 Agent 能引导用户写出高质量 Spec - 定义一份"Agent 可执行的设计文档"的标准模板和最佳实践
- 借鉴 Cursor
.mdc、Cline Memory Bank 等主流工具的 Spec 方法论，融会贯通 - 让 Spec 和下游 plan → implement → test 流程无缝衔接
工具与模型
- Agent：Hermes
- 模型：MiniMax-M2.7（创作）+ DeepSeek-V4-Pro（审查与优化）
- 主要工具：skill_manage、read_file、patch、write_file、search_files、session_search
二、用户提示词与 Agent 执行记录
2.1 初始创建：从零到 v1.2.0
用户提示词：
我想要创建一个写 spec 的 skill。你先写一下 spec 的定义，如何编写的最佳实践，主要用于 vibe coding，写在本工程目录。
Agent 关键动作：
- 加载
writing-plans和planskill 作为参考，对比现有方法论 - 创建
~/.hermes/skills/software-development/spec/目录结构：SKILL.md— 路由框架，8 步对话流程references/spec-definition.md— 完整方法论（446 行）references/template-quick.md— 单文件模板（小项目）references/template-full.md— 多文件模板（大项目）references/progress.md— 进度追踪模板
- 借鉴三大竞品：Cursor（
> WHY:每条注释 + scope frontmatter）、Cline（productContext/techContext 拆分 + progress.md）、OpenHands（单文件 prompt） - 定义 P0/P1/P2 三级模块优先级，P0 五件套（productContext、techContext、架构、模块、约束）永远不省
- 与下游 skills 建立衔接链：spec → writing-plans → subagent-driven-development → test-driven-development
Agent 关键反馈：
Spec 是核心，代码是 Spec 的产物——在 AI 时代，这句话不是口号，是工作流的基础。没有 Spec，Agent 今天这样实现、明天那样实现，模块越来越乱。
2.2 多模型交叉审查
用户提示词：
监视一下当前的 spec skills，有没有优化点，先不修改，把意见序列化到本地。
Agent 关键动作：
- 完整阅读 SKILL.md + 4 个 references 文件（共约 20KB）
- 逐条分析，输出 7 条优化意见到
SPEC_SKILL_OBSERVATIONS.md - 涵盖：反触发缺位、需求模糊处理、自检清单语言、WHY 占位符、缺少完整示例、渐进迭代时间、约束模板格式
- 数据驱动的竞品对比矩阵
Agent 关键反馈：
7 条优化意见中，优先级最高的是"反触发"（何时不该用 spec）和"需求不清 fallback"。它们不是锦上添花，是防止 skill 被滥用和返工的防线。
2.3 换模型交叉审查与最终修改
用户提示词：
这是另一个模型给的修改意见，里面有有价值的意见吗？
Agent 关键动作：
- 逐条评估 7 条意见的价值：采纳 2 条（反触发 + WHY 强制）、部分采纳 1 条（TODO fallback）、拒绝 4 条（外观问题或实现成本大于收益）
- 同时发现审查者漏掉的 3 个问题：vibe coding 适配说明、
spec/目录命名冲突、planvswriting-plans区分不清 - 总共落地 7 处改动，版本升至 v1.2.1
Agent 关键反馈：
多模型交叉审查的价值在于：一个模型的盲区恰好是另一个模型的强项。审查者关注了模板层面，但漏掉了方法论层面——vibe coding 和 spec-driven 的天然张力、目录冲突的实际工程问题。
改动清单：
| # | 改动 | 位置 |
|---|---|---|
| 1 | 反触发：5 种场景 + 1 条判断标准 | SKILL.md Trigger |
| 2 | plan/writing-plans 决策树 | SKILL.md Related Skills |
| 3 | WHY 强制占位符 [必填] |
template-quick.md §四 |
| 4 | 约束格式两行对齐 + 示例值 | template-quick.md §五 |
| 5 | 需求不清 5 问 + [TODO: 待确认] fallback |
spec-definition.md §四 |
| 6 | Vibe Coding 适配（何时轻/重 + 过渡信号） | spec-definition.md §五 |
| 7 | spec/ 目录冲突处理 |
spec-definition.md §七 |
三、最终产物与经验
产物结构
~/.hermes/skills/software-development/spec/
├── SKILL.md (路由框架，8步流程 + 反触发)
└── references/├── spec-definition.md (方法论 516行，14章节)├── template-quick.md (单文件模板，6 Section)├── template-full.md (目录版模板，9 文件)└── progress.md (进度追踪)
核心设计决策
| 决策 | 理由 |
|---|---|
| P0 五件套永远不省 | productContext + techContext 告诉 Agent why/how，架构 + 模块 + 约束给边界 |
每条约束带 > WHY: |
借鉴 Cursor，Agent 理解 WHY 就不会误删关键设计 |
| scope frontmatter | 告诉 Agent 改哪些文件，防范围蔓延 |
| progress.md 独立文件 | 借鉴 Cline，迭代时一眼看到阻塞和状态 |
| 加载策略：on demand | SKILL.md 只做路由，14KB 方法论按需加载，不浪费 context |
| Vibe → Spec 过渡信号 | 同一文件被改 3+ 次、跨模块改动、用户开始说"上次那样改的"——这些是停下手头 vibe coding、写 spec 的信号 |
关键经验
- 多模型交叉审查是 skill 质量控制的低成本手段——一个模型写、另一个模型（或同模型的不同视角）审查，能揪出创作盲区
- 反触发比触发更重要——定义"何时不该用 skill"能防止滥用，比写更多的触发条件更有效
- Vibe coding 不是不要 Spec，是要"刚好够用的 Spec"——快速原型 3 行 productContext 足矣，多模块项目才需要完整 spec/ 目录
- 借鉴不是复制——Cursor 的 WHY 模式、Cline 的 progress.md、OpenHands 的单文件思路，各自取其精华为我所用
- 模板只是载体，方法论才是核心——template-quick 和 template-full 会过期，但 spec-definition.md 里的原则（为什么 P0 永远不省、为什么每条规则必须 WHY）才是 skill 的长期价值