Entry/Exit
- Entry: Using unfamiliar APIs/libraries, implementing framework-specific code, introducing new dependencies
- Exit: Every decision has a correct implementation backed by official documentation/source code
- Points to: Continue the current build process
- Preload: CANON.md
- Output paths: build-workflow-execute
When not to use
- Entirely inside a module you wrote yourself (no external API calls)
- Using an API that has already been used correctly multiple times within the project (working examples have verified the signature)
Iron Law
每个框架特定的代码决策必须有官方文档支持。
"我感觉"、"我相信"、"是" → 都不是证据。
模糊 = 最差选项。要么验证,要么标注未验证。
Flow: DETECT → FETCH → IMPLEMENT → CITE
DETECT → 识别出哪些代码是框架特定的
FETCH → 查找官方文档/源码验证 API 签名和行为
IMPLEMENT → 按文档正确的签名和模式实现
CITE → 在代码注释或对话中留下完整引用 URL
Step 1: DETECT — Identify framework-specific code
Before writing any code, if it involves:
- Importing APIs from external packages/libraries
- Using framework-specific patterns (such as Next.js routing, Prisma queries, React Hook signatures)
- Depending on third-party API behavior (such as Stripe SDK, AWS SDK)
→ Trigger the Source-Driven flow. Do not write from memory.
DETECT practical example:
Scan import statements to identify all framework-specific code:
// 你准备写的代码中有这些 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
Each import → one item to verify. Do not assume any API signature.
Step 2: FETCH — Check official sources
Source priority (high to low):
| Priority | Source | Use case |
|---|---|---|
| P0 | Official documentation (.docs site) | API signatures, configuration options, breaking changes |
| P1 | GitHub source code / type definitions | Edge-case behavior, default values, return types not covered by documentation |
| P2 | Existing correct code within the project | Verifying patterns that have already been used successfully in this project |
| P3 | Official example repositories / integration tests | End-to-end patterns for complex flows (OAuth, Webhook handling) |
| P4 | Community (Stack Overflow / Blog) | Only when none of the above sources have an answer, and cross-validation is needed |
Do not use P4 when P0-P3 all exist.
FETCH practical example:
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 — Implement according to the documentation
Write code according to verified signatures and patterns. No "I think this works too" changes — every change is consistent with the documentation.
Step 4: CITE — Leave citations
// 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 }],
},
},
});
Citation rules:
- Full URL, not abbreviated
- Explainwhythis source was chosen (do not repeat documentation content)
- When the implementation deviates from the documentation (explicit version compatibility handling), note the reason for the deviation
Conflict handling
文档说 X,现有代码做 Y?
│
├── 现有代码按旧版本文档写的 → 按最新文档修正
├── 现有代码有意为特定坑而偏离文档 → 找到那个坑(issue/PR/ADR)
└── 找不到为什么偏离 → STOP。问人类。
Good/Bad comparison — blind guessing vs source-driven
// ❌ 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]);
Anti-pattern fix table
| Anti-pattern | Problem | Fix |
|---|---|---|
| Writing API calls from memory | Memory may be from a previous version, and the signature has changed | The DETECT phase must search official documentation to verify the signature |
| Replace official documentation with Stack Overflow answers (treat P4 priority as P0) | Community answers may be outdated or target a different version | P4 sources are for reference only; defer to P0-P1 |
| Skip conflict handling and use the solution you found directly | When documentation and existing code contradict, don't resolve it | Judge level by level according to the conflict-handling decision tree |
| Documentation says deprecated but the code still uses it | Documentation may lag behind the actual version | Defer to the actual version's CHANGELOG; documentation may lag |
| Copied example code without checking the context version | Examples may correspond to a different major version | Record the documentation version and date in CITE |
| The same API is described contradictorily in P0 and P1 sources | Official documentation and type definitions are out of sync | Defer to P0, and note the discrepancy in CITE |
| Stopped as soon as you found a solution that runs | There may be a better solution or hidden pitfalls | Check at least two sources, P0 and P1, before deciding |
| Treat workarounds in GitHub Issues as official APIs | Temporary solutions in Issues may be removed in the next version | Use only as P3 reference, not as an official API |
Common sayings
| Saying | Reality | Consequence |
|---|---|---|
| "I know this API" | Might be a memory from the previous version. Verify > trust your memory. | Signature differences from the previous version cause a runtime crash; rollback cost ≥ 1 hour |
| "Code is better than docs, just read the source" | Source tells you "what"; docs tell you "why" and "how". Docs first, then source. | Missing semantic constraints and side effects; implicit bugs erupt after launch, troubleshooting ≥ 4 hours |
| "Docs are too long, can't be bothered to read" | Use search to locate the specific section. No need to read from start to finish. | Wrong parameter order or missing required fields; compiles but behaves incorrectly, wasting ≥ 30 minutes debugging |
| "This is just a simple API call" | Even simple calls have version differences. 30 seconds checking docs > 30 minutes debugging a bug. | Version differences cause implicit behavior changes; when tests don't cover edge cases, users report errors after launch |
| "Type definitions are enough, no need to read the docs" | Type definitions don't include semantic constraints, side effects, or deprecation notes. Read the docs. | Using a deprecated API; full refactor needed when upgrading to the next version, changes ≥ N call sites |
| "I've used this API in another project" | The version may differ. The API signature may have changed. Verify. | Cross-project version differences cause parameter mismatches; production error fix ≥ 2 hours |
| "The CHANGELOG is too long, don't want to read it" | That's exactly where bugs hide. Read the Breaking Changes section. | Missing a breaking change; batch runtime errors after upgrade, affecting ≥ all modules using that API |
| "This framework is simple, no docs needed" | Simple frameworks have pitfalls too. React's useEffect dependency array is a counterexample. | Implicit pitfalls lead to performance degradation or memory leaks, only exposed after user growth, with a fix cost of ≥ 1 week |
| "It's fine as long as the example code runs" | Runs ≠ correct. The example may use a deprecated API. | After the deprecated API is removed in the next version, emergency fixes are needed, affecting ≥ all downstream dependencies of that feature |
| "Official documentation is sometimes wrong too" | Isolated errors are not a reason to skip the documentation. When documentation errors are found, annotate them in CITE. | Skipping documentation leads to code without source verification, which cannot pass review, and rework ≥ rewriting the module |
Red Flags — STOP
- Describing an API with "it is X", "it is most likely X", "I remember X"
- Not recording the reference URL ("it's probably like this" won't work)
- Using Stack Overflow answers instead of official documentation (P4 cannot replace P0)
- Not annotating version/expiration information while still using an old API
- "The API documentation and the existing code disagree, I'll go with the code" (not resolving the conflict)
- Not verifying compatibility between multiple external APIs when using them in combination
Pay attention to signals from human partners:
- "Are you sure this is correct?" — You may have skipped the verification step, go back and do DETECT
- "Is there documentation?" — You did not CITE, go back and add references
- "Is the version correct?" — You did not DETECT the version, check package.json and then verify the documentation version
- "I remember this API is not like this" — Your source may be outdated, re-FETCH the latest documentation
- "This API has been deprecated, right?" — You may have used an old API, check the CHANGELOG to confirm
All of them mean: STOP. Go back to DETECT.
Handling Verification Failures
| Failure Scenario | Handling Method |
|---|---|
| Official documentation unreachable | Downgrade to P1 sources (GitHub README, type definitions). If there is no documentation at all, mark as Unknown and inform the human partner |
| P0 documentation contradicts actual code behavior | Use code behavior as the standard and record the discrepancy in CITE. The documentation version may be lagging |
| Unable to determine the framework version | Check package.json / lock file. If still unable to determine → mark as Unknown |
| Multiple P0 sources contradict each other | Go with the most recently updated one, and record all contradictory sources |
| No documentation can be found at all | Mark as Unknown. Read the source code type definitions as a last resort. Do not guess |
| Community solutions contradict each other | Do not trust any P4 solution. Go back to P0-P1 to look for authoritative sources. If there is no authoritative source, mark as Unknown |
Output Template
Each module that goes through the Source-Driven process should produce the following structure (which can be recorded in code comments or an ADR):
### Source-Driven 验证记录
**模块**: [文件路径或模块名]
**框架/库**: [库名 + 版本号]
| 决策点 | API 签名 | 来源等级 | 引用 URL | 偏离说明 |
|--------|----------|----------|----------|----------|
| [具体决策] | [验证过的签名] | P0/P1/P2/P3 | [完整 URL] | 无 / [偏离原因] |
**冲突记录**(如有):
- [冲突描述] → [处理方式: 按最新文档修正 / 找到偏离原因 / 标记 Unknown]
**未验证项**(如有):
- [未验证决策] → 标记 Unknown,待人类伙伴确认
Verification Checklist
- Each framework-specific decision has a corresponding official documentation reference
- References use complete URLs
- Uncovered boundary behavior is verified through source code or tests
- The referenced documentation version matches the library version used by the project
- Places that deviate from the documentation have clear annotations of the version/pitfall reason