4 min read
Back to How-to guides

How to apply GARDEN to a new project

This guide walks through setting up a greenfield project so that it follows the six GARDEN principles from the first commit. It assumes you already understand what GARDEN is; for the rationale behind each step, see GARDEN principles.

1. Choose a slice map before writing code

List the capabilities your system must support (for example: create-order, cancel-order, list-orders). Each capability becomes one atomic vertical slice (A): it owns its entry point, logic, data access, and tests.

  • Action: write the capability list as a flat directory plan, one directory per capability, before any implementation.
  • Acceptance signal: every planned directory maps to exactly one capability, and no capability spans more than one directory.

2. Set a naming registry

Pick one canonical name per domain concept (G) and write it down — a short table of concept -> name is enough. This is the single source of truth for what things are called in code, tests, docs, and error messages.

# naming-registry.txt
concept: order
concept: order-status
concept: shipment
  • Action: create the registry file at the project root before writing the first slice.
  • Acceptance signal: every identifier, file name, and directory name introduced later can be traced back to an entry in the registry; no synonyms exist for the same concept.

3. Write the root context file

Create a short, hand-written context file (for example AGENTS.md or CLAUDE.md) that an agent loads at the start of every session. Keep it under 200 lines and under roughly 150-200 discrete instructions — see the context-file evidence in Why agent-first principles.

  • Action: write the context file by hand, listing the naming registry location, the slice directory layout, and links to where deterministic gates and contracts live.
  • Acceptance signal: the file is under 200 lines, contains no autogenerated bulk dump, and a new contributor (human or agent) can find any other project document within one hop from it.

4. Scaffold one directory per slice, each with a README

For every capability in the slice map, create its directory with a README.md stating its purpose, its contract, and links to related slices (N).

slices/
  create-order/
    README.md
    entry.*
    logic.*
    data.*
    tests/
  • Action: scaffold all planned slice directories up front, each with a README stub, even before logic is implemented.
  • Acceptance signal: README.md exists in every slice directory and states the slice's purpose in the first paragraph.

5. Define contracts before code

For each slice, write its contract (interface, behavioral spec, examples) before writing the implementation (R). The contract is what makes the slice regenerable.

# create-order contract (pseudocode)
input:  { customer_id: string, items: list<item> }
output: { order_id: string, status: "pending" }
errors: invalid_items, unknown_customer
  • Action: write and version the contract file alongside the slice's future code, before writing the entry point or logic.
  • Acceptance signal: a reviewer unfamiliar with the implementation can predict the slice's observable behavior from the contract alone.

6. Wire deterministic gates from day one

Set up type checking, lint rules, and a test runner as CI gates before the codebase grows past the first slice (D). See How to set up verification gates for the full pipeline.

  • Action: add a CI job that runs type checks, lint, and tests on every change, ordered fail-fast (type check before test, test before review).
  • Acceptance signal: a change that violates a stated invariant fails CI without requiring a human or an agent to notice it manually.

7. Set a clone-detection budget

Decide the duplication threshold your project tolerates before extracting a shared abstraction (managed duplication, per A's rule of three).

  • Action: add a clone-detection job to CI and set a threshold (for example, flag blocks duplicated three or more times) rather than banning duplication outright.
  • Acceptance signal: the clone-detection job runs in CI and produces a report; no abstraction is extracted in response to fewer than three concrete usages.

Next steps