Agentic Squad: modelando o SDLC com agentes, contratos e aprendizado contínuo

Existe uma diferença grande entre usar IA para acelerar tarefas e redesenhar o fluxo de engenharia para trabalhar melhor com IA.

A primeira coisa é comum: pedir para um modelo escrever testes, explicar código, gerar um README ou sugerir um refactor. A segunda é mais difícil: criar um sistema onde agentes, contexto, decisões técnicas, regras do time, histórico do projeto e revisão humana trabalham juntos sem virar caos.

É nesse segundo espaço que entra a ideia da Agentic Squad.

A Agentic Squad não é uma tentativa de substituir uma equipe de engenharia. Também não é uma coleção de prompts soltos. A proposta é modelar um modo de trabalho em que agentes ajudam em etapas específicas do SDLC, com contratos claros, contexto versionado, papéis explícitos, validações e aprendizado contínuo.

O problema: agentes sem sistema viram automação frágil

A forma mais comum de usar agentes hoje ainda é improvisada.

Alguém abre uma ferramenta, cola uma tarefa grande, adiciona alguns arquivos, pede para implementar e espera um resultado bom. Às vezes funciona. Muitas vezes parece funcionar. Em sistemas reais, porém, os problemas aparecem rápido:

• o agente não conhece as decisões anteriores;
• o contexto fica grande, caro e inconsistente;
• regras importantes do time não são lembradas;
• padrões locais são misturados com padrões genéricos;
• o código parece correto, mas quebra uma convenção;
• a revisão humana vira caça a efeitos colaterais;
• aprendizados de uma tarefa não melhoram a próxima.

O erro não está em usar agentes. O erro está em usar agentes sem arquitetura de trabalho.

O que é Agentic Squad

Agentic Squad é uma proposta de arquitetura para coordenar agentes de IA ao longo do ciclo de desenvolvimento de software.

Ela organiza:

• etapas do SDLC;
• capacidades acionadas em cada etapa;
• contratos de contexto;
• regras e playbooks;
• skills reutilizáveis;
• validações automáticas;
• revisão humana;
• aprendizado contínuo;
• separação entre conhecimento global, conhecimento do time e conhecimento local do repositório.

Em vez de pensar "quero um agente PM, um agente Tech Lead, um agente QA e um agente Dev", a ideia central é outra:

modelar o SDLC por etapas, e acionar capacidades conforme a necessidade.

Isso evita um teatro de cargos artificiais e aproxima o sistema do fluxo real de engenharia.

A decisão mais importante: etapas antes de papéis

Uma armadilha comum em sistemas agentic é começar pelos papéis.

Parece natural desenhar algo como:

Isso é sedutor, mas pode ficar teatral. Em times reais, trabalho não acontece em caixas tão limpas. Um Tech Lead participa de discovery. Um dev identifica risco de arquitetura. QA ajuda a esclarecer requisito. Segurança aparece no refinamento. SRE influencia decisões de deploy.

Por isso, a Agentic Squad modela primeiro as etapas.

A frase-guia é:

SDLC primeiro; papéis como capacidades.

Um modelo em camadas

A Agentic Squad precisa separar o que é genérico, o que é do time e o que é local.

Uma forma prática de organizar isso é em camadas:

agentic-squad-reference/
  ├─ patterns/
  ├─ skills/
  ├─ rules/
  ├─ playbooks/
  ├─ checklists/
  └─ examples/
agentic-squad-team-core/
  ├─ domain/
  ├─ architecture-decisions/
  ├─ team-rules/
  ├─ delivery-playbooks/
  └─ quality-gates/
consumer-repo/
  ├─ agentic-squad.yaml
  ├─ .agentic/
  │   ├─ context.md
  │   ├─ local-rules.md
  │   └─ lessons.md
  └─ src/

A camada de referência contém padrões reutilizáveis. A camada do time contém decisões específicas daquele contexto. O repositório consumidor carrega apenas o necessário para operar bem localmente.

Essa separação reduz dois riscos:

1. transformar cada repositório em um depósito de prompts duplicados;
2. colocar regras locais demais em um template global.

O contrato: agentic-squad.yaml

Uma Agentic Squad precisa de contrato.

