How to brief a coding agent so it follows team decisions

To get a coding agent to follow team decisions, put those decisions in an instruction file the agent reads every session, write them as specific rules with the reason attached, and give each task a short brief with a clear definition of done. For anything that must never happen, enforce it with hooks or CI instead of trusting the instructions.

Coding agents are good at reading code. They are bad at knowing why the code looks the way it does. That gap is where they reintroduce the library you removed, or "fix" the pattern you chose on purpose.

Why coding agents ignore team decisions

Each agent session starts with a fresh context. Cursor's docs put it simply: models don't retain memory between completions (Cursor rules docs). So the agent rebuilds its picture of your project from whatever it reads in that session.

That causes three problems:

• The code contains old patterns too. If half the codebase still uses the old date library, the agent may well copy it.

• Decisions live outside the repo. "We stopped using Redux in March" was agreed in a meeting and lives in a Slack thread.

• Nobody told it what not to touch. The agent doesn't know that billing/ is frozen until the audit is done.

None of this is a model problem. It's a briefing problem.

Where agent instructions live

Most coding agents read a Markdown file of instructions at the start of a session. The three you'll meet most:

If your team uses more than one agent, keep one source file. Write your team's rules in AGENTS.md, and if you use Claude Code alongside a CLAUDE.md, import it with a line like @AGENTS.md so both tools see the same rules. Check each tool's docs for its current behavior, because these details change.

What to put in the file

Keep it short. Anthropic suggests aiming for under 200 lines per CLAUDE.md, because longer files use more context and reduce how well the agent follows them. Cursor suggests keeping rules under 500 lines and splitting large ones up. A good team file has five parts:

1. Commands. How to install, build, test and lint. Exact commands, not descriptions.

2. Conventions. Naming, file layout, error handling, where new code goes.

3. Decisions, with reasons. What you chose, what it replaced, and why.

4. Boundaries. Folders, files or systems the agent must not change.

5. Definition of done. What has to pass before the agent says it's finished.

Here's what the decisions section might look like:

## Decisions
- Use date-fns for dates. Moment is deprecated here (bundle size). Don't add new Moment imports; migrate when you touch a file.
- Server state uses TanStack Query. We removed Redux in 2026-03. Don't reintroduce it.
- Money is stored as integer cents. Never use floats for prices.
- All new API routes need an integration test in tests/api/.

## Boundaries
- Don't edit anything in billing/ without asking first.
- Don't change database migrations that have already shipped.

Write decisions an agent can follow

The way you phrase a rule matters as much as having it.

Be concrete enough to check

Claude Code's docs give good examples: "Use 2-space indentation" instead of "Format code properly," and "Run npm test before committing" instead of "Test your changes." If you can't tell whether the agent followed a rule, it can't either.

Include the why

"Don't use Moment" gets followed until the agent finds a case where Moment seems easier. "Don't use Moment, we removed it to cut bundle size" lets the agent reason about edge cases the way a teammate would.

Point, don't paste

Link to the source of a decision rather than copying the full write-up into the file. Cursor's docs recommend referencing files instead of copying their contents. A line like "See docs/decisions/014-state-management.md" keeps the instruction file short and the reasoning in one place. If you don't have a place for that reasoning yet, start a decision log.

Remove contradictions

If two instructions disagree, Anthropic notes that Claude may pick one arbitrarily. When a decision changes, delete the old rule in the same pull request that adds the new one.

Brief each task, not just the project

The instruction file covers how your team works. Each task still needs its own short brief. A template that works:

• Goal: what should be true when this is done, in one sentence.

• Context: links to the ticket, the relevant decision, and one or two example files.

• Constraints: what not to change, which patterns to follow.

• Done means: tests pass, lint is clean, and a specific behavior works.

• Out of scope: the nearby thing it shouldn't fix in this pass.

Example: "Add CSV export to the invoices page. Follow the pattern in reports/export.ts. Use the existing formatCents helper for amounts. Don't touch billing/. Done means the new test in tests/api/invoices.test.ts passes and the export matches the columns on screen. Don't refactor the table component."

That's six sentences, and it heads off the most likely ways the task could go wrong. If the same brief shape keeps working, turn it into a shared template. Turning one person's best prompt into a team skill covers how.

Enforce what really matters

Instruction files guide the agent. They don't stop it. Claude Code's docs say instructions are treated as context, not enforced configuration, and point to hooks when you need to block an action no matter what. Use the right layer for each rule:

• Style and conventions: instruction file, plus a linter or formatter.

• Architecture rules (no new Redux, no floats for money): instruction file, plus a lint rule or CI check where you can.

• Hard boundaries (never push to main, never touch production secrets): permissions, hooks and branch protection.

The more a rule matters, the less it should depend on the agent remembering it.

FAQ

Should I use AGENTS.md or CLAUDE.md?

If your team uses several coding agents, AGENTS.md is read by the widest set of tools. If you also use Claude Code, it reads AGENTS.md when there's no CLAUDE.md, or you can import AGENTS.md from a CLAUDE.md.

How long should an instruction file be?

Short enough that every line earns its place. Anthropic suggests under 200 lines for CLAUDE.md, and Cursor suggests under 500 lines per rule. Move area-specific rules into scoped files.

Can the agent update the file itself?

It can draft changes, and that's useful after a review where it got something wrong. Have a person approve the change in a pull request, like any other code.

What if decisions change often?

Then the file should point to where decisions live instead of copying them, and someone should own updating it. Stale rules are worse than none, because the agent follows them confidently.

Wrapping up

A coding agent follows team decisions when it can read them, understand why they exist and check its own work against a clear definition of done. Keep the instruction file short, keep decisions in one place, and enforce the rules that can't be broken. We're building Shane to keep your team's decisions in one place and hand them to every coding agent and AI tool you use, with sources. If that's a problem your team has, you can join the waitlist at tryshane.ai.