Projetando trabalho para sistemas de IA em vez de combatê-los

‍

Introdução — Por que comecei a explorar o desenvolvimento orientado por especificações

Nas últimas semanas, tenho trabalhado em um projeto focado em geração automática de código. Nem demonstrações, nem exemplos de brinquedos, fluxos de trabalho reais, restrições reais, iteração real.

Nos estágios iniciais, durante a execução de experimentos isolados, tudo parecia funcionar bem. Os modelos modernos são realmente muito bons para escrever código, então os resultados iniciais pareciam promissores e o progresso pareceu rápido.

Mas, muito rapidamente, apareceu um padrão: o problema não era a qualidade dos modelos, era como eu estava estruturando o trabalho, com muita dependência de correções manuais e estrutura inicial insuficiente.

Foi isso que me levou a me aprofundar Desenvolvimento orientado por especificações (SDD). Não como uma teoria, mas como uma resposta prática ao atrito de criar software com LLMs envolvidos em cada etapa.

O fluxo de trabalho pré-SDD — A solicitação funciona... até que não funcione

Meu fluxo de trabalho inicial parecia familiar:

• Eu tive uma ideia ou exigência
• Eu escrevi um aviso
• Eu tenho o código
• Eu o ajustei
• Eu repeti o loop

Isso funciona surpreendentemente bem... no começo.

Os problemas aparecem quando:

• mudança de requisitos
• o sistema cresce em tamanho e complexidade
• ou você precisa reproduzir os resultados de forma confiável

O que continuou quebrando não era o código. Foi intenção.

O “porquê” por trás das decisões estava na minha cabeça, não no sistema. Cada novo prompt estava tentando reconstruir um contexto que nunca foi capturado explicitamente.

Primeiro, contextualize — antes de iniciar o SDD

Uma constatação importante ao adotar o desenvolvimento orientado por especificações é que a qualidade da geração de código depende da qualidade do contexto.

Quando o contexto está apenas nas instruções ou na cabeça de alguém, os resultados tendem a se desviar, a iteração se torna cara e as correções manuais se acumulam. O SDD funciona melhor quando a intenção é explicitada antes que qualquer plano ou código seja gerado.

Para ver a diferença em tempo real, compare esses dois níveis de “profundidade contextual”:

• Baixo contexto: > “Importe um PDF.”
  
  • O problema: A IA precisa adivinhar tudo: o idioma, os limites de tamanho, a arquitetura e o tratamento de erros. Você provavelmente receberá um trecho que não se encaixa no seu projeto.
• Contexto superior (o ponto de partida do SDD):
  “Importe um PDF de forma assíncrona, confirmando que o tamanho é menor que 5 MB, usando uma classe 'FileManager' separada para lidar com a lógica.”
  
  • A vitória: Você definiu o conduta (assíncrono), o restrição (5 MB) e o arquitetura (aula extra). Você não está apenas pedindo código; você está fornecendo um plano.

Várias ferramentas abordam esse problema de diferentes ângulos, mas todas visam o mesmo objetivo: estabelecendo um contexto durável fora do prompt.

Três formas complementares de definir o contexto

No fluxo de trabalho tradicional, “contexto” é exatamente o que você pode encaixar em um único prompt antes que a IA comece a ter alucinações. No desenvolvimento orientado por especificações, o contexto é um ambiente estruturado. É o “sistema operacional” no qual seus agentes de IA vivem.

Para construir esse ambiente, precisamos decompor o contexto em três elementos fundamentais:

1. A camada comportamental (direção): Esses são os inegociáveis. É a “personalidade” da sua base de código. Sua equipe prefere programação funcional? Você usa convenções de nomenclatura específicas para seus arquivos? A direção garante que cada agente, não importa quando seja chamado, siga a mesma direção filosófica.
2. A camada situacional (memória): Esse é o “conhecimento tribal” do seu projeto. É o registro do motivo pelo qual você escolheu a Biblioteca A em vez da Biblioteca B, ou o caso extremo específico que você encontrou no último sprint. A memória evita o efeito “Dia da Marmota”, em que você precisa explicar a mesma restrição à IA todas as manhãs.
3. A camada operacional (regras): Essas são as “grades de proteção” para a tarefa imediata. É a sintaxe, a estrutura da pasta e as restrições específicas da API. As regras funcionam como um fio condutor em tempo real para o processo de pensamento da IA, impedindo erros antes mesmo que eles se tornem código.

Ao separar esses três, você deixa de ser um “engenheiro rápido” e começa a ser um arquiteto de sistemas. Você não está apenas dando ordens; você está projetando os limites dentro dos quais a inteligência opera.

É exatamente isso que as ferramentas modernas estão começando a resolver por meio de lentes diferentes:

• Kiro — Arquivos de direção: Define a direção de longo prazo e a intenção arquitetônica para garantir o alinhamento e evitar a improvisação.
• Claude — Memória: Permite a continuidade ao persistir decisões e preferências importantes em todas as sessões.‍
• Cursor — Regras: Fornece controle por meio de restrições locais explícitas que evitam erros de baixo nível durante a execução.

Adoção em equipe: compartilhando o contexto para garantir consistência

Para implementar com eficácia o Desenvolvimento Orientado por Especificações (SDD) em uma equipe, as principais camadas de contexto, especificamente a Camada situacional (memória) e o Camada operacional (regras), devem ser compartilhados, visíveis e com controle de versão.

A abordagem mais simples é enviar esses arquivos contextuais diretamente no repositório do projeto, permitindo que todos os membros da equipe e todos os agentes de IA operem a partir de uma única fonte confiável.

O diretório rules/ contém restrições imediatas de baixo nível que governam a qualidade, a estrutura e a execução do código para a tarefa imediata.

