画板 1

    Six-Layer Architecture and Context Governance for AI Coding Agents

    4 hr ago0 views

    This article breaks down the architecture of AI-powered coding agents into six distinct layers—long-term conventions, action capabilities, on-demand skills, enforced control, sub-agents, and verification loops—and explains how context, action, and control surfaces interact. It provides practical governance strategies for reducing context pollution, managing tool selection, enforcing permissions, and building verifiable agent workflows. The discussion is intended for developers and engineering teams who want to move from intermittent usability to stable, deliverable AI-assisted coding systems.

    The Core Problem: It’s Not Just About the Model

    After months of intensive use of AI-powered coding agents, one key insight emerges repeatedly: many “poor results” are not caused by a lack of model intelligence, but by poor system design. Treating the agent like a simple chatbot quickly leads to declining performance: context becomes noisy, tool selection becomes ambiguous, and long rule files are increasingly ignored. The real issue is not prompt wording alone—it is the failure to create a stable structure across the context surface, action surface, and control surface of the agent system.

    A practical way to understand this is to view the coding agent as a six-layer architecture:

    1. Long-term conventions layer: project rules, team agreements, structured memory—tells the agent “what things are”.
    2. Action capability layer: built-in tools, external tool integrations, scripts, and plugins—tells the agent “what it can do”.
    3. On-demand skills layer: methodology and runbooks loaded per scenario—tells the agent “how to do things”.
    4. Enforced control layer: permissions, sandboxes, hooks, and auditing—ensures certain actions do not rely on the agent’s discretion.
    5. Sub-agent layer: isolated-context workers for controlled autonomy and role separation.
    6. Verification loop layer: build, test, review, rollback, and audit—make outputs verifiable, reversible, and traceable.

    Strengthening only one layer creates imbalance. Overwriting long-term conventions pollutes the context itself. Too many tools increase selection cost. Uncontrolled sub-agent proliferation leads to state drift. Skipping verification makes failure diagnosis impossible. Below, each layer is examined with actionable governance strategies.

    The Agent Loop: Not a Single Answer, But a Repeated Process

    An intelligent coding agent is not about one-shot answers—it is an iterative cycle:

    1. Collect context → Take action → Verify result → Complete or return to collect
    2.       ↑                              ↓
    3.   long-term conventions/memory        hooks/permissions/sandbox
    4.   on-demand skills                    tools/external integrations

    Most bottlenecks surface not from “the model cannot code,” but from three recurring problems: wrong context is provided; results are produced but cannot be validated; actions are irreversible or un-auditable. These map to three surfaces:

    • Context surface: which information stays resident, which is loaded on demand, and which must be isolated.
    • Action surface: what capabilities are currently available, how clear tool descriptions are, and whether outputs are structured.
    • Control surface: which actions must be constrained, blocked, or audited, and how rollback works after failure.

    Debugging often reduces to these three surfaces: if context is chaotic, inspect resident information. If tool selection is wrong, inspect the width of the action surface. If rules are not followed, inspect whether the control surface depends solely on model discretion.

    Why Context Gets Messy, and How to Fix It

    Context chaos is rarely a single-point issue. It comes from compound sources: overly long convention files, un-trimmed tool returns, accumulating session history, conflicting rules, and uncleaned state after task switching. When the agent continuously reads large files, executes commands, and receives long outputs, the context window fills with low-value information, while critical interface constraints and acceptance criteria get lost.

    The governance approach is “layered loading, on-demand retrieval, contamination isolation, and stable prefixes.” Only a small set of hard, essential project conventions should stay resident. Domain methodologies belong in on-demand skills, loaded by triggers. Large volumes of historical decisions should be stored as structured memory and retrieved, not stitched into the full context. Sub-tasks are isolated through sub-agents to avoid polluting the main context. After each phase, temporary state is cleared, keeping only conclusions and evidence.

    A common workspace can be organized as:

    1. agent-workspace/
    2.   rules/
    3.     global.md
    4.     project.md
    5.   notes/
    6.     decisions.md
    7.     interfaces.md
    8.   methods/
    9.     test-strategy.md
    10.     refactor-guide.md
    11.   policies/
    12.     policy.json
    13.   workers/
    14.     reviewer.md
    15.     explorer.md
    16.   checks/
    17.     build.sh
    18.     test.sh

    rules/ should only contain must-stay-hard constraints. notes/ holds searchable structured memory. methods/ contains on-demand methodologies. policies/ defines enforced policies. workers/ describes sub-agent roles. checks/ contains verification scripts. The key is that not everything needs to be resident.

    The Action Surface: More Tools Does Not Mean More Capability

    Tools are the agent’s hands and feet, but an increasing number of tools raises selection cost and misuse risk. Every tool must have a clear purpose, input/output constraints, failure semantics, and permission boundaries. Tool descriptions must answer: when to use, when not to use, whether output is structured, whether the tool is idempotent, and whether retry is safe after failure. Write operations should be designed for rollback. External calls should go through a unified access layer, avoiding scattered implementation details in prompts.

    Action surface governance suggestions:

    • Keep a minimal tool set.
    • Open tools dynamically based on the task phase.
    • Trim tool outputs to a summary plus key fields.
    • High-risk actions require approval.
    • Low-risk read-only actions remain open.
    • All write operations go to audit logs.

    Tools are not better when numerous; they are better when predictable.

    The Control Surface: Hooks and Permissions Cannot Rely on Willpower

    No matter how long a rule file is, if compliance depends solely on the model “remembering to obey,” execution stability will fluctuate. Truly hard constraints belong in the control surface: permissions, sandboxes, hooks, and auditing. For example, direct writes to production directories are denied, command execution needs approval, and every write operation is logged—these must be enforced externally.

    An example policy definition:

    1. {
    2.   "before_action": [
    3.     {"match": "write:prod/**", "decision": "deny"},
    4.     {"match": "command:*", "decision": "require_approval"}
    5.   ],
    6.   "after_action": [
    7.     {"match": "write:**", "record": "audit-log"}
    8.   ]
    9. }

    The value of such policies is turning “should” into “must.” The agent can be intelligent, but the system must not assume it is always self-disciplined. The clearer the control surface, the more confidently the action surface can be opened.

    On-Demand Skills: Methodology Should Not Be Always Resident

    The skills layer solves “how to do things,” but it should not cram all methodologies into the resident context. A better approach is to load skills by trigger conditions: load testing strategy when the task involves tests, refactoring guide when refactoring is involved, release checklist when a release is planned. Each skill should include applicable scenarios, inputs, steps, output format, checklist, and counterexamples. Skills must be versioned to avoid conflicting versions across tasks.

    Sub-Agents: Isolate Context, Not Unlimited Autonomy

    The correct use of sub-agents is to isolate context and separate roles, not to spawn uncontrolled autonomous agents everywhere. An executor modifies code, a reviewer identifies risks, an explorer reads wide code ranges and returns summaries. Every sub-agent should have a clear input/output contract, minimum permissions, and a state-reclamation mechanism. Parallel sub-agents must have clear boundaries to avoid simultaneous writes to the same region. After completion, sub-agents return only conclusions, evidence, and next steps—not the full process—back to the main context.

    Verification Loop: Make Outputs Verifiable, Reversible, and Auditable

    A coding agent system without verification cannot be engineered. Verification must include at least: whether the build passes, tests pass, static checks pass, changes are reversible, and key actions are auditable. Validators should be scripted where possible, return structured errors on failure, and let the agent continue fixing based on those errors. For high-risk changes, an additional human review gate is recommended. The verification loop is not a final step—it is an integral part of the cycle.

    Architectural Impact of Prompt Caching

    Prompt caching greatly affects cost and latency, but its premise is a “stable prefix.” If long-term conventions, tool definitions, or skill descriptions change frequently, cache hit rate drops. Architecturally, stable content should go first and volatile content later: project constraints stay stable, tool definitions are version-managed, and dynamic task information is placed at the end. Avoid arbitrarily reordering large rule sections across sessions. Caching is not an isolated optimization—it is a consequence of layered context design.

    How to Write a Long-Term Conventions File That Is Actually Useful

    A long-term conventions file should be concise, hard, executable, layered, and versioned. It should contain only: mandatory boundaries, common commands, directory conventions, acceptance criteria, forbidden actions, and counterexamples. Avoid lengthy background narratives and do not push methodologies into this file.

    Example:

    1. # Project Conventions
    2. - Read the interface description before modifying core modules.
    3. - All write operations must be reversible.
    4. - Direct modification of production config is forbidden.
    5. - Run build and tests before committing.
    6. - If unsure, first present a plan and risks, then ask for confirmation.

    These rules are short, hard, and checkable—far more effective than long passages of “please be careful.”

    Start with the control surface and verification loop, then move to tool governance and on-demand skills, and finally introduce sub-agents. Measure the following: resident context size, tool misuse rate, verification pass rate, rollback frequency, audit coverage, and cache hit rate. The experience of using an intelligent coding agent improves not by writing longer prompts, but by completing all six layers—making context controllable, actions constrainable, and results verifiable. Only then can the system move from “sometimes usable” to “consistently deliverable.”

    09040904

    Top articles