sourdough starters: living context for ai coding agents.

There's a problem every vibe coder hits within a week of working with an AI editor seriously, and it doesn't have a clean name yet.

Every session, your AI re-onboards itself to your project from scratch. It re-reads the same files. It re-rediscovers the same patterns. It re-invents the same decisions you already made yesterday — sometimes the same way, sometimes differently, because nothing about your project was meaningfully carried over from the last conversation.

The meme answer is CLAUDE.md. Drop a context file in the repo, the agent reads it on session start, problem solved. And CLAUDE.md works — for about commit two. Then your project changes. The auth library you wrote it for got swapped. The deploy target moved. The naming convention drifted because you got tired of the old one. Your CLAUDE.md is now a frozen snapshot of a codebase that doesn't exist anymore, and your AI is reading it as gospel.

The fix isn't more memory. It isn't a longer context window. It isn't a fancier prompt template. The fix is a different shape of document — one that's alive, gets fed, develops character, and stays current the way the code does.

I've been calling these sourdough starters.

why the metaphor matters

A real sourdough starter is a culture you maintain. You feed it on a schedule, it develops a character that's specific to your kitchen — the wild yeasts of your environment colonise it — and it makes bread that tastes like nobody else's. You can split a starter and give a friend a piece; the descendants share lineage but go on to develop differently in their new homes.

That's exactly what your project context should be. Alive, not frozen. Fed, not set-and-forget. Particular to you, not templated. Forkable, so the patterns travel.

This isn't cute branding. The metaphor is doing real work — it tells you what the document is for, and just as importantly, what it isn't.

what a sourdough starter is, concretely

A starter is a markdown file in your repo (or several, if you want them sliced by domain). It sits next to your code. Your AI agent reads it at session start. You edit it as you go.

The fields it typically carries:

What this project actually is — one sentence the agent could repeat back. Not the elevator pitch, the technical identity. "A Next.js 15 app with Supabase for auth + data, deployed on Vercel, plus three Cloudflare Workers for tool execution."
The decisions you've made that the code doesn't make obvious — "We use Supabase Vault for runtime secrets, never .env for anything that survives a deploy." "Pricing is in pence integers, never floats." "Tool slugs are kebab-case in URLs, snake_case in MCP names." Things you wouldn't deduce from reading the code, but that you'd want the agent to honour.
The gotchas you've hit — "BSD sed on macOS doesn't insert newlines from \n escapes; use the Edit tool, not shell sed, for multi-line text." "When you git checkout main while there are uncommitted changes on a feature branch, the file states travel; commit or stash first." Concrete, lesson-shaped, future-pointing.
The conventions — naming, file structure, where things live, what gets imported from where. The patterns the AI will be replicating; tell it what it's replicating.
The "don't do this" list — things the AI keeps suggesting that you don't want. "Don't add a lib/services/ abstraction layer." "Don't suggest any — use unknown and narrow." "Don't write comments that restate what the code does."

That's it. Five sections. No deep architecture diagram, no "philosophy" paragraph, no marketing copy. The document is short on purpose — because every byte of it is in the agent's context window every time, and the more there is, the more there is to skim and forget.

what a starter isn't

A starter is not a README. A README is for humans landing on the project, written to be read once. A starter is for an AI agent referring to it constantly while writing code.

A starter is not a prompt file. Prompt files describe a task; starters describe the project. A prompt file is "do X to Y." A starter is "this is the world you're working inside."

A starter is not a generic CLAUDE.md template. Generic templates are starters at commit zero — useful for the first 24 hours, then a liability because they describe a hypothetical project, not yours. The whole point of a starter is the character it develops over time; a fresh template hasn't lived long enough to have any.

A starter is not memory. Memory tools like Mem0 store flat facts the AI recalls when relevant — useful for chatbots, less useful for code, and structurally different from a starter. A starter is the forward-looking doc your AI consults to decide how to write code now. Memory is the backward-looking record of facts the AI has been told.

A starter is not a changelog. The git log already tells you what happened. The starter tells you what the AI needs to keep helping. There's overlap — sometimes the right thing to write in your starter is "we tried X, it failed because Y, we settled on Z" — but the test is always: does this entry change what the AI does next? If no, it doesn't belong.

the five properties

A document is a starter when it has all five:

