Source-Driven — 源码驱动开发

入口/出口

• 入口: 使用不熟悉的 API/库、实现涉及框架特定代码、引入新依赖
• 出口: 每个决策都有官方文档/源码背书的正确实现
• 指向: 继续当前 build 流程
• 前置加载: CANON.md
• 输出路径: build-workflow-execute

何时不使用

• 完全在自己写的模块内部（无外部 API 调用）
• 使用项目内已多次正确使用过的 API（工作示例已验证签名）

Iron Law

每个框架特定的代码决策必须有官方文档支持。
"我感觉"、"我相信"、"是" → 都不是证据。
模糊 = 最差选项。要么验证，要么标注未验证。

流程: DETECT → FETCH → IMPLEMENT → CITE

DETECT         →  识别出哪些代码是框架特定的
FETCH          →  查找官方文档/源码验证 API 签名和行为
IMPLEMENT      →  按文档正确的签名和模式实现
CITE           →  在代码注释或对话中留下完整引用 URL

Step 1: DETECT — 识别框架特定代码

在写任何代码之前，如果它涉及：

• 导入外部包/库的 API
• 使用框架特定的模式（如 Next.js 路由、Prisma 查询、React Hook 签名）
• 依赖第三方 API 行为（如 Stripe SDK、AWS SDK）

→ 触发 Source-Driven 流程。不要凭记忆写。

DETECT 实际操作示例：

扫描 import 语句，识别出所有框架特定代码：

// 你准备写的代码中有这些 import：
import { PrismaClient } from '@prisma/client';       // → Prisma ORM
import { useRouter } from 'next/navigation';          // → Next.js App Router
import { z } from 'zod';                              // → Zod 验证库
import { createHmac } from 'crypto';                  // → Node.js 内置（查 Node 文档）

// DETECT 阶段产出：
// - Prisma: prisma.order.create() 的 nested write API → 需查 prisma.io docs
// - Next.js: useRouter() 的返回类型和方法 → 需查 nextjs.org docs
// - Zod: z.object() 的 refine/transform 链式 API → 需查 zod.dev docs
// - crypto: createHmac 的算法参数列表 → 需查 nodejs.org docs

每个 import → 一个待验证项。不要假设任何 API 签名。

Step 2: FETCH — 查官方来源

来源优先级（从高到低）：

不使用 P4 当 P0-P3 都存在。

FETCH 实际操作示例：

DETECT 识别出：需要用 Prisma 的 nested write 创建订单

FETCH 执行：
1. WebSearch "prisma nested create official documentation"
2. 命中 P0: https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries
3. 定位到 "Nested writes" 章节
4. 验证 API 签名: prisma.order.create({ data: { items: { create: [...] } } })
5. 确认版本兼容: 项目用 Prisma 5.x，文档对应 5.x ✓
6. 记录来源 URL 用于 CITE 阶段

如果 P0 不可达 → 降级到 P1：
1. WebSearch "prisma github prisma-client relation queries"
2. 读 TypeScript 类型定义中的 create 方法签名
3. 在 CITE 中标注：来源为类型定义（P1），官方文档不可达

Step 3: IMPLEMENT — 按文档实现

按验证过的签名和模式写代码。不要"我觉得这样也行"的改动——每个改动和文档一致。

Step 4: CITE — 留下引用

// ref: https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries#nested-writes
// Prisma nested create — creates parent + children in one transaction
await prisma.order.create({
  data: {
    items: {
      create: [{ name: 'Widget', quantity: 2 }],
    },
  },
});

引用规则：

• 完整 URL，不缩略
• 说明为什么选这个来源（不重复文档内容）
• 当实现偏离文档时（明确的版本兼容处理），标注偏离原因

冲突处理

文档说 X，现有代码做 Y？
    │
    ├── 现有代码按旧版本文档写的 → 按最新文档修正
    ├── 现有代码有意为特定坑而偏离文档 → 找到那个坑（issue/PR/ADR）
    └── 找不到为什么偏离 → STOP。问人类。

好/坏对照 — 盲猜 vs 源码驱动

// ❌ Bad: 凭记忆写 API，不查文档
// "我记得 Prisma 的 create 可以嵌套，大概是这样："
await prisma.order.create({
  data: {
    items: {
      push: [{ name: 'Widget' }],  // push 不存在！应该是 create
    },
  },
});
// 结果：运行时报错，浪费 30 分钟调试

// ✅ Good: DETECT → FETCH → IMPLEMENT → CITE
// DETECT: prisma.order.create + nested items → 需查 Prisma 文档
// FETCH: 搜索 "prisma nested create" → 定位官方文档
// IMPLEMENT: 按验证过的签名实现
// ref: https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries#nested-writes
await prisma.order.create({
  data: {
    items: {
      create: [{ name: 'Widget', quantity: 2 }],
    },
  },
});

// ❌ Bad: 从 Stack Overflow 复制代码（P4 当 P0）
// "Stack Overflow 上说 useEffect 这样用"
useEffect(() => {
  fetchData();
}, []); // 缺少依赖项，ESLint 警告被忽略

// ✅ Good: 查 React 官方文档
// DETECT: useEffect + 依赖数组 → 需查 React 文档
// FETCH: 搜索 "react useEffect dependencies official"
// ref: https://react.dev/reference/react/useEffect#my-effect-keeps-re-running-every-render
useEffect(() => {
  fetchData();
  // fetchData 已用 useCallback 包裹，依赖稳定
}, [fetchData]);

反模式修复表

常见说辞

红旗 — STOP

• 用 "是 X"、"大概率是 X"、"我记得 X" 描述 API
• 不记引用 URL（"大概是这样"行不通）
• 用 Stack Overflow 答案代替官方文档（P4 不能替代 P0）
• 在仍使用旧版 API 时不标注版本/过期信息
• "API 文档和现有代码不一致，我选代码继续"（不解决冲突）
• 多个外部 API 组合使用时没有验证它们之间的兼容性

注意来自人类伙伴的信号：

• "你确定这是对的？" — 你可能跳过了验证步骤，回去做 DETECT
• "有文档吗？" — 你没有 CITE，回去补充引用
• "版本对吗？" — 你没有 DETECT 版本，检查 package.json 后验证文档版本
• "我记得这个 API 不是这样的" — 你的来源可能过时了，重新 FETCH 最新文档
• "这个 API 已经废弃了吧？" — 你可能用了旧 API，查 CHANGELOG 确认

全部意味着：STOP。回到 DETECT。

验证失败处理

输出模板

每个经过 Source-Driven 流程的模块应产出以下结构（可在代码注释或 ADR 中记录）：

### Source-Driven 验证记录

**模块**: [文件路径或模块名]
**框架/库**: [库名 + 版本号]

| 决策点 | API 签名 | 来源等级 | 引用 URL | 偏离说明 |
|--------|----------|----------|----------|----------|
| [具体决策] | [验证过的签名] | P0/P1/P2/P3 | [完整 URL] | 无 / [偏离原因] |

**冲突记录**（如有）:
- [冲突描述] → [处理方式: 按最新文档修正 / 找到偏离原因 / 标记 Unknown]

**未验证项**（如有）:
- [未验证决策] → 标记 Unknown，待人类伙伴确认

验证清单

• 每个框架特定决策有对应的官方文档引用
• 引用使用完整 URL
• 未覆盖的边界行为通过源码或测试验证
• 引用的文档版本与项目使用的库版本匹配
• 偏离文档的地方有明确的版本/坑位原因标注