A memória/diretório captura decisões de alto nível, contexto histórico e conhecimento específico do projeto que evitam instruções repetitivas ou cenários do “Dia da Marmota”.

Um exemplo simples de estrutura

Na prática, isso geralmente é mapeado para uma estrutura pequena e intencional:

project-root/
├─ specs/
│  ├─ system.md
│
├─ steering/
│  ├─ principles.md
│
├─ rules/
│  ├─ coding.md
│
├─ memory/
│  ├─ decisions.md

O equipamento exato pode variar, mas o padrão permanece o mesmo:

direção separada, restrições e contexto persistente para que os sistemas de IA possam operar com menos intervenção manual e menos correções pós-geração.

Para obter detalhes mais detalhados, a documentação oficial é o melhor lugar para começar:

• https://code.claude.com/docs/en/memory
• https://cursor.com/en-US/docs/context/rules
• https://kiro.dev/docs/steering/

Essa camada de contexto explícita não é separada do Spec-Driven Development, é a base que torna o SDD possível na prática.

A integração ao fluxo de trabalho da equipe é direta e orientada por disciplinas:

1. Leia o contexto: Antes de iniciar uma tarefa, um desenvolvedor (ou o agente de IA especializado agindo em seu nome) primeiro ingere os arquivos de direção/, regras/ e memória/ relevantes.
2. Defina a especificação: O desenvolvedor escreve uma nova especificação (specs/new-feature.md) que faz referência às restrições e ao histórico.
3. Atualize o contexto: Se uma nova decisão arquitetônica for tomada durante a execução da especificação, o desenvolvedor mosto atualize o arquivo memory/decisions.md e coloque a alteração junto com o código resultante.
4. Analise as mudanças de contexto: Nas solicitações pull, o processo de revisão deve incluir a análise de quaisquer alterações propostas na memória/e regras/arquivos para garantir que elas reflitam com precisão o consenso da equipe.

O que significa desenvolvimento orientado por especificações (na prática)

Com o contexto estabelecido, o Spec-Driven Development inverte o centro de gravidade.

Em vez de:

• prompts → código → correções

Você muda para:

• especificações → planos → execução → revisão

Na prática, SDD significa:

• As especificações são a entrada principal
• O código é um artefato derivado
• A intenção é explícita e inspecionável

Isso não é:

• escrevendo mais documentação
• cachoeira disfarçada
• engenharia excessiva

É:

• restrições de design
• definindo o escopo
• tomando decisões visíveis tanto para humanos quanto para modelos

Especificações como camada de controle para desenvolvimento assistido por IA

Os LLMs são excelentes executores.

Eles não são bons em adivinhar limites.

As especificações funcionam como:

• contratos
• mecanismos de alinhamento
• reguladores de escopo

Essa ideia se reflete em várias ferramentas e abordagens:

• Kit de especificações do GitHub
• Arquivos de direção Kiro
• Habilidades, documentos e regras de Tessl
• O trabalho SDD de Martin Fowler

O novo fluxo de trabalho — SDD em ação

Ferramentas e referências que moldaram minha abordagem

• GitHub Kit de especificações
• Kiro arquivos de direção
• Tessl — habilidades, documentos, regras como primitivas
• Martin Fowler — Explorando GenAI e SDD

Claude é usado principalmente como executor dentro dessa estrutura.

Criando meu próprio fluxo de trabalho de SDD

Eu bifurquei um repositório existente e o desenvolvi em meu próprio fluxo de trabalho:

https://github.com/perzequiel/perze-claude-code

Inclui:

• agentes personalizados
• especificação → plano → ciclos de execução
• uma estrutura intencionalmente extensível

Da escrita de código à coordenação de agentes

Passo menos tempo no IDE e mais tempo:

• definindo especificações
• revisando planos
• avaliando compensações

O valor muda da implementação para estruturação de problemas.

Compensações e limitações atuais

Custos:

• design mais inicial
• mais ciclos de revisão
• disciplina exigida

Benefícios:

• menos caos
• melhor raciocínio
• sistemas mais claros

O que vem por aí (pequeno spoiler)

• MCPs
• habilidades mais especializadas
• colaboração mais estreita entre agentes

Detalhes para outra postagem.

Uma nota sobre Warp

Estou usando Urdidura como um sistema operacional de trabalho com fluxos de trabalho multiagentes, me afastando ainda mais do IDE.

Fale:

https://www.youtube.com/watch?v=w0bJFC0u0pE

Fechando

No cenário de desenvolvimento moderno, a simples acessibilidade de ferramentas e estruturas poderosas mudou drasticamente o foco do esforço de engenharia. Quando o código se torna barato, o design se torna o trabalho. Isso não quer dizer que escrever código seja trivial, mas sim que o custo, em termos de tempo, complexidade e experiência, de produzir código funcional diminuiu em relação ao custo de produzir sistemas bem projetados, sustentáveis e corretos. O valor está em uma arquitetura cuidadosa, interfaces claras e uma compreensão compartilhada da intenção.

O desenvolvimento orientado por especificações é uma forma prática de tornar esse design explícito, revisável e executável. O SDD exige que a definição do comportamento de um sistema, sua especificação ou “especificação”, seja criada antes ou simultaneamente com a implementação. Essa especificação serve como a única fonte de verdade, movendo o processo de design da cabeça do desenvolvedor para um artefato formalizado e acessível. Ao formalizar o projeto por meio de especificações executáveis, o SDD transforma conceitos arquitetônicos abstratos em contratos concretos e testáveis. Essa abordagem facilita o feedback precoce, os testes automatizados de conformidade e um maior grau de confiança na capacidade do sistema de atender aos requisitos.