The artifact layers

Agents keep nothing between sessions; every context window starts near zero. Some written knowledge layer is therefore necessary. At the same time, writing everything down and keeping it all current fails on cost, because a document pile grows until nobody can afford the upkeep, and then it decays all at once. Aigile handles this tension by splitting all project documents into three layers, each with its own maintenance rules.

The durable layer: small, maintained with care

This layer holds the constitution, decision records, and hard invariants. Every agent reads it at the start of every session, so every line in it has a recurring cost, and the layer works best when it stays small. Here is an example clause from an order system:

C-03  Monetary amounts are integer cents. Floating point money is
      inadmissible anywhere. [since v1.0.0]

A single line like this can hold for years, and every agent session is bound by it.

The ephemeral layer: written per slice, then archived

This layer holds the working material: feature intents, slice specs, acceptance criteria. A slice spec fits on one screen:

# Spec: reconciliation view / slice 1 (skeleton)
Constitution version: v2.5.0

Summary: a billing admin selects one entity and one closed month and
sees a table of that entity's orders with the invoice line each
landed on. Real data path, no fixtures.

A1 [test] Given entity E with 3 invoiced orders in period P, the
   view lists exactly 3 rows with order id, amount (integer cents,
   C-03), and invoice line id.
A2 [test] Orders of other entities or periods never appear.
A3 [test] p95 under 300 ms at 10k orders per entity (C-19).
A4 [prose: visual quality is judged at the demo] The table is
   readable enough for the ops lead to orient herself.

Three of the four criteria are tests. Once the slice is validated, this file moves to an archive. Nobody maintains it after that, and its staleness costs nothing, because nothing reads it as input anymore.

A note on technical conventions

The durable layer holds law, and law is defined by enforcement: a clause belongs in the constitution only if violating it should stop work. Most global technical material does not meet that bar. Naming rules, error-handling patterns, API style, test structure, and library choices are durable and global, but violating one of them earns a review comment rather than a stopped line. This material lives in scoped standards files, one technical area per file and each a screen or less, for example standards/persistence.md or standards/api.md. A slice spec declares which areas it touches on a Standards: line, and the building agent loads exactly those files in addition to the constitution. The reasoning is partly about tokens, since a full engineering handbook loaded in every session costs more context than all the slice specs combined, and partly about attention, since hard constraints buried in convention text tend to get lost. The reasoning behind constitution clauses follows the same principle: it lives in decision records that are read on demand, while the clause itself stays at one line with a reference. Business knowledge gets the same treatment as technical conventions: cross-feature facts such as domain rules, fixed enumerations, or how the customer operates live in small human-written files under a domain folder, one topic per file, and a slice declares which ones apply. Together with the constitution and the intent’s known-requirements list, this gives requirement knowledge four homes sorted by scope and rate of change: law in the constitution, cross-feature facts in domain files, feature facts in the intent, and per-slice verification in the acceptance criteria.

The derived layer: generated when needed

Module overviews, interface summaries, and similar descriptions of current behavior belong to the third layer. These are generated fresh, on demand, by an agent reading the code and tests, and discarded after reading. Because such a document is rebuilt from the source of truth each time, it cannot go stale.

A practical test for this layer: if an agent with access to the code could reproduce the document, the document is derived, and maintaining it by hand means paying for work a machine does for free.

What the sorting looks like in practice

One team inherited 14,000 lines of maintained markdown from an earlier SDD phase. Sorting it into layers produced a one-page constitution (durable), archived specs (ephemeral, sealed), and a set of deleted module descriptions replaced by a regeneration prompt (derived). The maintained pile shrank to about 300 lines. Six months later, the only documents anyone had learned to distrust were two overviews that someone had hand-edited against the rule.

When documents and code disagree

The layers settle this question in advance. For what the system does, the code and its tests are authoritative, and wrong prose gets corrected. For what the system should do and why, the durable layer is authoritative, since intent and reasoning cannot live in tests. A contradiction between these two authorities means one of them has a real defect, and the finding gets treated as a useful discovery rather than a documentation chore.

Full treatment: Organizing project documents.