Context-First Development · CFD
Your AI agent has amnesia at the start of every session. CFD is the cure.
A methodology for engineers working with AI coding agents (Claude Code, Codex, GitHub Copilot, Gemini CLI, Cursor) on real repositories. It treats context as a first-class artifact: structured, versioned, and reviewed like code.
The problem
Models restart every session with no memory of your architectural decisions. The result: you correct more AI-generated code than you would save writing it by hand, because the agent lacks the “why” that code alone can’t express.
The problem isn’t context capacity. It’s context quality.
The real payoff
Adherence, not tokens.
Almost everyone sells token savings. CFD targets something harder to argue with: code that respects your conventions on the first try, decisions that don’t get re-litigated, corrections that never repeat. Token savings are a welcome side effect, not the headline.
Six principles
Context Before Code
Resolve context at session start, not while you work.
Single Source of Truth
Every fact lives in exactly one file; everything else references it.
Hierarchical Context
CLAUDE.md is an index (~100 lines), not an encyclopedia.
Decisions as First-Class Citizens
Every significant decision becomes an ADR with alternatives and rationale, before the code.
English as Context Language
Tokenizers compress English ~20–40% better. It applies to the context the AI eats, not to what you publish.
Automation Through Agent Skills
Maintaining context is a procedure any agent runs, not a chore to remember.
A real issue
The issue body is the spec.
Every unit of work lives in the tracker with five fixed sections. The session starts by reading that, not by reconstructing it from code. This is #116 of sii, a CLI and MCP server for Chile’s tax authority, born with CFD on day 0 and now at 26 ADRs.
Not docs, mechanism
The discipline enforces itself.
What separates CFD from “just write good docs” is that context is enforced by mechanism, not goodwill:
Injects context automatically on start and warns when it’s stale.
Blocks commits that stage code without updating CURRENT_STATUS.md.
Fails the PR when two ADRs share a slug and warns when code changes without touching status. It reaches any agent, including one you never configured.
Measured, not claimed
Reproducible numbers.
tokens to orient a session with CFD
tokens scanning the whole repo without CFD
less context to get started
freshness of CURRENT_STATUS.md
Measured with scripts/measure-session-cost.sh over the node-express example the repo shipped until July 2026. Run the same script on your own repo.
Automation
The procedures are Agent Skills.
One copy in .agents/skills/, the open format Claude Code, Codex, GitHub Copilot and Gemini CLI all read. The session rituals run only when you invoke them, never on the model’s judgement.
/project-initBootstraps the CFD scaffold in an existing repo./session-startLoads CLAUDE.md + CURRENT_STATUS.md + decisions index./issue-newCreates an issue with a fixed template and ADRs to preload./issue-startStarts work with the decision context already loaded./review-prReviews the diff against the AC, the conventions and the ADRs. Before closing./session-closeEnsures CURRENT_STATUS.md ships alongside your code.
In Codex they are invoked as $session-start. Install them into every agent with npx skills add albertomarturelo/context-first-development.
CFD in your setup
The files and the loop are the same. What changes is where state lives and who decides.
Find your case. They stack: a team running Codex and Claude in worktrees reads all four.
Case 1
One developer, one repo
- →One issue per session. /issue-new forces decomposition until an issue fits one.
- →What you correct goes to CONVENTIONS.md; what you decide becomes an ADR before the code. The agent never hears the same correction twice.
- →Review your own diff before you close, while the context is still loaded. Reviewing after the close means paying a new session to rebuild it.
Case 2
A team on one repo
- →Status goes personal: CURRENT_STATUS.md leaves git. Shared, it conflicts on every PR and injects everyone’s work-in-progress into your session.
- →The tracker is the shared picture: assignees and issue state answer “who is doing what”.
- →When a teammate reviews, the order flips: you close, and their findings open your next session.
Case 3
Parallel loops in git worktrees
- →A worktree isolates files, not decisions. Everything on main when you branch is shared; anything decided inside one worktree is invisible to the others until it merges.
- →So decide first, and stop when a new decision appears. Disjoint target paths; a mid-loop ADR lands on main as its own PR and the other loops rebase.
- →You are the bottleneck on purpose: each merge is reviewed against the current main. Run as many loops as you can actually review, usually two or three.
Case 4
Several agents, one source
- →Nothing to translate. The index and the procedures exist once; symlinks give each agent the path it looks for.
- →CI is the guarantee: hooks help inside Claude Code, but the CI checks hold any agent’s PR to the same rules.
What it costs, honestly
It is a discipline, not a tool that works while you look away.
- →A few minutes per session for the start and close rituals, and about 30 minutes to bootstrap an existing repo.
- →Decisions get written before code. The first week feels slower; the payoff is the week after, when nothing gets re-explained.
- →It only works if the docs stay true. A stale ADR misleads the agent with full confidence. The hooks and CI exist to prevent that, but someone still has to run the ritual.
Get started
Adopt CFD in 60 seconds.
Clone the templates over your repo, edit CLAUDE.md with your project description, and start your first session.
git clone https://github.com/albertomarturelo/context-first-development.git /tmp/cfd
cp -R /tmp/cfd/templates/. .
# Edit CLAUDE.md with your project, then:
> /session-start
# or install just the skills into every agent:
npx skills add albertomarturelo/context-first-developmentDon’t feel like cloning? The repo ships a zero-install bootstrap prompt: paste it into your agent, it generates the scaffold and embeds the rules into CLAUDE.md so future sessions inherit the full workflow.
Fit
Who is it for?
- →Solo developers on non-trivial repos (100+ files).
- →Teams of 2–20 adopting agents in production.
- →Tech leads evaluating AI-assisted development at scale.
Not for: quick scripts, throwaway code, or “vibe coding” workflows.
Context first. Code second.
Open source, multi-model, and vendor-neutral. It’s plain Markdown: it works the same with Claude Code, Codex, GitHub Copilot, Gemini CLI, or Cursor.
Code MIT · Prose CC-BY-SA 4.0