Version-Controlled Agent Configuration in Production Repos

Version-controlled agent configuration means treating an AI agent's instructions, tool permissions, and behavioral scope as files that live in the same repo as the code it touches, subject to the same pull request review, the same git history, and the same rollback discipline. That is the entire thesis. Everything else in this piece is an argument for why that pattern is not a nicety but the only way to actually govern what agents do once they stop completing snippets and start opening pull requests on their own.

The default state: how most teams are running agents today, and what it leaves uncontrolled

In most engineering orgs running agents in production workflows, the configuration story looks roughly the same: a developer types a prompt into a terminal, or pastes one into a chat window, and the agent goes off and does something. A developer types a prompt into a terminal, or pastes one into a chat window, and the agent goes off and does something. The instructions live nowhere durable. Maybe there's a system prompt, but it exists in a UI text box that only that developer has touched.

Some teams have gotten slightly further than that: a wiki page that describes how to invoke the agent, a Slack thread with what someone calls the "current" system prompt, a .env file committed once at project kickoff and never looked at again. These are better than nothing. They are still not governance.

What all of these patterns share is the absence of four things: a review gate before a change takes effect, a history of what changed and when, attribution tying a change to a person, and a rollback path if something breaks. Without those four, a few consequences follow almost mechanically. Agent behavior shifts when someone edits a prompt in a UI and doesn't mention it to the rest of the team. When an agent opens a bad pull request or calls an external service it had no business calling, nobody can reconstruct which configuration was actually running at that moment. Secrets and tool permissions, set once during setup, accumulate scope creep silently because no one revisits them. Two engineers who believe they're running "the same agent" may, in practice, be running materially different configurations, because nothing forced those configurations to converge.

There's a dimension here that makes this worse than it looks at first glance, not better. Agent execution is non-deterministic by design: identical inputs can produce different outputs, unlike a Terraform plan, which is at least a comparison against a known previous state. That non-determinism makes configuration drift harder to catch, not easier, because the symptom (a weird PR, a wrong tool call) can look like normal model variance right up until it isn't. Research on agent drift found that task success rates in drifting multi-agent systems fell from 87.3% to 50.6%, a 42% drop, and that drift became detectable only after a median of 73 interactions. By the time a team notices something is wrong, the system has usually been wrong for a while.

The cause is that agent configuration is treated as ephemeral, a runtime detail rather than a persistent artifact, and this produces the gap described next. That assumption doesn't hold once an agent has write access to a codebase, credentials to external services, and the ability to act across many steps without a human in the loop at every turn.

What engineers already know about governing systems that touch production code

None of this is a new problem, actually. The same problem now appears in a new place. Engineering teams have had a working contract for decades: anything capable of touching production, a deployment script, a CI job, an IAM policy, lives in git, goes through pull request review, and accumulates a history that can be inspected later. Nobody debates whether a change to an IAM policy needs a reviewer. The debate agents are forcing is whether the same standard applies to them, and the honest answer is that it has to.

Version control, in this context, isn't just a backup mechanism. It supplies four specific things: review (a human gate before a change takes effect), history (an exact reconstruction of what was running at any point in time), attribution (who changed what, and when), and rollback (a revert to a known-good state without ceremony or guesswork). The review step matters for a reason that goes beyond catching mistakes. It forces the team to say, explicitly and in writing, what the system is supposed to do before it does it. That forcing function is worth more than the bugs it catches.

Infrastructure-as-code went through exactly this argument a decade ago. Terraform didn't invent version control, and it didn't invent the idea of a review gate. It applied a discipline engineers already trusted to a new class of artifact, cloud resources, that had previously been configured by hand through a console. Agent configuration is the next artifact in that lineage. If an agent can write to a repo, call external APIs, and spend an organization's credentials, it is a production system, full stop, and it should be governed like one.

MLflow's 2026 guide on production agents makes a version of this point directly: reproducibility needs to hold at every layer, "model weights, prompt versions, tool definitions, and runtime configuration." Tool definitions and runtime configuration are, not coincidentally, the two layers most teams currently leave completely ungoverned.

There's an underappreciated benefit to putting agent config in a review-friendly text format, too. It decouples the review role from the engineering role. A security reviewer or a compliance officer doesn't need to read the agent's underlying code to understand what it's authorized to do. They need to read the YAML. That's a real expansion of who can participate in oversight.

AGENTS.md as the emerging standard for checked-in agent instructions

The clearest sign that this problem has a standard forming around it is AGENTS.md. It started at OpenAI, driven by Codex CLI's need for project-specific instructions, but it grew through contributions across the broader AI development tooling ecosystem rather than staying a single-vendor format. As of December 2025, governance of the spec moved to the Agentic AI Foundation, a directed fund under the Linux Foundation, the same body that now stewards MCP. That's a meaningful signal: this isn't a convention one company controls, it's infrastructure being treated as shared.

