Development
Context Engineering
Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when configuring rules files.
Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when configuring rules files.
Feed agents the right information at the right time. Context is the single biggest lever for agent output quality.
┌─────────────────────────────────────┐
│ 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
└─────────────────────────────────────┘
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
Load the relevant spec section when starting a feature. Don't load the entire spec.
Before editing a file, read it. Before implementing a pattern, find an existing example.
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.
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]
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:
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?
| 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 |
After setting up context: