Refraction: A Documentation Standard for AI-Managed Codebases

The problem with existing documentation

Most documentation approaches were designed for human readers: wikis, READMEs, ADRs, Confluence pages. They assume someone will search for the relevant section, skim it, and navigate using a sidebar or browser tabs.

Agents don't work that way. An agent has a context window and a cost per token. Loading an entire wiki before it can answer a question is wasteful. Loading nothing leaves it guessing. What it actually needs is hierarchical loading: a clear entry point, explicit pointers to more detail, and the ability to stop as soon as it has enough.

None of the standard documentation approaches provide this. ADRs are flat. READMEs are L1-only with no enforced hierarchy below. Confluence and Notion are designed to be browsed, not traversed. Arc42 is structured but heavy, designed to be read front-to-back by a human auditor.

I wanted something purpose-built for agent-managed projects. The result is Refraction.

The C4 insight

The C4 model, developed by Simon Brown, describes software architecture at four levels: System Context, Container, Component, and Code. It's a good mental model but it outputs diagrams: Structurizr DSL, PlantUML, Mermaid. Diagrams are hard to diff, hard to maintain, and agents can't generate them reliably.

The insight behind Refraction: take C4's layered thinking and express the first three levels as plain markdown files instead of diagrams. Each file is self-contained at its own level of abstraction. Each links downward to the next level.

The result is a structure an agent can traverse like a tree: start at the root, follow exactly the branches it needs, stop when it has enough context.

Three layers

Refraction has three file types:

L1: docs/system.md, one file per project. What the system does, who it talks to, what it deliberately doesn't do, and links to every container. An agent loads this for broad context. A human reads it to understand the project without reading code.

L2: docs/containers/[name].md, one file per separately deployable unit. What this container is responsible for, its technology, its interfaces with other containers, and links to its components. Shared infrastructure (auth, logging, feature flags) belongs in platform.md rather than being duplicated across service docs.

L3: docs/components/[name].md, one file per meaningful architectural component. The granularity test: if you'd explain it separately when onboarding a new developer, it's a component. Each file requires code pointers: explicit paths to the source files it describes. This bridges spec to implementation in one hop.

The full structure looks like this:

docs/
  system.md
  containers/
    api-gateway.md
    auth.md
    platform.md          ← shared concerns
  components/
    routing.md
    rate-limiter.md
    token-service.md
    user-store.md
    logging.md
    feature-flags.md
  reference/             ← optional: config schemas, protocol specs
    api-schema.md
    auth-protocol.md

No diagrams

Refraction does not use diagrams: not Mermaid, not PlantUML, not ASCII art. Prose, lists, and tables only.

Diagrams have a hidden cost. Their diffs in git are unreadable. Every format requires learning a DSL. Agents hallucinate diagram syntax: invalid node IDs, broken alignment, unclosed blocks. ASCII art is no better; agents produce it inconsistently, and it breaks the moment anyone edits the surrounding text.

The text constraint is useful. If you can't describe a component's interfaces in a paragraph, the component boundary isn't well-defined yet. Writing it out forces clarity that diagrams obscure behind boxes and arrows.

Docs and code, both directions

Documentation rots because maintenance is expensive. Every time you ship code, updating the docs is an extra step that gets skipped under time pressure. The docs drift. Eventually they're wrong enough to be misleading and someone stops trusting them.

Refraction changes the economics because the format works in both directions. Write the docs first and let the agent implement: the hierarchy gives the agent enough context to produce code that matches intent. Or let the agent write the docs after a code change and review them yourself. The plain markdown is easy to read and edit at whatever level you care about.

Either way, whoever needs to update something can. The format doesn't prescribe a fixed workflow. It just makes the structure clear enough that both humans and agents can navigate and maintain it.

Is "standard" the right word?

"Framework" implies tooling you install, configuration you write, a system with opinions enforced by code. Refraction has none of that. It's a convention: a file structure and a set of rules about what each file contains. Nothing to install. You adopt it by creating docs/system.md and following the pattern.

"Standard" is closer. It's a definition you can implement in any project, independently, without dependencies. The closest analogy is a coding style guide: valuable precisely because it's a shared convention, not because it's enforced by a linter.

Known tradeoffs

The C4 container/component boundary is fuzzy, and that doesn't go away just because the output is markdown. Teams will disagree on what constitutes a container versus a component. The granularity heuristic ("if you'd explain it separately to a new dev") helps, but it requires judgment calls that agents will sometimes get wrong.

L1 and L2 docs contain judgments about purpose, boundaries, and non-goals that can't be mechanically derived from code. An agent syncing docs after a code change might faithfully update implementation details while missing a boundary that quietly shifted. The docs are in git; if something looks wrong, you can see it. Refraction doesn't prescribe a review process.

The model also doesn't fit every architecture cleanly. Event-driven systems and heavily layered monoliths can be awkward in C4 generally; Refraction inherits those rough edges.

What's next

The spec is at signalshell.com/refraction. I'm testing it on real projects, starting with Tachikoma's own codebase, and will update the standard as the rough edges become clear.

The Claude Code skills at github.com/signalshell/refraction cover both directions: refraction-sync updates docs when code changes, refraction-implement updates code when docs change, and refraction-check uses git history to determine which side has drifted and which skill to run.

If you're working on agent-integrated development workflows and this resonates, I'd be interested to hear how your projects are structured.