Shared Agent Instruction Conventions
A convention guides an agent only when the session loads the relevant instruction. On a solo project, one file may be enough. On a team, developers sometimes copy the same convention into separate instructions, and those copies drift apart quietly.
One developer's AGENTS.md says: never write raw SQL, always use the ORM. A developer who joined later never saw the discussion where that was decided, and their own AGENTS.md says nothing about it. Their agent hits a performance problem and writes a raw query. The query is defensible in isolation. It is also out of step with every other data access path in the codebase, and the team burns a review cycle deciding whether to apply the rule retroactively or carve an exception.
Nothing in the shared instruction set told the agent the convention existed.
The team-level fix is one shared instruction set. Check that each agent setup loads it when a session starts.
Team-level AGENTS.md
On a solo project, AGENTS.md functions as a personal instruction set. On a team, the same file has to work as a shared one: it documents conventions every developer and every agent should follow, and unlike the solo version, it needs an owner and a review process.
The practical structure: AGENTS.md at the repo root is the team's instruction set. It covers conventions that apply to every change: code style, test naming, security rules, dependency hygiene, data access patterns, and which sections of docs/ to read for context. Individual developers do not maintain parallel AGENTS.md files that override the team instruction set.
Where teams get into trouble: the instruction set grows to cover every edge case a developer has explained to an agent. A long entry file spends context on unrelated rules and hides the security convention a task needs. The TOC pattern keeps AGENTS.md short and links to detail files in .agents/instructions/.
Sources: AGENTS.md (ongoing), the AGENTS.md convention as a shared project instruction set. AgentPatterns.ai, "AGENTS.md: Project-Level README for AI Coding Agents" (ongoing), keeping the instruction set short and linking out to detail files.
Shared .agents/skills/ libraries
Skills worth writing once and sharing: generate a change folder from a template, run the credibility pass on a draft spec, check task completion and test evidence before finishing a ticket, validate that AC IDs are in the AC registry. These live in .agents/skills/, referenced from AGENTS.md, and committed to the repo.
Skills also travel across repos via an inner source: a shared .agents/ repository teams pull from, or a directory within a shared infrastructure repo. The principle is the same as shared library dependencies: standardize what is common, extend for what is specific.
Sources: Sharing a skill library across repositories is this book's proposed team convention.
Onboarding: the first agent session
The test of a team AGENTS.md is a new developer's first agent session. They clone the repo, start a capability-class agent, and ask it to implement a small task. The output should match the team's existing test style, data access pattern, and security conventions.
If the output is inconsistent, first check which instruction files the session loaded. Then inspect whether the shared rule is missing, stale, or in conflict with another rule. Fix the file or loading path responsible, and repeat the small task before relying on the convention.
Onboarding exposes instruction drift while the task is small enough to inspect. Record the observed failure so the next developer does not have to diagnose it again.
Sources: AgentPatterns.ai, "Evaluating AGENTS.md" (ongoing), evaluating agent context files for quality and drift. The first-session onboarding test is this book's team workflow heuristic.
When to standardize, when to leave divergent
Not every developer convention belongs in the team instruction set. Personal notes, exploratory model choice, and local branch names before the change folder exists stay local.
The test: if developer A and developer B follow a convention independently, and the outputs would be inconsistent in the same codebase, standardize it. If the convention affects only local workflow and does not show up in committed code, leave it divergent.
Standardize data access patterns and security rules. Record the ticket-number proposal naming rule in the shared instructions too. Leave the choice of editor and personal shortcuts for invoking shared skills up to the individual.
Over-standardizing is its own failure mode. A team AGENTS.md that specifies every workflow detail produces brittle agents and developers who stop making local judgment calls. The team instruction set should specify conventions that affect the codebase. Everything else is a personal setup.
Role-based personal instruction sets are not divergence. A QA engineer's instructions might load extra test-coverage instructions, a security engineer's might run a threat-model pass, and a database specialist's might include query-plan analysis. These extend the team instruction set without contradicting it.
Depth is welcome in a personal instruction set. Overriding a team convention in one is not, and it becomes a review problem the moment someone notices.
Team conventions are organizational problems with technical artifacts. AGENTS.md records the agreement. A team that has never discussed data access conventions has to have the discussion first and record the outcome.
Shared conventions work within a team. Cross-team coordination needs a different mechanism, one already part of the SDLC and visible outside a single codebase.
Sources: AGENTS.md (ongoing), project-level instruction set as a repo convention. The standardize-versus-diverge test and agreement-before-instructions rule are this book's synthesis for team use.