Padrão AGENTS.md (agente development mudou)

Padrão AGENTS.md (agente development mudou).

Você é founder de SaaS.

Seu agente de IA:

• Built from scratch (custom logic, sem padrão)
• Your assumption: "Cada agente é único (precisa código custom)."
• Reality: "Anthropic just announced: Claude Code lê AGENTS.md (padrão emergente)."
• Your blind spot: ├─ Building agents: Sem framework padrão (repetir código) ├─ Every agent: Define tools, context, instructions (manual) ├─ New agente: Start from zero (not reusable) ├─ Team: Confused (como configurar agente?) ├─ Debugging: Hard (sem padrão, cada um diferente) ├─ Scaling: Nightmare (múltiplos agentes = múltiplas configs) ├─ Standards emerging: AGENTS.md (config file pra agentes) └─ Result: "Seu agente: building from scratch, competidor: using standard."

Anthropic just announced:

"Claude Code agora automatically lê AGENTS.md (if exists, no Claude.md). Implicação: Agent configuration é becoming standardized. AGENTS.md = agent framework (define tools, context, instructions, capabilities). Benefit: Framework-based development (vs custom every time)."

Translation to your SaaS:

• Old way: Build agente → define tools → define context → define instructions → test (custom, slow)
• New way: Write AGENTS.md → Claude Code reads automatically → deploy (standardized, fast)
• Implication: "Agent development is moving to framework-based (like web frameworks)."
• Opportunity: "Early adopters use standard (ship 2x faster)."

---

O que é AGENTS.md (e por que importa)

AGENTS.md: Agent configuration as code

=== WHAT IS AGENTS.MD ===

Definition: ├─ Configuration file for AI agents ├─ Defines: Tools, context, instructions, capabilities ├─ Format: Markdown (human-readable, not JSON) ├─ Purpose: Standardize agent configuration ├─ Benefit: Framework-based (vs custom every time) └─ Result: "Agent development becomes predictable."

=== EXAMPLE AGENTS.MD ===

markdown

My Support Agent

Description

Support agent for customer inquiries (WhatsApp, email, chat).

Instructions

• Be friendly and professional
• Always provide solution or escalate to human
• Max response time: 5 seconds
• Language: Portuguese (pt-BR)

Context

• Company: Acme Corp
• Industry: SaaS
• Customers: 10k active users
• Operating hours: 24/7 (automated support)

Tools

• get_customer_info(customer_id): Fetch customer data from CRM
• search_knowledge_base(query): Search support docs
• create_ticket(topic, description): Create support ticket
• escalate_to_human(reason): Escalate to human agent
• send_email(recipient, subject, body): Send email

Capabilities

• Answer FAQs: FAQ database indexed
• Troubleshoot issues: Common problems documented
• Escalate complex: Route to human (if needed)
• Track resolution: Log all interactions
• Follow-up: Send summary email after resolution

Constraints

• Can't: Access customer payment info
• Can't: Refund (must escalate to manager)
• Can't: Change account settings (user must approve)
• Can't: Make promises (always verify with team)

Performance targets

• Resolution rate: 80% (self-service)
• Escalation rate: 20% (needs human)
• Avg response time: <2 seconds
• Customer satisfaction: >4.5/5 stars

=== HOW IT WORKS ===

1. You write AGENTS.md (describe agent)
2. Claude Code reads AGENTS.md (automatically)
3. Claude Code understands requirements (from file)
4. Claude Code generates agent code (based on spec)
5. You deploy agent (no manual configuration)
6. Agent runs according to spec (defined in AGENTS.md)
7. Result: "Framework-based agent development."

=== KEY BENEFITS ===

Before AGENTS.md (custom building): ├─ Define tools: Manually code each tool ├─ Define context: Manually pass context to agent ├─ Define instructions: Hardcoded in prompt ├─ Debugging: How to fix? (custom code, unclear) ├─ Scaling: New agent? Start from zero (repeat code) ├─ Team: How to build agent? (no standard) ├─ Time: 2-3 weeks per new agent └─ Result: "Slow, error-prone, not scalable."

With AGENTS.md (framework-based): ├─ Define tools: List in AGENTS.md ├─ Define context: Describe in AGENTS.md ├─ Define instructions: Write in AGENTS.md ├─ Debugging: Clear spec (what went wrong) ├─ Scaling: Copy AGENTS.md, modify (reusable) ├─ Team: "Follow AGENTS.md template (standard)" ├─ Time: 2-3 days per new agent (10x faster) └─ Result: "Fast, clear, scalable."

AGENTS.md vs Claude.md

=== CLAUDE.MD vs AGENTS.MD ===

