# Source Driven Development

> 让每个实现决策都以官方文档为依据。当你需要权威、有来源引用且不含过时模式的代码时使用。使用任何框架或库构建且正确性很重要时使用。

- Skill: `vinvcn/source-driven-development` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vinvcn/source-driven-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinvcn/source-driven-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vinvcn (https://skillmd.com/u/vinvcn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vinvcn/source-driven-development

---


# 来源驱动开发

## 概览

每个框架特定的代码决策都必须有官方文档支撑。不要凭记忆实现；要验证、引用，并让用户看到你的来源。训练数据会过时，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 步：引用来源

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

**在代码注释中：**

```typescript
// React 19 form handling with useActionState
// Source: https://react.dev/reference/react/useActionState#usage
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` / 依赖文件
- 交付代码时没有为框架特定决策提供来源引用
- 只需要一个页面时，却获取整个文档站点

## 验证

完成来源驱动开发后：

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