context-first-engineering

name	context-first-engineering
description	Use when working with AI coding agents on real codebases, facing context quality degradation, or needing the model to learn from existing code rather than rely on pretrained knowledge

Context-First Engineering

Overview

The model doesn't understand your codebase. It only understands what's in the context window.

LLMs are optimized for reasoning from pretrained knowledge. Real programming requires learning from your specific codebase—its patterns, conventions, constraints. This mismatch is the root cause of AI coding failures.

Core principle: Context quality > Context quantity. 40% utilized with precise information beats 100% filled with noise.

The Problem

What LLMs optimize for        What programming needs
        ↓                              ↓
 Pretrained knowledge         Codebase-specific context
 General reasoning            Project conventions
 Pattern matching             Architectural understanding
        ↓                              ↓
              MISMATCH → Wrong patterns, wasted tokens

Symptoms:

• Model suggests patterns absent from your codebase
• Repeated file searches consuming context
• "Works in greenfield, fails in brownfield"
• Context exhaustion before completion
• Model "forgets" what it learned

Context Quality Hierarchy

Priority	Problem	Impact
🔴 Critical	Incorrect information	Corrupts entire output
🟡 High	Missing information	Incomplete solutions
🟢 Medium	Excessive noise	Reduces reasoning capacity

What wastes context:

• Repeated grep/find operations
• Raw build/test logs
• Unstructured JSON
• Failed approach history

The Three Phases

RESEARCH ──→ PLANNING ──→ IMPLEMENTATION
    │            │              │
    ↓            ↓              ↓
Learn from   Surgical       Execute
codebase     precision      faithfully
    │            │              │
    ↓            ↓              ↓
[Human checkpoint]    [Human checkpoint]

Phase 1: Research

Purpose: Learn from codebase, not pretrained knowledge.

• Use fresh context (subagent) for exploration
• Target specific questions
• Output structured findings

## Findings: [Topic]

### Relevant Files

- `path/file.ts:L100-150` — [Why]

### Patterns Observed

- [Pattern] → [Where used]

### Constraints

- [Constraint] — [Evidence]

Phase 2: Planning

Purpose: Specify exact changes.

• Build on research (not assumptions)
• File-by-file changes
• Verification steps

## Plan: [Task]

### Changes

1. `path/file.ts`
   - L50: Add [code]
   - L80: Modify [change]

### Verification

- [ ] Tests pass
- [ ] Follows pattern from [reference]

Critical: Plans amplify mistakes. Human review here prevents cascading errors.

Phase 3: Implementation

Purpose: Execute faithfully.

• Sequential, not creative
• Verify after each change
• Compact progress

Anti-pattern: Deviating from plan. If wrong, revise plan explicitly.

Intentional Compaction

Target: 40-60% context utilization.

Before	After
500 lines grep output	5 file:line references
Full test log	Error + assertion
Entire file	Function + signature
Approach discussion	Decision in 2 sentences

When to compact:

• After research → Findings only
• After failure → Lesson learned only
• Before limit → Decisions, not process

File-Based State

.claude/context/{task}/
├── research.md    # Phase 1 findings
├── plan.md        # Phase 2 plan
├── progress.md    # Phase 3 state
└── learnings.md   # Survives task completion

Rule: Files capture conclusions, not conversations.

Quick Reference

Situation	Action
Starting task	Research first, never assume
Context filling	Compact findings, discard process
Wrong pattern suggested	Did model learn from codebase?
Implementation diverging	Stop, revise plan
Session ending	Export to files
Resuming	Read files, don't re-explore

Common Mistakes

Mistake	Fix
Skip research	Always research first
Fill to 100%	Target 40-60%
Keep failures in context	Compact to lesson
Explore in main context	Use subagent
Trust pretrained patterns	Verify against research
Improvise during implementation	Follow or revise plan

Leverage Hierarchy

Research errors  → 1000s wrong lines
Planning errors  → 100s wrong lines
Implementation   → Single line fixes

Invest human attention in research and planning.

Mental Model

Specification-driven development:

• Specs (research + plan) = source of truth
• Code = implementation artifact
• Model executes specs, not intentions