源码驱动开发方法论

源码驱动开发方法论

学习目标

读完本章后，你将能够：

• 理解为什么训练数据会过时以及其对 AI 编码的危害
• 应用 DETECT → FETCH → IMPLEMENT → CITE 四步流程
• 识别和遵循来源权威性层级
• 处理官方文档与现有代码的冲突
• 正确引用来源并标注未验证内容

---

为什么需要源码驱动开发

AI 编码助手的训练数据包含大量过时的 API 模式、已废弃的函数签名、以及不再推荐的最佳实践。当 Agent 凭记忆编写框架特定代码时，它可能：

• 使用在新版本中已被废弃的 API
• 复制过时的样板代码，而非采用当前的推荐模式
• 引入已被安全修复替代的模式

源码驱动开发的核心理念：每个框架特定的实现决策都必须有官方文档支撑。不要凭记忆实现——验证、引用、让用户能看到你的来源。

---

四步流程

DETECT ──→ FETCH ──→ IMPLEMENT ──→ CITE
  │          │           │            │
  ▼          ▼           ▼            ▼
什么技术栈  获取相关    遵循文档    展示你的
和版本？    文档        模式        来源

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

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

依赖文件	可识别的技术栈
package.json	Node/React/Vue/Angular/Svelte
composer.json	PHP/Symfony/Laravel
requirements.txt / pyproject.toml	Python/Django/Flask
go.mod	Go
Cargo.toml	Rust
Gemfile	Ruby/Rails

显式声明你发现的内容：

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

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

Step 2: FETCH — 获取官方文档

获取你正在实现的功能的具体文档页面。不是首页，不是完整文档——是相关页面。

来源权威性层级（按权威降序排列）：

优先级	来源	示例
1	官方文档	react.dev, docs.djangoproject.com, symfony.com/doc
2	官方博客 / 变更日志	react.dev/blog, nextjs.org/blog
3	Web 标准参考	MDN, web.dev, html.spec.whatwg.org
4	浏览器/运行时兼容性	caniuse.com, node.green

不具权威性——永远不要作为主要来源引用：

• Stack Overflow 答案
• 博客文章或教程（即使是热门的）
• AI 生成的文档或摘要
• 你自己的训练数据（这正是源码驱动开发要解决的问题）

精确获取：

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

❌ 搜索 "django authentication best practices"
✅ 获取 docs.djangoproject.com/en/6.0/topics/auth/

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

编写与文档展示的模式一致的代码：

• 使用文档中的 API 签名，不是记忆中的
• 如果文档展示了新做法，使用新做法
• 如果文档标记某个模式为已废弃，不要使用已废弃版本
• 如果文档没有覆盖某个内容，显式标记为未验证

当文档与现有代码冲突时：

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

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

展示冲突。不要静默选择。

Step 4: CITE — 引用来源

每个框架特定的模式都应有引用。用户必须能够验证每个决策。

在代码注释中：

// React 19 表单处理，使用 useActionState
// 来源：https://react.dev/reference/react/useActionState#usage
const [state, formAction, isPending] = useActionState(submitOrder, initialState);

在对话中：

我使用 useActionState 而非手动 useState 来处理
表单提交状态。React 19 用这个 hook 替代了手动
的 isPending/setIsPending 模式。

来源：https://react.dev/blog/2024/12/05/react-19#actions
"useTransition 现在支持异步函数 [...] 自动处理 pending 状态"

引用规范：

• 完整 URL，不是短链接
• 优先使用深链接（锚点），因为锚点在文档重构后比顶层页面更稳定
• 当支持一个非显而易见的决策时，引用相关段落
• 当推荐平台特性时，包含浏览器/运行时支持数据
• 如果你找不到某个模式的文档，显式说明：

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

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

---

与对抗式审查的区别

维度	源码驱动开发	对抗式审查
验证对象	框架事实（API 是否存在？签名是否正确？）	你的推理（这个用法在契约下正确吗？）
验证来源	官方文档	新上下文的审查者
问题类型	”React 19 中 useActionState 的签名是什么？"	"这个缓存层在读重负载下是线程安全的吗？“
互补关系	SDD 确保 API 存在且用法正确	Doubt-Driven 确保你正确使用了它

---

何时不使用

• 正确性不依赖特定版本时（重命名变量、修复拼写错误、移动文件）
• 在所有版本中行为相同的纯逻辑（循环、条件、数据结构）
• 用户明确要求速度优先于验证（“快点做就行”）

---

检查清单

应用源码驱动开发后，确认：

• 框架和库版本已从依赖文件中识别
• 官方文档已获取（针对框架特定的模式）
• 所有来源均为官方文档，而非博客文章或训练数据
• 代码遵循当前版本文档中展示的模式
• 非平凡决策包含带有完整 URL 的来源引用
• 没有使用已废弃的 API（已检查迁移指南）
• 文档与现有代码的冲突已向用户展示
• 任何无法验证的内容已显式标记为未验证