Claude.md: ├─ Purpose: Describe your project/repo (Claude context) ├─ Content: Project overview, architecture, conventions ├─ Scope: Entire project (not just agents) ├─ Format: Markdown (freeform) ├─ Use case: General code development ├─ Example: "This is a Python project, uses FastAPI, stores data in PostgreSQL, follows PEP8" └─ Claude reads it: When generating code for project

Agents.md: ├─ Purpose: Describe your agent specifically (agent config) ├─ Content: Agent tools, context, instructions, capabilities ├─ Scope: Single agent (focused) ├─ Format: Markdown (structured) ├─ Use case: Agent development specifically ├─ Example: "This agent handles customer support, uses CRM API, escalates to humans" └─ Claude reads it: When building/updating agent

=== CLAUDE.MD + AGENTS.MD TOGETHER ===

Scenario: Building support agent in SaaS product

1. Claude.md (project context):

   MyCompany SaaS

   • Stack: Python + FastAPI + PostgreSQL
   • Codebase: src/agents/, src/api/, src/db/
   • Convention: Async/await for all I/O
   • Testing: pytest in tests/ folder
   • Deployment: Docker on AWS ECS

2. Agents.md (agent config):

   Support Agent

   • Type: Customer support (WhatsApp, email)
   • Tools: get_customer(), search_kb(), create_ticket()
   • Instructions: Be friendly, escalate complex issues
   • Performance: <2 sec response, 80% resolution

3. Claude Code reads both:

   From Claude.md: "Use async/await, pytest for testing, Docker for deployment" From Agents.md: "Need these tools, follow these instructions" Result: Generates agent code that follows project standards + agent spec

4. Result: Consistent code (project style + agent spec)

=== PRIORITY WHEN BOTH EXIST ===

If both Claude.md and Agents.md exist: ├─ Claude Code reads both ├─ Agents.md takes priority (specific to agent) ├─ Claude.md provides context (project standards) ├─ Conflict: Agents.md wins (more specific) ├─ Example: Claude.md says "use sync code", Agents.md says "use async" │ └─ Result: Agent uses async (Agents.md wins) └─ Recommendation: Keep them aligned (avoid conflicts)

---

Por que AGENTS.md é game changer

Before: Custom agent development

=== BUILDING AGENT WITHOUT AGENTS.MD ===

Step 1: Plan agent (hours) ├─ What should agent do? ├─ What tools does it need? ├─ What context should it have? ├─ How should it behave? └─ Result: List in notebook (not structured)

Step 2: Code agent (days) ├─ Define tools (manually write functions) ├─ Define tools list (pass to agent) ├─ Define system prompt (write instructions) ├─ Define context (hardcode in prompt) ├─ Integrate with codebase ├─ Write tests (if time) ├─ Deploy └─ Result: ~2-3 weeks for one agent

Step 3: Debug agent (days-weeks) ├─ Agent behavior unexpected? ├─ Which part wrong? (tools? prompt? context?) ├─ Read code (try to understand) ├─ Try fix (change prompt?) ├─ Test again (hope it works) ├─ Repeat (multiple iterations) └─ Result: Unpredictable (custom code = hard to debug)

Step 4: Build second agent (2-3 weeks again) ├─ Similar to first agent ├─ Can't reuse first agent (custom, specific) ├─ Build from scratch (repeat work) ├─ Copy-paste code (error-prone) └─ Result: Not scalable

Step 5: Team scaling (nightmare) ├─ Junior dev: "How do I build an agent?" ├─ Senior: "Learn from this agent" (points to custom code) ├─ Junior: "I don't understand (code is complex)" ├─ Result: High onboarding cost, inconsistent agents

=== COST ANALYSIS (WITHOUT AGENTS.MD) ===

