Optimize Agent Context
Enforce the Band-Aid Philosophy: an agent context file should only contain rules that fix mistakes the agent is actively making. Everything else is bloat that degrades performance and increases cost.
Core Rules (Non-Negotiable)
- NO BLOAT — Never include directory structures, file trees, dependency lists, or package inventories. The agent has tools to discover these.
- NO SUMMARIES — Never include vague app descriptions ("This is a video sharing app"). This distracts the model and triggers hallucinations.
- ONLY FIX KNOWN FAILURES — Every line must correct a specific, observed agent mistake or enforce an architectural constraint the agent cannot guess.
- USE NEGATIVE CONSTRAINTS — When the agent uses the wrong tool/library, explicitly state what NOT to use, then what TO use.
- BE MINIMAL — Target under 20 lines. Bullet points preferred. If a rule can be removed without the agent breaking, remove it.
Why This Matters
Studies show bloated, AI-generated context files:
- Degrade agent performance by ~3%
- Increase token costs by 20%+
- Trigger hallucinations by surfacing legacy code the agent then tries to use ("pink elephants" effect)
Workflow
Mode A: Create New Agent File (Interview)
When the user wants to create a new context file from scratch:
- Ask these questions one at a time (do not dump all at once):
- "What specific mistakes has the AI agent been making repeatedly?" (e.g., wrong imports, forgetting to format, modifying wrong files) - "Are there legacy tools/libraries the agent keeps using but shouldn't?" (e.g., "We have Redux but use Zustand for new features") - "Any build/test/env quirks the agent can't figure out on its own?" (e.g., special env vars, non-standard test commands)
- Synthesize answers into a ruthlessly minimal bulleted markdown file.
- Validate the output against the Core Rules above. Strip anything that violates them.
- Present the file and ask: "Does this capture the mistakes? Anything to add or remove?"
Mode B: Audit Existing Agent File
When the user has an existing agent.md / claude.md / cursorrules and wants it optimized:
- Read the file using
view_file. - Classify every line into one of:
- ✅ KEEP — Fixes a known failure or states an ungessable constraint - ❌ BLOAT — Directory trees, dependency lists, file structures - ❌ SUMMARY — Vague app descriptions, project overviews - ❌ OBVIOUS — Things the agent can discover via tools (package.json, tsconfig, etc.) - ⚠️ MAYBE — Potentially useful but needs user confirmation
- Present the audit as a table showing each section and its classification.
- Generate the optimized version with only ✅ KEEP and confirmed ⚠️ MAYBE lines.
- Show before/after line count to demonstrate the reduction.
Mode C: Add a Band-Aid
When the user reports a specific agent mistake mid-session:
- Ask: "What did the agent do wrong?"
- Write a single, precise negative constraint:
Do NOT [wrong thing]. Instead, [correct thing]. - Suggest appending it to the existing context file.
Output Format
The generated file should follow this structure:
# Agent Rules
- [Negative constraint or correction]
- [Negative constraint or correction]
- [Build/test quirk]
- [Architectural constraint]No headers beyond the title. No explanations. No examples. Just rules.
Anti-Patterns to Reject
If the user or another agent tries to include any of these, push back:
| Anti-Pattern | Why It's Bad |
|---|---|
| Folder tree / file structure | Agent has list_dir and find_by_name |
| Dependency list | Agent reads package.json / requirements.txt |
| "This app is a..." summary | Distracts model, triggers hallucination |
| Tech stack overview | Agent reads config files |
| Code style rules already in linter config | Redundant — linter enforces these |
| Long code examples | Bloats context, agent writes its own code |