source-driven-development

Source-Driven Development

Every framework-specific decision must be backed by official documentation, not training data. LLMs hallucinate APIs, invent method signatures, and confuse library versions. The antidote is to verify against the source of truth before writing code.

Rules

1. Detect the stack first — read CLAUDE.md, package.json, requirements.txt, go.mod, or equivalent to know exact versions
2. Fetch docs, don't guess — use WebFetch to read official docs for the specific version in use
3. Cite your source — add a comment or docstring with the doc URL when using a non-obvious API
4. Say UNVERIFIED — if you cannot find official documentation for a claim, explicitly mark it as // UNVERIFIED: could not find docs for this API
5. Never cite Stack Overflow, blog posts, or tutorials as primary source — they may be outdated or wrong. Official docs and source code are the only primary sources
6. Version matters — docs for v3 don't apply to v2. Always check the version installed

Workflow

Phase 1: Detect stack and versions

# Node.js
cat package.json | grep -A1 '"dependencies"'

# Python
cat requirements.txt  # or pyproject.toml

# Go
cat go.mod

Phase 2: Before implementing

For each framework-specific decision:

1. Identify the specific API/method/pattern you need
2. Fetch the official docs page for that API
3. Verify: does this method exist? What are the parameters? What version introduced it?
4. If docs are unavailable → mark as UNVERIFIED and note what you assumed

Phase 3: Implement with citation

// Ref: https://docs.example.com/api/v3/client#create
const client = new Client({ timeout: 5000 });

Phase 4: Verify after implementing

1. Does the code compile/type-check? (catches hallucinated APIs)
2. Do tests pass? (catches wrong method signatures)
3. Are all UNVERIFIED markers resolved or documented?

Source hierarchy

Priority	Source	Use for
1	Official docs (versioned)	API signatures, configuration, behavior
2	Source code (GitHub)	When docs are incomplete or ambiguous
3	Official migration guides	Version upgrade patterns
4	Official examples/cookbooks	Integration patterns
5	UNVERIFIED (mark explicitly)	Last resort — document the assumption