Context Engineering

Feed agents the right information at the right time. Context is the single biggest lever for agent output quality.

When to Use

• Starting a new coding session
• Agent output quality is declining
• Switching between different parts of a codebase
• Setting up a new project for AI-assisted development
• The agent is not following project conventions

The Context Hierarchy

┌─────────────────────────────────────┐
│  1. Rules Files (CLAUDE.md, etc.)   │ ← Always loaded, project-wide
├─────────────────────────────────────┤
│  2. Spec / Architecture Docs        │ ← Loaded per feature/session
├─────────────────────────────────────┤
│  3. Relevant Source Files            │ ← Loaded per task
├─────────────────────────────────────┤
│  4. Error Output / Test Results      │ ← Loaded per iteration
├─────────────────────────────────────┤
│  5. Conversation History             │ ← Accumulates, compacts
└─────────────────────────────────────┘

Level 1: Rules Files

Create a rules file that persists across sessions:

# Project: [Name]

## Tech Stack
- React 18, TypeScript 5, Vite, Tailwind CSS 4
- Node.js 22, Express, PostgreSQL, Prisma

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint --fix`
- Dev: `npm run dev`

## Code Conventions
- Functional components with hooks
- Named exports (no default exports)
- Colocate tests next to source
- Use `cn()` utility for conditional classNames

## Boundaries
- Never commit .env files or secrets
- Never add dependencies without checking bundle size
- Ask before modifying database schema
- Always run tests before committing

Level 2: Specs and Architecture

Load the relevant spec section when starting a feature. Don't load the entire spec.

Level 3: Relevant Source Files

Before editing a file, read it. Before implementing a pattern, find an existing example.

Level 4: Error Output

When tests fail, feed the specific error back to the agent:

Effective: "The test failed with: TypeError: Cannot read property 'id' of undefined at UserService.ts:42"

Wasteful: Pasting the entire 500-line test output.

Level 5: Conversation Management

• Start fresh sessions when switching between major features
• Summarize progress when context is getting long
• Compact deliberately before critical work

Context Packing Strategies

The Brain Dump

At session start, provide everything the agent needs:

PROJECT CONTEXT:
- We're building [X] using [tech stack]
- The relevant spec section is: [spec excerpt]
- Key constraints: [list]
- Files involved: [list with brief descriptions]
- Known gotchas: [list]

The Selective Include

Only include what's relevant to the current task:

TASK: Add email validation to the registration endpoint

RELEVANT FILES:
- src/routes/auth.ts (the endpoint to modify)
- src/lib/validation.ts (existing validation utilities)
- tests/routes/auth.test.ts (existing tests to extend)

PATTERN TO FOLLOW:
- See how phone validation works in src/lib/validation.ts:45-60

CONSTRAINT:
- Must use the existing ValidationError class

Confusion Management

When Context Conflicts

CONFUSION:
The spec calls for REST endpoints, but the existing codebase uses GraphQL
for user queries (src/graphql/user.ts).

Options:
A) Follow the spec — add REST endpoint
B) Follow existing patterns — use GraphQL
C) Ask — this seems like an intentional decision

→ Which approach should I take?

When Requirements Are Incomplete

1. Check existing code for precedent
2. If no precedent exists, stop and ask
3. Don't invent requirements

Anti-Patterns

Anti-Pattern	Problem	Fix
Context starvation	Agent invents APIs, ignores conventions	Load rules file + relevant source files
Context flooding	Agent loses focus with >5,000 lines	Include only task-relevant context
Stale context	Agent references outdated patterns	Start fresh sessions when context drifts
Missing examples	Agent invents a new style	Include one example of the pattern
Implicit knowledge	Agent doesn't know project rules	Write it down in rules files

Verification

After setting up context:

• Rules file exists and covers tech stack, commands, conventions
• Agent output follows the patterns in the rules file
• Agent references actual project files and APIs
• Context is refreshed when switching between major tasks