Engineering Agent Context
Auditing an existing CLAUDE.md, Skill, or system prompt? Ask these questions for every rule you find:
- Is this rule true 100% of the time? If no, delete it and trust the model's judgment instead.
- Is this an example meant to teach tool usage? Replace it with a better-designed interface (clearer parameter names, enums, types) instead.
- Is this loaded upfront but rarely needed? Move it into a separate Skill file loaded on demand (progressive disclosure).
- Is this repeated in multiple places (system prompt + tool description + CLAUDE.md)? Keep it in exactly one place — prefer the tool/skill description closest to where it's used.
- Is this a "spec" written as prose? Consider replacing it with code, tests, or a runnable artifact instead.
If you answered "delete/move/replace" more than half the time, your context needs simplification.
Progress:
- Step 1: Inventory all context sources (system prompt, CLAUDE.md, Skills, tool descriptions, memory)
- Step 2: Flag contradictory or overly rigid rules ("never do X" / "always do Y")
- Step 3: Classify each rule: Universal truth / Contextual preference / Redundant / Example-only
- Step 4: Remove contextual preferences and examples that constrain more than they help
- Step 5: Redesign tools/interfaces to convey intent (enums, param names) instead of prose examples
- Step 6: Split long instructions into separate Skill files, referenced only when relevant
- Step 7: Replace prose specs with code, tests, prototypes, or rubrics where possible
- Step 8: Re-test behavior; confirm no regression before finalizing
| Old approach | New approach |
|---|---|
| Give Claude rigid rules | Let Claude use judgment; state defaults, not absolutes |
| Give examples of tool usage | Design expressive interfaces (enums, clear params) |
| Front-load all instructions | Use progressive disclosure; load Skills on demand |
| Repeat instructions in multiple places | State once, in the tool/skill description itself |
| Store memory manually in CLAUDE.md | Let automatic memory handle persistence |
| Simple markdown specs | Rich references: code, tests, prototypes, rubrics |
Example 1: Comment style rule Input: System prompt says "Never write docstrings with multiple paragraphs. No multi-line comment blocks. Max one short line." Output: Replace with "Write code that matches the surrounding style: comment density, naming, and tone should match the existing codebase." (Lets Claude adapt instead of applying a blanket rule that breaks on complex code.)
Example 2: Tool usage via examples
Input: Tool description includes 3 worked examples showing how to call a todo tool.
Output: Redesign the tool's status parameter as an enum (pending | in_progress | completed) with a constraint that only one item can be in_progress at a time. Remove the examples — the interface now communicates intent directly.
Example 3: CLAUDE.md bloat
Input: CLAUDE.md contains a 200-line section on "how to verify your code" mixed with repo overview.
Output: Move verification steps into a dedicated verification.skill.md file. CLAUDE.md keeps a one-line pointer: "For code verification steps, see the verification skill." Repo overview stays concise; details live in source code (e.g., a single monolithic types file) rather than being restated in prose.
Example 4: Spec as reference Input: A written paragraph describing a desired UI design. Output: Provide an HTML prototype or existing component code as the reference instead — richer, higher-fidelity, and in a language Claude already understands well.
- Trust judgment over restriction — only keep hard rules for genuinely universal, high-stakes cases (e.g., "never delete files without confirmation").
- Keep CLAUDE.md short — repo purpose + pointers to Skills/code, not exhaustive rules.
- Push detail into code and Skills, not prose — code is unambiguous and Claude already understands it well.
- One source of truth per instruction — don't restate the same guidance in system prompt, skill, and CLAUDE.md.
- Design tools to be self-explanatory — good parameter naming/typing beats usage examples.
- Use progressive disclosure aggressively — split long skills into multiple files; load only what's needed per task.
- Prefer rich references (code, tests, prototypes, rubrics) over plain-text specs whenever possible.
- Periodically re-audit — as models improve, previously-necessary constraints often become unnecessary friction.
- Don't hedge every instruction "just in case." Conflicting guidance (e.g., "add docs as appropriate" + "NEVER add comments") forces the model to reconcile contradictions instead of acting.
- Don't build a single giant knowledge repository assuming the model won't find info otherwise — this bloats context. Use a discoverable tree of files loaded at the right time instead.
- Don't over-supply examples for tool use — they narrow the model's exploration space rather than expanding it.
- Don't repeat the same instruction in system prompt and tool description — pick one location.
- Don't manually manage memory if automatic memory features are available — let the system persist relevant context.
- Don't assume older best practices still apply — re-validate constraints against current model capabilities before keeping them.