Skip to content

Document Types ​

A change proposal stops being active after its implementation is verified and integrated. Leave it in openspec/changes/ and the next agent may read it as unfinished work. That is not a documentation problem. It is a type problem.

This book uses a small working set of document types. Each one has a different lifespan and a different job. If you blur those jobs, the agent reads stale material as if it were current.

The types ​

The taxonomy below is a working set for agent-readable repos. It combines established forms such as ADRs with repo conventions that make those forms legible to coding agents.

Content documents are the baseline: wiki pages, guides, articles, reference documentation. They carry no lifecycle constraint, no structural requirement, and no size limit the agent must respect. Write them, update them in place, and let them grow or shrink as the subject demands.

The other types carry stronger rules because the agent needs to know whether each document is current, frozen, or ready to archive.

Directory placement makes the distinction inspectable. In this book's layout, structured documents live under docs/, while content pages live under content/, wiki/, or another publishing directory. A configured check can validate files under docs/ and openspec/. AGENTS.md points the agent at those places.

Sources: Nygard, "Documenting Architecture Decisions," Cognitect (November 15, 2011), the ADR concept. Kopp, Armbruster, Zimmermann, MADR template (2018), structured ADR format. OpenSpec (openspec.dev), the change-folder lifecycle. iec repo conventions in this project family, the docs/ vs. content/ directory placement.

README files with an embedded index ​

A directory with a README listing and a separate INDEX table lists every file twice. The two lists drift apart as soon as a commit updates only one of them.

One README per documentation directory serves both readers. Its opening lines say what the directory holds for a developer who lands there from GitHub or GitLab, which render README files in repository navigation. Below those lines, between two marker comments, sits the index: one row per file, with a link and a one-line description.

markdown
---
type: index
title: Architectural Decision Records
---

# Architectural Decision Records

Decisions that shaped this repo. Accepted records are frozen.

<!-- index:start -->
| File | Description |
|---|---|
| [0001-vitepress.md](0001-vitepress.md) | Use VitePress for the book site |
| [0002-content-dir.md](0002-content-dir.md) | Keep prose in `content/`, free `docs/` for project docs |
<!-- index:end -->

Write each row so the reader knows which question the file answers: "Use VitePress for the book site" beats "Architecture decision". Keep prose and diagrams out of the block. Point the agent to the README when the task needs that directory, and let a script read the lines between the markers. The type: index front matter lets one query list every index in the repo.

Make it a standing repo rule that the commit adding, renaming, or removing a file also updates its row. A stale row misdirects every session that loads the README.

The price is context. A separate INDEX held only the map, while the README makes the agent read the opening lines too. Keep them to a few lines. When the human-facing text has to run long, as in a project's front-page README, keep the map in its own file.

This book's own content/ directories use the same shape under a different name. Each section opens with an index.md that carries prose and a chapter list, because VitePress serves index.md as the page at a directory root. There the file name follows the site generator and the pattern stays the same.

A check that compares the rows with the directory's files flags a stale row before a session loads it. It is optional. A table kept by hand and reviewed in the same pull request does the job. The first stale row that slips through review is the argument for adding the check.

Sources: GitHub, "About the repository README file" and "Get a repository README for a directory" (reviewed October 23, 2026), README display and directory lookup. GitLab, "File management" (reviewed October 23, 2026), automatic README rendering. VitePress, "Routing" guide (accessed October 2026), index.md served at the directory root. iec repo conventions in this project family, the one-line-per-file map format. Embedding the map in the README is this book's synthesis.

Design docs ​

Design docs live in docs/design/ and hold per-feature thinking: options weighed, approach chosen, risks named. They are not decision records, and they are not specs: a design doc describes the approach, a spec defines the behavior.

Some teams write them and move on, others keep them current, and both are reasonable. Pick one policy and apply it consistently, so the agent does not load a 2025 design doc as if it still described the 2026 implementation.

Sources: iec repo conventions in this project family, the docs/design/ placement and write-and-forget vs. keep-current treatment.

