# Zc Source Driven Development

> 官方文档实现

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

---


# 基于官方文档的开发

## 概述

当实现依赖外部框架、库或平台的当前 API、版本差异、弃用状态、兼容性或安全约束时，先核对对应版本的第一方资料。项目内已固定的契约、封装、类型、源码、测试和运行证据能证明局部行为时，不为形式重复联网或逐行引用；外部资料用于补足会随版本漂移的事实，不覆盖项目自己的约定。

## 何时使用

- 用户明确要求当前、官方、引用或跨版本结论
- 构建模板、脚手架或将被跨项目复制的模式
- 使用不熟悉、变化快或版本敏感的 API
- 判断迁移、弃用、兼容性、认证或安全约束
- 审查会改变公共框架边界的模式

**不需要使用的场景：**

- 正确性不依赖特定版本的操作（重命名变量、修复拼写、移动文件）
- 在所有版本中行为一致的纯逻辑（循环、条件、数据结构）
- 沿用仓库已有 wrapper / pattern，且类型、测试或运行路径足以证明局部行为
- 项目私有配置、约定和不改变外部 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
→ 正在拉取相关模式的官方文档。
```

版本缺失或模糊时，先检查 lockfile、resolved dependency、类型声明、运行时版本和 CI。只有版本选择会实质改变实现且本地无法确定时才询问用户。

### 步骤 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 签名，而非凭记忆
- 如果文档展示了新的做法，使用新做法
- 如果文档弃用了某个模式，不要使用弃用版本
- 如果文档没有覆盖某些内容，标记为未验证

**当文档与现有项目代码冲突时：**项目 wrapper、兼容层、ADR、测试和团队约定优先于通用示例。只有迁移到新模式会改变公共 API、兼容范围或任务范围时才列出选项请求决定；否则保持本地一致，并在 handoff 说明差异。

### 步骤 4：标注来源

引用非显而易见且会随版本漂移的关键决策。优先集中放在 handoff、设计说明或 ADR；代码注释只保留维护者需要理解的版本陷阱或兼容原因。

**需要解释版本陷阱时才在代码注释中引用：**

```typescript
// 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，不使用缩短链接
- 尽可能使用带锚点的深链接（如 `/useActionState#usage` 优于 `/useActionState`）
- 当支撑非显而易见且版本敏感的决策时，引用相关段落
- 推荐平台特性时，附上浏览器/运行时兼容性数据
- 如果找不到某个模式的文档，明确说明：

```
未验证：未找到此模式的官方文档。
此实现基于训练数据，可能已过时。
请在用于生产前自行验证。
```

诚实说明未能验证的内容，比虚假自信更有价值。

## 常见借口

| 借口 | 现实 |
|------|------|
| "我对这个 API 很有信心" | 信心不是证据。训练数据里充满了看起来正确但在当前版本会出错的过时模式。验证它。 |
| "拉取文档浪费 token" | 编造 API 浪费更多。用户花一小时调试，才发现函数签名变了。一次拉取能省数小时返工。 |
| "文档里不会有我需要的" | 如果文档没覆盖，这本身就是有价值的信息——该模式可能不是官方推荐的。 |
| "我会注明可能已过时" | 免责声明没用。要么验证并引用，要么明确标记为未验证。模棱两可是最差选项。 |
| "仓库里已有 wrapper，所以永远不用查" | 局部修复可沿用已验证封装；迁移、兼容性、安全或公共模板仍需核对当前第一方资料。 |

## 危险信号

- 处理版本敏感 API 前既没有查第一方资料，也没有本地锁定版本证据
- 对 API 使用"我认为""应该是"而非引用来源
- 实现模式时不知道它适用于哪个版本
- 引用 Stack Overflow 或博客而非官方文档
- 因为出现在训练数据中而使用弃用的 API
- 实现前没有读 `package.json` / 依赖文件
- 交付时没有说明关键版本敏感决策的来源或本地证据
- 需要一个页面却拉取了整个文档站

## 检查清单

实现完成后自查：

- [ ] 已从依赖文件中识别框架和库的版本
- [ ] 已为版本敏感、兼容性或安全决策核对第一方资料
- [ ] 所有来源都是官方文档，不是博客或训练数据
- [ ] 代码遵循当前版本文档中展示的模式
- [ ] 非显而易见且会漂移的决策在 handoff / ADR 中包含可验证来源
- [ ] 未使用弃用 API（已对照迁移指南检查）
- [ ] 文档与现有代码的冲突已向用户说明
- [ ] 无法验证的内容已明确标记为未验证