AGENTS.md Design Guide: Multi-Agent Context Isolation and Permission Delegation Patterns

Have you ever assigned "refactor this entire repo" to a single AI agent, only to watch the context window hit its limit or the agent suddenly start modifying completely unrelated files? I ran into that myself early on, cramming everything into a single agent and ending up in some frustrating situations. After adopting multi-agent orchestration, the quality and reliability of my work improved noticeably.

The essence of a multi-agent system is clearly defining "who knows what, and who can do what." The container for that definition is AGENTS.md. This article walks through designing AGENTS.md hierarchically to cleanly isolate context between orchestrators and sub-agents, and safely delegate role-based permissions — with code examples throughout.

Major AI coding tools like Claude Code, Cursor, GitHub Copilot, and Gemini CLI already support AGENTS.md, so mastering these patterns now means you can apply them immediately regardless of which toolchain you use.

Core Concepts

AGENTS.md — A README for Agents

AGENTS.md is a markdown file that conveys project context and behavioral rules to coding agents. If a README is documentation for human developers, think of AGENTS.md as documentation for AI agents. You write it in plain markdown with no special schema or YAML frontmatter, and the AGENTS.md closest to the file the agent is trying to edit takes precedence.

It may look like a simple rules file, but in a multi-agent system each layer's AGENTS.md acts like that agent's "constitution." The orchestrator's AGENTS.md holds the big picture of the entire system and the agent registry, while a sub-agent's AGENTS.md contains narrow, deep rules focused solely on its domain.

The Orchestrator-Worker Pattern

The most widely used multi-agent structure in practice. Think of it like a project manager assigning roles to team members and aggregating their results. A central orchestrator receives user requests, breaks them into subtasks, routes each to a specialized worker agent, and aggregates the results.

User Request
    │
    ▼
┌─────────────────────────┐
│       Orchestrator       │  ← Task decomposition, routing, result aggregation
│  (maintains full context)│
└─────────────────────────┘
    │           │           │
    ▼           ▼           ▼
┌────────┐ ┌────────┐ ┌────────┐
│  Code  │ │  Test  │ │Security│  ← Each runs independently in its own context
│  Gen   │ │ Runner │ │Auditor │
│ Agent  │ │ Agent  │ │ Agent  │
└────────┘ └────────┘ └────────┘
    │           │           │
    └───────────┴───────────┘
          Returns summary only

The key point here is that when a sub-agent finishes its work, the entire exploration history is isolated within the sub-agent's context, and only the final summary is passed up to the orchestrator. This keeps the orchestrator's context window clean.

Context Isolation — Why It Matters

Every time a sub-agent is spawned, a fresh context window (e.g., 200K tokens for Claude) is allocated. If this isolation structure isn't designed properly, the orchestrator burns context on unnecessary intermediate exploration logs, and output quality degrades toward the end of the context — a phenomenon commonly called "Context Rot." Parallel sub-agents can also interfere with each other's state.

For these reasons, "context engineering" emerged as a more important topic in the industry than "prompt engineering" throughout 2025–2026. The core is designing which tokens to give the model and when. Rather than loading all context at agent initialization, "Progressive Disclosure" — providing only the information needed for the current step, incrementally — has become the standard solution. Specific implementations have actually reported significant reductions in token usage while maintaining quality.

Role-Based Permission Delegation Patterns

Agent permission design follows three core principles:

Statically inheriting permissions follows the logic of "if the parent can do it, the child can too" — which is quite risky in practice. Just because the orchestrator has permission to delete from the DB doesn't mean that permission should flow down to the code generation sub-agent. That's why context-aware permission design is necessary.

Practical Application

Example 1: Designing a Hierarchical AGENTS.md Directory Structure

The most commonly used structure places global rules at the root and domain-specific rules in subdirectories.

/AGENTS.md                  # Global: tech stack, architecture principles, agent registry
/agents/
  code-reviewer.md          # Code review sub-agent definition
  test-runner.md            # Test execution sub-agent definition
  security-auditor.md       # Security audit sub-agent definition
/src/AGENTS.md              # Source code writing rules (references global rules + additions)
/docs/AGENTS.md             # Documentation rules

How does inheritance work? AGENTS.md "inheritance" is not the framework automatically merging files. Instead, the agent walks up from the target file toward the root and directly reads each directory's AGENTS.md. Writing "inherits from /AGENTS.md" in /src/AGENTS.md clearly communicates the intent that the agent should reference both files.

Here is an example root AGENTS.md:

# Project: MyApp
 