Sem contrato, cada execução vira uma conversa nova. Com contrato, o agente entende quais capacidades existem, quais arquivos são fonte de verdade, quais comandos validam a entrega e quais limites não podem ser cruzados.

Um exemplo simplificado:

version: "0.1"
project:
  name: "booking-backoffice"
  domain: "post-sale travel operations"
  defaultLocale: "pt-BR"
sources:
  localContext:
    - ".agentic/context.md"
    - ".agentic/local-rules.md"
  teamCore:
    - "../agentic-squad-team-core/team-rules/"
    - "../agentic-squad-team-core/architecture-decisions/"
  reference:
    - "../agentic-squad-reference/playbooks/"
    - "../agentic-squad-reference/checklists/"
stages:
  discovery:
    requiredOutputs:
      - problem-statement
      - constraints
      - open-questions
  architecture:
    requiredOutputs:
      - tradeoffs
      - risks
      - decision-record
  implementation:
    qualityGates:
      - pnpm lint
      - pnpm typecheck
      - pnpm test
      - pnpm build
  review:
    requiredChecks:
      - "Does this preserve existing behavior?"
      - "Are errors observable?"
      - "Is rollback clear?"
policies:
  humanInTheLoop: true
  neverCommitWithoutApproval: true
  neverExposeSecrets: true
  preferSmallDiffs: true

Esse arquivo não precisa ser grande no começo. O valor está em declarar o mínimo necessário para evitar improviso.

Como um agente deveria usar esse contrato

Um agente não deveria receber só uma tarefa. Ele deveria receber uma tarefa dentro de uma etapa.

Exemplo ruim:

Implemente a tela de busca.

Exemplo melhor:

Estamos na etapa de Specification.
Objetivo:
definir o contrato da busca antes de implementar.
Use:
- agentic-squad.yaml
- regras locais
- decisões de arquitetura do time
- handoff de UX
Entregue:
- casos de uso
- estados
- eventos
- critérios de aceite
- riscos
- perguntas em aberto
Não implemente código ainda.

A diferença parece pequena, mas muda o comportamento do agente. Ele deixa de correr para código e passa a respeitar a etapa.

CLI como setup e compilador de contexto

Uma ideia importante da Agentic Squad é ter uma CLI que prepare o contexto certo para cada etapa.

Por exemplo:

agentic-squad init
agentic-squad run discovery --issue 123 --repo booking-backoffice
agentic-squad run architecture --input .agentic/work/discovery-123.md
agentic-squad run implementation --plan .agentic/work/plan-123.md
agentic-squad learn --from-pr 456

A CLI não precisa "ser inteligente" no começo. Ela pode apenas validar o agentic-squad.yaml, resolver caminhos, montar contexto, selecionar playbooks, gerar prompts, rodar quality gates, salvar outputs e registrar aprendizados.

O valor está menos em automação mágica e mais em consistência operacional.

Exemplo de compilação de contexto

Um comando como agentic-squad context poderia produzir um pacote temporário:

{
  "stage": "implementation",
  "repo": "booking-backoffice",
  "task": "add newsletter subscribe endpoint",
  "contextFiles": [
    ".agentic/context.md",
    ".agentic/local-rules.md",
    "../agentic-squad-team-core/team-rules/api-style.md",
    "../agentic-squad-reference/checklists/implementation.md"
  ],
  "qualityGates": ["pnpm lint", "pnpm typecheck", "pnpm test", "pnpm build"],
  "constraints": [
    "do not commit without approval",
    "do not add dependencies without justification",
    "preserve i18n",
    "preserve data-theme"
  ]
}

Esse pacote pode virar prompt para Claude Code, Codex ou outra ferramenta.

Um exemplo didático de implementação

Um esqueleto de loader em TypeScript poderia começar assim:

// Esqueleto didático: carrega e valida o contrato (Zod) antes de qualquer execução.
import { readFile } from "node:fs/promises";
import path from "node:path";
import { z } from "zod";
 
const StageSchema = z.object({
  requiredOutputs: z.array(z.string()).optional(),
  qualityGates: z.array(z.string()).optional(),
  requiredChecks: z.array(z.string()).optional(),
});
 
