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.
The same principle supports software supply-chain assurance. The supply-chain provenance specification records where, when, and how an artifact was produced. An agent workspace needs a smaller but related record: source revision, environment definition, commands, outputs, and the resulting diff.
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. The npm documentation, for example, says a lockfile supplies exact versions for reproducible installs.
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.
The minimum environment record should include:
- Starting commit and branch
- Operating system and architecture
- Language, runtime, and package-manager versions
- Lockfile checksum or immutable dependency reference
- Setup and validation commands
- Network and secret sources, without recording secret values
Isolate reproducible environments
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.
Isolation does not require rebuilding every byte for every run. Shared read-only caches can reduce setup time if cache keys include all relevant inputs. A cache miss should cost time, not change behavior. Writable caches need per-run namespaces or careful locking.
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.
Reproducible environments for coding agents also improve evaluation. Teams can compare models or instructions against the same commit and test suite, then attribute differences to the agent run instead of machine drift. That makes failure analysis faster and gives reviewers a concrete basis for trusting the change.
