If you work with an assistant day-to-day, you’ll eventually hit the same wall:
- You explain the project.
- You explain the constraints.
- You explain what “done” means.
- Two prompts later, you explain it again.
Not because the assistant is “bad” — but because your context is scattered across Slack messages, half-written docs, your memory, and whatever you typed five minutes ago.
My fix for this is a tiny habit I call the Seed File Pattern:
Create one small, human-written file that “seeds” the assistant with the minimum context needed to do good work — and keep it updated as the project evolves.
It’s basically a lightweight, version-controlled briefing packet.
What a seed file is (and what it isn’t)
A seed file is a short document (usually seed.md) that answers:
- What is this project?
- What are we trying to do right now?
- What must not change?
- How do we validate the result?
It is not:
- a full architecture document
- a replacement for your README
- a dumping ground for everything you know
Think: 1 page of high-signal context.
Why this works so well
Seed files solve three failure modes that make AI-assisted work feel flaky:
1) “Context drift”
When you re-explain things ad-hoc, details change without you noticing. The assistant gets a different picture each time.
A seed file creates a single source of truth you can point to.
2) “Invisible constraints”
Most projects have unwritten rules:
- “We can’t add new dependencies.”
- “We don’t touch the billing module on Fridays.”
- “We prefer SQL over ORM magic.”
If those constraints aren’t explicit, you’ll keep paying the same coordination tax.
3) “Undefined done”
A lot of assistant output fails not because it’s wrong — but because it’s not done.
A seed file forces you to write a definition of done once, then reuse it.
The template (copy/paste)
Create seed.md at the repo root (or in a dedicated folder like .assistant/seed.md). Start with this:
# Seed: <project name>
## 1) One-paragraph overview
What this project is and who it’s for.
## 2) Current goal (this week)
- Primary goal: …
- Non-goals: …
## 3) Constraints (hard rules)
- No new dependencies.
- Keep public API stable.
- Prefer small diffs; avoid formatting-only churn.
## 4) Key facts / definitions
- “Invoice”: …
- “Sync”: …
- “Workspace”: …
## 5) How to run / test
bash
install
...
run
...
tests
...
## 6) Acceptance criteria
- [ ] …
- [ ] …
## 7) Output contract (what you want back)
When responding, provide:
1) a short plan
2) the patch/diff (or file edits)
3) how to validate
4) risks / edge cases
The “output contract” part is underrated: it turns “chatty answers” into reviewable artifacts.
A concrete example (realistic, not idealized)
Here’s what a seed file looks like for a small Node CLI:
# Seed: Acme Sync CLI
## Overview
A Node.js CLI used by ops to sync customer records from PartnerX into our Postgres DB.
## Current goal
- Add a `--dry-run` flag to `acme sync`.
- Non-goals: refactor the command structure, change logging format.
## Constraints
- No new dependencies.
- Keep behavior identical when `--dry-run` is not provided.
- Only touch `src/commands/sync.ts` and `README.md` unless truly necessary.
## Definitions
- “dry-run”: do everything except writes; print what would be written.
## How to run / test
bash
npm ci
npm test
node dist/cli.js sync --help
## Acceptance criteria
- [ ] `acme sync --dry-run` prints intended changes and exits 0.
- [ ] no DB writes happen in dry-run mode.
- [ ] README includes one usage example.
## Output contract
Return:
1) a minimal diff
2) a short explanation
3) tests proving dry-run doesn’t write
Now when you start a new session, your prompt becomes extremely short:
Read seed.md.
Task: implement --dry-run for sync.
Follow the constraints and output contract.
That’s it.
Workflow: how to actually use it (without turning it into “process”)
Step 1: Write the seed file before the first big request
Do this at the moment you notice repeated explanations.
If you’re mid-task, write the seed file with what you know now and refine it later.
Step 2: Update it when reality changes
Treat seed.md like code:
- if a constraint changes, update it
- if a definition changes, update it
- if “how to run tests” changes, update it
If you’re in a repo, commit the seed file. It’s part of the project’s working memory.
Step 3: Make the assistant prove it read the seed
This one prompt line pays for itself:
“Before you start, summarize the constraints from seed.md in 3 bullets.”
If the summary is wrong, you correct once — and every later request inherits the fix.
Step 4: Keep it small on purpose
If your seed file grows beyond ~60–80 lines, you’re probably mixing it with documentation.
A nice rule:
- seed file: what the assistant needs to act
- docs: what humans need to understand
Variations that work well
-
One seed per area:
seed-api.md,seed-frontend.mdif the project has very different constraints. -
Seed + examples folder: put 2–3 “golden” examples in
.assistant/examples/and reference them. - Seed + checklist: add a small “pre-flight” list (lint, tests, build) so the assistant always returns validation steps.
Common mistakes (and fixes)
Mistake: turning it into a novel
Fix: move details into docs and link them.
Mistake: no explicit non-goals
Fix: always write a “do not” list. The assistant will fill empty space with “helpful improvements.”
Mistake: no acceptance criteria
Fix: write at least 2 checkboxes. If you can’t, the task is probably underspecified.
The payoff
The Seed File Pattern isn’t about making prompts longer. It’s about making them repeatable.
You write the context once, and then your day-to-day prompts shrink to:
- “Read seed.md.”
- “Here’s the task.”
- “Return a minimal diff + validation steps.”
That’s the kind of workflow that scales from “I’m experimenting” to “this is how we ship.”
Top comments (0)