How Brandon's production multi-agent SDLC harness turns Claude Code into a structured, scalable workflow engine — from scoped sessions to parallel worktrees.
Quando comecei a usar o Claude Code em projetos reais, meu primeiro instinto foi o mesmo que o da maioria dos engenheiros: abrir um terminal, descrever o que quero e deixá-lo rodar. Isso funciona bem para um script pontual ou uma correção rápida de bug. Quebra no momento em que a tarefa se estende por mais de um arquivo, mais de um ponto de decisão ou mais de uma hora.
O modo de falha é sempre o mesmo. O contexto cresce até as sugestões do Claude pararem de ser fundamentadas na sua base de código real. Você aceita uma mudança em uma área sem perceber que ela quebra um contrato em outra. A sessão deriva, e ao final você não tem certeza do que realmente construiu.
Bati nessa parede cedo no trabalho do meu framework de orquestração Python. Estava construindo um harness SDLC multi-agente — um sistema que pega um spec de funcionalidade e o conduz pelas fases implement → test → review → document, em paralelo, em worktrees git, num Mac Mini atrás de um Cloudflare Tunnel. Tentar construir todo esse harness em uma longa sessão do Claude Code era como tentar fundir a fundação, estruturar as paredes e passar a fiação elétrica ao mesmo tempo.
O insight central: O Claude Code se torna uma ferramenta de fluxo de trabalho escalável quando você trata cada sessão como uma unidade de trabalho delimitada — com uma entrada clara, uma saída clara e um critério explícito de saída.
Três primitivas tornam isso possível:
Analogia: Pense em um arquivo CLAUDE.md da mesma forma que você pensa em um bom documento de integração para engenheiros. Um novo contratado acelera lendo-o; uma nova sessão do Claude adquire contexto do projeto da mesma forma. A diferença é que o "novo contratado" reinicia completamente entre cada conversa — o documento é a única memória dele.
O restante deste módulo constrói a partir do caso mais simples e útil até o padrão de orquestração em ondas de produção que conduz meu harness SDLC.
Antes de chegar a worktrees paralelos ou scripts de orquestração, comece com o que funciona para 80% das tarefas reais: uma única sessão com um CLAUDE.md com escopo e um spec de tarefa claro.
Um CLAUDE.md na raiz do seu projeto (ou de um worktree) é lido automaticamente no início de cada sessão do Claude Code naquele diretório. É a alavanca mais subutilizada para manter sessões focadas.
O CLAUDE.md mais útil para um branch de funcionalidade tem três partes:
<CodeExample title="CLAUDE.md — Contexto do Branch de Funcionalidade" language="markdown" code={`# Contexto
Este branch adiciona rate limiting à API de submissão de tarefas. Ver: planning/tasks/rate-limiting/tasks.md
Uma vez que o padrão de sessão única esteja sólido, o próximo nível é executar múltiplas sessões em paralelo em worktrees git isolados. Esse é o padrão central do meu harness SDLC de produção.
Um git worktree cria um diretório de trabalho separado para um branch sem precisar de stash ou troca de branch. Duas sessões do Claude Code em dois worktrees trabalham em paralelo sem estado de arquivo compartilhado, sem contenção de lock, sem interferência.
Cada diretório de worktree é um checkout completo do repositório no seu próprio branch. A única diferença em relação ao diretório de trabalho principal é qual branch ele está. Sessões do Claude Code iniciadas nesses diretórios são completamente independentes.
Com os worktrees configurados, cada sessão roda no seu próprio terminal:
A chave é dizer a cada sessão para parar em uma condição específica e verificável. "Parar quando npm test passar" é um critério de saída real. "Faça a funcionalidade" não é.
Armadilha: Duas sessões do Claude Code modificando o mesmo arquivo no mesmo diretório criam condições de corrida. Sempre dê a cada sessão paralela o seu próprio worktree. O custo de configuração de dois comandos vale a pena sempre.
Quando ambas as sessões terminam, eu mesclo na ordem em que as dependências exigem. Se o endpoint do webhook depende da biblioteca de entrega, a biblioteca vai para o main primeiro:
Essa sequência é exatamente o que o harness SDLC automatiza: ondas ordenadas por dependência, com cada onda mesclando antes da próxima começar. A versão manual torna a lógica explícita antes de automatizá-la.
Uma vez que o padrão manual seja rotineiro, extraí-lo para um script é direto. O seguinte é uma versão simplificada de como o harness SDLC conduz uma onda de tarefas paralelas:
O harness SDLC de produção lê um grafo de dependências do spec de tarefa e agrupa tarefas em ondas automaticamente. Mas o loop central acima é o esqueleto sobre o qual cada camada do sistema completo é construída.
Arquivos CLAUDE.md são hierárquicos. Um arquivo na raiz de um worktree se aplica a toda a sessão; um arquivo em um subdiretório restringe o contexto para aquele escopo. Uso isso no harness SDLC para dar restrições específicas de tarefa sem inchar o arquivo de nível de projeto:
O CLAUDE.md mais interno vence para seu diretório — o mesmo princípio de configuração com escopo de diretório na maioria das cadeias de ferramentas. Regras mais amplas definem padrões; regras específicas de tarefa as substituem conscientemente.
Antes do quiz, trabalhe mentalmente por estas verificações:
Verificação 1: Você tem uma funcionalidade que muda um esquema de banco de dados compartilhado e adiciona uma rota de API que lê dele. Estas podem ser duas sessões paralelas de worktree, ou devem ser sequenciais? Por quê?
Verificação 2: O que acontece com a Sessão 2 após a Sessão 1 mesclar ao main e a Sessão 2 ainda estar rodando? O que você precisa fazer antes de mesclar a Sessão 2?
Verificação 3: No script de orquestração por ondas, npm test roda após cada mesclagem, não uma vez ao final. Por que a ordem importa?
Reserve um minuto para trabalhar cada um antes do quiz. As perguntas abaixo testam o mesmo raciocínio por ângulos diferentes.
O caminho mais curto para sessões confiáveis do Claude Code: Escreva um CLAUDE.md com limites explícitos de arquivo e um critério de saída verificável. Essas duas adições eliminam a maioria do alargamento de escopo e da deriva de contexto.
1. Uma hora numa sessão do Claude Code para adicionar uma nova rota de API, o Claude começa a sugerir mudanças na camada de autenticação. Qual é a causa raiz mais provável?
Correct Answer: B
Sem limites explícitos de arquivo no CLAUDE.md, o Claude segue as conexões lógicas do código — a rota referencia auth, então explora auth. Um limite 'Toque APENAS nesses arquivos' no CLAUDE.md previne o alargamento de escopo na origem, antes da sessão começar.
2. A Funcionalidade A adiciona uma nova tabela de banco de dados. A Funcionalidade B adiciona uma rota de API que consulta essa tabela. Como você deve estruturar essas como sessões de worktree?
Correct Answer: C
B depende da saída de A. Paralelo só é seguro para tarefas independentes. Executar A primeiro, verificar que mescla de forma limpa, então iniciar B no main atualizado garante que B tenha o esquema real para trabalhar — não uma suposição sobre o que A vai produzir.
3. A Sessão 1 termina e você a mescla ao main. A Sessão 2 ainda está rodando no seu worktree. O que você deve fazer antes de mesclar a Sessão 2?
Correct Answer: C
A Sessão 2 fez branch do main antes da Sessão 1 pousar. Um rebase sobre o main atualizado garante que a saída da Sessão 2 seja compatível com as mudanças da Sessão 1. Sempre re-execute o portão de validação após um rebase — o rebase pode revelar incompatibilidades que apenas testes vão capturar.
4. No script de orquestração por ondas, por que npm test roda após cada mesclagem em vez de uma vez ao final?
Correct Answer: C
Um portão após cada mesclagem age como um checkpoint. Se a segunda mesclagem falha nos testes, você sabe exatamente qual funcionalidade introduziu a regressão e o main está apenas uma mesclagem à frente de onde estava. Capturar ao final deixa você depurando um diff combinado que pode ser muito maior.
5. O que um spec de sessão delimitada precisa minimamente para ser confiável?
Correct Answer: C
Escopo sem critério de saída causa deriva. Critério de saída sem escopo causa alargamento de escopo. Restrições sem escopo deixam o Claude modificar qualquer arquivo que satisfaça a restrição. Todos os três juntos tornam uma sessão autocontida e auto-terminante.
6. Um CLAUDE.md raiz do projeto diz 'Nunca modifique auth/'. Um CLAUDE.md de nível de tarefa em um worktree diz 'Atualize auth/middleware.ts para adicionar cabeçalhos de rate-limit'. Qual tem precedência, e por quê?
Correct Answer: B
Arquivos CLAUDE.md mais específicos restringem ou substituem os mais amplos — o mesmo princípio de configuração com escopo de diretório na maioria das cadeias de ferramentas. O arquivo de nível de tarefa reflete uma substituição deliberada e com escopo. O arquivo raiz define padrões de projeto; arquivos de tarefa os estendem conscientemente para um contexto delimitado específico.