Executive Summary
The landscape of software development has shifted from code completion to autonomous system architecture. However, Large Language Models (LLMs) suffer from "context burden" and "drift"—a gradual divergence from the project's reality. To build production-grade software with agents, developers must shift their role from "writer of code" to "Architect of Context." This handbook outlines the operational framework for managing this collaboration.
The Core Challenge
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.
The Solution — Efficiency Accelerators
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.mdto 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.
Explicit Constraints
It defines "Critical Data Constraints" (e.g., Likert scores must be 1-5; Quality scores 0-1). This prevents the agent from generating valid code that violates business logic.
Defined Dependencies
It explicitly maps "Page Routes" to "Primary API Calls" (e.g., The Audit Dashboard depends on /api/engagements/[id]/scores-filtered). This ensures the agent understands the full stack relationship before writing a single line of frontend code.
Single Source of Truth
It clarifies complex logic, such as the "Dual-Stream Isolation" pattern, ensuring Partner and Internal surveys are joined by category_name rather than ID.
The Progress Loop Framework
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.
Human-in-the-Loop Imperatives
Curator of Relevance (Preventing "AI Pollution")
The developer's primary role is to prevent "AI Pollution".
The Issue
A "findings document" created to debug a specific error becomes pollution once the error is fixed. If left in the context, it consumes tokens and confuses the model.
The Fix
Ruthlessly discard information that has outlived its usefulness. Ensure the model sees the current state (the Solution), not the historical confusion (the Problem).
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
"See it, Touch it, Prove it"
Code generation is not completion. Agents can write code that passes lint checks but fails in the browser.
- •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.
Conclusion
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.