| name | source-driven-development |
| description | 让每个实现决策都以官方文档为依据。当你需要权威、有来源引用且不含过时模式的代码时使用。使用任何框架或库构建且正确性很重要时使用。 |
来源驱动开发
概览
每个框架特定的代码决策都必须有官方文档支撑。不要凭记忆实现；要验证、引用，并让用户看到你的来源。训练数据会过时，API 会废弃，最佳实践会演进。这个 skill 确保用户拿到可信的代码，因为每个模式都能追溯到他们可以检查的权威来源。
何时使用
- 用户希望代码遵循某个框架的当前最佳实践
- 构建样板代码、starter code，或会被复制到整个项目中的模式
- 用户明确要求有文档、有验证或“正确”的实现
- 实现框架推荐做法很重要的功能（表单、路由、数据获取、状态管理、认证）
- 审查或改进使用框架特定模式的代码
- 任何你准备凭记忆编写框架特定代码的时候
何时不使用：
- 正确性不依赖特定版本（重命名变量、修 typo、移动文件）
- 在所有版本中行为相同的纯逻辑（循环、条件、数据结构）
- 用户明确希望速度优先于验证（“just do it quickly”）
流程
DETECT ──→ FETCH ──→ IMPLEMENT ──→ CITE
│ │ │ │
▼ ▼ ▼ ▼
What Get the Follow the Show your
stack? relevant documented sources
docs patterns
第 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
明确说明你发现了什么：
STACK DETECTED:
- React 19.1.0 (from package.json)
- Vite 6.2.0
- Tailwind CSS 4.0.3
→ Fetching official docs for the relevant patterns.
如果版本缺失或有歧义，询问用户。不要猜，版本决定哪些模式是正确的。
第 2 步：获取官方文档
获取你正在实现的功能对应的具体文档页。不是主页，也不是整套文档，而是相关页面。
来源层级（按权威性排序）：
| 优先级 | 来源 | 示例 |
|---|
| 1 | 官方文档 | react.dev, docs.djangoproject.com, symfony.com/doc |
| 2 | 官方博客 / changelog | react.dev/blog, nextjs.org/blog |
| 3 | Web 标准参考 | MDN, web.dev, html.spec.whatwg.org |
| 4 | 浏览器/运行时兼容性 | caniuse.com, node.green |
不具权威性：绝不要作为主要来源引用：
- Stack Overflow 答案
- 博客文章或教程（即使很流行）
- AI 生成的文档或摘要
- 你自己的训练数据（这正是重点：要验证）
精确获取所需内容：
BAD: Fetch the React homepage
GOOD: Fetch react.dev/reference/react/useActionState
BAD: Search "django authentication best practices"
GOOD: Fetch docs.djangoproject.com/en/6.0/topics/auth/
获取后，提取关键模式，并记录任何废弃警告或迁移指导。
当官方来源彼此冲突时（例如迁移指南与 API reference 矛盾），把差异呈现给用户，并根据检测到的版本验证哪个模式实际可用。
第 3 步：按文档模式实现
编写与文档展示一致的代码：
- 使用文档中的 API 签名，而不是凭记忆
- 如果文档展示了新的做法，使用新的做法
- 如果文档废弃了某个模式，不要使用已废弃版本
- 如果文档没有覆盖某个点，将其标记为未验证
当文档与项目现有代码冲突时：
CONFLICT DETECTED:
The existing codebase uses useState for form loading state,
but React 19 docs recommend useActionState for this pattern.
(Source: react.dev/reference/react/useActionState)
Options:
A) Use the modern pattern (useActionState) — consistent with current docs
B) Match existing code (useState) — consistent with codebase
→ Which approach do you prefer?
呈现冲突。不要悄悄选择一种。
第 4 步：引用来源
每个框架特定模式都要有引用。用户必须能验证每个决策。
在代码注释中：
const [state, formAction, isPending] = useActionState(submitOrder, initialState);
在对话中：
I'm using useActionState instead of manual useState for the
form submission state. React 19 replaced the manual
isPending/setIsPending pattern with this hook.
Source: https://react.dev/blog/2024/12/05/react-19#actions
"useTransition now supports async functions [...] to handle
pending states automatically"
引用规则：
- 使用完整 URL，不要用短链接
- 尽可能使用带 anchor 的深链接（例如
/useActionState#usage 优于 /useActionState），anchor 比顶层页面更能承受文档重组
- 当某个非显而易见的决策需要支撑时，引用相关段落
- 推荐平台特性时包含浏览器/运行时支持数据
- 如果找不到某个模式的文档，要明确说明：
UNVERIFIED: I could not find official documentation for this
pattern. This is based on training data and may be outdated.
Verify before using in production.
诚实说明无法验证的内容，比虚假的自信更有价值。
常见自我合理化
| 自我合理化 | 现实 |
|---|
| “我对这个 API 很有把握” | 自信不是证据。训练数据包含看起来正确、但在当前版本中会出错的过时模式。去验证。 |
| “获取文档浪费 token” | 幻觉 API 更浪费。用户调试一小时后才发现函数签名变了。一次获取可以避免数小时返工。 |
| “文档不会有我需要的内容” | 如果文档没有覆盖，那本身就是有价值的信息：该模式可能不是官方推荐。 |
| “我提一句它可能过时就行” | 免责声明没用。要么验证并引用，要么明确标记为未验证。含糊其辞是最差选项。 |
| “这是个简单任务，不需要检查” | 带错误模式的简单任务会变成模板。用户把你已废弃的表单处理器复制到十个组件里，之后才发现有现代做法。 |
危险信号
- 没有检查该版本文档就编写框架特定代码
- 对 API 使用“我相信”或“我觉得”，而不是引用来源
- 在不知道适用版本的情况下实现某种模式
- 引用 Stack Overflow 或博客文章，而不是官方文档
- 因为训练数据中出现过而使用已废弃 API
- 实现前没有阅读
package.json / 依赖文件
- 交付代码时没有为框架特定决策提供来源引用
- 只需要一个页面时，却获取整个文档站点
验证
完成来源驱动开发后：
