How-to guides on vshuraeff — Infrastructure. DevOps. Cloud.

How to apply GARDEN to a new project

Mon, 01 Jan 0001 00:00:00 +0000

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.

How to retrofit GARDEN onto a legacy codebase

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers incremental adoption of GARDEN in an existing codebase that was not built with agent-first principles. Do not attempt a rewrite; retrofit through measurement, strangler-style extraction, and ratcheted enforcement. For the principles being applied, see GARDEN principles.

1. Measure before changing anything

Establish a baseline so you can tell whether the retrofit is working.

Action: measure the search-miss rate (how often an agent fails to find an existing utility and reimplements it), the duplication level (copy-pasted and cloned code as a share of changed lines), and current gate coverage (share of stated invariants that are checked by a type, lint rule, test, or CI job rather than by prose).
Acceptance signal: you have three baseline numbers recorded and dated, so later passes can show delta.

Gather the search-miss rate by sampling recent agent sessions or pull requests and checking whether a new function duplicates an existing one that a grep for its purpose would have surfaced. Gather duplication from a clone-detection tool run once over the current tree. Gather gate coverage by listing the invariants stated in existing docs or comments and checking, one by one, whether a type, lint rule, or test currently fails if the invariant is violated.

How to set up verification gates

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers building the deterministic verification pipeline (D) that lets a codebase avoid self-certification: an agent's own assessment is never sufficient, gates decide. For the underlying rule set, see GARDEN principles.

1. Encode invariants as types first

The cheapest and earliest gate is the type system. Push as many invariants as possible into types before reaching for lint or tests.

Action: for every invariant currently stated only in prose or a comment, check whether it can be expressed as a type (a named shape, an enum instead of a string, a non-nullable field instead of a documented "must not be null").
Acceptance signal: a change that violates the invariant fails to type-check, without running any test.

2. Add lint rules for what types cannot express

Import boundaries, naming conventions, and banned constructs are architecture decisions that types alone do not enforce. Treat lint configuration as executable architecture specification.

How to review code as an agent

Mon, 01 Jan 0001 00:00:00 +0000

This guide is written to be used directly as a review prompt for an agent conducting a GARDEN-lens code review. It assumes the deterministic gates described in How to set up verification gates already ran. For the rule definitions referenced below, see GARDEN principles and GARDEN compliance checklist.

1. Check what the gates already covered

Before reading a single line for review, check the CI results for this change.

Action: read the type check, lint, test, and clone-detection results for the change under review.
Acceptance signal: you can state, for each of those four gates, whether it ran and whether it passed, before writing any review finding.

Do not re-litigate anything a passing gate already proved. If lint enforces an import boundary and lint passed, do not raise a finding about that boundary; instead, look for what the gates cannot see. If a gate did not run at all (for example, no contract test exists for the slice being changed), treat that absence itself as a finding under the D lens in step 5, rather than trying to manually verify what the missing gate would have checked.

How to install and manage the GARDEN plugin

Mon, 01 Jan 0001 00:00:00 +0000

GARDEN supports Claude Code and Codex CLI. uv must be on PATH for either harness: bundled Python entry points run through uv run --no-project. See GARDEN principles for the methodology.

1. Confirm the prerequisite

Install uv and make it available on PATH before adding the plugin in either harness.

Action: confirm that uv is available in the shell used for Claude Code or Codex CLI.
Acceptance signal: uv resolves on PATH before any bundled Python entry point runs.

2. Add the marketplace

Claude Code

Add the GARDEN marketplace. Pass --scope user|project|local to choose where it is registered; the default is user.