const AgenticSquadConfigSchema = z.object({
  version: z.string(),
  project: z.object({
    name: z.string(),
    domain: z.string().optional(),
    defaultLocale: z.string().default("pt-BR"),
  }),
  sources: z.object({
    localContext: z.array(z.string()).default([]),
    teamCore: z.array(z.string()).default([]),
    reference: z.array(z.string()).default([]),
  }),
  stages: z.record(StageSchema),
  policies: z.object({
    humanInTheLoop: z.boolean().default(true),
    neverCommitWithoutApproval: z.boolean().default(true),
    neverExposeSecrets: z.boolean().default(true),
    preferSmallDiffs: z.boolean().default(true),
  }),
});
 
export type AgenticSquadConfig = z.infer<typeof AgenticSquadConfigSchema>;
 
export async function loadAgenticSquadConfig(
  cwd: string,
): Promise<AgenticSquadConfig> {
  const configPath = path.join(cwd, "agentic-squad.yaml");
  const raw = await readFile(configPath, "utf8");
  const parsed = parseYaml(raw);
  return AgenticSquadConfigSchema.parse(parsed);
}
 
function parseYaml(_raw: string): unknown {
  throw new Error(
    "This is a teaching skeleton — wire a real YAML parser here before parsing the agentic-squad.yaml contract.",
  );
}

Esse código não resolve o problema inteiro. Ele só mostra uma direção: contrato primeiro, validação depois, execução por etapa.

O ciclo de aprendizado

Sem aprendizado, a Agentic Squad vira apenas um gerador de prompts.

Classificar aprendizado em camadas

O aprendizado precisa ser classificado em camadas.

Nem todo aprendizado merece virar regra global.

Esse ponto é crítico. Times ruins transformam qualquer incidente em regra universal. Times bons perguntam:

• isso é local ou recorrente?
• isso é regra, exemplo ou cheiro?
• isso deve bloquear entrega?
• isso melhora o próximo PR?
• isso envelhece rápido?
• isso é verdade em todos os contextos?

Exemplo de registro de aprendizado

# Learning Record
 
## Context
 
PR #456 introduced a regression in the search page after changing locale-aware URLs.
 
## What happened
 
The implementation updated visible links but missed canonical URLs and sitemap entries.
 
## Lesson
 
When changing public URL structure, update:
 
- route helpers
- canonical metadata
- hreflang
- sitemap
- RSS
- language switcher
- redirect tests
 
## Scope
 
team-core
 
## Suggested artifact
 
Add this to the URL migration checklist.

Do registro ao checklist

Esse registro pode depois virar um checklist que o agente realmente consegue usar:

# URL Migration Checklist
 
Before implementation:
 
- [ ] Identify route helpers
- [ ] Identify canonical generation
- [ ] Identify hreflang generation
- [ ] Identify sitemap generation
- [ ] Identify RSS generation
- [ ] Identify language switcher behavior
- [ ] Identify redirects
 
During implementation:
 
- [ ] Update public route mapping
- [ ] Preserve internal locale model
- [ ] Add redirects from old URLs
- [ ] Update tests
- [ ] Update screenshots
 
Before PR:
 
- [ ] Validate canonical URLs
- [ ] Validate sitemap output
- [ ] Validate RSS output
- [ ] Validate language switcher
- [ ] Validate old URLs redirect

Esse tipo de artefato é mais útil do que um prompt genérico dizendo "seja cuidadoso".

O que a Agentic Squad não deve ser

A Agentic Squad não deveria virar uma fantasia de autonomia total.

Ela não deve ser:

• uma equipe falsa de avatares;
• uma tentativa de remover revisão humana;
• um monte de prompts duplicados;
• uma camada burocrática sobre o desenvolvimento;
• um sistema que aprova o próprio trabalho;
• uma desculpa para aceitar código sem entender;
• um orquestrador complexo antes de existir problema real.

Trade-offs

Um fluxo possível de trabalho

1. Discovery
   ↓
2. Refinement
   ↓
3. Specification
   ↓
4. Architecture
   ↓
5. Planning
   ↓
6. Implementation
   ↓
7. Quality
   ↓
8. Review
   ↓
9. Merge/Deploy
   ↓
10. Retrospective/Learning

