SuperAPI AI Directory

build-cognitive-source-driven

General & other

View repository

Updated 10-16 09:44

About this skill

Source-Driven — source-driven development

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