--- title: Version-Controlled AI Governance for Engineering Teams date: 2026-05-18 summary: Every team using AI assistants has governance. The question is whether it's a reviewed file in the repo or a habit in someone's head. How I've done it at work and on my own projects, and what it changed. status: published tags: ai governance, engineering leadership, amazon q developer, rules profiles prompts, team standards, version control mediaSourcePath: /ai-lab/agent-workflow/app.html mediaSourceSelector: .agent-agenda-layout, main mediaSourceTheme: dark imageAlt: Agent Agenda, an editor for the personas, rules, skills, and tools that governance documents are made of. imageCaption: Governance artifacts should be composable, versioned, and reviewed like any other code. --- # Version-Controlled AI Governance for Engineering Teams Every team using AI assistants has governance, whether or not anyone wrote it down. The only question is whether it's explicit and reviewable or implicit and different for every engineer. At my current job I drafted and iterate on the Rules, Profiles, and Prompts our team uses with Amazon Q Developer, checked in and reviewed like test configuration or deployment scripts. On my own projects the same idea shows up as `CLAUDE.md`, `AGENTS.md`, and Copilot instruction files. This is what that looks like in practice and why I'd push any team toward it. ## The governance gap Before the files existed, the team's AI usage lived in heads. One engineer had a great prompt for triaging a flaky test. Another had learned the hard way not to let the assistant touch the shared fixtures. A third was new and had none of that. The output varied with the person, and the variance showed up in code review as inconsistency nobody could name. Writing it down didn't make anyone's individual work better. It made everyone's work the same kind of good. ## Three kinds of artifact **Rules** are engineering constraints the repository owns. Behavior changes require the matching test update. No edits outside the stated task. Deterministic assertions over timing-based waits. Non-trivial releases carry rollback notes. These are reviewed in pull requests. Changing a rule is a team decision with a diff. **Profiles** describe how the assistant should behave for a kind of work. A regression-triage profile prioritizes finding the root cause over proposing a fix. A script-maintenance profile stays inside the existing patterns of the codebase. Profiles are the reusable behavior, separate from the task at hand. **Prompts** are the reusable task templates: diagnose this failure, extend this page object, convert this manual test case. They're short, they reference the rules, and they exist so nobody rewrites the same instruction from scratch. The names come from the tooling we use, but the structure is general. On [good-vibes](https://github.com/benmcnulty/good-vibes) it's three instruction files, one per assistant, each with a stated role. On this site it's one canonical rule file with a delegation protocol and a set of skills. On [startup-cohort](https://github.com/benmcnulty/startup-cohort), an experiment in running an AI-agent organization in public, the governance is the whole repo: `SOUL.md` for values, `AGENTS.md` for execution standards and memory discipline, `SECURITY.md` for what may never be committed. ## Review it like code The change I'd argue for hardest is treating governance edits as code changes. A pull request that loosens a rule gets the same scrutiny as one that loosens an assertion. A new prompt gets read by someone who'll have to live with its output. That's also where the audit trail comes from. When someone asks why the assistant is allowed to do a thing, the answer is a commit with a reviewer, not a memory of a meeting. ## How the documents evolve They evolve the same way tests do: from failures. A regression the assistant introduced becomes a rule. A prompt that produced inconsistent output gets tightened. A profile that was too broad gets split. On this site the rule that bugs get a written diagnosis before a fix exists because I watched assistants, and myself, cycle through three CSS approaches without ever naming the property that was wrong. ## Onboarding is the payoff A new engineer who reads the rules file knows how the team works with AI on day one. So does a new assistant session. That's the same document doing both jobs, which is the strongest argument I have for keeping it in the repo. It's also why I built an internal documentation app at work that puts the governance artifacts and the auto-generated codebase docs behind one interface: the onboarding path and the AI context path turned out to be the same path. ## What changed The measurable effects at work were in the weekly regression cycle. Triage, diagnosis, and resolution got faster and more consistent because everyone started from shared context. Script maintenance improved for the same reason. The less measurable effect was that AI adoption stopped being a set of individual experiments and became a team practice with a definition. If I were interviewing an engineer for a team that uses assistants, I'd ask to see their rule files. Not because the files are impressive, but because whether they exist tells you almost everything about how that person works.