Agent Context Engineer

The Problem

Your CLAUDE.md is 500 lines long and costs 15K tokens per session to load. Your agent reads it all, then contradicts an architectural decision from January because that rule was buried on line 387. Or it starts a fresh session with zero context, asks you to re-explain the project, and burns 4 minutes of your time re-establishing what a 30-line session-state file could have provided instantly.

What You Get

• Three-layer context architecture: permanent project knowledge (CLAUDE.md under 200 lines), session state files, and real-time retrieval with search-driven targeted file reads
• CLIMB design protocol: Compress (remove anything not actionable), Layer (separate permanent from transient), Isolate (one purpose per file), Maintain (context files rot), Brief (ruthless editing for relevance)
• Anti-amnesia protocols: session-state file that the agent writes at session end and reads at session start, decision logs for architectural choices, and gotcha entries for recurring mistakes
• Context compression strategies: summarization instead of truncation, progressive disclosure (a 30-line CLAUDE.md plus targeted reads beats a 300-line dump), context rotation for long projects, and diff-only mode for continuation sessions (80-95% token savings)
• Cross-agent compatibility: CLAUDE.md for Claude Code, .cursorrules for Cursor, CODEX.md for Codex CLI, with symlink strategy for unified setup
• Context audit methodology: weekly checks for file size, relevance, accuracy against the current codebase, token budget consumption, and forgetting incident frequency

Why This Beats Prompting It Yourself

"Be more concise" doesn't fix a 500-line CLAUDE.md because you don't know which 300 lines to remove. "Remember our decisions" doesn't work because the agent has no structured mechanism to store or retrieve them. This skill provides the architectural framework — the layer separation, the compression strategies, the maintenance protocols — that turns generic advice into systematic infrastructure. The difference between a 15K-token context dump and a 2.5K-token precision context is engineering, not prompting.

Example Session

You: "My agent keeps forgetting decisions and burning tokens"

Agent: "Context audit results:

CLAUDE.md: 234 lines (over the 200-line limit)

• 47 lines of historical decisions from January: archive to .agent/sessions/
• 23 lines of code snippets: replace with file links
• 8 lines of vendor comparison narrative: cut, not actionable
• Target: 164 lines after cleanup

.agent/session-state.md: missing

• No session continuity: agent has zero memory between sessions
• Action: create it from the recent commit history and start tracking

Forgetting incidents this week: 3

• Used wrong ORM pattern (decided against June 15)
• Tried to add wrong auth library after team chose the current one (June 28)
• Used an approach explicitly rejected in ADR-003
• Action: add all three to the gotchas section

Recommended architecture: Layer 1 (CLAUDE.md): 87 lines of stack, conventions, key files, gotchas Layer 2 (session-state): current task, decisions, files, next steps Layer 3 (real-time): search-driven targeted lookups for specific symbols

Estimated token savings: 15K down to 2.5K per session start, an 83% reduction."

Use Cases

• Developers whose agents forget everything between sessions
• Teams standardizing context patterns across multiple agent tools (Claude Code and Cursor)
• Projects where token costs are a concern and context is bloated
• New project setup where you want good agent context architecture from day one
• Auditing existing CLAUDE.md or cursor rules that have grown unwieldy over months

Known Limitations

Context engineering is an ongoing practice, not a one-time fix — context files rot when the codebase changes and must be maintained. Session-state files may become stale if the agent crashes before writing them. Cross-agent symlink strategies assume all agents use the same context format; agent-specific features may need separate handling. The 200-line CLAUDE.md guideline is a starting point — some projects legitimately need more, but should be audited for actionability.