鸭梨公共文档

主题

面向规范开发 ​

1. SKILL ​

在 Agent 协作场景里，SKILL 可以理解为“可复用的能力说明书”。它不等同于代码模块，而是面向任务的知识单元，回答三个问题：

  1. 这个能力解决什么问题。
  2. 在什么约束下使用。
  3. 输出应该满足什么验收标准。

一个可落地的 SKILL 模板至少需要包含以下字段：

  • Intent：业务意图与边界。
  • Inputs：输入数据、上下文依赖、权限要求。
  • Process：关键步骤与失败分支。
  • Outputs：结果结构、质量阈值、异常语义。
  • Validation：最小可执行校验。

如果没有 SKILL 层，团队通常会把大量约束硬塞进一次性 Prompt，结果是可复用性差、可审计性低。把能力抽象为稳定的 SKILL，本质上是在做“知识资产化”，“规范是组织记忆”。

面向 Spec 开发不是“先写文档”，而是“先冻结意图，再放大实现”。你可以把它理解成三层递进：

  1. Spec：定义 WHAT 与 WHY。
  2. Design：定义 HOW。
  3. Tasks：定义 DO。

在 AI 参与编码时，最容易失控的不是写代码速度，而是需求漂移速度。Spec 的价值就在于把“需求讨论”从聊天记录迁移到版本库，让每次变更都可追踪、可回放、可审查。

一个简化的执行流可以是：

这条链路里最关键的一步是 Verify。如果实现没有回写到 Spec，规范会快速失效，系统又会回到“口口相传”的状态。

2. AGENTS.md ​

AGENTS.md 是当前最实用的“仓库级 Agent 说明入口”之一。它的价值不在于格式本身，而在于跨工具可读：无论你用哪种 coding agent，都能先读取同一个项目约束。

一个高可用的 AGENTS.md，建议最少覆盖四类信息：

  1. Dev Environment：启动、依赖、目录约定。
  2. Coding Rules：命名、分层、错误处理、禁用项。
  3. Validation Rules：测试命令、通过标准、回归范围。
  4. PR Rules：提交粒度、描述模板、审查清单。

AGENTS.md 可以看作 “团队宪法”，Spec 是“变更法案”，Tasks 是“执行清单”。三者分工明确后，AI 的行为稳定性会明显提升。

3. RFC 驱动开发 ​

当需求跨团队、跨系统、跨季度时，只靠短平快的 Spec 往往不够，需要 RFC 提前做共识压缩。RFC 的重点不是篇幅，而是决策质量：

  1. 问题是否定义清楚。
  2. 约束与非目标是否显式声明。
  3. 备选方案是否被公平比较。
  4. 风险与回滚路径是否可执行。

建议采用“轻重双模板”：

  • 轻量 RFC：面向局部技术决策，控制在一次评审可读完。
  • 重型 RFC：面向架构或组织级变更，强制包含迁移与治理计划。

在实践上，RFC 与 Spec 并不冲突：RFC 决定方向，Spec 承载落地，Tasks 驱动执行。这也是本文“规范驱动 + 多 Agent 协作”主题最值得保留的方法论。

4. Prompt 指令 ​

在面向规范开发的体系下，Prompt 不再是“灵感表达”，而是“执行接口”。高质量 Prompt 应该只做两件事：

  1. 引用规范，而不是重复规范。
  2. 约束输出，而不是期待模型自行猜测。

建议采用以下最小结构： Role: 你要扮演的角色 Goal: 本次任务目标 Context: 仅引用必要的 Spec / RFC / AGENTS 片段 Constraints: 不可违反的边界 Output: 输出格式与验收标准 Validation: 需要运行的检查项

与“超长一次性 Prompt”相比，这种结构化指令更适合多轮协作，也更容易在失败时定位问题来源。简单说，Prompt 的工程化就是把“表达”升级为“协议”。

参考文献 ​

  1. Fission AI. OpenSpec（GitHub 仓库）. https://github.com/Fission-AI/OpenSpec
  2. GitHub Blog. Spec-driven development with AI: Get started with a new open source toolkit. https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
  3. agentsmd. AGENTS.md Official Site. https://agents.md/
  4. agentsmd. AGENTS.md — a simple, open format for guiding coding agents. https://github.com/agentsmd/agents.md
  5. Fuchsia Docs. RFC best practices. https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/best_practices
  6. IETF. RFC 7282: On Consensus and Humming in the IETF. https://www.rfc-editor.org/rfc/rfc7282
  7. Anthropic Docs. Prompt engineering overview. https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview
  8. OpenAI Docs. Prompt engineering best practices. https://platform.openai.com/docs/guides/prompt-engineering