## Tech Stack
- Runtime: Node.js 22, TypeScript 5.x
- Framework: NestJS (backend), Next.js 15 (frontend)
- DB: PostgreSQL 16, Redis 7
 
## Architecture Principles
- Business logic goes in the Service layer only
- Keep controllers thin
- All external input must be validated via DTOs
 
## Agent Registry
| Agent | Role | Entry Point |
|-------|------|-------------|
| code-reviewer | PR review and code quality checks | /agents/code-reviewer.md |
| test-runner | Test execution and coverage analysis | /agents/test-runner.md |
| security-auditor | Security vulnerability audit (read-only) | /agents/security-auditor.md |
 
## Global Prohibitions
- No direct queries to the production DB
- No modifying .env files
- No direct pushes to main/master branches

/src/AGENTS.md references the root rules and adds only rules specific to writing source code:

# Source Code Rules (inherits from /AGENTS.md)
 
## Code Style
- 2-space indentation
- async/await (not .then())
- TypeScript strict mode required
 
## File Structure Rules
- Service files: *.service.ts
- Controller files: *.controller.ts
- DTO files: dto/*.dto.ts
 
## Permitted Actions in This Directory
- Read/write files under src/
- Create new modules
 
## Prohibited Actions in This Directory
- Directly modifying test files (*.spec.ts)
- Modifying DB migration files

Example 2: Writing Role-Based Permission-Separated AGENTS.md

For each sub-agent's AGENTS.md, it's important to clearly define what that agent can and cannot do. Honestly, at first I thought "can't I just write it in the prompt?" — but separating it into AGENTS.md means the agent loads that file before starting work and internalizes its own boundaries, resulting in far greater consistency.

One thing worth saying upfront: the allow/deny rules defined in AGENTS.md are declarative commitments. The agent reads this file and follows it through its own judgment — there is no runtime-level mechanism that forcibly blocks violations. For production environments, it's recommended to pair AGENTS.md rules with runtime-level permission restrictions such as sandboxing or tool filtering.

# Security Auditor Agent
 
## Role
Detects security vulnerabilities in the codebase and generates reports.
Analyzes based on the OWASP Top 10; provides remediation suggestions only and does not apply actual fixes.
 
## Permitted Actions
- Read all source files (read-only)
- Analyze dependency files (package.json, pom.xml, etc.)
- Create security report files (in reports/ directory only)
- Query external CVE databases (read)
 
## Absolute Prohibitions
- Modifying or deleting source files
- Accessing configuration files (.env, config/)
- Network connections (except CVE DB queries)
- Spawning other agents
 
## Output Format
Results must be returned in the following structure:
{
  "severity": "critical|high|medium|low",
  "location": "file-path:line-number",
  "description": "Vulnerability description",
  "cwe": "CWE-XXX",
  "recommendation": "Remediation direction (without directly modifying code)"
}

# Code Generation Agent
 
## Role
Generates source code for new features as directed by the orchestrator.
 
## Permitted Actions
- Read/write files under the src/ directory
- Create new files (inside src/ only)
- Modify type definition files (src/types/)
- Install pnpm packages (excluding devDependencies)
 
## Absolute Prohibitions
- Modifying files outside src/
- Changing DB schemas (no access to migrations/)
- Modifying environment variable files (.env*)
- Modifying test files (*.spec.ts, *.test.ts)
- Directly calling other agents
 
## Return Format on Completion
Return only a summary when the task is done:
- List of created/modified files
- Summary of key changes in 3 lines or fewer
- Next steps needed (if any)

Example 3: Hierarchical Orchestration Design (3-Tier)

A 3-tier structure that is more effective in practice than a simple 1:N setup. Instead of an orchestrator directly managing 6 sub-agents, feature lead agents coordinate their own specialists. The key is keeping the orchestrator's context much lighter.

Orchestrator (context: full task plan only)
├── Feature Lead A: User Authentication
│   ├── Frontend Specialist (src/components/auth/)
│   └── API Specialist (src/modules/auth/)
└── Feature Lead B: Payment
    ├── DB Specialist (migrations/, src/repositories/)
    └── Test Specialist (test/payment/)

Orchestrator AGENTS.md:

# Orchestrator Agent
 
## Role
Analyzes user requests and delegates to feature lead agents.
Does not directly write code or modify files.
 
## Task Decomposition Principles
1. Break the request into independent functional units
2. Select the feature lead agent responsible for each function
3. Deliver instructions to the feature lead with a clear interface contract (input/output)
4. Integrate results and mediate conflicts
 
## Permitted Actions
- File reading (full scope, for exploration purposes)
- Spawning feature lead agents
- Writing integrated result reports
 
## Absolute Prohibitions
- Directly modifying/deleting files
- Directly calling external APIs
- DB access
- Storing sub-agent results in full in context (receive summaries only)
 
## Context Management Rules
- When spawning sub-agents, pass only necessary information (Progressive Disclosure)
- Do not include sub-agent exploration history in context
- Aggregate only the final summary from each feature lead

Feature lead agent AGENTS.md coordinates within a narrower scope than the orchestrator:

# Feature Lead Agent: Auth
 
## Role
Coordinates implementation of the user authentication feature.
Spawns frontend and API specialists and integrates their results.
 
## Scope
- src/components/auth/ (frontend)
- src/modules/auth/ (backend API)
 
## Permitted Actions
- Read files within scope
- Spawn frontend specialist and API specialist
- Validate interface contracts (check input/output type consistency)
 
## Absolute Prohibitions
- Modifying files outside scope
- Directly accessing DB schemas
- Interfering with other feature leads' areas

Pros and Cons Analysis

Advantages

Disadvantages and Caveats

Most Common Mistakes in Practice

1. Writing AGENTS.md in excessive detail: Counter to the intuition that "more rules = better results," longer AGENTS.md files actually degrade performance. Research shows that LLM-generated AGENTS.md lowers task success rates and increases costs. Keep it to only the essential rules, written concisely, and it's recommended to write it by hand.

2. Overloading the orchestrator: When the orchestrator starts exploring files and writing code directly, its context fills up fast and it loses the capacity to delegate to sub-agents. It's recommended that the orchestrator focus solely on the "conductor" role and delegate actual work to sub-agents.

3. Deferring permission design: The "make it work first, then restrict permissions later" approach doesn't actually work well. Defining each agent's allow and deny lists from the start makes debugging much easier and prevents accidental file modifications or privilege abuse incidents.

Closing Thoughts

The essence of AGENTS.md is not accumulating many rules — it's designing responsibility boundaries so each agent clearly knows "what I should do and what I must not do."

Three steps you can start with right now:

1. Create the root file: Create /AGENTS.md at your existing project root and write only three things — tech stack, architecture principles, and global prohibitions — in under 50 lines. If you're using a tool like Claude Code or Cursor, the file is recognized the moment you create it.

2. Write role files: Pick one task you assign repeatedly (code review, test execution, etc.) and write /agents/[role-name].md. Just two sections — "Permitted Actions" and "Absolute Prohibitions" — is enough to get started.

3. Add context management rules: Add a rule to the orchestrator agent's AGENTS.md like "on completion, return only a summary without sub-agent exploration history," and you should notice a visible improvement in context efficiency.

Next article: Once you want to implement the inter-agent role boundaries discussed here at the protocol level, you inevitably reach a fork in the road of standard selection — the differences between MCP (Model Context Protocol) and A2A (Agent-to-Agent) protocol, and how to combine the two standards, will be covered next.

References

• AGENTS.md Official Site and Format Specification
• GitHub - agentsmd/agents.md: AGENTS.md Open Format
• How to Build Your AGENTS.md (2026) - Augment Code Guide
• The Complete Guide to AI Agent Memory Files (CLAUDE.md, AGENTS.md) - Medium
• Improve your AI code output with AGENTS.md - Builder.io
• Create custom subagents - Claude Code Docs
• Subagents & Context Isolation - ClaudeWorld
• How GSD's Multi-Agent Orchestration Runs Entire Phases Without Filling Your Context Window
• The Code Agent Orchestra - Addy Osmani
• Agent orchestration - OpenAI Agents SDK
• Handoffs - OpenAI Agents SDK
• Guardrails - OpenAI Agents SDK
• AI Agent Orchestration Patterns - Azure Architecture Center
• Orchestrator and subagent multi-agent patterns - Microsoft Copilot Studio
• Best Practices of Authorizing AI Agents - Oso
• AI Agents and Context-Aware Permissions - Oso
• Setting Permissions for AI Agents - Oso
• Effective context engineering for AI agents - Anthropic Engineering
• Progressive Disclosure in AI Agents - MindStudio
• Context Engineering: Why More Tokens Makes Agents Worse - MorphLLM
• Spring AI Agentic Patterns (Part 4): Subagent Orchestration
• The Orchestration of Multi-Agent Systems: Architectures, Protocols, and Enterprise Adoption - arXiv
• Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems - arXiv
• Multi-Agent Orchestration Patterns: Pattern Language 2026 - Digital Applied
• Guidance for Multi-Agent Orchestration on AWS
• How to Build Multi Agent AI Systems With Context Engineering - Vellum