Time: ├─ First agent: 2-3 weeks ├─ Second agent: 2-3 weeks (can't reuse) ├─ Third agent: 2-3 weeks (still custom) ├─ 5 agents per year: 10-15 weeks of engineering ├─ Total: ~3+ months of year on agent development └─ Result: Limited capacity (can only build few agents)

Cost: ├─ 5 agents/year * $10k per agent (1 senior engineer * 3 weeks) = $50k ├─ Debugging/fixing: +$20k ├─ Onboarding new team: +$15k └─ Total annual: ~$85k

Risk: ├─ Inconsistent agents (each different) ├─ Hard to maintain (custom code) ├─ Hard to scale (can't reuse) ├─ Knowledge silos (only one person knows agent) └─ Technical debt (accumulates)

After: AGENTS.md framework

=== BUILDING AGENT WITH AGENTS.MD ===

Step 1: Write AGENTS.md (hours) ├─ What should agent do? (describe) ├─ What tools? (list) ├─ What context? (describe) ├─ What instructions? (write) └─ Result: AGENTS.md file (structured)

Step 2: Claude Code generates agent (minutes) ├─ Claude Code reads AGENTS.md ├─ Claude Code generates agent code (based on spec) ├─ Code follows project standards (from Claude.md) ├─ Code is production-ready (tested template) ├─ Deploy └─ Result: ~2-3 days for one agent (10x faster)

Step 3: Debug agent (hours-days) ├─ Agent behavior unexpected? ├─ Check AGENTS.md (spec vs reality) ├─ Problem clear (spec defines what should happen) ├─ Update AGENTS.md (change spec) ├─ Claude Code regenerates (automatic) ├─ Deploy updated version └─ Result: Predictable (spec-driven = clear debugging)

Step 4: Build second agent (2-3 hours) ├─ Copy AGENTS.md from first agent ├─ Modify for second agent (change tools, instructions) ├─ Claude Code generates (automatic) ├─ Deploy └─ Result: Reusable (template-based)

Step 5: Team scaling (easy) ├─ Junior dev: "How do I build an agent?" ├─ Senior: "Write AGENTS.md, follow template" ├─ Junior: "Oh, that's clear" (structured) ├─ Result: Low onboarding cost, consistent agents

=== COST ANALYSIS (WITH AGENTS.MD) ===

Time: ├─ First agent: 2-3 days (write AGENTS.md) ├─ Second agent: 2-3 hours (copy + modify) ├─ Third agent: 2-3 hours (copy + modify) ├─ 5 agents per year: 1-2 weeks of engineering ├─ Total: ~5% of year on agent development (vs 25%) └─ Result: 5x more agent capacity (can build 25+ agents/year)

Cost: ├─ 5 agents/year * $2k per agent (1 day work) = $10k ├─ Debugging/fixing: +$2k (clear spec = easy debug) ├─ Onboarding new team: +$5k (template-based) └─ Total annual: ~$17k

Savings: $85k (old) - $17k (new) = $68k/year saved

Risk: ├─ Consistent agents (same framework) ├─ Easy to maintain (spec-driven) ├─ Easy to scale (reusable template) ├─ Knowledge sharing (everyone understands AGENTS.md) └─ Lower technical debt (standardized approach)

=== COMPARISON ===

Metric	Without AGENTS.md	With AGENTS.md	Improvement
Time per agent	2-3 weeks	2-3 days	10x faster
Cost per agent	$10k	$2k	5x cheaper
Reusability	0% (custom)	80% (template)	Massive
Team onboarding	Weeks	Hours	100x faster
Debugging time	Days-weeks	Hours	10x faster
Agents/year scale	5	25+	5x capacity
Annual cost (5 ag)	$85k	$17k	80% savings

---

Como adotar AGENTS.md

Phase 1: Understanding (1 day)

[ ] Learn AGENTS.md structure: [ ] Read Anthropic docs (AGENTS.md spec) [ ] Look at examples (reference agents) [ ] Understand sections (tools, context, instructions) [ ] Review Claude.md integration (how they work together) [ ] Ask: Do we need AGENTS.md? (for what agents)

[ ] Evaluate current agents: [ ] List all agents you have [ ] How are they configured? (code? prompt? config file?) [ ] Can they be standardized? (are they similar?) [ ] What's different? (unique logic) [ ] What's reusable? (common patterns)

[ ] Decision: [ ] Worth it? (time saved > time to adopt) [ ] Scope: Which agents to standardize first [ ] Timeline: When to start [ ] Owner: Who manages this (tech lead, engineer)

Phase 2: Design (3-5 days)

[ ] Design AGENTS.md template: [ ] Sections (tools, context, instructions, etc) [ ] Format (how to structure) [ ] Examples (what good AGENTS.md looks like) [ ] Validation (what makes it valid) [ ] Versioning (how to version AGENTS.md)

[ ] Create agent taxonomy: [ ] Types of agents (support, sales, code, etc) [ ] Common tools by type (what tools each needs) [ ] Common context (what info each needs) [ ] Common instructions (what behavior expected) [ ] Variations (what's different per agent)

[ ] Plan implementation: [ ] Which agent first (start simple) [ ] How to test AGENTS.md (validation) [ ] How to deploy (Claude Code integration) [ ] How to iterate (update AGENTS.md) [ ] How to document (team training)

[ ] Documentation: [ ] AGENTS.md spec (what goes in each section) [ ] Template (copy-paste starter) [ ] Examples (3-5 real examples) [ ] FAQ (common questions) [ ] Runbook (how to build new agent)

Phase 3: Implementation (1-2 weeks)

[ ] Convert first agent: [ ] Write AGENTS.md (describe agent) [ ] Use Claude Code (read AGENTS.md) [ ] Generate code (automated) [ ] Test (verify behavior) [ ] Deploy (staging first) [ ] Validate (works as spec?) [ ] Document (capture learnings)

[ ] Standardize tools: [ ] List all tools used [ ] Categorize (support tools, sales tools, etc) [ ] Create reusable tool definitions (standard format) [ ] Add to AGENTS.md template (tools section) [ ] Document each tool (what it does, inputs, outputs)

[ ] Create library: [ ] Build AGENTS.md template (starter) [ ] Add examples (multiple agent types) [ ] Add tool library (common tools) [ ] Create runbook (step-by-step guide) [ ] Share with team (training)

[ ] Team training: [ ] Workshop: What is AGENTS.md [ ] Demo: How to build agent (live) [ ] Hands-on: Team builds first agent [ ] Q&A: Address questions [ ] Iteration: Refine based on feedback

Phase 4: Scaling (ongoing)

[ ] Build agents systematically: [ ] Use AGENTS.md template [ ] Claude Code generates code [ ] Deploy and iterate [ ] Measure: Time saved vs manual

[ ] Continuous improvement: [ ] Collect feedback (team experience) [ ] Refine template (what works, what doesn't) [ ] Add tool library (new tools discovered) [ ] Update examples (new patterns) [ ] Share learnings (team knowledge)

[ ] Metrics: [ ] Time per agent (track reduction) [ ] Cost per agent (track savings) [ ] Agent quality (same or better) [ ] Team satisfaction (adoption rate) [ ] Reusability (% code reused)

[ ] Future: [ ] Build more agents (20+) [ ] Standardize further (mature framework) [ ] Contribute upstream (help Anthropic improve AGENTS.md) [ ] Train new team members (standard onboarding)

---

AGENTS.md + Claude Code = agent development revolution

O que aconteceu:

1. Claude Code agora lê AGENTS.md (automatically, if no Claude.md)

   • Implicação: "Agent configuration is becoming standardized."
   • Action: "Adopt AGENTS.md (get ahead of curve)."

2. AGENTS.md = configuration file for agents (tools, context, instructions)

   • Implicação: "Agent development is moving to framework-based (like web frameworks)."
   • Action: "Write AGENTS.md instead of custom code."

3. Claude Code generates agent code from AGENTS.md (automatic)

   • Implicação: "Building agents is 10x faster (minutes vs weeks)."
   • Action: "Let AI generate code (you focus on spec)."

4. AGENTS.md is reusable (copy, modify, deploy)

   • Implicação: "Second agent is 100x faster than first (template-based)."
   • Action: "Build agent library (scale to 20+ agents)."

5. AGENTS.md is team-friendly (structured, standardized)

   • Implicação: "Anyone on team can build agent (low onboarding)."
   • Action: "Empower team to ship agents independently."

Your options:

• Ignore: Keep building agents manually = slow, expensive
• Wait: See if AGENTS.md becomes standard = miss opportunity
• Adopt: Use AGENTS.md now = 10x faster, 80% cost savings = recommended

Recommendation: IF YOU'RE BUILDING MULTIPLE AGENTS: Adopt AGENTS.md TODAY. Time to standardize: 1-2 weeks. Benefit: Build agents 10x faster. Cost savings: $68k/year (for 5 agents). Competitive advantage: Early adoption (competitors scrambling in 6 months). By the time industry adopts AGENTS.md, you'll have built 20+ agents (they're still on first one).

Na OpenClaw:

Ajudamos SaaS builders adopt AGENTS.md framework:

• AGENTS.md strategy: Como estruturar pra seu SaaS? (design)
• Template development: Como criar template reutilizável? (framework)
• First agent: Como converter primeiro agente pra AGENTS.md? (implementation)
• Tool library: Quais tools reutilizáveis? (architecture)
• Team training: Como treinar time em AGENTS.md? (enablement)
• Scaling strategy: Como escalar pra 20+ agents? (growth)
• Continuous improvement: Como iterar no framework? (evolution)
• Metrics & ROI: Como medir economia de tempo? (measurement).

AGENTS.md isn't just a config file. It's the future of agent development. Write spec, Claude Code generates code, deploy. That's it. Early adopters will ship 10x more agents with 1/5 the cost. Late adopters will be scrambling to catch up.

Adopt AGENTS.md | Agent Framework | Standardization →