Guardrails, skills and workflow for agents

Intent

This pattern assumes a team using AI coding agents across several repos, with AGENTS.md as each repo's entry point. It splits agent instructions into three layers, by the question each one answers: guardrails for what any output must look like, skills for how this business builds a given thing, and workflow for how work moves through delivery. This enables three outcomes:

1. What agents produce meets your standards, without anyone restating them in every prompt.
2. A correction goes in one place, and reaches every repo, person and agent tool.
3. A large library takes up little context, because each instruction loads only when a task needs it.

Motivation

Most teams start with one instructions file, and add to it each time an agent gets something wrong. That file grows until it fails in three ways:

1. Agents skim it. Coding rules, build guides and process steps all compete for the same context window.
2. Corrections have nowhere to go. When an agent gets something wrong, nobody can tell which line to change, so the same mistake comes back.
3. Rules get copied. Each repo ends up with its own version, and the versions drift apart.

This pattern separates instructions by why they change. Guardrails change when a standard does, rarely and deliberately. Skills change as the architecture and libraries move on. Workflow changes with the team's process. Kept apart, a correction goes in one place, and a reviewer can tell from where a change sits whether it's a rule, a technique or a process. All three layers live in one versioned repo, reviewed like code, so every repo gets the same version of all of them.

Applicability

Use this pattern when:

1. A team uses AI coding agents, and wants what they produce to meet its standards without restating them in every prompt.
2. The same rules and know-how should hold across many repos, people or agent tools.
3. Agents take part in delivery, not just in writing code, so how they plan, stop and hand over matters as much as what they write.

Do not use this pattern when:

1. You have one repo with a handful of rules, where a single AGENTS.md is enough. Split into layers once rules repeat across repos, or the file grows past what an agent reads closely.

Structure

Participants

Constraints and trade-offs

1. There's more to own. Three layers, plus each repo's AGENTS.md, need owners and upkeep, or they drift from the code they describe.
2. Instructions are context, not controls. Language models are non-deterministic, so an agent can ignore a guardrail or fail to load a skill, and anything that must hold also needs enforcing by the platform, through CI gates, protected branches and the agent's permissions.

Part of how I deliver

When a team adopts AI coding agents, this is the foundation I put in first. It's one of many patterns I bring through contract delivery, and the layers grow with your team's own standards and architecture.

Related