The problem: every engineer has their own invisible AI standard
In teams of 50-200 engineers, I see the same thing: one engineer lets Cursor write migrations, another does not. One lets an agent into production scripts, another never does. One immediately merges AI-generated tests, another requires manual verification. Every engineer chooses the standard independently.
Result: AI rollout cannot be controlled. Every review becomes re-litigation of basic rules: “well, I thought this was allowed.” The first incident shows that rules do not formally exist. README exists, a Confluence page exists, but nobody reads them, and agents certainly do not.
The cost of the problem is review tax
Without explicit rules, AI-generated diffs enter review with different degrees of “trust” from seniors. One spends 10 minutes, another spends an hour on the same volume, because they do not know: can this be trusted, was there SDD, did someone check boundary conditions. This is direct review tax, and it grows linearly with the number of AI tools in the team.
Solution: policy-as-code in three layers
Working frame: rules live in the repo, next to code, as files the agent must consider. The agents.md standard formalizes this. Steering files extend it with “how to reason.” Hooks add the event-driven layer: “before every commit, run a check,” “before deploy, reread the security checklist.”
| Layer | What it expresses | Where it lives | When it runs |
|---|---|---|---|
agents.md | Explicit rules: allow / deny, formats, style, owners | Repo root + service folders | On every prompt in this folder |
| Steering files | How to reason: step order, what not to do nearby | .kiro, .cursor, .claude | On every prompt |
| Hooks | Automated actions before/after an event | hooks, git hooks, CI | pre-commit, post-edit, pre-deploy |
The set is interchangeable: agents.md without hooks is declaration without enforcement. Hooks without agents.md are enforcement without context. Steering without the rest is pleasant engineer tuning without organizational effect.
What belongs in agents.md
Below is the minimal agents.md skeleton I have seen work in teams of different sizes.
- Project context (3-5 lines): what the service is, stack, versions.
- Coding standards: what is allowed and what is forbidden.
- Boundaries: which files/services cannot be touched without review.
- Data rules: what to do and not do with PII, secrets, production data.
- Tool use: which tools the agent may and may not use.
- Output format: return a diff, not the whole file. Keep commits conventional.
- Owners: who owns the file, CODEOWNERS-style inside the file.
Steering files: “how to reason”
agents.md describes boundaries. Steering files describe the thinking process. These are different things and easy to confuse.
- Step order for refactoring: “first a test for current behavior, then changes, then test expansion.”
- Step order for a new feature: “spec -> acceptance criteria -> API contract -> implementation -> tests -> provable examples.”
- Limits on “refactoring along the way”: “if you see a problem in a neighboring file, create a separate issue, do not fix it in this PR.”
- Error-analysis template: “reproduce -> localize -> fix -> add regression test.”
Difference from agents.md: agents.md is read once per session as a list of rules. Steering is lived through at every reasoning step.
Hooks: event-driven layer
Hooks are what move governance from “wishes” to “enforcement.” A typical event set:
- on-edit: recalculate types, run linter on changed files.
- on-save: format, check that there are no secrets.
- pre-commit: run fast tests, check PR size.
- pre-pr: check against
agents.md: forbidden files untouched, commit formatted correctly. - pre-deploy: check security checklist, ask a human for confirmation.
Key property: hooks live in the repo and apply equally to all engineers and all agents. Individual IDE settings do not solve this.
Notion Agents: governance layer over docs
agents.md in the repo solves governance inside code. But a second layer lives nearby: specs, runbooks, ADRs, onboarding docs. Product teams, support, and sales live there too.
What Notion Agents actually give in this context:
- Answer rules from your docs base: answer only from the “E” section, if there is no answer, say “I do not know.”
- Access isolation by teamspaces: the sales agent cannot see finance docs.
- Triggers on page changes: “when this page updates, reindex,” “when a spec is created in this database, notify the owner.”
- Audit log: who asked, what the agent answered, which pages it used.
The parallel with agents.md is direct: in both cases, rules live next to content, tied to an owner and access model.
What breaks at scale
- 30 engineers: one
agents.mdat root + simple hooks work. Steering files are optional. - 50-100 engineers: service-level
agents.mdwith enforcement through hooks is needed. Without this, teams diverge in style and security standards. - 100+ engineers: without explicit ownership for
agents.mdand regular review, the file grows, contradicts itself, and gets ignored.
Minimal steps for 2-4 weeks
- Write
agents.mdfor 1-2 key repos: 100-200 lines with all 7 sections above. - Add 2-3 hooks: pre-commit, pre-pr, pre-deploy.
- Assign an owner for
agents.md(a name, not "the team"), put the file under CODEOWNERS. - Review
agents.mdonce a quarter with a separate checklist, like an ADR. - Add basic steering files immediately or after the first quarterly review.
Metrics that show something changed
- Share of PRs that pass hooks without manual fixes. Goal: above 80% after the first two weeks of adaptation.
- Number of repeated comments from seniors. Should fall because chronic comments get codified.
- Incident analysis speed. Should increase because audit log + owners give a quick answer to “who and why.”
FAQ
How is agents.md different from README or CONTRIBUTING?
README and CONTRIBUTING are written for humans and assume "read once." agents.md is written for AI and assumes "reread on every prompt." That explains strict wording, limited size, and orientation toward rules.
If we have several IDEs and tools, how do we bind them to agents.md?
Keep one agents.md as the source of truth, generate the other formats from it through a script + CI. Manual synchronization diverges within a month.
We do not use Kiro or Claude Code, and there is nowhere to define hooks. What do we do?
Hooks are effectively git hooks + CI checks. Take husky / lefthook + GitHub Actions and define the same events. A pre-PR check against agents.md is implemented as a CI job.
Should we forbid engineers from having personal rules?
No. People will have personal settings anyway. What matters is that shared rules have priority over personal ones and live in the repo.
How is agents.md connected to the AI Act?
agents.md captures operational guidance for the AI system together with audit log through hooks. It is one formal artifact the organization should be able to show: rules are described, compliance is checked.