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),
});

Step 4: Flag What You Couldn't Verify

If you're using a pattern you cannot confirm is current, say so explicitly:

# NOTE: Verify this middleware pattern against the current FastAPI docs.
# Used based on prior codebase patterns — may have changed in recent versions.
app.add_middleware(GZipMiddleware, minimum_size=1000)

And note it in the PR description or task update.

GitScape-Specific Sources

For the GitScape stack, always verify against:

| Technology | Official Source | |---|---| | FastAPI | https://fastapi.tiangolo.com/ | | Google Gen AI SDK (Python) | https://googleapis.github.io/python-genai/ | | Google Cloud Run | https://cloud.google.com/run/docs | | GitHub API (PyGithub) | https://pygithub.readthedocs.io/ | | React / TypeScript | https://react.dev/ | | Vite | https://vitejs.dev/ | | Cloud Build | https://cloud.google.com/build/docs |

Check the version in api/requirements.txt and web/package.json before citing docs for a specific version.

Anti-Patterns to Avoid

| Anti-Pattern | Why It Fails | |---|---| | Using an API without checking the version | Libraries break across major versions | | Copying a pattern from memory | Training data may lag 12-24 months behind current releases | | "This looks right" as verification | Looks right ≠ is right | | Citing an AI as a source | AI outputs require human-verified sources, not circular citation |

Common Rationalizations

| Rationalization | Reality | |---|---| | "I know this library well" | APIs change. Verify. The minute spent checking prevents the hour debugging. | | "I'll verify later" | You won't. And by then the wrong pattern is baked in. | | "The existing code uses this pattern" | Great — that's evidence. Check if the existing usage is from a current dependency version. |

Red Flags

• Library usage with no reference to a source
• Patterns that differ from every other usage in the codebase without explanation
• Using a deprecated API (check for deprecation warnings in docs)
• Citing a blog post or Stack Overflow answer as the source

Verification

After writing code that uses external libraries:

• [ ] Every external API usage is confirmed in official docs or the existing codebase
• [ ] The docs version matches the version in requirements.txt / package.json
• [ ] Unverified patterns are explicitly flagged with a # NOTE: verify comment
• [ ] No deprecated APIs are used (or if used, the deprecation is documented)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jmxt3
• Source: jmxt3/gitscape.ai
• License: Apache-2.0
• Homepage: https://gitscape.ai

Install and usage instructions live in the source repository linked above.