Chapter 2: Policies that work

A policy that lives in a PDF is a policy nobody follows. A policy that lives in configuration is enforced whether anyone remembers it or not. This chapter is about writing the first kind short enough to read and converting as much of it as possible into the second kind.

The one-page policy

Engineers will read one page. Here is a template that covers the seven risks from Chapter 1 and fits on it.

# AI-assisted development policy

## Approved tools
- Claude Code, GitHub Copilot (Business), Cursor (Business) - under the company accounts only.
- Personal accounts and other tools: not for company code. Ask #eng-ai-tools to add one.

## Data
- Never paste customer data, credentials or production exports into a prompt or attach them
  as context. Use the synthetic fixtures in `tests/fixtures/`.
- Secret files (`.env*`, `*.pem`, `secrets/`) are excluded from tool access by configuration.
  Do not work around the exclusion. A secret that reached a model is rotated, no exceptions.

## Code
- You are the author of everything you merge. "The AI wrote it" is not a sentence we use.
- Pull requests over 400 changed lines are split. Review comments reference lines.
- New dependencies go through the licence gate in CI. Do not bypass it.
- Agents run with read-only access by default. Write access is scoped to one repository and
  one branch. No agent approves or merges its own work.

## Provenance
- Commits that include generated code carry the `Co-authored-by:` trailer the tool adds.
  Do not strip it.

## When in doubt
- Ask in #eng-ai-tools. Nobody is in trouble for asking.

Short, concrete, and every line maps to a control below. Review it quarterly; delete anything that has become automatic.

Converting policy into configuration

Policy line	Enforcement
Approved tools, company accounts	SSO-only tool licences; block personal-account endpoints at the proxy if the risk warrants it
Secret files excluded	Tool ignore files committed to each repository; rules-file line; pre-commit secret scanner
Secret reached a model → rotate	Secret scanning on PRs and on agent transcripts where the tool exposes them; runbook for rotation
You are the author	Branch protection: required human review; CODEOWNERS; no bot-approved merges
PRs over 400 lines are split	A CI check that fails PRs above the limit (with a label to override, which is itself logged)
Licence gate	Dependency review action with an allowlist; fails on unapproved licence
Agents read-only by default	Separate service identities per agent; token scopes reviewed in the identity provider
No self-approval	Branch protection rule: approvals from the PR author's identity do not count; agent identity is the author of its PRs
Co-authored-by kept	A lightweight commit-message check; or simply accept that most tools add it and audit periodically

Notice that most rows are a GitHub setting, a CI step or a file in the repository. Governance is mostly configuration.

Permission scopes for agents

An agent is a user. Give it an identity and the smallest set of permissions that lets it do the task.

For agents that read untrusted content (anything from the internet, from users, from documents you did not write), the default is the left column only. The middle column is granted per task and revoked after. The right column is never granted to an automated identity; a human does those things, and the audit log says which human.

The audit trail

When something goes wrong - and when a customer or auditor asks - you need to answer four questions about any change:

1. Who merged it? A human name. Branch protection makes this automatic.
2. What tool produced it, and which model? The Co-authored-by trailer gives the tool; the model is in the tool's own logs if you have an enterprise tier. Some teams add a PR template field.
3. What did the agent read and run? Enterprise tiers of the major tools retain session transcripts. Know where they are, how long they are kept, and who can read them.
4. What did review find? PR comments, review decisions, CI results. Standard GitHub, as long as reviews actually have comments.

If you can answer those four for any commit in the last year, you have an audit trail. If you cannot, fix the gap before you need it.

Talking to auditors and customers

You will be asked about AI in your development process on security questionnaires and in compliance audits. The questions map to frameworks you may already follow:

Framework	What they will ask	What you point at
SOC 2 (CC6, CC7, CC8)	Access control for AI tools; change management for generated code; monitoring	Scoped identities, branch protection, review requirements, audit trail
ISO 27001 (A.8, A.5.23 cloud services)	Supplier management for AI providers; data handling	Provider data-processing terms; data classification policy; approved-tool list
EU AI Act	Are you a provider or deployer of a high-risk AI system?	For coding assistants used internally: you are a deployer of a general-purpose AI system, and the obligations are mostly transparency and documented use. For AI features you ship to customers, the classification depends on the use case - get legal advice
Customer questionnaires	"Do you use AI to write code? Is our data used to train models?"	The policy; the provider's zero-retention terms; the data section

You do not need to be a lawyer. You need to be able to say: here is our policy, here is how it is enforced, here is the trail that proves it was followed. That sentence, backed by the configuration in this chapter, answers most of what you will be asked.

Summary

• One page, concrete lines, each mapped to an enforcement mechanism.
• Governance is mostly configuration: branch protection, CI gates, ignore files, scoped identities.
• Agents are users with the smallest necessary permissions; never approve, merge, or touch production.
• The audit trail answers: who merged, what tool, what the agent read and ran, what review found.
• For auditors: policy, enforcement, trail.