Adoption has moved fast by open standard timelines. As of mid-2026, AGENTS.md shows up in more than 60,000 open-source repositories, and it's supported across Codex, Claude Code, Windsurf, Devin, Jules, and dozens of other tools.

The loading mechanism is simple and borrows a pattern engineers already know. The CLI walks the filesystem from the git repository root down to the current working directory, reading every AGENTS.md file it passes along the way, with a global ~/.codex/AGENTS.md providing user-level defaults. Higher-level files set defaults, deeper files override for specific subdirectories, and the whole thing composes the way .gitignore files compose. A monolithic config file isn't required; a packages/billing/AGENTS.md can carry rules specific to that directory without touching the rest of the tree.

A proposed structured tool-permissions frontmatter, tracked as issue #105 in the agentsmd/agents.md repository. It would let a team declare, in YAML, what an agent can touch across files, shell commands, and browser access, and so on. What makes this different from a prompt instruction telling the agent to "only edit files in src" is enforcement timing. This check happens before any LLM action is attempted, as a deterministic policy layer enforced independently of the model, not a suggestion the model can ignore under the right (or wrong) framing.

Write AGENTS.md as the canonical source of truth for teams juggling multiple tools, and in tool-specific files, a CLAUDE.md for instance, just point back to it with an instruction to read AGENTS.md first. One file to maintain, and every compatible tool inherits the same behavior.

There is a ceiling here, too. AGENTS.md governs behavior, not infrastructure. It doesn't provide structured credential scoping, budget caps, or session isolation. Those live at a different layer, one this piece gets to shortly.

Agent Skills and the Open Agent Specification: reusable, versioned capabilities as first-class artifacts

Instructions are one layer. Capabilities are another, and that's where Agent Skills come in: reusable, portable packages of domain knowledge or team procedure that an agent loads on demand rather than having re-explained to it every session. A skill might encode a team convention or a repeatable procedure, each one self-contained and, critically, versioned in the same repo as everything else.

Skills were released as an open standard in late 2025. Adoption followed quickly: Claude Code, OpenAI Codex, VS Code, and more than 30 other tools support the format, and at launch, Atlassian, Figma, Canva, Stripe, Notion, and Zapier all published skills of their own.

The governance property this adds is subtle but important. Because a skill is a file in a repo rather than a setting in a platform's database, upgrading it means opening a pull request like upgrading any other dependency. The team sees the diff. Someone approves it. Agents don't start behaving differently until that approval happens, which closes off exactly the kind of silent behavior change that plagues prompts configured through a settings interface.

The most ambitious effort to standardize this space further is Oracle's Open Agent Specification, introduced in October 2025 alongside a technical report on arXiv. OAS is framework-agnostic and declarative, aiming at something bigger than any single vendor's format: agent definitions that are portable across different runners.

Elsewhere, the industry is converging on the same underlying idea from different directions. Microsoft's Azure Foundry uses an azure.yaml file that declares an entire project (model deployments, connections, toolboxes, skills, routines, agents) as a set of services in one place, replacing an earlier two-file model. That consolidation, going from two files to one, is itself telling: config tends to converge toward a single source of truth once teams start actually operating it at scale. Other vendors are pursuing related approaches, using declarative formats that let teams assemble agents out of composable parts, which broadens who inside an organization is capable of authoring agent configuration.

The thread running through AGENTS.md, Agent Skills, and OAS is the same: capabilities, behaviors, and permissions expressed as declared, reviewable, versioned files.

What a production-grade CI/CD pipeline for agent configuration looks like

Writing the config down and checking it in is step one. Shipping it reliably is a separate problem, and it turns out to be the same problem application software solved years ago: evaluation-driven quality gates, promotion across environments, role-based access control enforced at every stage.

Microsoft's Foundry reference implementation lays out a five-step pipeline, because the structure applies well beyond that one product. Static checks come first: linting, security scanning, and YAML schema validation against the agent config itself. Then unit and tool tests, typically pytest suites that cover both the agent's logic and its tool integrations. Next comes the evaluation gate, arguably the most important step: evaluation datasets run against the new config, and the pipeline fails if quality thresholds are breached. A config change that measurably degrades output quality simply doesn't reach production. After that, an image build for hosted agents, or a YAML bundle validation for prompt-based ones. Finally, promotion gated by RBAC: developers can deploy freely to a dev environment, but only appropriately credentialed CI/CD principals can promote a build into test or production.

