source-driven-development

源码驱动开发

概述

每个特定于框架的代码决策都必须有官方文档支持。不要凭记忆实现——要验证、引用，并让用户看到你的来源。训练数据会过时，API 会被弃用，最佳实践会演变。此技能确保用户获得他们可以信任的代码，因为每个模式都可以追溯到他们可以检查的权威来源。

何时使用

• 用户希望代码遵循给定框架的当前最佳实践
• 构建样板、起始代码或将在项目中复制的模式
• 用户明确要求有文档、已验证或“正确”的实现
• 实现框架推荐方法很重要的功能（表单、路由、数据获取、状态管理、认证）
• 审查或改进使用特定于框架的模式的代码
• 任何你即将凭记忆编写特定于框架的代码时

何时不使用：

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

流程

检测 ──→ 获取 ──→ 实现 ──→ 引用
  │          │           │            │
  ▼          ▼           ▼            ▼
 什么       获取相关   遵循文档    展示你的
 技术栈？   文档       中的模式    来源

步骤 1：检测技术栈和版本

读取项目的依赖文件以确定确切的版本：

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
→ 正在获取相关模式的官方文档。

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

步骤 2：获取官方文档

获取你要实现的功能的特定文档页面。不是主页，不是完整文档——而是相关页面。

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

优先级	来源	示例
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/

获取后，提取关键模式并注意任何弃用警告或迁移指南。

当官方来源相互冲突时（例如，迁移指南与 API 参考矛盾），向用户展示差异，并验证哪个模式实际上适用于检测到的版本。

步骤 3：按照文档中的模式实现

编写与文档所示匹配的代码：

• 使用文档中的 API 签名，而不是凭记忆
• 如果文档展示了做某事的新方法，使用新方法
• 如果文档弃用了某个模式，不要使用已弃用的版本
• 如果文档未涵盖某些内容，将其标记为未验证

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

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

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

展示冲突。不要默默地选择其中一个。

步骤 4：引用你的来源

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

在代码注释中：

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

在对话中：

我正在使用 useActionState 而不是手动使用 useState 来处理
表单提交状态。React 19 用这个钩子替换了手动的
isPending/setIsPending 模式。

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

引用规则：

• 完整 URL，不要缩短
• 尽可能使用带锚点的深层链接（例如 /useActionState#usage 优于 /useActionState）——锚点比顶层页面更能适应文档重构
• 当引用支持非显而易见的决策时，引用相关段落
• 在推荐平台功能时，包含浏览器/运行时支持数据
• 如果找不到某个模式的文档，明确说明：

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

对无法验证的内容诚实比虚假的自信更有价值。

常见借口

借口	现实
“我对这个 API 很有信心”	信心不是证据。训练数据包含看似正确但针对当前版本会出错的过时模式。请验证。
“获取文档浪费 token”	幻觉一个 API 浪费更多。用户调试一小时，然后发现函数签名变了。一次获取可以避免数小时的重做。
“文档不会有我需要的”	如果文档没有涵盖，那是有价值的信息——该模式可能不是官方推荐的。
“我只会提一下它可能过时”	免责声明没有帮助。要么验证并引用，要么明确标记为未验证。含糊其辞是最糟糕的选择。
“这是一个简单的任务，不需要检查”	带有错误模式的简单任务会成为模板。用户在发现现代方法存在之前，将你弃用的表单处理器复制到十个组件中。

红旗

• 在未检查该版本的文档的情况下编写特定于框架的代码
• 使用“我相信”或“我认为”来描述 API，而不是引用来源
• 在不知道模式适用于哪个版本的情况下实现它
• 引用 Stack Overflow 或博客文章而不是官方文档
• 使用已弃用的 API，因为它们出现在训练数据中
• 在实现之前未读取 package.json / 依赖文件
• 交付代码时没有为特定于框架的决策提供来源引用
• 获取整个文档站点，而只有一页是相关的

验证

在使用源码驱动开发实现后：

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