optimize-agent-context

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)

1. NO BLOAT — Never include directory structures, file trees, dependency lists, or package inventories. The agent has tools to discover these.
2. NO SUMMARIES — Never include vague app descriptions ("This is a video sharing app"). This distracts the model and triggers hallucinations.
3. ONLY FIX KNOWN FAILURES — Every line must correct a specific, observed agent mistake or enforce an architectural constraint the agent cannot guess.
4. USE NEGATIVE CONSTRAINTS — When the agent uses the wrong tool/library, explicitly state what NOT to use, then what TO use.
5. 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:

1. 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)

2. Synthesize answers into a ruthlessly minimal bulleted markdown file.

3. Validate the output against the Core Rules above. Strip anything that violates them.

4. Present the file and ask: "Does this capture the mistakes? Anything to add or remove?"