That pipeline generates an audit trail almost as a side effect. That pipeline structure naturally generates an audit trail covering which agent version is live in each environment and when it was promoted, without bolting on separate tooling for the purpose. Credential handling follows the same discipline: each deployed agent version gets its own dedicated managed identity, scoped tightly to that deployment.

The evaluation gate deserves particular attention because it's where the non-determinism from earlier gets managed rather than ignored. Since agent outputs vary run to run, the gate can't check for a single expected output the way a traditional unit test does. Instead it tests behavioral properties across a distribution of runs, catching config changes that shift that distribution in a bad direction even when no individual output looks obviously wrong.

What this buys a team, compared to ad hoc invocation, is concrete: rollback becomes a single git revert, promotion history is fully auditable, and no config change reaches production without clearing the same quality bar as application code. The same principle extends further: embedding evaluation probes directly inside agentic workflows rather than running them only as offline batch jobs keeps behavioral drift visible before it turns into an incident.

The governance properties that only version-controlled config can provide, and the ones config alone cannot

Checked-in config delivers a genuinely strong list. Review: every behavioral change passes through a PR gate before it can affect a single execution. History: the exact configuration running at any past point is reconstructible from git blame, no guessing required. Attribution: who changed a tool permission, a prompt's scope, or a skill's version, and exactly when. Rollback: reverting a bad config change without touching the runtime that executes it. Composability: hierarchical overrides and shared skills without duplicating logic across a dozen files. And accessibility: a YAML file is readable by a security reviewer or a product owner who has never opened the agent's source code.

That's a genuinely long list, and it's tempting to stop there. But config-as-code has a ceiling, and pretending otherwise does the reader a disservice.

A YAML file can declare that credentials should be minted fresh per session and revoked on completion. It cannot enforce that. Enforcement requires a runtime that actually honors the declaration, which is a separate piece of infrastructure. Session isolation lives there, in the runtime. Budget enforcement follows the same logic: a config file can document a spending cap, but only a managed execution layer sitting between the agent and its tools can actually stop spend before it happens. Full observability of tool calls is another gap. Git history shows what configuration was deployed; it says nothing about what the agent actually did once it started running; every tool call, every diff, every token needs runtime logging that lives outside version control. And a config file is only ever as safe as the sandbox executing it. Declaring an agent restricted to a directory means nothing if the execution environment doesn't actually confine it there.

So the governance stack has two layers, not one. Config-as-code declares what an agent is authorized to do, and that declaration gets reviewed by humans before it takes effect. Managed infrastructure enforces those declarations at runtime and produces the audit trail of what actually happened. Microsoft's Agent Governance Toolkit (v3.6.0) states that governance decisions get enforced deterministically at the application layer before actions execute, and blocked actions are denied at the policy layer rather than left as instructions the model may or may not follow.

The drift research cited earlier is useful again here, because it maps cleanly onto these two layers. Drift becomes statistically detectable only after a median of 73 interactions, and human intervention frequency rises sharply in systems already drifting. Config review is what catches intent drift before deployment, before an agent ever runs with the bad configuration. Runtime observability is what catches behavioral drift after it has already started, closer to real time than a git log ever could be.

None of this makes version-controlled config less important. It makes it necessary but not sufficient, the entry point every team can build today with tools already sitting in their stack, and the foundation that makes the runtime enforcement layer interpretable. Without the config layer, the runtime layer has nothing legible to enforce against.

How to move an engineering team from ad hoc agent invocation to config-governed workflows

Start by writing down what already exists. An agent's current behavior, however informally it was arrived at, gets captured as an AGENTS.md file or an equivalent YAML spec and checked into the repo. An imperfect written spec beats an undocumented one every time, because it gives the team something to argue about, revise, and eventually trust.

From there, add tool scoping before trying to nail down every behavioral nuance. Use a structured permissions block, or whatever the equivalent is in the tooling a team has chosen, to declare which file paths, shell commands, and external services the agent may touch. This matters more urgently than getting the prompt wording perfect.

Wire the whole thing into normal PR review next. Agent config changes go through the same process as application code changes, with no carve-out for "just a quick prompt tweak." That exception, once granted, tends to swallow the whole discipline within a few weeks.

Finally, pull anything reused across multiple agents or repos out into a versioned skill rather than letting it get copy-pasted across a dozen config files. A migration pattern or a deployment checklist that lives in five different AGENTS.md files with five slightly different wordings isn't governed, it's just distributed. A single skill, reviewed once and referenced everywhere, is.

None of these four steps require new infrastructure. They require treating a file that happens to configure an agent the same way an engineering org already treats a file that configures a deployment pipeline. That standard already exists. Agent configuration is just the next thing that has to meet it.