How We Built a Team Instructions Layer for Our AI Agent Fleet

We run over a dozen specialized AI coding agents across our infrastructure. Each handles a different domain—one manages workflow automation, another handles infrastructure, another focuses on web development, another on marketing. Each agent has its own project directory with a configuration file containing behavioral rules.

Over time, we accumulated hundreds of operational lessons in our shared knowledge base—things like "never deploy to production without pushing to remote first" and "always store credentials in the centralized vault, not in environment files." A friction audit revealed a pattern we hadn't expected: the same rules were being duplicated across three to five project files, and agents were still violating them.

Something was fundamentally broken in how we distributed rules to our agents.

The Trigger: An Identity Crisis

The problem crystallized around a bug report: messages sent to one agent using its short name weren't reaching the same agent under its full directory-derived name. Two agents had been talking past each other for days because the messaging system treated the short name and long name as different identities.

Our agent framework derives identity from the project directory name. Long directory names produce long agent IDs, but teams naturally shorten names in daily use. One agent's full ID and its common shorthand were treated as separate identities across credentials, knowledge entries, session logs, and messages. Messages were split between both identities—dozens on each side—and neither saw the other's mail.

"Two agents collaborating on a feature had been sending messages into the void for three days. The messages were delivered successfully—just to two different identities that happened to be the same agent."

The Fix: Alias Resolution

We built three things into our shared knowledge base to solve the identity problem:

1. An alias table — Maps alternate names to canonical agent IDs. Any agent can be referenced by any known name, and the system resolves to the correct identity.
2. A resolver function — Checks the alias table for every agent reference, returning the canonical name or passing through if no alias exists.
3. Updated messaging functions — Every function that sends, receives, or routes messages now calls the resolver automatically. Agents don't need to know which name is canonical.

We then migrated all existing records to use canonical names. The identity split was healed, and no agent needed to change its behavior.

The Bigger Problem: Rule Duplication

Fixing the alias issue was satisfying, but the friction audit revealed something deeper. When we analyzed our knowledge base entries by category, a dominant pattern emerged: over 20 agent-behavior rules were universal—every agent should follow them—but they lived only in a database queried at session start. Agents could ignore or forget them mid-session.

Meanwhile, the same rules were copied into three to five project configuration files, each with slightly different wording:

• "Push before deploy" appeared in four project files with four different phrasings
• "Store credentials in the vault" was in five files, two of which were outdated
• "Don't modify production workflows directly" was in three files but missing from two agents that needed it most

The knowledge base had the right information, but it was advisory—surfaced as context, not enforced as constraints. Project files had the enforcement mechanism, but rules drifted as each file was maintained independently.

The Solution: A Global Team Instructions File

Most AI agent frameworks support a layered configuration system. In our case, instructions load from three levels:

We had 17 project-level configuration files and a robust session-start system, but zero team-level instructions. The most critical layer was completely missing.

We created a single team instructions file—73 lines, roughly 800 tokens—covering seven sections:

1. Agent Identity — Use canonical names; aliases resolve automatically
2. Deployment Safety — Test staging first, push before deploy, committed does not mean deployed
3. Knowledge Base Access — Only the orchestration agent writes to system tables
4. Credentials — Store in the centralized vault, never send raw tokens in messages
5. Messaging — Acknowledge inbox before starting new work, use reply functions for threading
6. Workflow Boundaries — Production workflows belong to the workflow specialist agent only
7. Efficiency — Search existing knowledge first, limit output from remote commands, don't save scripts in temporary directories

The Cleanup

With global rules in place, we removed approximately 45 lines of duplicated instructions from three project files. Each file now focuses only on what's unique to that agent's domain: deploy scripts, target URLs, architecture decisions, and domain-specific constraints.

The result was cleaner, shorter project files that are easier to maintain and less likely to drift out of sync.

The Architecture: Five Layers of Agent Context

After this refactoring, our agent context system has five distinct layers, each with a clear purpose:

The team instructions layer sits at the top. It's the one thing every agent reads before doing anything else. Small enough to not bloat context windows, but authoritative enough to prevent the most common recurring violations.

Each layer serves a different purpose and has different characteristics:

• Team instructions are static and authoritative. They change rarely and apply universally.
• Project configuration is static but scoped. Each agent sees only its own project rules.
• Session hooks are dynamic and fresh. They pull the latest state at every session start.
• Knowledge base is persistent and searchable. Agents query it as needed during work.
• Agent teams are ephemeral and real-time. Multiple agents coordinate within a single session.

What We Learned

Rules in a database are suggestions. No matter how many operational lessons you accumulate, if they're only surfaced as advisory context at session start, agents can and will forget or ignore them mid-session. Instruction-layer rules are treated as binding constraints.

Duplication across project files guarantees drift. When the same rule exists in five places with five different phrasings, updates don't propagate. Some files get the fix, others don't. Eventually you have agents following different versions of the same rule.

Small is powerful. Our team instructions file is 73 lines. It covers the seven most critical behavioral categories. The temptation to make it comprehensive is strong, but brevity is a feature—every token in a team instructions file is consumed by every agent in every session. Keep it tight.

The combination of hard rules and soft knowledge is the sweet spot. Instructions for hard rules that must always be followed. Knowledge base for soft knowledge that should be searchable when relevant. Trying to put everything in one place fails in both directions.

"We stopped duplicating rules across project files and started treating behavioral governance like code: one source of truth, inherited everywhere, overridden only when necessary."

Applying This to Your Organization

If you're running multiple AI agents—whether they're coding assistants, workflow automators, or operational agents—ask yourself these questions:

1. Do you have universal rules that every agent should follow? Where do they live?
2. Are any rules duplicated across project configurations? How many versions exist?
3. When a rule changes, how many files need updating? Is that process reliable?
4. Can agents violate rules that exist only as advisory context? What's the blast radius when they do?

The organizations that invest in governance infrastructure early—team instructions, alias resolution, layered configuration—avoid the compounding costs of rule drift and identity fragmentation as their agent fleet grows.