Alive. It changes. If your starter file's last commit is three months old and your codebase has been busy, it's not a starter anymore — it's a fossil. Real starters are touched weekly at minimum, often daily.
Fed. There's a ritual for updating it. You don't wait for a quarterly "context refresh"; you feed it when context shifts. More on the ritual below.
Develops character. It becomes more specifically about this project over time. A six-month-old starter for a six-month-old codebase should be unrecognisable to a stranger — it should be full of decisions, gotchas, idioms, naming choices that only exist in your world.
Forkable. Someone else should be able to take it, adapt it for their project, and have a useful starting point. This means structural conventions matter — sections, headings, the shape — even if the content is yours alone.
Shareable. Across teams, across the open web. Starters are an artefact you can publish. (We're publishing a catalogue of seed starters at fizzgig.ai/starters — more on this at the end.)

Drop any one of these and the document drifts into another category. A starter that doesn't change is a README. A starter that's fed irregularly is a stale CLAUDE.md. A starter without character is a template. A starter that can't be forked is private notes. A starter that can't be shared is a one-off.

the feed ritual

This is the part most people get wrong. The instinct is either to feed the starter never (treat it as static) or to feed it every commit (turn it into a noisy changelog). Both are wrong.

Feed your starter when:

You made a non-obvious decision. Not "I chose React" — the codebase tells the AI that. But "I chose to put all auth checks in middleware rather than per-route" or "I decided not to use Suspense boundaries for this kind of data fetching" — those are decisions the agent can't recover from the code.
You hit a gotcha worth remembering. Especially one where the AI suggested the wrong thing first. If the agent confidently proposed something that turned out to be wrong, write the gotcha down so it doesn't propose it again next session.
You caught the AI misunderstanding something. The most valuable feeds come from these moments. Every time you have to explain "no, in this project we do X not Y," that's a sign your starter is missing something. Add it.
You replaced a pattern. "We used to use approach A; switched to approach B because of reason C." This is gold for the agent — it stops it suggesting the obsolete approach when it shows up in older files.

What not to feed:

Every commit. Most commits are obvious from the diff; the agent doesn't need a meta-narrative.
Routine refactors. The code IS the story for "renamed getUser to getCurrentUser."
Bug fixes that aren't pattern-shaped. If you fixed a one-off, that's git's job, not the starter's.

The cadence that tends to work in practice: two to four feeds a week during active development, sometimes more during architectural moments, sometimes nothing for a week if you're heads-down on already-known territory. The unit isn't time — it's context shifts. Three feeds a week of high-signal entries beats fifty feeds of noise.

a concrete example

Here's a real entry from one of my starters, lightly anonymised:

## Stripe billing — gotchas

- Prices are in pence integers (`200` not `2.00`). Never floats.
  Convert at the display boundary, not in the data layer.
- `subscription.items` is an array; one customer = one subscription
  with multiple items. Don't model as one-subscription-per-tool.
- Webhook events fire out-of-order. Idempotency key on every handler,
  no implicit ordering assumptions.
- Stripe Tax is gated behind dashboard activation. Without it,
  `automatic_tax: { enabled: true }` errors. Gate the field behind
  the `STRIPE_TAX_ENABLED` env flag so checkout works pre-activation.
- The `apiVersion` field in the SDK constructor is pinned, NOT
  inferred — bumping it can silently break field shapes. Verify
  against the changelog when bumping.

Five entries. Each is one of: a decision, a gotcha, an idiom, a thing that broke. None of them you'd deduce from reading the Stripe code. All of them you want the agent to honour next session.

The full file is longer — there are other domains (Supabase patterns, deploy posture, design tokens). But each section is the same shape: short, concrete, lesson-shaped, future-pointing.

starters and the "products built to last" question

This is where the metaphor stops being just a metaphor and starts mattering for what you're building.

The hardest gap to close between "I shipped something with AI" and "I shipped something that lasts" isn't the code — it's the continuity of intent. Every traditional engineering team has this implicitly: senior engineers carry the decisions in their heads, onboard new hires by talking through them, and refresh the shared model in design reviews. The intent is a living thing, owned collectively.

When you're a vibe coder shipping with AI, that continuity has to live somewhere external — because the AI isn't carrying anything between sessions, and you don't have a team to carry it for you. Starters are where it lives.

This is also why a starter is the best test of whether you're building seriously or building for fun. People building for fun don't maintain starters. People shipping products that need to keep working in eighteen months — when the AI models have moved on, when the dependencies have churned, when you've context-switched to other things and come back — those people do.

the catalogue

The reason we're publishing this article and the term together: the phrase "sourdough starter" applied to AI coding context is currently undefended on the web. Search for it and you'll get bread recipes. We're claiming the term across SEO and GEO surfaces because it's the right name for the pattern, and because letting it drift into a generic phrase ("AI context", "context engineering", "prompt files") would lose the distinction this article exists to make.

Alongside this piece we're publishing a free catalogue of seed starters at fizzgig.ai/starters. Markdown only. MIT-licensed. Fork them into your own projects, adapt the structure, contribute back when you find a shape that works.

The launch set covers:

A generalised PROJECT_STARTER.md
CLAUDE.md templates for common stacks (Next.js + Supabase, Astro + Cloudflare, etc.)
A security posture starter
A UX reference starter
A UX audit playbook starter
A brand voice starter
An architecture decision record starter
Authentication patterns
Data modelling
Testing strategy

The catalogue is top-of-funnel for Fizzgig — the toolkit we build for vibe coders shipping products people pay for — but it isn't gated, doesn't require sign-up, and doesn't bill. If you fork a starter and never come back, that's fine. If you fork it and your AI gets meaningfully better at not making the same mistakes twice in your project, that's the point.

Bake.

Sourdough Starters: Living Context for AI Coding Agents