Context-First Development (CFD): A Methodology for AI-Assisted CLI Development

"The most expensive code an AI agent can write is code written without context."

Introduction: The Problem Nobody Wants to Admit

There's an elephant in the room of AI-assisted development. Every time you start a new session with your AI agent — whether it's Claude Code, Gemini CLI, or any terminal tool — you start from scratch. The model doesn't remember the architectural decisions you made yesterday. It doesn't know why you chose PostgreSQL over MongoDB. It doesn't understand that your team decided to use the Repository pattern for specific testability reasons.

The result is predictable: the agent generates technically correct but contextually incorrect code. And you end up spending more time correcting the model than writing the code yourself.

This problem scales in direct proportion to project size. In a 50-file project, the model can scan everything and understand the structure. In a 500-file project, scanning consumes tokens exponentially and the model starts losing coherence. In a 5,000-file project — where any serious production project lives — the model is essentially blind.

The solution isn't a model with more context. GPT-4 Turbo has 128K tokens. Claude has 200K. Gemini reaches 2M. And yet, the problem persists. Because the problem isn't context capacity — it's context quality.

This article proposes Context-First Development (CFD): a methodology for structuring code repositories so that AI agents can operate with persistent, accurate, and efficient context. It's not a framework. It's not a tool. It's a work discipline that transforms your repository into a living knowledge base that any agent can consume.

The Current Landscape: What Exists and Why It's Not Enough

Before proposing something new, let's understand what the industry has built so far.

CLAUDE.md and the First Generation of "Agent Instructions"

Anthropic introduced the concept of `CLAUDE.md` as an instruction file that Claude Code reads automatically when starting a session. The idea is simple: a Markdown file at the project root that tells the model how to behave.

Anthropic's official best practices recommend keeping the file between 100-200 lines and applying a strict rule: "For each line, ask yourself: would removing this cause Claude to make mistakes? If not, cut it."

The problem is that most CLAUDE.md files end up being lists of build and lint commands. An academic study from September 2025 analyzed 253 CLAUDE.md files from 242 repositories and found that 77.1% only contained Build/Run instructions, 71.9% implementation details, and a mere 8.7% mentioned security. The industry is using the most powerful context file available to do what a Makefile already did.

AGENTS.md: The Standardization Attempt

In July 2025, Sourcegraph's Amp team launched AGENTS.md — an open format designed to be a "README for agents" that works with any tool: OpenAI Codex, Google Jules, Cursor, Aider, Gemini CLI. By February 2026, over 40,000 open source repositories had adopted it.

AGENTS.md proposes one file per directory level (ideal for monorepos), with a recommended limit of 150 lines and content oriented toward: project description, architecture, commands, conventions, and navigation hints.

It's a good step toward interoperability, but it suffers from the same fundamental problem: it's a static file that doesn't scale with project complexity.

Cole Medin's Template: Practical Context Engineering

Cole Medin published a template repository that goes a step further. Its structure includes:

`CLAUDE.md` with project rules
`.claude/commands/` with custom slash commands
`examples/` with patterns for the model to follow
`PRPs/` (Product Requirements Prompts) — specifications the model executes

This approach is significantly more sophisticated because it introduces the idea of commands as workflow and examples as context. But it remains a template that each team must adapt without a clear methodology for when and how to evolve each piece.

Spotify: 1,500 PRs in Production with Claude Code

Spotify published a three-part series in November-December 2025 documenting their experience with coding agents in production. Key findings:

Claude Code was their top-performing agent
They executed ~50 automated migrations
Over 1,500 AI-generated PRs merged
Critical discovery: Claude Code works better with end-state descriptions rather than step-by-step instructions

This last point is fundamental and we'll incorporate it into CFD: context should describe the "what" and "why", not the "how".

ADRs: The Missing Piece

Chris Swan wrote in July 2025 about the connection between Architecture Decision Records and AI agents. His central argument: ADRs provide structured, natural-language context that is inherently LLM-friendly. Each documented decision includes context, evaluated alternatives, consequences, and status — exactly what a model needs to understand why the code is the way it is.

Josh Rotenberg published a complete ADR system designed specifically for Claude integration. Piethein Strengholt built an agent that automates ADR creation. But nobody has integrated ADRs as the central piece of an AI development methodology.

