Context Engineering: Optimizing AI Agent Tasks for First-Try Success

The Anatomy of a Perfect AI Agent Task

John Young outlines a framework for context engineering to maximize AI coding agent efficiency. Frontier LLMs typically suffer performance degradation after processing more than 150–200 instructions.

Why This Matters

In technical reality, more context is not always better; every irrelevant detail dilutes the signal for the agent. Studies on ‘Context Rot’ (Hong et al., 2025) show that model attention to input grows non-uniformly and degrades as length increases, meaning over-specifying or under-specifying both carry heavy performance costs.

Key Insights

• Frontier LLMs reliably follow only ~150–200 instructions before performance degrades (HumanLayer, 2025).
• Context Rot studies show models attend to context less reliably as input length grows (Chroma: Hong et al., 2025).
• Agents perform better when users state outcomes rather than micro-managed instruction sequences (Claude Directory).
• Including Bash commands for verification provides persistent context that agents cannot infer from static code (Claude Code).
• Reference implementations, such as existing test organization examples, act as high-leverage guidance for agents (Augment Code).

Working Examples

A full example of a non-trivial task specification for an AI agent.

## Task Spec: Add E.164 phone validation to UserService
### Goal
Phone numbers submitted to user registration must be rejected at the service layer when they aren't valid E.164.
### Architectural Context
- Semantic validation belongs in the service, not the handler.
- `UserService.ValidateEmail` is the canonical example.
### Reference Implementation
Mirror `UserService.ValidateEmail` in `service.go`.
### Constraints
- Use `validate.PhoneE164`. No regex, no new dependencies.
### Acceptance Criteria
1. `ValidatePhone(phone *string) error` on `UserService`.
2. Valid E.164 (e.g., `+14155552671`) → returns nil.
### Verification
go test ./internal/user/... -v -run TestValidatePhone

Practical Applications

• Use Case: Implementing service-layer validation by pointing the agent to a canonical ‘ValidateEmail’ pattern. Pitfall: Missing constraints leads agents to ignore project conventions or introduce unnecessary dependencies.
• Use Case: Using specific Bash commands for self-verification to ensure code passes builds before completion. Pitfall: Over-loading CLAUDE.md with non-universal instructions dilutes the signal of critical project rules.
• Use Case: Defining non-goals to prevent agents from refactoring unrelated auth or frontend layers during a simple feature addition. Pitfall: Failing to define ‘Done’ allows the agent to decide completion criteria, often leading to missing edge cases.

References:

• https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• https://code.claude.com/docs/en/best-practices
• https://www.claudedirectory.org/blog/context-engineering-claude-code
• https://www.augmentcode.com/blog/best-practices-for-using-ai-coding-agents
• https://blog.jetbrains.com/idea/2025/05/coding-guidelines-for-your-ai-agents/
• https://cloud.google.com/blog/topics/developers-practitioners/five-best-practices-for-using-ai-coding-assistants
• https://www.humanlayer.dev/blog/writing-a-good-claude-md
• https://research.trychroma.com/context-rot