Analysis documents ​

You spend an afternoon finding out why the nightly build fails on one runner. The answer lives in a chat session closed since Friday. Next month an agent starts the same investigation, or retries the fix you already ruled out.

An analysis document keeps that work. It answers an open question before a decision, a design, or a spec exists: why something fails, which option holds up, what the legacy code does. It lives in docs/analysis/, and every analysis ends in a finding. Each rejected alternative either becomes an ADR or is named in the findings, so the why-not outlasts the session that produced it.

The shape is small. The file opens with the question, then states the evidence boundary: the date, the commit or release it ran against, what you ran and what you did not. Next come what was tried and the findings. Each finding is labeled observed or inferred, so a later reader knows a measured result from a guess.

markdown
---
type: analysis
title: Why the nightly build fails on the arm64 runner
status: concluded
---

# Why the nightly build fails on the arm64 runner

## Open question
## Evidence boundary
## What was tried
## Findings

1. The cache restore step exceeds its timeout on every failing run (observed).
2. The runner image changed the week the failures began (inferred).

An analysis is a snapshot. While its status is active, edit it as the work proceeds. Once it is concluded, the findings freeze, because they describe a system at one point in time. Later evidence goes into a new analysis, which supersedes the old one the way a new ADR supersedes an accepted one.

Three neighbors look similar to an analysis, and each answers a different question:

DocumentQuestion it answers
AnalysisWhat is true, and how do we know?
Design docWhich approach did we choose?
ADRWhat did we decide, and why?
proposal.mdWhich change are we proposing?

OpenSpec's proposal.md lives inside a change folder, so an analysis comes before any proposal exists. skeleton.md is the other near neighbor: it recovers a brownfield system and retires once its findings are distilled, while an analysis answers any question and stays.

Point the agent at the analysis index before it starts an investigation. A concluded analysis on the same question saves the spike. Check its evidence boundary against the current system first, because a finding about last year's runner image says nothing about this year's.

Sources: Nygard, "Documenting Architecture Decisions," Cognitect (November 15, 2011), the supersede-instead-of-rewrite practice for accepted records. The analysis document type, its evidence boundary, its active and concluded statuses, and the observed or inferred labels are this book's synthesis.

skeleton.md ​

skeleton.md exists to get a brownfield repo into the rest of the taxonomy. This book uses it as a first pass: reverse-engineered structure, visible business rules, recovered constraints, and the first draft of decisions nobody had written down.

That gives it a lifecycle: live while the brownfield recovery is in progress, retired once the stable findings have been distilled into the durable docs/ set. Brownfield vs Greenfield works out the mechanics.

Sources: Schwab, "AI as Your Legacy Code Archaeologist," Caimito blog (February 7, 2026), agents extracting structure and business rules from legacy code. The skeleton.md lifecycle framing is this book's synthesis.

Architectural Decision Records ​

Architectural Decision Records (ADRs) record what was decided, which alternatives were considered, why this option won, and what consequences follow. The rationale stops the next agent from reopening rejected options or treating an old compromise as a general rule.

While an ADR is still proposed, change it as much as the discussion requires. Once its status moves to accepted, the decision freezes. Reversing it means writing a new ADR that references the old one and supersedes it, not rewriting the original to say something different.

Supporting context is not frozen. If you sharpen the record without changing the decision, record an amendment at the bottom of the file with the date and what changed.

The proposed and accepted statuses come from MADR itself, recorded in YAML front matter at the top of the file: status: accepted, date: 2024-03-01. The amendment record does not come from MADR. It is this book's own convention.

Sources: Nygard, "Documenting Architecture Decisions," Cognitect (November 15, 2011), the ADR form and the why-over-what value. Kopp, Armbruster, Zimmermann, MADR template (adr.github.io/madr, 2018), the proposed/accepted status field in front matter. The amendment-record convention is this book's own.

MADR ​

This book uses MADR (Markdown Architectural Decision Records), a structured template developed by Oliver Kopp, Anita Armbruster, and Olaf Zimmermann (2018). MADR gives every ADR the same shape: context, considered options, decision outcome, consequences.

