The Agentic Engineering Handbook

The Context Problem & "Drift"

As an application grows, its context complexity expands beyond the fixed windows of LLMs. Models cannot distinguish between relevant architectural decisions made yesterday and a debugging log from last week.

• Drift: This results in "drift," where the model hallucinates code that conflicts with established patterns (e.g., calling an API endpoint that was refactored).
• The Consequence: Without intervention, drift compounds, leading to a codebase that is internally inconsistent and fragile.

Institutional Memory

To combat drift, we use Efficiency Accelerators. These are not static documentation files; they are living artifacts that serve as the project's "institutional memory". They encode lessons learned, architectural constraints, and validated patterns.

• Token Efficiency: Instead of loading thousands of lines of code, an agent refers to a high-density markdown file.
• Implementation: Use prompts like @file architecture-schema.md to load only the specific context needed for the current task.

Case Study: A Production Architecture Document

A well-structured data schema document (e.g., architecture-schema.md) serves as the gold standard for an Efficiency Accelerator. It functions as a rigid blueprint that constraints the agent's creativity to safe boundaries.

Success in agentic coding requires a structured workflow known as the Progress Loop.

Step A & B: Planning & Vision

• The Vision: Leverage the LLM to explore tech stacks, security, and hosting.
• The Blueprint: Refine this into a comprehensive plan (>2,000 lines of markdown) covering every API route and schema.
• Human Validation: The human architect validates this plan before implementation begins.

Step C: Segmentation

• The "Monolith" Trap: Agents fail when asked to build the whole system at once.
• The Strategy: Ask the model to "segment the plan into logical sequential steps".
• Example: A well-architected system supports segmentation by defining layers: Data Models, Business Logic, API Layer, UI Components, and Integrations. A developer can safely ask the agent to "Implement the Data Models layer" without confusing it with the UI Components layer.

Step D: Implementation & Tooling

• Compounding Capabilities: Combine the core model (e.g., Claude Code) with persistent memory tools (e.g., claude-mem) and plugins.
• Hooks: Use "hooks" (if-then conditions) to automate hygiene. Example: "If a bug is fixed, update the efficiency accelerator document automatically".

Step E: Documentation & Contextualization

• The Feedback Loop: After a segment is built, document what was learned and what risks remain. This feeds into the next segment's context.

Curator of Relevance (Preventing "AI Pollution")

The developer's primary role is to prevent "AI Pollution".

Visual Context & Interpretation

• The "Screenshot" Adage: Frontier models possess high fidelity for interpreting visual information.
• Application: When fixing UI issues (misalignment, truncation), do not describe the error. Paste a screenshot. This bridges the gap between code and user experience instantly.
• Diagramming: Architecture documents should imply visual structures (like Mermaid diagrams) to help the model "see" the data flow.

The Testing Imperative

• •Ankle-Biters: Visual and interactive bugs (e.g., a button that doesn't click) accumulate. If not caught in their specific segment, they compound into complex, hard-to-diagnose failures later.
• •Rule: Every segment must conclude with manual verification.

The era of Agentic Development is not about magic; it is about Structure.

• Efficiency Accelerators manage the context.
• The Progress Loop imposes discipline.
• Human Curation prevents pollution.
• Rigorous Testing ensures reality matches the design.

By treating architecture documents as the "Source of Truth," we transform the LLM from a chaotic code-generator into a precise, architectural engine.