The new GARDEN section is about a change in the primary reader of a codebase. Classic principles such as SOLID, DRY, and layered architecture were tuned for a human working in an IDE: someone who has built an accumulated mental map, recognizes familiar patterns at a glance, and can ask a colleague when that map runs out.
In an agent-first codebase, LLM agents write, review, and analyze the code while humans set intent, constraints, and approvals. Humans still own the important decisions, but they rarely inspect every line. That changes the mechanics that architecture must support.
An agent has finite context and, without an external memory system, no persistent memory between sessions. It navigates through lexical or vector search rather than accumulated familiarity, and usually reads only the fragments relevant to its current task. Long sessions can also degrade its ability to retain established state. A rule written only in CLAUDE.md or AGENTS.md is therefore a compliance request, not enforcement; deterministic gates have a different role because the agent cannot proceed when a check fails.
GARDEN is a set of six language-agnostic principles for this environment. The metaphor is deliberate: a codebase is a garden that agents continuously tend, and code left untended grows wild.
- G — Grep-first Discoverability. Use structure and names that minimize search steps. Give each concept one canonical name, keep call sites statically traceable, and avoid magic or dynamic dispatch that conceals relationships.
- A — Atomic Vertical Slices. Keep a capability's entry point, logic, data access, and tests together in a small module that fits one task's context window. Accept managed duplication until real repeated use justifies an abstraction.
- R — Regenerable Components. Make a component replaceable from its contract without affecting unrelated code. The contract is the durable artifact; implementation code is expendable, and extension happens through explicit ports.
- D — Deterministic Verification. An agent cannot certify its own result. Encode invariants as types, lint rules, tests, or CI gates. LLM review can add independent lenses, but it does not replace reproducible checks.
- E — Explicit Everything. Surface dependencies, interfaces, errors, values, and ordering requirements. Avoid hidden globals, temporal coupling, magic values, and compact code that depends on unstated conventions.
- N — Navigable Knowledge. Put layered documentation and human-authored intent close to the code they govern, with progressive disclosure. The knowledge needed for an edit should be at most one hop from the edit site.
The Garden documentation is organized with Diataxis: tutorials, how-to guides, reference, and explanation each answer a different kind of question. The canonical principles reference is self-contained so it can be copied directly into a project's CLAUDE.md or AGENTS.md as an agent-facing reference.
Read the full GARDEN section, start with the principles reference, or work through the getting started tutorial.