Team rules for coding agents

Four decisions are enough to get started: what the agent may touch, what it may run, what the machine verifies, and what a human still has to approve. Without them, every developer invents their own agentic workflow and review absorbs the differences.

This framework comes from two limited settings: my daily setup, equipped with roughly fifteen hooks, and a Kilo Code rollout in a development team. I have not tested it in a hundred-developer organization. At that scale, the same principles may hold, but roles, access, and auditing require additional work.

Which rules are worth writing down?

An instruction file carries context the agent cannot infer: project commands, local conventions, scope limits, and exit criteria. The document should stay short enough to be read. Generic rules consume space without changing a decision.

For an application repository, the first version can fit into four sections:

## Scope
- Only modify files required by the request.
- Never add `.env` files or secrets to the repository.

## Checks
- Run types, lint, then the relevant tests.
- Show the output before declaring the work complete.

## Human approval
- Do not push or merge without an explicit request.

Codex reads AGENTS.md files before working and composes instructions from the root to the current directory. A subdirectory can therefore refine commands for one service without duplicating the whole repository policy. OpenAI documents this instruction hierarchy.

What can remain at the agent’s discretion?

Freedom should follow the cost of a mistake. Reading the repository, proposing a plan, or running a local test can be corrected easily. Publishing, changing permissions, transmitting data, or running a destructive command affects more than the diff: the team must decide who keeps control.

A short matrix removes ambiguity:

Action	Default	Expected control
Read and search the repository	Allowed	Project scope
Modify requested code	Allowed	Diff limited to the task
Run types, lint, and tests	Allowed	Versioned commands
Install a dependency	Confirm first	Rationale and official source
Push, merge, or publish	Confirm first	Explicit human approval
Handle a secret	Denied by default	Dedicated channel and tool

The table does not try to predict every tool. It defines authority. A new tool inherits the rule matching its actual effect.

Which rules should become automated checks?

A convention remains useful when it requires judgment. A binary condition is better enforced by an automated check: lint passes or fails, a sensitive file is present or absent, a review ran or it did not.

In my current setup, commits are blocked until a review has run, and pushes require types, lint, and tests in that order. These checks removed repeated verification from my head, but they also added code to maintain. The guardrails dispatch documents the hooks and their cost in detail.

The right enforcement point is the cheapest one that still catches the error in time. Formatting belongs in lint. A rule that must prevent a commit belongs in a hook. A system-level incompatibility stays in CI or review.

How should a team roll these rules out?

The first rollout should remain small enough for false positives to stay visible. One pilot project, two or three task types, and a few weeks provide more information than a policy written before the first use.

1. Version the commands and limits the team already shares.
2. Add one automated check for a mistake that actually happened.
3. Record blocked actions and substantial review corrections.
4. Fix the rule before applying it to a second repository.

My team’s Kilo Code rollout confirmed one point: tool choice matters less than how the team integrates it. A model that fails on real tasks can kill adoption; a capable model without shared rules merely moves the cost into review. This remains one team’s experience on a PHP/TypeScript stack, not a universal measurement.

How do you know whether the rules help?

Generated code volume says nothing about delivered work. Four measurements are enough for a first feedback loop:

• substantial corrections requested in review;
• tasks that pass checks on the first attempt;
• time spent unblocking sessions;
• incidents prevented or detected before push.

Measure the baseline before the pilot. Without a comparison, fewer review comments can look like success even when the team has merely assigned easier tasks to the agent.

When does this framework become too heavy?

A disposable script or experiment repository does not need the same machinery as a production application. Two written rules and a diff review may cover the risk. Adding a hook, a dashboard, and an escalation procedure would then cost more than the prevented error.

The opposite limit also exists. Once an agent can touch several repositories, call external services, or act without direct supervision, repository rules no longer cover everything. Identity, permissions, activity logs, and isolation become platform concerns.

Resources and next steps

OpenAI documents the AGENTS.md instruction hierarchy and how Codex composes project rules.

Continue with:

• Agentic workflow: the founding principles
• Managing context in a multi-agent workflow
• Guardrails vs guidelines: why I left CLAUDE.md