Why the same model produces wildly different results

Two teams using the exact same AI coding model can get very different quality of output - not because one has a better prompt-writer, but because one gives the model persistent context about the actual system it's working on, and the other re-explains from scratch (or doesn't explain at all) every session. A model with no memory of your schema, your existing conventions, or last week's architecture decision is not being lazy when it generates something inconsistent - it's working with exactly the information it was given, which was none.

What "context" concretely means

Database schema

Table names, relationships, and constraints - so generated queries match what actually exists instead of inventing plausible-sounding columns.

User flows

How a user actually moves through the product - so a new feature is generated consistent with existing navigation and state, not as an island.

Technical decisions

Why the team chose Postgres over Mongo, or REST over GraphQL - so the agent doesn't quietly reintroduce an option that was already rejected for a reason.

The practice: a living context document

GitHub's own analysis of thousands of real agent configuration files (their AGENTS.md and similar conventions) found the most effective specs consistently cover the same handful of areas: exact commands to run (not just tool names - full commands with flags), how tests work and where they live, and where source code, tests, and docs are organized in the project. The pattern holds whether it's a solo founder's SPEC.md or an enterprise team's shared configuration file - the goal is the same: a document the agent reads at the start of every session, so context survives between sessions instead of evaporating when the chat window closes. 

# CONTEXT.md - example structure for a shared workspace

## Commands
- Dev server: `npm run dev`
- Run tests: `npm run test -- --watch=false`
- Type check: `npm run typecheck`

## Project structure
- `/app` - Next.js App Router pages and layouts
- `/lib/db` - Supabase client + query helpers
- `/lib/schema.sql` - source of truth for the database schema

## Key decisions (with reasoning, not just the choice)
- Postgres via Supabase, not Mongo: relational data (orgs -> users -> projects)
  needs joins and row-level security we'd otherwise reimplement in app code.
- Server actions over a separate API layer: this is a single Next.js app,
  not a multi-client product - a separate REST layer would add indirection
  with no current consumer that needs it.

## Current user flow (signup -> first value)
Signup -> email verify -> org creation -> invite teammates -> first project.
Entitlement checks happen at the org level, not the user level - see
/lib/entitlements.ts for the single gate function.

Why "with reasoning, not just the choice" matters: an agent that only knows "we use Postgres" might still suggest denormalizing data the way it would for Mongo. An agent that knows why Postgres was chosen is far less likely to suggest an approach the reasoning already rules out.

From random generator to collaborator

The practical difference this makes: without shared context, an AI coding agent behaves like a contractor with no onboarding - technically competent, architecturally unmoored. With a maintained context document, the same agent behaves closer to a teammate who's read the project's own documentation before starting - proposing changes that fit existing patterns instead of introducing a new one every time. This is the same underlying discipline as the Prompt-Refactor-Verify cycle covered in our PRV piece, applied specifically to the "what does the agent already know" question.

Keeping the context document alive

  • Update it when a real architectural decision is made - not retroactively, as part of making the decision.
  • Keep the "why," not just the "what" - future sessions (and future teammates) need the reasoning to avoid re-litigating settled decisions.
  • Treat schema drift as a signal to update the document immediately - a stale schema section is worse than none, since it actively misleads the agent.
  • Review it periodically the way you'd review onboarding docs for a new hire - if a human would find it confusing, an agent will misuse it too.

Key takeaways

  • The same AI model produces very different quality output depending on whether it has persistent context about the actual system - this, not prompt-writing skill, is usually the real gap.
  • Effective context documents consistently cover commands, project structure, and the reasoning behind key technical decisions - this pattern holds from solo founders to enterprise teams.
  • Include the "why" behind decisions, not just the decision - it's what stops an agent from re-suggesting an option the team already rejected.
  • A maintained context document is what turns an AI coding agent from a random generator into something closer to an onboarded collaborator.
  • This is a natural next step after the architecture and stack choices covered in our vibe-coding-to-production pieces - context is what keeps those choices consistently applied.
If your AI coding tools keep generating code that technically works but doesn't feel like it belongs in your codebase, the missing piece is usually context, not a better prompt.