AI Coding Agents
Platform Engineering
Reproducible environments for coding agents
September 24, 2026 - 2 minute read
Reproducible environments for coding agents turn an agent result into something another engineer can verify. When the operating system, toolchain, dependency graph, or starting commit changes between runs, a passing result can be hard to explain and harder to repeat.
Suppose a test passes locally because an undeclared environment variable selects a test service, then fails in CI where that variable is absent. Retrying the agent run will not explain the difference. Preserve the source revision, environment definition, and commands so another engineer can reconstruct the conditions.
Define reproducible environments
Begin from a named commit on a clean branch or worktree. Record the runtime and package-manager versions. Install from the checked-in lockfile rather than resolving a fresh dependency graph.
Keep setup executable. A container definition, image digest, or machine template is more reliable than a prose list of packages. Put the canonical install, test, lint, and build commands in repository instructions. Factory's AGENTS.md guidance recommends committing those commands and verification rules with the project so interactive and automated sessions receive the same context.
Record the operating system and architecture alongside the starting commit. A lockfile checksum identifies the dependency input used for the run. Name approved network and secret sources without retaining secret values, so a missing internal registry or credential injection step can be distinguished from a code failure.
The SLSA build provenance specification similarly records how an artifact was produced. An agent's environment record serves a narrower debugging purpose and does not by itself establish SLSA compliance.
Isolate reproducible environments
A cache miss should cost time, not change behavior. Shared read-only caches can reduce setup time when their keys include all relevant inputs. Writable caches need per-run namespaces or careful locking.
Parallel agents should not share a mutable checkout. One run can change generated files, caches, or dependencies while another is testing, which makes both results ambiguous. Give every task its own worktree or disposable workspace and merge changes only through version control.
Factory's Droid Exec worktree support creates isolated git worktrees for concurrent runs. The command also accepts a working directory, which helps constrain a job to one package in a large repository. Dirty worktrees are preserved for review rather than silently discarded.
Capture evidence with the change
A useful agent result contains more than a final sentence. Preserve the exact commands, exit status, test summary, and relevant screenshots or logs. Keep generated evidence separate from source unless the repository intentionally versions it.
Compare the same checks locally and in CI. A local pass followed by a CI failure often points to an undeclared tool, environment variable, service, or platform assumption. Fix the environment definition rather than adding an unexplained retry.
Keep the environment correction with the change that exposed it. The next run should use the declared setup rather than depend on a developer remembering the missing variable.
