Context Engineering for Modern AI Agents: Less Instruction, Better Results
Modern AI agents often work better with fewer, clearer instructions.
This sounds counterintuitive. Older models needed detailed rules, repeated warnings, and examples for nearly every action. Newer models are better at reading a repository, understanding intent, and choosing an appropriate method. Too many instructions can now slow an agent down or create conflicts.
This article explains the idea in practical terms and shows how to improve the context supplied to a coding agent.
What is context engineering?
A prompt is the request you send now:
Add an endpoint that returns the current user.
Context is everything else the agent can see: system instructions, repository rules, skills, memory, source files, tool descriptions, tests, and design references.
Context engineering means organizing that information so the agent receives the right guidance at the right time.
The goal is not to provide the largest possible instruction file. The goal is to provide enough information for a good decision without burying the task under irrelevant rules.
1. Replace rigid rules with clear intent
Rigid rules may prevent obvious mistakes, but they also fail in legitimate special cases.
Too rigid:
Never add comments. Never create documentation files.
Better:
Match the surrounding code's naming, style, and comment density.
Create documentation only when the task requires it.
The second version explains the desired result and lets the agent use the repository as evidence.
Keep strict rules for actions where judgment is not enough: secrets, production data, destructive commands, legal requirements, and irreversible changes.
2. Design better tools instead of writing long examples
Examples can help, but they can also make an agent copy one path even when another path is better. A well-designed interface communicates its own rules.
Weak tool design:
update_task(task)
Clearer design:
update_task(
status: "pending" | "in_progress" | "completed",
summary: string
)
If only one task may be active, state that constraint once in the tool description. The agent then knows what values are valid and how the state should behave without reading several sample conversations.
3. Load detailed guidance only when needed
Do not put deployment, database migration, code review, UI writing, and incident-response instructions into one giant repository file.
Keep the root instructions short:
This is a Hugo site.
Run `hugo --gc --minify` before completing content or layout changes.
For migration work, read `docs/migration-guide.md`.
For release work, use the deployment skill.
This is called progressive disclosure: begin with a small map, then load the detailed guide that matches the current task.
A practical structure could be:
AGENTS.md
docs/
architecture.md
migration-guide.md
skills/
verify-site/
publish-release/
The agent sees the map immediately but spends context on a detailed file only when it becomes relevant.
4. Put instructions next to the tool they control
Repeating the same rule in the system prompt, repository guide, and tool description wastes space and creates a maintenance problem.
Prefer one authoritative location:
Tool: delete_preview
Description: Deletes a generated preview. Never use it for source content.
If the rule changes, you update one place. More importantly, the instruction appears exactly when the agent considers using that tool.
5. Use high-quality references
Sometimes a reference communicates the goal better than another paragraph of instructions.
Useful references include:
- a test suite that defines expected behavior;
- an existing API with the desired design;
- an HTML mockup of a page;
- a schema or type definition;
- a short rubric describing what “good” means.
For example, instead of writing “make the new card look like the rest of the site,” point to the existing card component and its tests. Code and structured artifacts are precise and easy for an agent to inspect.
A simple cleanup exercise
Review your agent instructions and classify every line:
- Essential rule — keep it, especially for safety or unusual project constraints.
- Obvious from the repository — remove it.
- Task-specific detail — move it to a skill or focused guide.
- Tool behavior — move it into that tool’s description.
- Duplicate or conflicting rule — keep one authoritative version.
Before:
Use TypeScript.
Always inspect existing files.
Never guess types.
Run tests.
Use the release checklist...
[150 more lines]
After:
Match the existing TypeScript architecture.
Do not edit generated files under `dist/`.
Run `npm test` for code changes.
Use `docs/release.md` only for releases.
The practical rule
Good context is small, relevant, and easy to find.
Give the agent a concise map of the project. Preserve strict constraints where failure is costly. Move specialist instructions into focused guides. Design tools with clear parameters. Provide real code, tests, or mockups when they express the target better than prose.
Modern agents need direction, but they do not need every decision made in advance.
Source: Thariq Shihipar, Anthropic — “The new rules of context engineering for Claude 5 generation models”.