Advanced Context Engineering for Agents
Dexter Horthy of Human Layer explains why naive AI coding agents fail in complex software projects and introduces 'Advanced Context Engineering.' He details a spec-first, three-phase workflow (Research, Plan, Implement) designed to manage context intentionally, keeping utilization below 40% to maximize model performance. This approach uses subagents and frequent compaction to turn AI from a prototyping tool into a production-ready system for large, brownfield codebases.
The prevailing approach of “vibe coding”—engaging in a lengthy, unstructured dialogue with an AI coding agent—is fundamentally flawed for real-world software engineering. This method is akin to writing extensive Java code, compiling it into a JAR file, checking in the compiled asset, and then discarding the original source code. The specification and the prompts that describe the software’s desired behavior are the true source code of the future.
Current AI coding tools often fail in large, complex, or legacy (“brownfield”) codebases. Studies and anecdotal evidence show that while they can be useful for prototypes, they frequently lead to sloppy code and significant rework, sometimes even becoming counterproductive and slowing developers down. To overcome these limitations, a shift in methodology is required.
The Shift to Spec-First Development
The core challenge in using AI for complex coding tasks is maintaining alignment and ensuring quality at scale. When an AI can generate a 20,000-line pull request of complex systems code, traditional line-by-line code review becomes impossible. This necessitates a move to spec-first development, where the human’s role shifts from writing and reviewing code to writing and reviewing detailed specifications. By trusting well-written specs and the accompanying tests, teams can maintain alignment and velocity without getting bogged down in massive, AI-generated code reviews.
Advanced Context Engineering: The Core Principles
The key to making AI agents effective in production is “context engineering”—optimizing the information provided to the LLM to maximize the quality of its output. Since LLMs are pure functions, the quality of the input context is the primary lever for improving results.
The goal is to engineer the context for correctness, completeness, and minimal size. The worst thing to have in your context window is bad information, followed by missing information, and then excessive noise. A core objective is to keep context utilization under 40%. The fewer tokens are used for boilerplate “work” like searching for files, the more capacity the model has for reasoning and generating high-quality code.
This leads to a hierarchy of leverage:
- A bad line of code is a single error.
- A bad line in a plan can result in hundreds of bad lines of code.
- A bad line in the initial research—a misunderstanding of the system—can lead to thousands of bad lines of code.
Therefore, the most effective use of human oversight is at the research and planning stages, not the implementation stage.
A Three-Phase Workflow for Intentional Compaction
Instead of a continuous, messy dialogue, a structured, multi-phase process built around frequent intentional compaction yields far better results. This involves building the entire development workflow around deliberate context management.
1. Research
The first phase is dedicated to understanding the existing system. The agent is prompted to analyze the codebase and produce a research document that identifies all relevant files, data flows, and logic.
- Output: A markdown file with file names and specific line numbers.
- Human Role: Review this research document for accuracy. This is a critical step to prevent the agent from proceeding with a flawed understanding of the system.
2. Plan
Once the research is validated, the agent creates a detailed implementation plan. This plan explicitly outlines every change to be made, including the files to be modified, snippets of the proposed changes, and a strategy for testing and verification.
- Output: A detailed, step-by-step implementation plan.
- Human Role: This plan becomes the primary artifact for “code review.” It allows the team to align on the proposed changes at a high level, catching architectural and logical errors before any code is written. Reviewing a 200-line plan is far more efficient than reviewing a 2,000-line PR and achieves the main goal of code review: mental alignment.
3. Implement
With a validated plan, the agent proceeds to write the code. Because the plan is explicit and the context is clean, this phase requires minimal corrective intervention. As the agent completes steps in the plan, the context is updated to reflect the progress, always keeping utilization low for the next task.
Supporting Techniques
- Subagents for Context Control: Subagents are highly effective for delegating specific, context-heavy tasks. For example, a parent agent can ask a subagent to “go find where this happens.” The subagent performs the necessary file searches and returns a concise answer (e.g., file and line number), freeing the parent agent’s context from the noise of the search process.
- Intentional Human Review: This workflow is not fully automated. It is built around intentional human review steps at the end of the Research and Plan phases. This ensures that errors are caught early, at the point of highest leverage.
This structured approach transforms coding agents from a prototyping toy into a powerful tool for shipping production code in large, complex systems. The future of AI-assisted development lies not in the models themselves, which will become commoditized, but in the team workflows that effectively manage context and collaboration between humans and AI.