How to set up AI governance for any repo

TL;DR

• Tell the agent the rules in AGENTS.md. Ban libraries by name, and name the replacement.
• Check the rules at every stage: each commit, each pull request and each tag.
• Gate the release. Who merges is a choice of trust. Start with a person, and let agents merge once journey checks pass. Only a tag deploys.
• The same setup works for React, TypeScript and Python repos. Only the tools change.

Why asking is not enough

AI coding agents write code fast. They also pick the library they saw most in training. They push straight to main. They forget the rules you gave them three prompts ago.

Asking nicely does not work. Write the rules where the agent reads them. Then make a check fail when the agent breaks them.

I built a template repo that does this for a team’s React apps. It has three layers:

Layer 1: Tell the agent

Most AI coding tools read AGENTS.md at the repo root. Keep it short and blunt. Agents follow tables and checklists better than prose.

The template’s AGENTS.md has five parts:

• Critical rules. Read CONTRIBUTING.md first. Never commit to a protected branch. Build and lint must pass.
• Approved libraries. One library for each job, such as one chart library and one data grid.
• Banned libraries. Each banned library, why it is banned, and what to use instead.
• Branching. One change per branch, named feat/ or fix/, merged by pull request.
• A pre-commit checklist. A tick list the agent runs through before each commit.

The banned list matters most. Ask an agent for “a bar chart”, and it reaches for the most popular free library. If your company licenses a different one, the agent must be told. “Use approved libraries” is too vague. “Recharts is banned, use Highcharts” is a rule the agent can follow.

CONTRIBUTING.md holds the full workflow, from branch to merge. Commit messages follow the conventional format, such as feat: add a sales chart or fix: correct the date filter. Short supporting docs give the folder layout, the official docs for each library, and how code reaches each environment. With these, the agent cites real docs and keeps to one folder layout.

This is a template, so every line a team must change is tagged [MODIFY]. A team lead searches for the tag and fills in each one. When none are left, the setup is done.

If you use more than one agent tool, keep one copy of the rules. Claude Code imports AGENTS.md with a one-line CLAUDE.md. Other tools read AGENTS.md directly.

Layer 2: Check at every stage

The docs are a request. The checks are what enforce them. Each stage stops a different kind of mistake, and the cheap checks run first.

At each commit

Git hooks run on every commit, for people and agents alike. Set the hooks path once, and it covers every repo on the machine. A repo with its own hooks path must call the global hooks from it.

• In the template, a commit-msg hook rejects AI attribution lines. It also checks the conventional format.
• A pre-commit hook blocks a commit on main. It also blocks secret files, such as .env and private keys. A template such as .env.example still gets through.

Hooks are fast, but they run on one machine. CI runs on every pull request, whatever machine the code came from.

The hooks work the same for every coding agent, because git does not know who made the commit. My own machine uses the same approach, with its own checks. Read one local setup for every coding agent.

At each pull request

CI runs in a fixed order: install, lint, test, then build. Lint and the governance tests come first. They are cheap, and they catch most agent mistakes before a full build starts.

• Lint with zero warnings. A warning fails the build. So an agent cannot leave unused imports or disabled rules behind.
• Governance tests. These test the repo itself, not the app. They fail when a required doc is missing or a banned library appears. They also check versions, branch names and commits to a protected branch.

The tests check imports as well as the dependency list. An agent might remove a dependency but leave the import. It might also pull a library in through another package.

Keep the banned lists as plain data at the top of the test file. Teams change the lists, not the test logic.

Write each failure message for the agent, because the agent reads the CI log.

FAIL governance.test.ts
  AssertionError:
  expected false, got true

  at governance.test.ts:42
  at runTest (runner.js:118)
  at runSuite (runner.js:96)

FAIL governance.test.ts
  Recharts is banned.
  Use Highcharts instead.
  To fix:
  1. Remove it from package.json
  2. Replace its imports in src/
  3. Run the tests again

Skip what does not apply

A check that fails on a good build teaches people to ignore red. So each check runs only where it makes sense:

• Tag builds only deploy, so the governance tests are skipped there.
• Branch names are checked only on pull request builds.
• A detached HEAD in CI skips the protected branch check, because the branch cannot be read.

Layer 3: Gate the release

Agents can open pull requests, and only a tag deploys. Who merges depends on how much you trust the checks. The flow below is the starting point.

A release goes out in rings, one environment at a time. A small group gets it first and finds problems early, like a canary in a mine. The release goes to more people only when that ring is healthy. The tag name picks the environment: X.Y.Z-alpha.N for early testing, X.Y.Z-uat.N for UAT and X.Y.Z for production.

Teams with an external pipeline, such as Azure Pipelines or GitHub Actions, follow the same flow. The merge triggers the pipeline, and the pipeline does the deploy.

Turn on branch protection in the repo settings too. The protected branch test is a backstop, not a replacement for it.

Who merges is a choice

Start with a person merging every pull request. As the checks prove themselves, move routine merges to agents. The condition: the end-to-end journey checks pass, not only the unit tests. Read why we gate agent work on evidence for the trust levels.

TypeScript and Python repos

Nothing in the three layers depends on React. A TypeScript service or a Python repo keeps the same docs, the same stages and the same release gate. Only the tools change:

The commit hooks and the release gate do not change at all. Neither do the docs. A recommended layout keeps them in the same place in every repo:

my-app/  AGENTS.md  CONTRIBUTING.md  DEPLOYMENT.md  LINKS.md  PROJECT_STRUCTURE.md  README.md  src/    components/    features/    lib/  tests/    governance.test.ts  .env.example  .nvmrc  package.json

my-service/  AGENTS.md  CONTRIBUTING.md  DEPLOYMENT.md  LINKS.md  PROJECT_STRUCTURE.md  README.md  src/    routes/    services/    lib/  tests/    governance.test.ts  .env.example  .nvmrc  package.json

my-package/  AGENTS.md  CONTRIBUTING.md  DEPLOYMENT.md  LINKS.md  PROJECT_STRUCTURE.md  README.md  src/    my_package/      api/      services/  tests/    test_governance.py  .env.example  .python-version  pyproject.toml

Protect the machine

The checks above protect the code. They do not stop a shell command that deletes data. An agent runs shell commands, so guard those too.

Give the agent a deny list for the worst commands, such as a recursive force delete or dropping a database. Add a guard that reads each command before it runs and says what to do instead. It should also refuse --no-verify, which skips the commit hooks. The local setup article shows how.

Set it up in your own repo

1. Copy AGENTS.md, CONTRIBUTING.md and the supporting docs.
2. Copy the governance test, and add Vitest or pytest.
3. Search for [MODIFY] and fill in each one: branches, approved and banned lists, versions and the deploy target.
4. Set lint to fail on any warning.
5. Install the commit hooks once, for every repo.
6. Wire CI to run lint, then the tests, then the build.
7. Turn on branch protection, and deploy only from tags.
8. Test it. Ask the agent to “add a chart with Recharts”, and watch the build go red.

What I learned

• Docs alone do not hold. The agent reads AGENTS.md and follows it most of the time. The checks cover the rest.
• Ban by name, and give the replacement. A vague rule gives the agent nothing to follow.
• Write failure messages for the agent. It is the one reading the CI log.
• Keep the config as data. Teams change the lists, not the test logic.
• Merge is a choice of trust. Start with a person at merge and release. Let agents merge on green once the journey checks earn it. A tag still deploys.

Read why we gate agent work on evidence.