Writing down how the team uses agents

The lessons of this part each gave the team one agreement. The lesson on attribution and review agreed how a change says what the agent did. The lesson on hooks and CI made two rules run by themselves, and the lesson on 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, 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 [1]. 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 [2]. 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 [3].

Checkpoint · choice

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.

CheckHintSkip

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:

## 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 · run it

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.

python3 history.py

Output

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>

Output verified in CI from site/examples/coding-with-agents/team-practice/history.py.

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 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 [1].

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 [4].

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 · scenario

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.

DecideHintSkip

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 [1]. 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 [5].

Checkpoint · match

Which rule does each incident support?

Match each incident to the rule it supports.

An agent edited the recorded test data until a failing test passed, and the pull request was approvedChoose…Agents never edit tests/recorded/, and a hook blocks itAgents check pages with the build and never start the dev serverAgent commits end with an Assisted-by trailer in the last paragraphAgents write at most 200 lines in one session

Two sessions in worktrees of one clone used the same port, and one checked pages the other servedChoose…Agents never edit tests/recorded/, and a hook blocks itAgents check pages with the build and never start the dev serverAgent commits end with an Assisted-by trailer in the last paragraphAgents write at most 200 lines in one session

An agent put its trailer in the middle of the body, and the count of agent-assisted commits missed itChoose…Agents never edit tests/recorded/, and a hook blocks itAgents check pages with the build and never start the dev serverAgent commits end with an Assisted-by trailer in the last paragraphAgents write at most 200 lines in one session

CheckHintSkip

Checkpoint · sort

Does a check enforce it too?

Unplaced (drag an item to a bucket, or select it and then click the bucket)

Agents never run git stash in any worktreeNo commit carries a Signed-off-by in the agent's nameThe lockfile changes only in a pull request of its ownThe author reads every changed line before asking for reviewThe pull request says truthfully what the author ran and saw

The file says it, and a hook or CI check enforces it

The file says it, and people keep to it

CheckHintSkip

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:

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 [1]. 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 [1], 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.

You can now

• Sets the team's practice for agent use

Mark lesson finishedI know this, skip it

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

1. Anthropic. How Claude remembers your project. Claude Code documentation. Reference. Claude Code memory
2. The AI Training contributors. Agent Instructions for ai-training. AI Training repository, AGENTS.md. Reference. AI Training AGENTS
3. Anthropic. The AI-native SDLC playbook. Claude Academy. Course. Academy ai-native-sdlc-playbook
4. The AI Training contributors. Writing a lesson. AI Training repository, docs/agents/writing-a-lesson.md. Reference. AI Training writing-a-lesson
5. The AI Training contributors. Orchestrating agents. AI Training repository, docs/agents/orchestration.md. Reference. AI Training orchestration