Chapter 12

Make the Environment Reproducible Before Autonomy

An agent won't fix a missing runtime, a nonexistent command, or a hidden local dependency. The more autonomous the run, the more precise the setup, lockfile, working directory, env, and cleanup must be. In the companion project this starts with a verified manifest.

JSON

{
  "name": "coding-agents-automation-2026-project",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=24.0.0"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "typecheck": "tsc -p tsconfig.json --noEmit",
    "test": "node --import tsx --test tests/*.test.ts",
    "demo": "node --import tsx src/demo.ts",
    "check": "npm run typecheck && npm test && npm run demo"
  },
  "devDependencies": {
    "@types/node": "26.1.2",
    "tsx": "4.23.1",
    "typescript": "7.0.2"
  }
}

The minimal environment contract fixes six things, each checkable.

Element · Fix · Check

Runtime - The Node, Python, Go, or JDK version; node --version or equivalent
Dependencies - Lockfile and install command; npm ci, not a random global package
Commands - Focused test, typecheck, build, full check; Exit code and bounded output
Environment - Names of required variables without values; Preflight with a safe message
Services - How to start and stop DB, browser, container; Health check and cleanup
Workspace - Root, writable paths, and temporary paths; Path containment test

It's worth separating two mechanisms people often confuse. A Git worktree isolates the checkout and branch but shares the Git object database - it helps against conflicts of parallel edits. A container adds a separate process, filesystem, and network boundary - it helps with a reproducible, bounded environment. One doesn't replace the other.

Setup is code too. Cursor documents .cursor/worktrees.json; Codex has its own worktree and environment support. Check the setup command on a clean checkout and don't copy a real .env automatically if the task doesn't need its secrets.

And the first-run rule.

A clean run first. Before handing a task to the agent, remove the dependency on unpinned global tools: run install by the lockfile, the focused test, and the full check in a fresh checkout or temporary fixture. "Works on my machine" doesn't work for an autonomous agent.

The environment is reproducible. Now we can return to the work itself - and its first stage on a large base is layered research.

Make the Environment Reproducible Before Autonomy

Links