Building AI‑Native Design Docs with Architecture as Code

Why a new form for a "living" design document?

Traditional architecture documents are written for people: a whiteboard sketch, a Confluence page, and informal discussions fill the gaps when the diagram is vague. AI agents, however, have no implicit knowledge; they can only consume the exact context you feed them. A vague description such as "the module handles core payment logic" is insufficient for an agent, which treats it as an unconstrained string.

Diagram ≠ Model: a key cognitive shift

Diagram‑as‑Code tools like Mermaid or PlantUML produce graphs —text that describes visual elements but lacks structured relationships. Each graph is an isolated file, so inconsistencies (e.g., a component named UserService in one diagram and AuthModule in another) can silently accumulate. For humans, a quick review resolves the conflict; for agents, contradictory information leads to hallucinations because the model cannot detect the mismatch.

In contrast, modeling tools generate a model , a structured data entity that defines components, their relationships, and responsibilities. The model serves as a single source of truth , automatically propagating name changes to all derived views.

Three limitations of Diagram as Code

Fragmented graphs cause hidden contradictions that agents cannot flag.

Drift of auxiliary artifacts such as descriptive text in Confluence or interface contracts in .yaml / .proto files, leading to mismatched versions.

Flat, non‑hierarchical graphs prevent slicing the architecture by granularity, which is needed to feed agents only the relevant view.

All three stem from the fact that Diagram as Code textualises the picture but does not capture the underlying data.

Architecture as Code: moving from diagrams to models

The solution mirrors the DevOps evolution from manual server manuals to Infrastructure as Code (Terraform .tf) and from Jenkins UI pipelines to Pipeline as Code ( Jenkinsfile). By treating the architecture as code, three engineering properties emerge:

Single source of truth : a DSL‑defined model replaces a collection of independent diagram files; any component rename instantly updates every view.

Traceable history : the model lives in Git, so each change is a commit that can be rolled back and linked to requirements.

Composable hierarchy : the model can be queried to generate System Context, Component, or Container views on demand.

Among open‑source tools, likec4 stands out. Its DSL is concise, and it provides a full toolchain (VS Code extension, static site export, React component). Crucially, likec4 implements a native Model Context Protocol (MCP) , allowing an AI agent to query the model directly (e.g., “list all downstream dependencies of the UserAuth module”).

// Tutorial:
// https://likec4.dev/tutorial/

specification {
  element actor
  element system
  element component

  tag ui {
    color #33B074
  }
  tag version1 {
    color #D6409F
  }
  tag warn
}

model {
  customer = actor 'Customer' {
    description 'The regular customer of the system'
  }

  saas = system 'Our SaaS' #version1 {
    component ui 'Frontend' #ui #warn {
      description 'Nextjs application, hosted on Vercel'
      style {
        icon tech:nextjs-icon
        shape browser
      }
    }
    component backend 'Backend Services' {
      description 'Implements business logic and exposes as REST API'
    }
    ui -> backend 'fetches via HTTPS'
  }

  customer -> ui 'opens in browser'
  customer -> saas 'enjoys our product'
}

views {
  view index {
    title 'Landscape view'
    include *
  }
  view saas of saas {
    include *
    style * { opacity 25% }
    style customer { color muted }
  }
}

The DSL above defines a simple system where a customer interacts with a UI, which calls a backend service. likec4 can render this model into an interactive diagram, and any change to component names or dependencies instantly updates all derived views.

Contracts: precise promises between components

While the model captures structure, interface contracts capture behavior: request formats, response fields, error codes, and timeout policies. Synchronous contracts include OpenAPI/Swagger, gRPC/Protobuf, GraphQL SDL, etc. Asynchronous contracts (AsyncAPI) cover event‑driven systems like Kafka or RabbitMQ. Language‑level contracts (Go interface, Java Interface, TypeScript type, Rust trait, Python Protocol) define module‑level promises.

These contracts are versioned, verifiable artifacts that should be linked to the architecture model so that every dependency in the model can be traced to a concrete contract file.

Narrative documentation: the semantic gap

Some information cannot be expressed in models or contracts: why an event‑driven approach was chosen, known scalability limits (e.g., >500k orders per day causing DB‑pool bottlenecks), or compliance requirements such as PCI DSS. This narrative content lives in textual documentation , stored alongside code (e.g., Markdown in the same repo) so that it evolves together with the model and contracts.

Three materials for AI‑native design docs

Architecture as Code (e.g., likec4) – structured model of components and relationships.

Interface contracts (OpenAPI, Protobuf, AsyncAPI, etc.) – precise behavioral promises.

Narrative documentation – design decisions, constraints, and business context.

Each material serves both humans (rendered diagrams, Swagger UI, Markdown) and agents (structured model, contract definitions, searchable text).

Context Engineering: deterministic organization

Simply placing all files in a repository is insufficient; agents need a deterministic mechanism to locate the exact piece of context required for a task. Over‑broad relevance (“everything might be relevant”) leads to token waste and missed information, a failure mode observed in large AGENTS.md files.

Context Engineering proposes a curated directory layout (e.g., ARCHITECTURE.md, design‑docs/, contracts/) and clear naming conventions so that an agent can, for example, retrieve the model slice for the payment subsystem, the OpenAPI spec for the checkout API, and the accompanying design rationale in a single, minimal context window.

For a deeper analysis of OpenAI's Harness Engineering, see my other blog “Harness 浪潮下的两条路径：OpenAI 与 Anthropic 的 Code Agent 工程化探索”.

Future articles in the Harness Architecture series will explore how to organise these three materials into a deterministic structure that enables AI agents to reliably locate the exact context they need.