Addy Osmani: The "Specs First" Workflow

Addy Osmani, engineering lead at Google Chrome, proposed a workflow that can be summarized as: specs first, then plan, then code. He also coined the 70/30 rule: AI completes ~70% of the task, but the last 30% (edge cases, production readiness) requires human expertise.

The Academic Research

Three fundamental papers from 2025:

"On the Use of Agentic Coding Manifests" (arXiv:2509.14744) — Empirical analysis of 253 CLAUDE.md files.
"Agent READMEs: An Empirical Study" (arXiv:2511.12884) — 2,303 context files from 1,925 repositories. Conclusion: these files are "not static documentation but complex, difficult-to-read artifacts that evolve like configuration code."
"Context Engineering for Multi-Agent LLM Code Assistants" (arXiv:2508.08322) — Proposes multi-agent architectures with semantic retrieval.

What's Missing

All of the above are valuable pieces of a puzzle that nobody has assembled. There are configuration files. There are templates. There are case studies. There are academic papers. But there is no cohesive, CLI-first methodology that an individual developer or small team can adopt tomorrow and that scales from a 10-file project to a 10,000-file one.

That's Context-First Development.

Context-First Development: The Six Principles

CFD is built on six non-negotiable principles. These aren't suggestions — they're design constraints.

Principle 1: Context Before Code

Before writing the first line of code in any session with an AI agent, context must be resolved. This means the model must be able to answer these questions without scanning source code:

What is the project's architecture?
What decisions have been made and why?
What conventions are followed?
What is the current state of work in progress?

If the model needs to read 50 files to answer any of these questions, your context is broken.

Principle 2: Single Source of Truth (SSOT)

Every piece of project knowledge must exist in exactly one place. If the architecture is documented in CLAUDE.md, in an ADR, in a README, and in code comments, you have four sources that will inevitably desynchronize. The model won't know which to trust.

CFD defines a clear hierarchy: the root file (CLAUDE.md or AGENTS.md) is an index that references specialized documents. It never duplicates content.

Principle 3: Hierarchical Context Architecture

Context is organized in layers, from most general to most specific:

1Level 0: Root file (CLAUDE.md / AGENTS.md)        → ~100-150 lines
2Level 1: Domain documents (docs/)                   → Architecture, stack, conventions
3Level 2: Decisions (docs/decisions/)                 → Individual ADRs
4Level 3: Module context (CLAUDE.md per folder)       → Area-specific instructions

The model only needs to read Level 0 to orient itself. It dives into lower levels when the task requires it. This minimizes token consumption per session.

Principle 4: Decisions as First-Class Citizens

Every significant technical decision is documented in an ADR (Architecture Decision Record) with a strict format:

1# ADR-NNN: Decision Title
2
3## Status
4Accepted | Superseded by ADR-XXX | Deprecated
5
6## Context
7What is the issue that we're seeing that is motivating this decision?
8
9## Decision
10What is the change that we're actually doing?
11
12## Alternatives Considered
13What other options were evaluated and why were they rejected?
14
15## Consequences
16What becomes easier or more difficult to do because of this change?

This isn't bureaucracy — it's persistent memory. When you start a new session and the model reads `docs/decisions/007-use-repository-pattern.md`, it instantly understands why the code is structured that way. Without the ADR, the model might suggest refactoring toward a different pattern, wasting your time and its tokens.

Principle 5: English as Context Language

All technical context is written in English. This isn't elitism — it's token efficiency.

LLM tokenizers (both Anthropic's and Google's) are optimized for English. The same information in Spanish can consume 20-40% more tokens than in English. In a context file that's loaded in every session, that adds up quickly.

Practical rule: code, file names, ADRs, context documents, and CLAUDE.md are written in English. PR comments and team communication can be in the team's language.

Principle 6: Automation Through Slash Commands

Repetitive context maintenance tasks are automated through custom slash commands. You don't depend on someone "remembering" to update a document — the agent itself executes commands that generate and update context.

Examples of commands that CFD defines:

`/project:init` — Initialize the context structure in an existing project
`/project:status` — Generate a summary of the current project state
`/decision:new` — Create a new ADR from a discussion
`/context:validate` — Verify that context is complete and consistent
`/session:start` — Session start routine with context loading

