# Writing down how the team uses agents

> Write the team's practice for agent use into the project instructions file, starting from the incidents in the project's history, take out the rule no incident supports, and decide which agreements a hook or a CI check also enforces.

Page: https://schubergphilis.github.io/ai-training/coding-with-agents/team-practice/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

The lessons of this part each gave the team one agreement. The
[lesson on attribution and review](https://schubergphilis.github.io/ai-training/coding-with-agents/attribution-and-review-norms/)
agreed how a change says what the agent did. The
[lesson on hooks and CI](https://schubergphilis.github.io/ai-training/coding-with-agents/ci-and-hooks/) made two rules
run by themselves, and the
[lesson on parallel sessions](https://schubergphilis.github.io/ai-training/coding-with-agents/parallel-sessions/)
kept sessions away from what they share. This last lesson of the course
doesn't add a new idea. We write those agreements down as the team's practice
for agent use, starting from the mistakes the team has seen. Then we
decide which of them a check enforces.

## Why the practice is written down

Ask five engineers how the team uses agents, and when nothing is written
down you get five answers. Each person follows the habits they built in
their own sessions. The agents follow none of them, because an agent
knows only what is in its context. A habit in someone's head never gets
there. A file that the agent loads at the start of every session does.

That file is the project instructions file from the
[lesson on project instructions](https://schubergphilis.github.io/ai-training/coding-with-agents/project-instructions/),
`AGENTS.md` or `CLAUDE.md` at the root of the repository. The Claude Code
documentation says that the agent reads the project's file at the start of
every session. The file reaches the whole team through the repository, and
the documentation advises keeping personal preferences out of it
(How Claude remembers your project, Claude Code documentation). A change to the practice is then a change to a
file, and it gets a diff and a review like any other change.

The practice section of that file says:

- what agents may do, and what every change must pass before it merges,
- how agent work is attributed in commits and pull requests,
- how agent work is reviewed, and what the author does before asking,
- which directories and commands are off limits to agents.

This course's repository is a worked example. Its `AGENTS.md` says that
the full check must pass before a push, that no agent pushes to `main`,
and that every commit message an agent writes ends with a
`Co-Authored-By` line and an `Assisted-by` line and carries no
`Signed-off-by` (Agent Instructions for ai-training, AI Training repository, AGENTS.md). The AI-native software development
playbook on Claude Academy has a lesson on the `CLAUDE.md` file, and its
course page describes that file and the team's skills as knowledge the
team keeps in versioned files that the agents read
(The AI-native SDLC playbook, Claude Academy).

#### Checkpoint: Where does the answer go?

A new engineer asks whether an agent may push to a shared branch, and the
other four engineers give three different answers. Where does the team
write the answer, so that every person and every agent session works from
the same one?

- On a page of the team wiki that every new member of the team reads in their first week.
- In the user instructions file of each engineer, the one their own agent loads in every session.
- In the project instructions file in the repository, where each change to it gets a review.
- In the minutes of the team meeting where the five engineers agreed on the answer together.

## Start from the mistakes you have seen

A few lines of the practice are decisions the team makes once, at the
start: the check every change passes, and the form of the attribution
trailer. The other lines come from incidents. An incident is a change the
team had to take back or repair, and each one shows a mistake that
happened on this project, with these people and these agents. A rule
written from an incident guards against a mistake the team knows it
makes. Write the incident next to the rule. A reader then knows why the
rule is there and can tell when the reason is gone.

The fixture for this lesson is a small invoice project in the course
repository under `site/examples/coding-with-agents/team-practice/`. Its
`AGENTS.md` has a practice section that the team wrote before any of the
incidents in its history:

```markdown
## Working with agents

- Be careful with dependencies.
- Don't lose other people's work.
- Say when an agent helped with a commit.
- Agents never edit the database migrations in `migrations/`.
```

#### Example: The invoice project's history

The course's script builds the project's git history with fixed dates and
prints each commit, oldest first, with its message body indented under
it. Run it from `site/examples/coding-with-agents/team-practice/` in your
clone of the course repository, and compare what you see with the output
below.

```sh
python3 history.py
```

Output:

```text
2026-05-04  chore: the invoice service
2026-05-11  feat: export invoices as CSV
            Assisted-by: Claude:claude-sonnet-4-6
2026-05-12  Revert "feat: export invoices as CSV"
            The agent ran the lock command while it added the export,
            and requirements.lock upgraded both dependencies. The review
            read invoices.py and skipped the lockfile, and the release
            failed its smoke test.
2026-05-13  feat: export invoices as CSV, lockfile unchanged
            Assisted-by: Claude:claude-sonnet-4-6
2026-05-18  feat: a due date on each invoice
2026-05-27  feat: discount for early payment
            Assisted-by: Claude:claude-sonnet-4-6
2026-06-02  fix: cap the early-payment discount at five days again
            Two agent sessions ran in two worktrees of one clone. The
            invoice session stashed its cap on the discount, and the
            report session popped that stash into its own worktree and
            discarded it with its other changes. The discount shipped
            without the cap.
2026-06-08  docs: list the invoice rules
2026-06-16  feat: late fee on overdue invoices
            Assisted-by: Claude:claude-sonnet-4-6
            Signed-off-by: Coding Agent <agent@example.com>
2026-06-17  Revert "feat: late fee on overdue invoices"
            The commit ends with a sign-off in the agent's name. Our
            sign-off certifies the Developer Certificate of Origin, and
            only a person can give that.
2026-06-18  feat: late fee on overdue invoices
            Assisted-by: Claude:claude-sonnet-4-6
            Signed-off-by: Robin <robin@example.com>
```

This example isn't graded. Three of the commits take back or repair an
earlier one, and their messages say what went wrong. You write the
practice from them in the exercise at the end of the lesson.

The practice also changes when the mistakes change. When a review finds
the same kind of mistake a second time, it gets a line, as the
[lesson on hooks and CI](https://schubergphilis.github.io/ai-training/coding-with-agents/ci-and-hooks/) said. A rule
whose reason is gone comes out, for example because the thing it guarded
no longer exists. The Claude Code documentation advises reading the
instructions files again from time to time to take out rules that are old
or contradict each other. It adds that a longer file uses more context and
the agent follows it less well (How Claude remembers your project, Claude Code documentation).

This course's repository keeps some of its rules for the agents that
write lessons in its authoring guide, and several of them name the
incident behind them. The rule that every number in the prose that a
fixture can produce is pasted from its output has its reason next to
it: in one group of agent branches, several had a number worked out by
hand that the fixture contradicted. The rule to check every invented
name comes from a made-up freight company that turned out to be real
(Writing a lesson, AI Training repository, docs/agents/writing-a-lesson.md).

#### Pitfall: Thirty rules for the agents they imagined

A team wrote its agent practice in a one-hour meeting, before anyone had
used an agent on the code. It had thirty rules on which files an agent
may read and how many lines it may write. In the first two months the
agents committed generated files from the build folder, and reviewers
approved pull requests they had only skimmed. The thirty rules missed
both mistakes, and nobody could say which rules were still needed. Write
the practice from the incidents you have, add a rule when a new mistake
shows up, and take out each rule that has no incident or day-one decision
behind it.

#### Checkpoint: A year of practice

The practice section has a rule that agents never edit `migrations/`,
written in the first week. The project has no database. This month two
agent pull requests changed the CI workflow file to skip a failing job.
What do you change in the practice?

- Add the rule on the workflow file, and keep the migrations rule, because a rule that never fired costs nothing.
- Leave the file as it is, and remind the team in chat to look for workflow edits in each review.
- Rewrite the whole section from a new list of risks that the team collects in a one-hour meeting.
- Add a rule on the workflow file that names the two pull requests, and remove the migrations rule.

## Say it in the file, check it where a script can

The practice section draws together what this part of the course taught.
Parallel sessions run in worktrees, each on its own branch, and leave
alone what the clone and the machine have only once. CI integration makes
one check the gate for every change, whoever wrote it. Team hooks stop an
agent's step before it happens. Review norms say what the author does
before asking for a review and what the pull request says. Attribution
names the agent in a trailer, and only a person signs off.

Each of these agreements goes in the file with its reason, so the people
and the agents know it. The file doesn't enforce anything. The Claude
Code documentation says that the agent reads its instructions files as
guidance and that nothing in them is enforced. For an action that must
never happen, it recommends a `PreToolUse` hook, which runs before the
tool call and can stop it (How Claude remembers your project, Claude Code documentation). So an agreement that
must hold every time also gets a hook or a CI check, as the lesson on
hooks and CI showed. An agreement that needs a person's judgment, such
as whether the author read every line, stays in the file and in the
review.

This course's repository does both for the stash. Its page on
orchestration says that agents never run `git stash` in any worktree and
gives the reason, the one stash that all worktrees of a clone share. A
hook in the repository rejects the command (Orchestrating agents, AI Training repository, docs/agents/orchestration.md).

#### Checkpoint: Which rule does each incident support?

Match each incident to the rule it supports.

Statements:

- An agent edited the recorded test data until a failing test passed, and the pull request was approved
- Two sessions in worktrees of one clone used the same port, and one checked pages the other served
- An agent put its trailer in the middle of the body, and the count of agent-assisted commits missed it

Options:

- Agents never edit tests/recorded/, and a hook blocks it
- Agents check pages with the build and never start the dev server
- Agent commits end with an Assisted-by trailer in the last paragraph
- Agents write at most 200 lines in one session

#### Checkpoint: Does a check enforce it too?

Buckets:

- The file says it, and a hook or CI check enforces it
- The file says it, and people keep to it

Items:

- Agents never run git stash in any worktree
- No commit carries a Signed-off-by in the agent's name
- The lockfile changes only in a pull request of its own
- The author reads every changed line before asking for review
- The pull request says truthfully what the author ran and saw

## Exercise

Build the invoice project where you can read it with git. From
`site/examples/coding-with-agents/team-practice/` in your clone of the
course repository, run this, with a folder name that doesn't exist yet:

```sh
python3 history.py ~/invoices
```

In `~/invoices`, read the history with `git log` and each incident with
`git show`. Then rewrite the "Working with agents" section of `AGENTS.md`
there. Write one rule for each of the three incidents, precise enough
that a reviewer can tell whether a change breaks it, and give the date of
the commit it came from. Say after each rule whether a hook or a CI check
should also enforce it, and which one. Drop the rule that no incident
supports. Delete `~/invoices` when you are done, and run the script again
to start over.

A good result has three rules, each tied to one of the two reverts or
the fix, and none of them as vague as the draft's
lines. The rule with no incident behind it is gone, and the section is
shorter than a screen. A colleague who reads only the section could say
why each rule is there. Then answer one question: which rule of your own
team's practice could nobody tie to an incident or a decision, and what
would happen if you took it out?

Stretch: Do the same for a repository your team uses with agents: read the last three months of history for reverts and fixes of agent work, and compare what you find with the practice section of its instructions file.

## Recap

1. Write the team's practice for agent use in the project instructions file, where every person and every agent session reads it (How Claude remembers your project, Claude Code documentation). It says what agents may do and what every change passes, how agent work is attributed and reviewed, and which directories and commands are off limits.
2. Make the gate and the attribution form decisions at the start. Write every other rule from an incident the team has seen, and name the incident next to the rule.
3. Add a rule when a mistake comes back. Read the file again from time to time (How Claude remembers your project, Claude Code documentation), and remove a rule when its reason is gone or no incident or day-one decision is behind it.
4. The file states each agreement and its reason. An agreement that must hold every time also gets a hook or a CI check, and one that needs a person's judgment stays with the review.

#### Habit

The next time a review finds an agent mistake that the team has seen before, add a rule to the practice section with the date or the pull request it came from.

## References

- How Claude remembers your project, Claude Code documentation, https://code.claude.com/docs/en/memory
- Agent Instructions for ai-training, AI Training repository, AGENTS.md, https://github.com/schubergphilis/ai-training/blob/cb658ad1859c1931f36b58fe8315e1883a927643/AGENTS.md
- The AI-native SDLC playbook, Claude Academy, https://academy.claude.com/courses/ai-native-sdlc-playbook
- Writing a lesson, AI Training repository, docs/agents/writing-a-lesson.md, https://github.com/schubergphilis/ai-training/blob/cb658ad1859c1931f36b58fe8315e1883a927643/docs/agents/writing-a-lesson.md
- Orchestrating agents, AI Training repository, docs/agents/orchestration.md, https://github.com/schubergphilis/ai-training/blob/main/docs/agents/orchestration.md