From AGENTS.md to sub-agents: structure and best practices
From AGENTES.md to sub-agents: structure and best practices
If you work in Platform Engineering or on a development team, you need to understand one thing: subagents ≠ MCPs.
They are not interchangeable. They are not the same.
And mixing their responsibilities is a fast track to incidents, permission disputes, and legal headaches.
In a future edition, I’ll cover use cases for subagents and MCP servers.
In today’s newsletter, you’ll learn the difference between subagents and MCP servers, and how to implement the subagent framework. Specifically:
What is a subagent?
What is an MCP server?
How can I start using subagents?
🎁 Heads up! Today’s edition comes with a little gift 🎁. You can find it at the end of this email.
To get you warmed up, and in case you missed it, this article about the AGENTS.md framework might be helpful as context for reading today’s edition.
Now, let’s get down to business.
What is a sub-agent and an MCP?
A sub-agent is a specialized cognitive role:
It has a prompt,
it reasons within a scope,
and it returns structured outputs.
Think of it as a senior specialist you receive via text message who responds with technical judgment.
Its main characteristics can be listed as:
It has its own objective.
It reasons autonomously within a scope.
It can call tools (MCPs), but it decides what and when.
It returns structured outputs (JSON, checklists, code diffs, etc.).
👉🏼 Sub-agents are knowledge, prompts, used, and orchestrated by your AI agent (GPT 5.2, Claude Opus 4.6, etc.).
On the other hand,
An MCP (Model Context Protocol) server is an application: an adapter that exposes capabilities, data, and tools to the agent.
It doesn’t reason: it responds to requests with typed data and functions (e.g., “searchLogs”, “createPR”, “queryMetrics”).
The main characteristics can be listed as:
Typed APIs and contracts.
Permission control and auditing.
Deterministic: it performs specific actions when requested.
It has no prompt and doesn’t make decisions on its own.
Keep this in mind 👇🏻
Subagent → thinks + decides.
MCP server → offers capabilities + data access
Now, let’s focus on subagents.
How can I start using subagents?
A lot of general information and not much specifics, right? Well, it was necessary so we can continue.
Let’s get into the details.
👉🏼 As you can see, at the end of the day, implementing a cognitive subagent is about organizing knowledge into different Markdown files.
However, the first time you encounter this, it can be a bit confusing; you don’t know what to put in AGENTS.md and what to put in the files dedicated to the subagents.
☝🏼 Something to keep in mind:
AGENTS.md is automatically injected into the agent’s context in every conversation. If it’s long, it unnecessarily consumes tokens with information that may not be relevant to the current task.
The subagent files are loaded on demand, only when the agent determines they are relevant.
So, what does this mean in practice? Let me explain how I think it works best.
The best practice is for AGENTS.md to be lean but not empty; basically, an index. It should contain:
Project overview (2-3 lines max): universal context.
Critical rules that apply to ANY task (naming, core architecture, prohibited patterns).
Quick commands: the agent needs these constantly.
The index of subagents with a clear description of WHEN to use each one.
Everything that’s only relevant in specific contexts: security details, detailed CI/CD, comprehensive test guides, etc. That goes in the subagents.
Okay, let me tell you what the ideal structure is 👇🏻
AGENTS.md (~80-100 líneas)
├── Project title + 2-line description
├── Architecture invariants (rules that never great)
├── Quick commands block
└── Subagent index:
├── subagent_architecture.md → “Use for: new features, design decisions”
├── subagent_build_test.md → “Use for: build issues, test creation”
├── subagent_configuration.md → “Use for: env setup, Kafka config”
├── subagent_code_style.md → “Use for: code review, formatting”
├── subagent_ci_pr.md → “Use for: PR creation, CI failures”
└── subagent_security.md → “Use for: secrets, auth, encryption”Some of those Markdowns might not apply to your situation, but you get the idea.
The key element 👇🏻
The AGENTS.md file must explicitly instruct the agent when to load each sub-agent. Without this, the agent might ignore them. Something like this:
## Subagent Files
Before starting any task, identify which subagent files apply and read them:
| File | Read when... |
|------|-------------|
| `subagent_architecture.md` | Adding features, refactoring, design questions |
| `subagent_build_test.md` | Running builds, writing/fixing tests |
| `subagent_configuration.md` | Setting up env, changing Kafka topics, config |
| `subagent_code_style.md` | Writing new code, reviewing PRs |
| `subagent_ci_pr.md` | Creating PRs, debugging CI pipeline |
| `subagent_security.md` | Handling credentials, auth, sensitive data |These sub-agents are examples, and some of them are the ones I use. Not all of them might apply to you, or some might, and you’ll probably have to create some for your specific situation.
However, following the example above, I’ll now explain what each of these Markdown files should contain.
subagent_architecture.md
Detailed architectural patterns (Hexagonal Architecture, Event-Driven, DDD)
Component architecture with code examples
Extension points for adding new features
Performance considerations and monitoring
Testing architecture patterns
subagent_build_test.md
Comprehensive build system documentation
Test framework structure and strategies
Performance testing guidelines
Common build issues and solutions
Quality gates and coverage requirements
subagent_configuration.md
Environment setup and prerequisites
Kafka topics configuration
Dynamic configuration management
Monitoring and health checks
Troubleshooting configuration issues
subagent_code_style.md
Java 21 best practices and modern features
Lombok usage guidelines
Package organization standards
Error handling patterns
Documentation and testing standards
subagent_ci_pr.md
GitHub Actions CI/CD pipeline configuration
Pull request workflow and templates
Branch protection and review processes
Deployment procedures and monitoring
Troubleshooting CI/CD issues
subagent_security.md
Comprehensive security guidelines
Secrets management and rotation
Input validation and data protection
Security monitoring and incident response
Compliance and audit requirements
You see where this is going, right?
From here on out, with those files in your working directory, each iteration with your AI agent will allow it to know where to navigate and what to add to its context, based on your requests.
And what’s the point of all this?
👉🏼 With the AGENTS and sub-agents framework, you can expect:
Token savings, a.k.a. cash 💸
Better results in responses and implementation of code generated by AI assistants.
I hope you enjoyed today’s edition.
I’d love to hear about your experiences implementing and using sub-agents and MCP Servers. Reply to this email, leave a comment on Substack, or reach out to me on social media.
🎁 The Gift!
I have a meta prompt that, when passed to your AI assistant, will create all the necessary files for you to implement, with a single press of ENTER, the entire infrastructure to start using sub-agents in your application.
Want it for free?
It’s easy:
Reply to this email,
Or send me an email to hello@ainativenewsletter.com,
And I’ll send it to you.
If you know someone who might be interested in AGENTS.md and sub-agents, forward this email to them or click the share button below 👇🏻