What is an Agent Context File
An agent context file is a configuration file (e.g., CLAUDE.md, AGENTS.md) that loads automatically into the agent's context at the start of every conversation.
Think of it as an onboarding document: instead of re-explaining your codebase structure every session, the agent reads it once and applies that knowledge throughout the conversation.
Why use it
AI agents are stateless so each session starts fresh. Without a context file, agents waste time rediscovering your project structure, conventions, and workflow every single time.
What to include
Your context file should answer three questions:
| Section | What to Include | Example |
|---|---|---|
| WHAT | Project structure, tech stack, folder organization | "Monorepo: /apps contains services, /libs has shared libraries" |
| WHY | Project purpose, architectural decisions | "We use event sourcing for audit compliance requirements" |
| HOW | Development workflows, build commands, testing approach | "Run bun test (not npm test), use gh pr create for PRs" |
What to avoid
Less instruction is more. LLMs can follow ~150-200 instructions consistently, but agent system prompts already use ~50 slots.
| Don't Include | Do Include |
|---|---|
| Code style rules | Use linters and formatters |
| Auto-generated content from init commands | Hand-crafted, deliberate instructions |
| Code snippets that will become outdated | File:line pointers to authoritative sources |
| Instructions only relevant to specific tasks | Information applicable across all sessions |
| Exhaustive documentation that belongs elsewhere | High-level structure and critical deviations |
Structure recommendations
Progressive disclosure
Don't cram everything into one file. Create task-specific docs and list them in your context file:
/
├── CLAUDE.md # Core (< 300 lines)
├── docs/
│ ├── building.md
│ ├── testing.md
│ └── deployment.mdThe agent reads them as needed.
Note: Consider the usage of a
skillfor specific documentation steps.
Use pointers, not copies
Don't duplicate code, reference it:
<!-- DO --> API routes: see `src/api/example.ts:15-30`
<!-- DO NOT --> API routes follow this pattern: [code snippet]Tips
- Target length: Under 300 lines (best: under 60)
- Universal applicability: If it doesn't apply to most tasks, move it elsewhere
- No style enforcement: Use linters/hooks instead
- Update regularly: Keep it in sync with your codebase
Remember: This is an onboarding tool, not comprehensive documentation.
Platform-specific names
Different AI tools use different conventions:
| Platform | Context File Location |
|---|---|
| Claude Code | CLAUDE.md (root directory) |
| GitHub Copilot CLI | AGENTS.md or .github/copilot-instructions.md or CLAUDE.md |
| Generic | AGENTS.md |