The Knowledge Architecture: Directory Structure

A project following CFD has the following context structure (coexisting with source code):

1project-root/
2├── CLAUDE.md                          # Root context file (Level 0)
3├── docs/
4│   ├── ARCHITECTURE.md                # Architecture overview
5│   ├── STACK.md                       # Tech stack and versions
6│   ├── CONVENTIONS.md                 # Code conventions and style
7│   ├── CURRENT_STATUS.md              # Current project status (WIP)
8│   └── decisions/
9│       ├── _index.md                  # Decision index with status
10│       ├── 001-initial-architecture.md
11│       ├── 002-database-selection.md
12│       ├── 003-auth-strategy.md
13│       └── ...
14├── .claude/
15│   └── commands/
16│       ├── init.md                    # /project:init
17│       ├── status.md                  # /project:status
18│       ├── new-decision.md            # /decision:new
19│       ├── validate-context.md        # /context:validate
20│       └── start-session.md           # /session:start
21└── src/                               # (or lib/, app/, etc.)
22    ├── feature-a/
23    │   └── CLAUDE.md                  # Module-specific context
24    ├── feature-b/
25    │   └── CLAUDE.md
26    └── ...

The Root File: CLAUDE.md

This is the entry point. The model reads it automatically when starting a session. It should be a map, not an encyclopedia.

1# Project: [project-name]
2
3## What This Project Does
4[2-3 sentences. What problem does it solve? Who uses it?]
5
6## Architecture
7@docs/ARCHITECTURE.md
8
9## Tech Stack
10@docs/STACK.md
11
12## Conventions
13@docs/CONVENTIONS.md
14
15## Current Status
16@docs/CURRENT_STATUS.md
17
18## Key Decisions
19@docs/decisions/_index.md
20
21## Build & Run
22- Install: `[command]`
23- Dev: `[command]`
24- Test: `[command]`
25- Lint: `[command]`
26
27## Critical Rules
28- [Rule 1: e.g., "Never modify the migration files directly"]
29- [Rule 2: e.g., "All API endpoints must have integration tests"]
30- [Rule 3: e.g., "Use the repository pattern for data access"]

The `@docs/ARCHITECTURE.md` syntax is a reference that Claude Code resolves automatically. This keeps the root file compact while allowing depth exploration.

ARCHITECTURE.md

1# Architecture Overview
2
3## System Diagram
4[ASCII diagram or reference to an image in assets/]
5
6## Layer Structure
7- **Presentation**: [framework, patterns]
8- **Domain**: [business logic organization]
9- **Data**: [persistence strategy, repositories]
10
11## Module Map
12| Module | Purpose | Key Files |
13|--------|---------|-----------|
14| auth   | Authentication & authorization | src/auth/ |
15| users  | User management CRUD | src/users/ |
16| ...    | ... | ... |
17
18## Data Flow
19[Description of how data flows through the system]
20
21## External Dependencies
22| Service | Purpose | Docs |
23|---------|---------|------|
24| Stripe  | Payments | [link] |
25| ...     | ...      | ...    |

CURRENT_STATUS.md

This file is dynamic. It's updated at the end of every work session. It's the first thing the model reads (via the reference in CLAUDE.md) to know what was happening.

1# Current Project Status
2
3Last updated: 2026-02-19
4
5## In Progress
6- [ ] Implementing user profile API (#142)
7  - Endpoint created, missing validation tests
8  - Blocked by: Decision on email validation strategy (see ADR-015)
9
10## Recently Completed
11- [x] Database migration for user preferences (#138)
12- [x] Auth middleware refactor (#135)
13
14## Known Issues
15- Performance degradation in search endpoint when > 1000 results
16- Flaky test in auth.integration.test (timing issue)
17
18## Next Priorities
191. Complete user profile API
202. Address search performance issue
213. Begin notification system (ADR pending)

The Decision Index: decisions/_index.md

1# Architecture Decision Records
2
3| ID | Title | Status | Date |
4|----|-------|--------|------|
5| 001 | [Initial architecture](001-initial-architecture.md) | Accepted | 2026-01-15 |
6| 002 | [Use PostgreSQL](002-database-selection.md) | Accepted | 2026-01-16 |
7| 003 | [JWT auth strategy](003-auth-strategy.md) | Superseded by 004 | 2026-01-20 |
8| 004 | [Switch to session auth](004-session-auth.md) | Accepted | 2026-02-10 |

The Daily Routine: The CFD Workflow

This is the practical part. CFD defines a daily routine with three clear phases.

Phase 1: Session Start (2-3 minutes)

Every work session with the agent begins with a context ritual. This is not optional.

1# 1. Sync with the remote repository
2gh repo sync
3
4# 2. Review project state (PRs, issues)
5gh pr list --state open
6gh issue list --label "in-progress"
7
8# 3. Start a session with Claude Code
9claude
10
11# 4. Inside Claude, run the start routine
12> /project:status

The slash command `/project:status` is defined in `.claude/commands/status.md`:

1Review the current project status by reading the following files in order:
21. docs/CURRENT_STATUS.md - What's in progress and what's blocked
32. docs/decisions/_index.md - Recent decisions that might affect current work
4
5Then provide a brief summary of:
6- What was being worked on
7- What's blocked and why
8- What should be the focus of this session
9
10Do NOT read source code files unless specifically needed to answer the above.

This command consumes ~500-800 tokens instead of the 10,000-50,000 that scanning source code would cost. That's the difference between a sustainable workflow and one that burns through your API budget.

Phase 2: Development (the main cycle)

During development, the flow follows a disciplined pattern:

Before implementing: Clarify and decide

1# If a significant technical decision arises
2> /decision:new

The command `/decision:new` in `.claude/commands/new-decision.md`:

1I need to document a new architectural decision. Guide me through the following:
2
31. Ask me what decision needs to be made
42. Help me articulate the context (what problem are we solving?)
53. Propose 2-3 alternatives with pros/cons
64. Once I choose, generate a new ADR file in docs/decisions/ following this format:

1# ADR-[next number]: [Title]
2
3## Status
4Accepted
5
6## Date
7[today's date]
8
9## Context
10[What I described]
11
12## Decision
13[What was chosen]
14
15## Alternatives Considered
16[The alternatives we discussed]
17
18## Consequences
19[What changes as a result]

Then update docs/decisions/_index.md with the new entry.

During implementation: Work in atomic blocks

CFD recommends implementation sessions focused on one atomic task at a time. This isn't basic productivity — it's context management. An AI agent works better when it has a clear, scoped instruction than when it has a list of 10 things to do.

1# Bad: vague instruction that scatters context
2> "Implement the notification system"
3
4# Good: atomic instruction with explicit context
5> "Create the notification repository interface in src/notifications/domain/.
6   Follow the repository pattern we use (see ADR-001).
7   Look at src/users/domain/user_repository for reference."

When the agent gets it wrong: Don't correct — document

One of the most common mistakes when working with AI agents is manually correcting code without updating context. If the model generates something incorrect, it will likely do it again in the next session because the context doesn't say it's incorrect.

1# The model generates a singleton where it should use dependency injection
2
3# Bad: you fix the code manually and move on
4
5# Good: you document the convention
6> "That's incorrect. We use dependency injection, never singletons.
7   Please fix the code AND add this rule to docs/CONVENTIONS.md
8   under the 'Patterns' section."

Now the convention is persisted. Next session, the model reads it automatically.

Phase 3: Session Close (3-5 minutes)

Before closing the session, the agent updates the project status. This is non-negotiable in CFD.

1# Update project status
2> Update docs/CURRENT_STATUS.md with what was accomplished in this session,
3  what's still pending, and any blockers discovered. Keep the same format.
4
5# If there are changes to commit
6> /commit  # or manually:
7gh pr create --title "feat: notification repository" --body "..."

The session close produces a diff in `CURRENT_STATUS.md` that is essentially a session log. This creates natural traceability:

1# View project evolution over time
2git log --oneline -- docs/CURRENT_STATUS.md

GitHub CLI Integration: The Complete Flow

GitHub CLI (`gh`) is a fundamental piece of CFD because it connects repository context with the team workflow.

Issues as Work Units

1# Create an issue with full context
2gh issue create \
3  --title "Implement notification repository" \
4  --body "## Context
5See ADR-012 for the notification system decision.
6
7## Acceptance Criteria
8- [ ] NotificationRepository interface in domain layer
9- [ ] PostgreSQL implementation in data layer
10- [ ] Unit tests for repository implementation
11- [ ] Integration test with test database
12
13## References
14- ADR-012: docs/decisions/012-notification-system.md
15- Pattern reference: src/users/domain/user_repository" \
16  --label "feature,notifications"

When starting a session to work on this issue:

1# View the issue with all its context
2gh issue view 42
3
4# Inside Claude Code, link the session to the issue
5> I'm working on issue #42. Read the issue description with
6  `gh issue view 42` and the referenced ADR before starting.

Pull Requests with Traceable Context

1# Create a PR that references decisions and context
2gh pr create \
3  --title "feat(notifications): add notification repository" \
4  --body "## Summary
5Implements the notification repository following ADR-012.
6
7## Changes
8- Added NotificationRepository interface
9- Added PostgresNotificationRepository implementation
10- Added unit and integration tests
11
12## Decision References
13- ADR-012: Notification system architecture
14- ADR-001: Repository pattern convention
15
16## Testing
17\`\`\`bash
18npm test -- --grep notification
19\`\`\`"

Context-Assisted Code Review

When reviewing a PR from another team member (or from an agent):

1# View the PR with its context
2gh pr view 87
3
4# Inside Claude Code, review with project context
5> Review PR #87. Read the PR description first, then check:
6  1. Does it follow our conventions in docs/CONVENTIONS.md?
7  2. Is it consistent with the referenced ADRs?
8  3. Are there missing tests per our testing standards?
9  Use `gh pr diff 87` to see the changes.

Automation with GitHub Actions

CFD recommends a validation workflow that checks context integrity:

1# .github/workflows/context-validation.yml
2name: Context Validation
3on:
4  pull_request:
5    paths:
6      - 'src/**'
7      - 'docs/**'
8      - 'CLAUDE.md'
9
10jobs:
11  validate-context:
12    runs-on: ubuntu-latest
13    steps:
14      - uses: actions/checkout@v4
15
16      - name: Check CURRENT_STATUS is updated
17        run: |
18          if git diff origin/main --name-only | grep -q "^src/"; then
19            if ! git diff origin/main --name-only | grep -q "docs/CURRENT_STATUS.md"; then
20              echo "::warning::Source code changed but CURRENT_STATUS.md was not updated"
21            fi
22          fi
23
24      - name: Validate ADR index
25        run: |
26          # Check that all ADR files are listed in the index
27          for adr in docs/decisions/[0-9]*.md; do
28            filename=$(basename "$adr")
29            if ! grep -q "$filename" docs/decisions/_index.md; then
30              echo "::error::ADR $filename is not listed in _index.md"
31              exit 1
32            fi
33          done

Anti-Patterns: What CFD Explicitly Forbids

A methodology is defined not only by what it recommends — but by what it forbids.

Anti-pattern 1: The Monolithic CLAUDE.md

1# ❌ BAD: Everything in a 500-line file
2# CLAUDE.md containing architecture, conventions, decisions,
3# project status, and a novel about the code's history

If your CLAUDE.md has more than 150 lines, it's already broken. Use `@references`.

Anti-pattern 2: Duplicated Context

1# ❌ BAD: Same information in three places
2# CLAUDE.md says "we use PostgreSQL"
3# docs/ARCHITECTURE.md says "the database is PostgreSQL"
4# docs/decisions/002.md says "we chose PostgreSQL"
5
6# ✅ GOOD: Single source, cross-references
7# CLAUDE.md: @docs/STACK.md
8# docs/STACK.md: "Database: PostgreSQL 16 (see ADR-002)"
9# docs/decisions/002.md: [source of truth with full context]

Anti-pattern 3: Documentation in Native Language

1# ❌ BAD: Context in Spanish
2## Arquitectura
3La aplicación utiliza una arquitectura de capas separadas...
4# Consumes ~30% more tokens than the English equivalent
5
6# ✅ GOOD: Context in English
7## Architecture
8The application uses a layered architecture...

Articles, PRs, and team communication can be in any language. Technical context consumed by the model should be in English.

Anti-pattern 4: Scanning Code Instead of Reading Context

1# ❌ BAD: Prompt that forces scanning
2> "Read all files in src/ and tell me how the project is structured"
3# Cost: 10,000-50,000+ tokens
4
5# ✅ GOOD: Prompt that uses existing context
6> "Read docs/ARCHITECTURE.md and summarize the project structure"
7# Cost: 500-1,500 tokens

Anti-pattern 5: Implicit Decisions

1# ❌ BAD: Decision made in a conversation that gets lost
2"Let's just use Redis for caching" → implemented → session ends →
3next session doesn't know why Redis is there
4
5# ✅ GOOD: Decision documented before implementing
6> /decision:new
7→ ADR-015: Use Redis for caching
8→ Recorded in docs/decisions/
9→ Next session reads the ADR automatically

Anti-pattern 6: Not Closing the Session

The most common and most costly mistake. If you don't update `CURRENT_STATUS.md` at the end of the session, the next session starts without knowing what was done. It's the equivalent of not committing — work that exists but is invisible.

Scaling CFD: From Individual to Team

For an Individual Developer

The minimum CFD implementation for a solo developer:

1CLAUDE.md                     # Root file (required)
2docs/
3  ARCHITECTURE.md             # Overview (required)
4  CURRENT_STATUS.md           # Current status (required)
5  decisions/
6    _index.md                 # Decision index (required)
7.claude/
8  commands/
9    start-session.md          # Session start (recommended)
10    new-decision.md           # New decision (recommended)

Setup time: ~30 minutes with `/project:init`. Daily overhead: ~5-8 minutes (session start + close). ROI: pays for itself after 3-4 work sessions.

For a Team

In a team, CFD extends with:

1docs/
2  TEAM_CONVENTIONS.md         # Team conventions
3  ONBOARDING.md               # Guide for new members (and new agents)
4  decisions/
5    TEMPLATE.md               # ADR template for consistency

Additional team rules:

ADRs require review — like code, decisions are reviewed in PRs.
CURRENT_STATUS.md is updated in the PR — not in a separate commit.
Slash commands are shared — `.claude/commands/` lives in the repository.
Each member can have local preferences — `~/.claude/CLAUDE.md` for personal configuration that doesn't affect the team.

For Monorepos

In monorepos, CFD leverages the hierarchical nature of context:

1CLAUDE.md                     # Global monorepo context
2docs/                         # Global documentation
3packages/
4  service-a/
5    CLAUDE.md                 # service-a specific context
6    docs/                     # Specific docs
7  service-b/
8    CLAUDE.md                 # service-b specific context
9    docs/                     # Specific docs

The model reads the nearest CLAUDE.md to the current working directory, with inheritance from the parent level.

Metrics: How to Know if CFD is Working

CFD is not dogma — it's a measurable practice. These are the metrics that matter:

Tokens Per Productive Session

Measure how many tokens an average session consumes. With well-implemented CFD, you should see:

Session start: 500-1,500 tokens (context reading)
Productive session: 5,000-15,000 tokens (actual work)
Session close: 500-1,000 tokens (status update)

Without CFD, session start alone can consume 20,000-50,000 tokens just scanning code.

Time to First Correct Action

How many minutes pass from session start until the agent produces correct code (that doesn't need manual correction)? With CFD, it should be < 5 minutes. Without context, it can be 15-30 minutes of back-and-forth.

Re-explanation Rate

How often do you have to explain to the model something that was already discussed in a previous session? If you're constantly re-explaining decisions, the context is incomplete.

CURRENT_STATUS.md Freshness

1# How many commits ago was it last updated?
2git log -1 --format="%ar" -- docs/CURRENT_STATUS.md

If the answer is "more than 1 working day ago", the context is stale.

Complementary Tools

Repomix: For When You Need Total Context

Repomix packages entire codebases into a single AI-optimized file. It's useful for:

Generating the initial `ARCHITECTURE.md`
Full project audits
Technology migrations

1# Generate a project snapshot (excluding context docs)
2npx repomix --ignore "docs/,node_modules/,.claude/"

Don't use it every session — it's the "nuclear context" tool for when you need the model to understand everything.

GitHub CLI: The Glue

Already covered in detail, but to summarize the essential `gh` commands in a CFD flow:

1gh issue list                  # View pending work
2gh issue view <n>              # Task context
3gh pr list                     # View open PRs
4gh pr create                   # Create PR with context
5gh pr diff <n>                 # View PR changes
6gh pr review <n>               # Review a PR
7gh repo sync                   # Sync with remote

Case Study: Implementing CFD in an Existing Project

Let's see how CFD is implemented in a project that already has code. We're not starting from zero — we have a project with 200+ files, 6 months of history, and zero context documentation.

Step 1: Initialization (30 minutes)

1# Start Claude Code in the project
2claude
3
4# Run initialization
5> I want to implement Context-First Development (CFD) in this project.
6  Analyze the directory structure (do NOT read individual files) and:
7  1. Create docs/ARCHITECTURE.md based on the directory structure and
8     dependency files (package.json, pubspec.yaml, etc.)
9  2. Create docs/STACK.md listing all technologies and their versions
10  3. Create docs/CONVENTIONS.md — infer 5-10 key conventions from
11     the project structure
12  4. Create docs/CURRENT_STATUS.md — initialize with "Project initialized
13     with CFD"
14  5. Create docs/decisions/_index.md — empty index
15  6. Create docs/decisions/001-initial-architecture.md documenting
16     the current architecture as the first ADR
17  7. Update CLAUDE.md to reference all docs/ files

Step 2: Document Existing Decisions (1-2 hours, distributed)

You don't need to document everything at once. Each time you work on an area of the code and discover an implicit decision:

1> I see we're using [pattern X] in this module.
2  Let's document this as an ADR. /decision:new

After 2-3 weeks of normal work, you'll have 10-15 ADRs that capture the project's most important decisions.

Step 3: Establish the Routine (permanent)

From here, the flow is:

1Session start → /session:start → Work → /decision:new (if applicable) → Close → Update CURRENT_STATUS.md

Conclusion: Context Is the Competitive Advantage

There's a dangerous illusion in the industry: that increasingly larger AI models will solve the context problem. They won't. A model with a 2 million token context window isn't more useful if you feed it 2 million tokens of noise.

The competitive advantage isn't in the model — it's in the context you provide. A developer with a well-documented project using Claude 3.5 Sonnet will consistently outperform a developer with zero context using Claude Opus. Context multiplies the model's capability; it's not a substitute for it.

Context-First Development is not a revolutionary framework. It's the disciplined application of principles that good engineers already know — clear documentation, explicit decisions, shared state — adapted to a world where your programming partner has amnesia at the start of every session.

The question isn't whether you need a methodology like CFD. The question is how many more sessions you'll waste re-explaining the same decisions before adopting one.

References

Anthropic. "Effective Context Engineering for AI Agents." anthropic.com, 2025.
Anthropic. "Claude Code Best Practices." code.claude.com, 2025.
Sourcegraph Amp Team. "AGENTS.md: A Standard for AI Agent Instructions." agents.md, 2025.
Medin, Cole. "Context Engineering Intro." GitHub, 2025.
Osmani, Addy. "My LLM Coding Workflow Going into 2026." addyosmani.com, 2025.
Osmani, Addy. "The AI-Native Software Engineer." Substack, 2025.
Spotify Engineering. "1,500+ PRs Later: Spotify's Journey with Our Background Coding Agent." engineering.atspotify.com, 2025.
Spotify Engineering. "Context Engineering: Background Coding Agents Part 2." engineering.atspotify.com, 2025.
Swan, Chris. "Using Architecture Decision Records (ADRs) with AI Coding Assistants." blog.thestateofme.com, 2025.
Rotenberg, Josh. "Claude ADR System Guide." GitHub Gist, 2025.
Strengholt, Piethein. "Building an Architecture Decision Record Writer Agent." Medium, 2025.
Chatlatanagulchai et al. "On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code." arXiv:2509.14744, 2025.
"Agent READMEs: An Empirical Study of Context Files for Agentic Coding." arXiv:2511.12884, 2025.
"Context Engineering for Multi-Agent LLM Code Assistants." arXiv:2508.08322, 2025.
Grandau, Mark. "Turning AI Code Reviews Into Continuous Improvement." Medium, 2025.
GitHub. "Agentic Workflows." github.github.io/gh-aw, 2026.
Steinberger, Peter. "agent-rules." GitHub, 2025 (archived).
Li, Bojie. "Claude's Context Engineering Secrets." 01.me, 2025.