source-driven-development

Source-Driven Development

Overview

Every framework decision and library usage should be grounded in official documentation. AI agents have training cutoffs and can produce outdated, deprecated, or hallucinated API patterns. Source-driven development means: verify before you code, cite what you verified, and flag what you couldn't confirm.

When to Use

• Using any external library or framework
• Implementing a pattern that isn't already established in the codebase
• Unsure whether an API or approach is current
• Seeing a pattern that looks right but isn't confirmed in the existing codebase

The Process

Step 1: Identify What Needs Verification

Before writing any code that uses an external library:

1. List the specific APIs, functions, or patterns you plan to use
2. Note the version you're targeting (check requirements.txt, package.json, or pyproject.toml)
3. Flag anything you're not 100% confident is current

Step 2: Verify in Official Sources

Priority order for sources:

1. Official docs — the library's own documentation site
2. Official GitHub — the library's README.md, CHANGELOG.md, or examples/
3. Release notes — for the specific version in use
4. Existing codebase — how the library is already used in this project

Never use as authoritative sources:

• Stack Overflow answers (can be outdated)
• Blog posts (may target a different version)
• Your own training knowledge without verification
• ChatGPT or other AI outputs as a source of truth

Step 3: Cite Your Sources

When writing code that uses verified patterns, leave a reference comment for future maintainers:

# FastAPI dependency injection pattern
# Source: https://fastapi.tiangolo.com/tutorial/dependencies/
async def get_db() -> AsyncGenerator[AsyncSession, None]:
    async with AsyncSessionLocal() as session:
        yield session

// React Query v5 data fetching
// Source: https://tanstack.com/query/v5/docs/framework/react/guides/queries
const { data, isLoading } = useQuery({
  queryKey: ['skills', repoId],
  queryFn: () => fetchSkills(repoId),
});