Cada etapa pode gerar artefatos pequenos, versionáveis e revisáveis. Por exemplo:

.agentic/work/123-discovery.md
.agentic/work/123-specification.md
.agentic/work/123-architecture.md
.agentic/work/123-plan.md
.agentic/work/123-review.md
.agentic/work/123-learning.md

Isso cria rastreabilidade sem precisar de uma plataforma pesada.

Como isso conversa com ferramentas como Claude Code e Codex

A Agentic Squad não precisa substituir ferramentas existentes. Ela pode funcionar como camada de contexto e governança.

Claude Code, Codex, GitHub Copilot, agentes locais e scripts internos podem ser consumidores do mesmo contrato. A lógica seria:

agentic-squad.yaml
        ↓
context compiler
        ↓
prompt/stage pack
        ↓
Claude Code / Codex / local agent
        ↓
diff + validation
        ↓
human review
        ↓
learning record

O ganho está em não depender da memória implícita de uma conversa.

Onde começar pequeno

A versão mínima não precisa ter multiagente real. Uma boa primeira versão poderia ter apenas um agentic-squad.yaml, um diretório .agentic/, três playbooks, três checklists, um script para montar contexto e um fluxo de aprendizado manual.

Por exemplo:

mkdir -p .agentic/work .agentic/lessons
touch agentic-squad.yaml
touch .agentic/context.md
touch .agentic/local-rules.md
touch .agentic/lessons.md

E três comandos:

agentic-squad context --stage implementation
agentic-squad check --stage review
agentic-squad learn --from-pr 123

Critérios para saber se está funcionando

A Agentic Squad só tem valor se melhorar a engenharia.

Sinais bons:

• PRs menores;
• menos retrabalho;
• decisões mais explícitas;
• menos prompts reinventados;
• onboarding mais rápido;
• validações mais consistentes;
• menos regressões por esquecimento;
• melhores checklists;
• revisão humana mais focada em trade-offs.

Sinais ruins:

• excesso de arquivos que ninguém lê;
• agentes produzindo documentação decorativa;
• regras conflitantes;
• prompts enormes e frágeis;
• baixa confiança nos diffs;
• humanos revisando mais, não menos;
• qualidade parecendo boa só porque o texto é bonito.

Um exemplo de prompt por etapa

# Stage: Architecture
 
You are helping with the architecture stage of a software change.
Use the configured Agentic Squad context.
Your job is not to implement code yet.
 
Produce:
 
1. problem summary
2. constraints
3. relevant existing patterns
4. proposed architecture
5. alternatives considered
6. trade-offs
7. risks
8. observability concerns
9. security concerns
10. quality gates
11. questions before implementation
 
Rules:
 
- Do not change files.
- Do not assume missing requirements.
- Prefer small, reversible decisions.
- Be explicit about uncertainty.

Esse prompt é simples, mas limita o agente ao papel certo naquele momento.

A parte humana continua sendo central

A Agentic Squad não elimina julgamento. Ela depende dele.

Humanos continuam decidindo:

• se o problema vale ser resolvido;
• se o design está correto;
• se o trade-off faz sentido;
• se a solução é simples o bastante;
• se a regra deve virar padrão;
• se o agente está alucinando com confiança;
• se a entrega realmente melhora o sistema.

A IA pode acelerar a produção de opções. A engenharia decide quais opções sobrevivem.

Conclusão

Agentic Squad é menos sobre criar agentes brilhantes e mais sobre criar um ambiente onde agentes comuns possam trabalhar melhor.

O núcleo da ideia é simples: etapas claras, contexto certo, contratos versionados, regras explícitas, validação automática, revisão humana e aprendizado contínuo.

Não é uma promessa de autonomia total. É uma proposta de governança técnica para IA aplicada ao desenvolvimento de software.

Se funcionar, o maior ganho não será escrever código mais rápido. Será reduzir o custo de manter coerência enquanto a velocidade aumenta.

Próximos passos

• Transformar o contrato agentic-squad.yaml em um schema versionado.
• Criar um CLI mínimo para compilar contexto.
• Escrever playbooks por etapa do SDLC.
• Rodar a Agentic Squad em um repositório real pequeno antes de escalar.

Quem quiser acompanhar a evolução pode seguir pela página de Writing.