Designing Inspectable Agent Architectures
Before touching any layer in a complex agent architecture, ask: "What property does this layer's existence protect, and what breaks if I collapse it?"
If you can't answer that question, you don't understand the architecture well enough to simplify it. Go read the authority files / design docs again.
Naive agent loops look like:
prompt → model → tool → stuff stdout back into chat → vibes
Deliberately-designed inspectable systems look like:
human intent
↓
explicit semantic representation
↓
machine-normalized representation
↓
auditable transformation
↓
AI receives compiled operating state
↓
real capability interaction
↓
typed evidence
↓
verification
↓
state changes
↓
recompilation
↓
AI receives updated operating state
Every extra noun in the second version (IR, lowering, source maps, evidence types, verification stages, lineage artifacts) exists to buy back a property that "vibes" architectures silently give up: traceability, inspectability, tunability, reproducibility, differential comparison, provider independence, or the ability to make honest claims about what actually happened.
When encountering an unfamiliar complex architecture (as reviewer, contributor, or maintainer):
Progress:
- Step 1: Read the actual authority files / design docs before forming an opinion — not skim, read
- Step 2: For each layer/artifact, identify what specific failure mode it prevents
- Step 3: Map the pattern back to the canonical pipeline (intent → representation → normalization → transformation → compiled state → interaction → evidence → verification → state change → recompilation)
- Step 4: Distinguish "this looks like accidental complexity" from "this is decomposition I don't yet understand"
- Step 5: Only propose collapsing a layer after articulating the property it currently protects, and how you'll protect it otherwise
- Step 6: Separately track "simplifications useful for explaining the system" vs "simplifications safe for implementing the system" — these are not the same list
Example 1: Input: "Why do we need a separate IR and source maps? Can't the agent just read the source config directly?" Output: The IR/source-map split exists so transformations on the compiled representation remain traceable back to human-authored intent. Collapsing it means you can no longer answer "why did the AI receive this instruction" without guessing. That's a provenance property, not an abstraction for its own sake — don't remove it unless you have another way to answer that question.
Example 2: Input: "This system has like ten named artifact types (PromptPackets, Outcome Contracts, evidence records, verification records, lineage records...). Isn't that overkill for what's basically an agent loop?" Output: Each named artifact type corresponds to a distinct moment in the pipeline where something is asserted, produced, or checked. Collapsing them into one generic "message" object destroys the ability to verify claims independently (was this claim generated, or was it verified?) and to diff behavior across runs/providers. The names aren't decoration — they're the seams where auditability lives.
Example 3: Input: A newcomer says a system's terminology (nautical names, domain-specific jargon) seems like arbitrary flavor over standard concepts. Output: Check whether the naming maps to a decomposition that doesn't exist in the "standard" version. If concept X only exists in this system and has no equivalent in the generic pattern, it's not renaming — it's added structure. Identify what problem that added structure solves before assuming it's just branding.
- Treat "this seems more complex than it needs to be" as a hypothesis to test, not a conclusion to act on.
- When a system separates human-semantic representation from machine-normalized representation, assume that's protecting against silent semantic drift during compilation — verify before removing.
- Prefer explaining complexity via examples/diagrams over removing it. Simplification-for-teaching and simplification-for-architecture are different activities with different risk profiles.
- If a layer produces "typed evidence" distinct from "verification," that split usually exists so evidence and its confirmation can be audited separately — don't merge production and validation into one step.
- Reproducibility and provider-independence are usually protected by the compiled/intermediate representation layer, not the surface prompt layer. If you flatten the intermediate layer, you likely lose both.
- Simplifying before understanding: proposing to collapse layers during onboarding, before reading the authority files that explain why they exist.
- Confusing decomposition with decoration: assuming domain-specific names are cosmetic instead of checking whether they track real structural distinctions.
- Conflating explanatory and architectural simplification: a simplified diagram for a README is fine; using that same simplified mental model to justify deleting code is not.
- Removing verification/evidence separation: merging "what happened" (evidence) with "was it correct" (verification) removes the ability to catch a system lying about its own success.
- Assuming your unfamiliarity implies the system's error: "I don't see why this is here" is evidence you need to read more, not evidence the layer is unnecessary.