源码驱动开发方法论

源码驱动开发方法论

学习目标

• 理解训练数据过时对 AI 编码的危害
• 掌握 DETECT → FETCH → IMPLEMENT → CITE 四步流程
• 学会处理官方文档与现有代码的冲突
• 掌握引用规范和未验证内容的标注方式

前置知识

本章涉及源码驱动开发的通用原理，建议先阅读：

• 源码驱动开发方法论

下文直接聚焦 agent-skills 的具体实现。

项目实践

四步流程的具体实现

agent-skills 将 Source-Driven Development 实现为一个四步工作流，每步都有明确的输入、输出和退出标准。

Step 1: DETECT — 识别技术栈和版本

从项目的依赖文件中读取确切版本：

检测到的技术栈：
- React 19.1.0（来自 package.json）
- Vite 6.2.0
- Tailwind CSS 4.0.3
→ 正在获取相关模式的官方文档。

关键约束：如果版本缺失或不明确，询问用户。不要猜测——版本决定了哪些模式是正确的。

Step 2: FETCH — 获取官方文档

获取具体功能的文档页面，不是首页：

❌ 获取 React 首页
✅ 获取 react.dev/reference/react/useActionState

遵循来源权威性层级：官方文档 > 官方博客 > Web 标准参考 > 兼容性数据。

Step 3: IMPLEMENT — 按文档模式实现

使用文档中的 API 签名，而非记忆中的。如果文档展示了新做法，使用新做法。

Step 4: CITE — 引用来源

在代码注释和对话中引用来源：

// React 19 表单处理，使用 useActionState
// 来源：https://react.dev/reference/react/useActionState#usage

文档与现有代码冲突的处理

这是 SDD 中最关键也最容易被忽略的场景：

检测到冲突：
现有代码库使用 useState 处理表单加载状态，
但 React 19 文档推荐对这种模式使用 useActionState。
（来源：react.dev/reference/react/useActionState）

选项：
A) 使用现代模式（useActionState）— 与当前文档一致
B) 匹配现有代码（useState）— 与代码库一致
→ 你偏好哪种方式？

关键原则：展示冲突。不要静默选择。

未验证内容的标注

当找不到官方文档时，agent-skills 要求显式标注：

未验证：我找不到该模式的官方文档。这基于训练数据，
可能已过时。在生产中使用前请验证。

诚实比虚假信心更有价值。 承认你无法验证的内容比提供看似正确的错误代码更有用。

SDD 与 Doubt-Driven 的区别

维度	SDD	Doubt-Driven
验证对象	框架事实	你的推理
验证来源	官方文档	新上下文的审查者
问题类型	”API 签名是什么？"	"这个用法在契约下正确吗？”

SDD 确保 API 存在且用法正确；Doubt-Driven 确保你正确使用了它。两者互补。

问题与规避

陷阱	表现	对策
获取整个文档站	浪费 token 和时间	获取具体功能的页面
引用非权威来源	Stack Overflow、博客	只引用官方文档
静默处理冲突	代码库不一致	显式展示冲突，提供选项
使用”可能过时”的模糊措辞	用户不知道是否可信	要么验证并引用，要么显式标注未验证

设计取舍

为什么要求完整 URL 而非短链接？

完整 URL 使得用户可以直接点击验证。短链接隐藏了来源，用户无法判断引用的是官方文档还是博客文章。

为什么优先使用深链接（锚点）？

锚点在文档重构后比顶层页面更稳定。/useActionState#usage 比 /useActionState 更精确地指向相关内容，且在文档结构变化时更可能保持有效。

参考来源

• 源码验证: skills/source-driven-development/SKILL.md — 完整的四步流程
• 源码验证: skills/doubt-driven-development/SKILL.md — 与 SDD 的交互说明