Alex' Gardenアレックスの庭

4 min read

Agent-Native Software Architecture

A new kind of software where there is essentially no “real” code — no main.js, no compiled artifact. The only code is helper scripts. The program is defined in an agent instruction file (e.g. CLAUDE.md / AGENTS.md), and everything runs through an agent runtime (Claude Code or any open alternative that supports skills, sub-agents, and MCP).

Layered Architecture

Think of it as a four-layer stack:

LayerAnalogyImplementation
Main orchestratormain() entry pointAgent instruction file (e.g. CLAUDE.md)
Sub-agentsClassesAgent definitions with description + scoped skill list
SkillsMethods / functionsMarkdown skill files describing a procedure
MCP / CLI toolsAPIs / SDKsConnectors to external data and services

The main orchestrator does no real work — it only delegates. Sub-agents are scoped to a subset of skills, which keeps permissions clean (most sub-agents don’t need full bash access, and shouldn’t have it).

State

Ordinary storage: a database via MCP, a CLI tool, or a flat JSON file. No special mechanism needed.

Self-Healing

Traditional software is immutable: a bug requires a fix + a new release. Agent-native software is mutable at runtime — a heal agent (or fix skill) can debug and rewrite a broken skill on the fly. For example, if an MCP server changes its API and a skill still references the old tool names, you don’t cut a release: the heal agent notices and rewrites the skill.

Whether runtime mutability is desirable is an open question. The dynamism feels genuinely powerful, but it also means the software is never frozen.

UX: Terminal-First (For Now)

  • Awkward currently: no UI, skills invoked as slash commands, setup runs once via a setup script. Feels like early computing before GUIs.
  • Visibility problem: all skills (user-facing and helper) are exposed to the user, which is noisy.
  • Optional UI: embed the SDK, build a front end that renders agent-produced data. The “just add a chat bar” answer isn’t right — this is heading toward intent-based / automatic interaction rather than explicit chat commands.

Performance: The Mainstream Threshold

The major blocker for mainstream adoption is speed and cost. A rough estimate: ~20–30× faster + ~20× cheaper than current state would make this viable for general use. Modularity helps — different sub-agents can run on different models, so you choose the right cost profile per task.

Debugging

Agent debugging is sub-agent level, not function level:

  • Which sub-agent is taking too long?
  • Is its instruction file describing a golden path that doesn’t actually work?
  • Is it making unnecessary tool calls?

The “logs” in Claude Code are the thought trace (thinking + tool calls). This is the developer’s primary instrument — though Anthropic is increasingly obscuring it, which is a problem.

Optimization: Context Window as RAM

The context window is the program’s RAM. Two ways to pass data between agents:

  • By value: include result content directly in the next agent’s prompt — expensive in output + input tokens.
  • By reference: write the result to a temp file, pass the file path — the receiving agent reads on demand, saving both output and input tokens.

This is analogous to pass-by-value vs. pass-by-pointer — appropriate for an era where context is scarce, like early computing with kilobytes of RAM.

This Vault as an Example

This vault is itself an agent-native software project:

  • AGENTS.md → instruction file (orchestrator spec)
  • 7_Agent/skills/ → skill library (functions)
  • process-inbox, reconcile, etc. → user-facing skills (top-level entry points)
  • Obsidian CLI, Git → MCP/CLI layer (connectors)

See My AI native Obsidian Setup for a full walkthrough.

Graph View

Backlinks