How to Design Agent Roles: The CLAUDE.md Pattern for AI Team Configuration
When you run a Cyborgenic Organization with 11 AI agents, role design is everything. A vague role produces vague output. A precise role produces an agent that behaves like a senior hire who read the onboarding docs.
At GenBrain AI, every agent gets a CLAUDE.md file — a structured configuration document that defines who the agent is, what tools it has, what rules it follows, and how it interacts with other agents. This is not a prompt template. It is the operational manual for an autonomous team member.
This tutorial walks through how we design these role configurations, what goes wrong when you skip steps, and the patterns that survived 11 months of production use.
Why Role Configuration Matters
An LLM without role configuration is a generalist. It will answer questions, write code, and generate text. But it will not:
- Stay in its lane (the marketing agent starts writing infrastructure code)
- Follow organizational protocols (agents skip verification steps or push to the wrong branch)
- Coordinate with other agents (the CTO and Backend agent do the same work in parallel)
- Respect boundaries (an agent accesses credentials it should not have)
Role configuration solves all four problems. The CLAUDE.md file is injected at session start, loaded as system-level instructions that persist across the agent's entire working session.
The CLAUDE.md Structure
Every agent's CLAUDE.md follows the same template. Here are the sections:
1. Identity Block
## Identity
| Field | Value |
|-------|-------|
| **Role** | Head of Marketing & Growth |
| **Manager** | CEO Agent |
| **Org** | GenBrain AI (agent.ceo) |
| **Branch** | `marketing` |
| **Domain** | marketing.genbrain.agent.ceo |
The identity block answers: who is this agent, who does it report to, and where does its work go? The Branch field prevents agents from pushing to branches they do not own. The Manager field determines escalation paths for task delegation.
2. Tools and Capabilities
## Your Tools
- `social-media` MCP server: post to X and LinkedIn
- `agent-browser`: headless browser for verification
- `git` / `gh`: version control, content publishing
- MCP tools: `send_to_agent`, `get_agent_inbox`
- Gmail OAuth: customer emails, press inquiries
This section is not just documentation — it shapes the agent's behavior. An agent that knows it has a headless browser will verify published content. An agent that knows it has Gmail will handle customer inquiries. An agent that does not know about a tool will not attempt to use it.
The principle: give agents the minimum set of tools for their role. Our Marketing agent has social-media and agent-browser. It does not have kubectl. Our DevOps agent has kubectl. It does not have social-media. Tool boundaries enforce role boundaries.
3. Core Rules
## Core Rules (ENFORCED BY HOOKS)
1. Ship content every session
2. Complete your assigned directive first
3. Call `complete_task_unverified()` with evidence when done
4. Never push to `main` or `develop` directly
5. Overcome problems — never dead-end
Core rules are non-negotiable behavioral constraints. We enforce them through session hooks — pre-commit checks, test evidence gates, and branch protection. But the rules also exist in the CLAUDE.md so the agent understands why the hooks exist and can self-correct before hitting a gate.
The most important rule for us: "Ship content every session." Without it, agents spend entire sessions on research, planning, and analysis — producing zero artifacts. The rule forces output.
4. Interaction Patterns
## Working with Other Agents
CEO → Content direction, innovation ideas
CTO → Technical details for deep dives
Fullstack → Website copy coordination
Use MCP tools:
send_to_agent("ceo", "...") # Report completed content
send_to_agent("cto", "...") # Request technical details
This section tells the agent who to talk to and when. Without it, agents either work in isolation (missing context from other agents) or broadcast messages to everyone (creating noise).
The pattern we converged on: each agent has 2-3 explicit communication partners. The Marketing agent talks to CEO, CTO, and Fullstack. The CSO talks to CTO. The Backend agent talks to CTO and DevOps. These are the edges in the org graph.
5. Anti-Patterns and Guardrails
## Token Budget & Anti-Pseudo-Work
Real work: Published blog posts, sent social posts, email responses.
Pseudo-work (NEVER): Strategy docs nobody reads, brand frameworks,
research without deliverables, planning without publishing.
Test: Before ANY task ask "What artifact will exist when I'm done?"
This is the section most people skip. It is the most valuable section in the file.
AI agents have a strong tendency toward pseudo-work — producing elaborate plans, frameworks, analyses, and strategies that feel productive but create zero external value. Our Marketing agent once spent an entire session writing a "brand positioning matrix" that nobody read. The anti-pseudo-work rule killed that pattern.
The test is simple: "What artifact will exist when I am done?" If the answer is not a committed file, a published post, a sent email, or a deployed change, the agent is doing pseudo-work.
Design Principles
After 11 months of iterating on agent roles, here are the principles that survived:
Narrow Beats General
Our first CTO agent was configured as "Senior Engineer — handles all technical work." It tried to do everything: code, infrastructure, security, testing, deployment. It did all of them badly.
We split it into CTO (architecture + code review), Backend (API implementation), Frontend (UI components), Fullstack (cross-stack features), DevOps (infrastructure), QA (testing), and CSO (security). Each agent became dramatically better at its narrow domain.
The benchmark: a specialized agent completes tasks 35% faster than a generalist with the same LLM. Less context to load, fewer decision branches, more predictable output.
Constraints Produce Better Output
It is counterintuitive, but agents with more rules produce higher quality work. An unconstrained agent makes random decisions about formatting, naming, structure, and communication style. A constrained agent is consistent.
Our Marketing agent has rules about:
- Content pillars (5 themes it can write about)
- Publishing channels (blog, X, LinkedIn — no others)
- Naming (never mention customer names)
- Session cadence (check inbox, pull latest, write, commit, report)
- Anti-patterns (no strategy docs, no brand frameworks)
These constraints are not limitations. They are guardrails that keep the agent in the productive zone.
Shared Rules, Role Overlays
Every agent loads two configuration layers:
- Shared discipline block — universal rules that apply to all agents (verification-as-code, decomposition before delegation, honest reporting, cost discipline)
- Role overlay — role-specific configuration (identity, tools, capabilities, anti-patterns)
The shared block is maintained in one file and injected into every agent's CLAUDE.md during build. This ensures consistent organizational behavior while allowing role-specific customization.
When we add a new rule (like the bypass audit trail), we add it once to the shared block and rebuild. Every agent gets it on next restart. No per-agent configuration drift.
Version Your Configs
Agent configurations are checked into Git alongside the application code. Every change is a commit with a diff. When an agent starts behaving differently, git blame on its CLAUDE.md tells you exactly what changed and when.
We have rolled back agent configurations three times — each time because a well-intentioned rule change produced unexpected behavior. Without version control, we would have been debugging blind.
Common Mistakes
Too much autonomy too early. Start with tight constraints and loosen as you observe behavior. Our agents earned autonomy over months. New agents start with explicit checklists for every task type.
Vague acceptance criteria. "Make the website better" produces random changes. "Update the hero section copy to emphasize the KB feature, keep under 50 words, link to /blog/kb-launch" produces a specific, reviewable artifact.
No communication protocol. Without explicit rules about who to message and when, agents either go silent (working in isolation for hours) or flood the inbox (sending updates on every minor step). Define the cadence.
Ignoring the anti-pattern section. Every role has failure modes. The CTO agent rewrites code that works. The Marketing agent writes strategy instead of content. The DevOps agent restarts pods instead of investigating root causes. Name the failure modes explicitly so the agent can recognize and avoid them.
Getting Started
If you are building your first AI agent team:
- Start with 3 roles: a technical lead, a generalist implementer, and a coordinator. Do not start with 11.
- Write the CLAUDE.md before launching the agent. The configuration is the spec. If you cannot write it, you do not understand the role well enough to automate it.
- Include at least 3 anti-patterns. What will this agent do wrong? Name it.
- Define the artifact test. For each task type, what is the concrete output? A file? A deployment? A message?
- Set communication partners. Who does this agent report to? Who does it request context from?
- Version control everything. The CLAUDE.md lives in Git. Changes are commits.
The goal is not to make agents that think like humans. It is to make agents that produce reliable, verifiable output within well-defined boundaries. The CLAUDE.md pattern is how we do that at GenBrain AI.
Build your own AI agent team with structured role configurations. agent.ceo provides fleet management, NATS messaging, task verification, and real-time monitoring for Cyborgenic Organizations.
Related reading: