Cross-links #
- AI Code Quality The shift in the human’s role to “agent manager” (defining constraints, validation loops) aligns with the move towards “executable architecture.”
- Applications of Vibe Coding The formalization of “Comprehension Debt” provides a deeper understanding of the “remediation of architectural debt” gap.
- Vibe Coding Approaches The distinction between “vibe coding” and “agentic engineering” (structured, verified) provides context for the move towards “executable architecture” and “Agentic Governance.”
- Claude-Specific Expertise The “loop” pattern, where developers write automated verification code, is a concrete example of “executable architecture” and embedding rules.
- Team & Org Use of Claude The focus on “Governance and Control Surfaces” and the
CLAUDE.md pattern for shared context align with the need for “executable architecture.”
A Pattern for Hardening Architecture: Executable Boundaries #
- Stop AI code sprawl before it destroys your software design (The New Stack) — This article introduces “Executable Architecture” as a concrete strategy to combat “Comprehension Debt”—the gap between the speed of AI code generation and a team’s understanding of the system. Instead of relying on documentation or manual code reviews which AI agents often ignore, this approach encodes architectural rules directly into automated tests that run in CI/CD pipelines. It provides a specific Python-based example using
pytest-archon (an analogue to Java’s ArchUnit) to create hard boundaries, such as asserting that a billing module cannot import from a shipping module, or that domain models are forbidden from importing infrastructure libraries like SQLAlchemy. The failure output from these tests can be fed back into the agent’s context, creating a feedback loop for self-correction and enforcing architectural coherence automatically. - Production repository conventions for AI coding agents: a working contract (Stack Overflow Blog) — This piece outlines a practical method for making a codebase legible to coding agents by creating an explicit “working contract” within the repository itself. The core idea is to move beyond prompts and establish clear, discoverable conventions that guide the agent’s behavior. This includes creating a compact repository map in the root
README, defining explicit ownership rules for module boundaries (e.g., routes/ owns transport validation, services/ owns product operations), and marking protected paths (e.g., migrations, authentication policy, billing logic) with notes on what kind of verification is required for any changes. This approach aims to make the architecturally correct path the path of least resistance for the AI agent.
Emerging Patterns for Multi-Agent and Background Systems #
- Harness-of-Harness: Multi-Day Autonomous Software Development with Continual Improvement (arXiv) — This paper proposes a novel “Harness-of-Harness” (HoH) architecture, which functions as a meta-framework for managing and coordinating existing AI coding agent harnesses. Rather than being a new agent, HoH is a higher-level orchestrator designed to manage long-duration, complex software development tasks that may take days to complete. It addresses the limitations of single-session agents by introducing a structure for continual improvement and task decomposition across multiple, specialized agent systems.
- Ramp Inspect Architecture: How Background Coding Agents Scale Safely (Wavect) — This post analyzes the architecture of Ramp’s internal background coding agent, “Inspect,” presenting a concrete pattern for safely executing autonomous agents. The key architectural choice is to treat each agent task as an isolated execution workload. Each session runs in its own “Modal Sandbox” which contains the full application stack, a browser, tests, and internal tooling. This allows the agent to not only edit code but also build the product, run tests, and visually verify UI behavior end-to-end before opening a pull request. The use of filesystem snapshots to pre-build environments is highlighted as a critical optimization to reduce startup latency for these background sessions.
- How I cut coding agent costs with model and harness routing (Arize AI) — This article details two specific, named architectural patterns for optimizing the cost and performance of agentic systems by routing tasks to different models. The first pattern is a “Frontier orchestrator with lower-cost subagents,” where a powerful model (e.g., GPT-5.x) handles high-level planning and architectural decisions while delegating token-heavy, routine work (like file discovery or simple implementation) to cheaper, specialized models. The second pattern inverts this: a “lower-cost orchestrator with a frontier advisor,” where a cheaper model runs the main loop but can escalate to a more powerful model for specific, complex decisions when it detects a situation beyond its capabilities.
Techniques for Architecting Agent Context and Control #
- How Would You Design an AI Coding Agent in a System Design Interview? (Medium) — While framed as an interview question, this article provides a substantive architectural blueprint for a coding agent, focusing on the critical and often costly step of context gathering. It proposes a key technique: before engaging a token-intensive LLM, first build a cheap “repository map” by walking the Abstract Syntax Tree (AST) of the codebase. An AST walk can extract all class definitions, function signatures, and import statements for a few milliseconds of CPU time and zero token cost, providing the agent with a structural overview of the entire repository. This map allows the agent to reason about the codebase’s structure and locate relevant files before loading their full content into the expensive context window.
- Claude Code Explained: The Complete Guide From Zero to AI Coding Agent (Medium) — This guide details the functionality of Claude Code and highlights a specific mechanism for providing architectural context to the agent: the
CLAUDE.md file. This file serves as a discoverable, project-specific instruction manual that the agent consults to understand non-obvious architectural constraints and patterns. The article provides concrete examples of what this file should contain, such as rules for module responsibility (“Controllers should not contain business logic. Services contain business logic.”), required data structures for API responses, and security guardrails (“Never log passwords, tokens, JWTs…”). This represents a formal, in-repository method for humans to enforce architectural decisions on the agent.
- Emerging Pattern: A dominant pattern is the move from relying on soft conventions (prose documentation, human memory) to “hard” or “executable” architecture. This involves embedding architectural rules, boundaries, and contracts directly into the repository in machine-readable formats (e.g., CI tests, dedicated
.md files for agents, AST-based repo maps) to create verifiable, automated guardrails for AI agents. - Emerging Theme: The “agent harness”—the infrastructure around the LLM that provides tools, memory, and orchestration—is becoming a well-defined architectural layer. The conversation is now maturing to a higher level of abstraction, focusing on patterns for routing between models/harnesses and meta-frameworks (“Harness-of-Harness”) to manage systems of multiple agents.
- Keyword suggestion: “Executable Architecture”, “Comprehension Debt”, “Agent Harness”, “Continuity Layer”, “Repository Contract”.
- Gap: While significant content focuses on preventing architectural drift and enforcing boundaries upfront, there is a noticeable lack of published patterns or frameworks for the remediation of architectural debt after it has been introduced at scale by AI coding agents.