The "considered options" section is not boilerplate. Rejected options tell the agent which paths were already evaluated and ruled out. The why-not carries almost as much weight as the why.

A second reason MADR works is that the headings already say what belongs under them. Write ## Considered Options and the agent usually fills it correctly without extra explanation.

Sources: Kopp, Armbruster, Zimmermann, MADR template (adr.github.io/madr) and CEUR-WS Vol-2072 (2018), the template's plain-English section headings. The named-standard-versus-custom-format argument is book synthesis.

Specs ​

Specs are the behavioral form of intent. Where an ADR records a decision and the reasoning behind it, a spec records what the system must do as a result, before you build it. In this book's OpenSpec workflow, delta specs carry scenarios while tasks.md holds implementation steps.

The task list makes incomplete work visible. Prose can describe the plan, but a reviewer then has to reconstruct which steps remain.

One instruction is worth adding to your AGENTS.md or to the spec itself. Tell the agent to check off each task immediately upon completion, not at the end of the run. That gives you live progress visibility and makes interruption safer.

Sources: OpenSpec documentation (openspec.dev), separate delta specs and tasks.md in a change folder. The task-list review advice is this book's workflow guidance.

Specs and OpenSpec ​

A spec is not the same thing as OpenSpec. OpenSpec is a framework for managing specs through a change lifecycle: one folder per change, containing proposal.md, tasks.md, delta specs under specs/, and optionally design.md for changes that require technical design decisions. The spec itself is one artifact inside that structure.

A team can also keep a simpler /specs folder with files named by feature. That choice leaves the team to define when a file becomes historical and how the agent finds the current version.

This book uses OpenSpec throughout, but the spec concept applies regardless of how the folder is organized.

Sources: OpenSpec (openspec.dev, Fission-AI/OpenSpec), the change-folder structure: proposal.md, tasks.md, delta specs under specs/, and optional design.md.

Archiving ​

A spec lives in two moments: written before the work begins, archived once it ends.

Change specs move to openspec/changes/archive/ after the implementation is verified and integrated. The full mechanics are in Spec Lifecycle.

Sources: OpenSpec documentation, concepts.md (Fission-AI/OpenSpec), the archive folder mechanics.

The lifespans matter more than the names ​

TypeLifespanWhat that means in practice
Content documentsDurable, updatedWrite and evolve in place. No lifecycle or size constraints
README files with an embedded indexDurable, updatedOpening lines written for readers on Git hosts. The index rows change with every file added, renamed, or removed in the directory
Analysis documentsSnapshot, frozen once concludedactive while the work runs, then concluded. New evidence goes into a new analysis that supersedes the old one
Design docsPreference-dependentWrite-and-forget, or keep current. Pick one and apply it consistently.
ADRsDurable, decision frozen at acceptedProposed: freely editable. Accepted: decision frozen. Reversal = new ADR. Supporting edits need an amendment record.
skeleton.mdTemporary bootstrap, then historical or retiredLive only during brownfield recovery. Distill stable findings into durable docs/, then archive, remove, or mark as historical.
SpecsActive during the change, then archivedMove the change folder to the archive after verification and integration

A team that grasps the lifespan column has the practice. A team that only learns the directory names ends up with superseded specs in the wrong place and half-live design notes nobody trusts.

Sources: Nygard, "Documenting Architecture Decisions" (November 15, 2011), durable decision records. Kopp, Armbruster, Zimmermann, MADR template and CEUR-WS Vol. 2072 (2018), structured ADR format. OpenSpec documentation, change folders and archive lifecycle. The remaining lifespan categories are this book's taxonomy.

Keeping the structure honest ​

A directory layout does not stop an agent from reading the wrong file. A later session still needs to load the correct active spec and check its status.

The taxonomy assumes a readable format ​

All of this assumes the documents are in a format the agent can read. A type taxonomy tells you where to put things and how long to keep them. It does not extract text from a Keynote file or a screenshot.