🔬 Anatomy of a subagent (system prompt, tools, output)
A subagent file has four parts: the frontmatter (name/description), the system prompt (who it is), the permitted tools, and the expected output format. Defining these four parts well is what separates a useful agent from one that returns loose text.
// .claude/agents/pesquisador-empresa.md
--- name: pesquisador-empresa description: Use para pesquisar uma empresa e devolver um CompanyContext estruturado (setor, stack, dores, IA). tools: WebSearch, Read --- És um pesquisador de empresas. Recebes nome + descrição, pesquisas e devolves SÓ um JSON CompanyContext. Não escreves o entregável; só coletas o contexto.
💡 Practical tip
The secret is to restrict the tools and fix the output format. An agent with access to everything and a free-form output becomes unpredictable; an agent with few tools and an output schema is reliable and easy to chain.
name + description
who it is
only what's needed
fixed format
🏢 The agent pesquisador-empresa (collects structured context)
It takes a name + description, does research, and returns a CompanyContext: industry, stack, pain points, competitors, and AI initiatives. It’s Phase 1 of the Factory embodied in a worker—it isolates the heavy research and returns clean context without cluttering the main conversation.
Receives the company
The main agent passes a name + short description. Nothing else — the subagent starts from scratch in an isolated context.
Web research
Uses WebSearch to identify the industry, tech stack, pain points by department, and AI developments. This is where cost and noise are contained.
Structure in CompanyContext
Turns what it found into JSON with fixed fields. It's not a loose summary — it's a predictable object, ready for the next agent.
Returns to the parent
Deliver only the CompanyContext to the main agent. All the heavy research stays outside—the orchestrator receives a lean package.
💡 Why isolate
Research fills the context window with junk. When it runs in a subagent, only the clean result comes back — the main agent never sees the 30 pages that were read. That's the core benefit of Phase 1 as a worker.
name + description
standalone research
CompanyContext
clean context
✍️ The agent redator-estrategia (drafts a deliverable)
It takes the CompanyContext one more framework (for example, quick wins) and write the deliverable in Markdown, ready for the skill gerar-entregavel (from 3.3) format. The golden rule: research and writing are different jobs—each agent does one, and does it well.
✓ One agent, one role
- ✓Each agent either researches OR writes—never both
- ✓Predictable output: you can trust the format
- ✓Easy to test and improve one piece at a time
✗ Do-it-all agent
- ✗Researches + writes + formats in the same call
- ✗Context overflows—the window fills with noise
- ✗Hard to debug: everything fails together, with no clear culprit
💡 Separate to improve
When research and writing are separate agents, you can improve the writer without touching the researcher — and vice versa. Each has only one reason to change. It's the same logic as small functions, applied to agents.
context + framework
writes the draft
Markdown
one role per agent
🧾 Structured output (schema, reliable JSON)
Ask the agent to return JSON in a fixed format — a schema — like the actual models CompanyInput e ResearchOutput from the Factory. Structured output is exactly what makes it possible to CHAIN agents; loose text breaks the pipeline at the first junction.
// CompanyContext schema (output JSON)
{
"company_name": "Stripe",
"sector": "Pagamentos B2B / fintech",
"tech_stack": ["Ruby", "Go", "AWS"],
"pain_points": ["onboarding lento", "fraude"],
"competitors": ["Adyen", "PayPal"],
"ai_initiatives": ["Radar (antifraude)"],
"maturity_1_5": 4
}
📊 Why JSON instead of text
- •Fixed-name fields: the next agent knows where to find each piece of data.
- •Verifiable: you can check whether
maturity_1_5came in between 1 and 5. - •Chainable: the JSON goes straight into the
redator-estrategiawithout fragile parsing.
💡 A schema is a contract
A schema is a contract — predictable fields connect agents. Define the fields once, and any agent that produces or consumes that object becomes pluggable. That’s how loose components become a pipeline.
fixed format
predictable fields
can be checked
agent → agent
🎛️ Orchestrate skill + agents together
The main agent calls the pesquisador-empresa, passes CompanyContext to the redator-estrategia and then uses the skill gerar-entregavel to produce the file. It's the Factory in miniature: research → writing → document.
// what you ask Claude Code
1. pesquisador-empresa("Stripe") -> CompanyContext
2. redator-estrategia(context, framework="quick-wins") -> Markdown
3. skill gerar-entregavel(markdown, "pptx") -> deck.pptx
This is the same chain of real models in the architecture: CompanyInput → ResearchOutput → SynthesisOutput → GenerationResult. Each arrow represents a worker handing a structured object to the next. The orchestrator just stitches the pieces together.
🧩 How the Factory grows (Extension Points)
- •New deliverable: a new prompt + register it, and the orchestrator already includes it.
- •New provider: a new client with
generate()— swap out the engine without changing anything else. - •New format: a new generator plugged into the generation orchestrator.
💡 Plug-in pieces
Because each stage is a structured object, you can plug in a new piece without rewriting the others. Adding a deliverable, a provider, or a format is a matter of fitting it in—not remodeling. That's how it was designed: to orchestrate, not to tie things together.
company researcher
redator-estrategia
gerar-entregavel
the orchestrator
⚡ When to parallelize agents
Run several subagents at once when the tasks are independent (with no shared state)—for example, researching 3 companies in parallel. If one depends on another's output, it's sequential. Knowing the difference prevents subtle bugs and saves time where possible.
✓ Parallelize when
- ✓The tasks are independent of one another
- ✓There’s no shared state during the work
- ✓You bring the results together only at the end
✗ Keep it sequential
- ✗One task depends on another task’s output
- ✗Shared state is being modified
- ✗The order matters for the final result
💡 Quick test
Ask: "does agent B need what agent A produced?" If yes, sequential. If not, parallel. In our case, redator-estrategia depends on pesquisador-empresa (sequential), but researching 3 companies is parallel.
independent tasks
one depends on the other
shared state
bug-free time
✅ Module summary
🎯 Mission 3.4 — pesquisador-empresa live
Get the Factory's first worker up and running:
- Create
.claude/agents/pesquisador-empresa.md(system prompt + tools + output). - Lock the output to the CompanyContext schema.
- Run it for 1 real company.
- Check that the JSON comes back populated and can be chained.
Success: the researcher-company agent returns a populated CompanyContext. What you gained: the Factory's first worker—ready to power the writer and the document skill.
Next module:
Track 4 — The Factory (live research, the 15 prompts, end-to-end orchestration)