Do diagnóstico ao sistema que a equipe mantém

Quarta-feira. A dona da primeira entrega já fez o que a peça anterior pediu: o retrato da organização virou memória do projeto, a ficha da iniciativa virou critérios e limites, quem executa e quem confere estão definidos. Ela pede a primeira versão e a recebe. Funciona. E então vem a segunda pergunta, menos óbvia do que a primeira: o que acontece entre esse primeiro ciclo e um sistema que uma equipe inteira consegue manter, documentar, auditar e expandir por meses?

A resposta não é um pedido melhor nem um assistente a mais. É um conjunto completo de capacidades ao redor da ferramenta, com caminho, memória, limites e conferência embutidos, que transforma o ciclo isolado em uma forma de trabalhar. Este artigo descreve o que esse conjunto contém, usando como fundação a implementação de referência que o ecossistema Lua mantém para os próprios projetos ("Lua Toolkit" [1]), e o que ele torna possível para uma empresa que está começando ou para um desenvolvedor que ainda não montou o seu.

Três tipos de capacidade, um princípio

Um conjunto completo se organiza em três tipos de peça, e a distinção entre elas evita a maior parte da confusão.

Comandos invocáveis. Capacidades que a pessoa chama pelo nome quando quer algo específico: conduzir uma entrevista de requisitos, gerar histórias de usuário, escrever o documento de uma área, rodar um ciclo de desenvolvimento, produzir a documentação final ("skills" [2]).

Consultores com janela própria. Assistentes especializados que trabalham em contexto isolado e devolvem só o resultado: o analista que valida requisitos, o especialista de banco de dados, o avaliador que julga o que foi produzido, o advogado do diabo que questiona decisões ("subagentes" [3]).

Automações fixas. Rotinas que rodam em eventos do ciclo de vida sem interpretação: ao iniciar a sessão, antes de executar um comando perigoso, depois que uma etapa termina. Atualizam estado, registram auditoria, bloqueiam o que não pode acontecer ("hooks" [4]).

O princípio que governa os três é simples de enunciar e difícil de manter: a pessoa decide, as ferramentas executam. Nenhuma capacidade dispara outra por conta própria, salvo em modos explicitamente autorizados por quem opera. Fato objetivo vai para automação; ação interpretativa vai para comando. Não é uma esteira que roda sozinha. É um conjunto de superpoderes ao alcance da mão, com a pessoa no comando.

O caminho em seis momentos

Um conjunto completo não é uma pilha de ferramentas. É um caminho com etapas nomeadas, artefatos definidos e um estado que registra onde o projeto está, qual é o próximo passo e o que está bloqueado. Na implementação de referência, são seis momentos e vinte e três etapas ("pipeline em 6 fases" [5]).

Requisitos. Uma entrevista estruturada em oito blocos, uma pergunta por vez, que desafia respostas vagas antes de avançar e registra cada decisão como fato, não como transcrição. Dela saem histórias de usuário validadas por um analista contra um conjunto de casos conhecidos, um desenho de interface tratado como contrato visual, um contrato de integração como fonte única do que o sistema expõe, e uma base de requisitos. Para quem chega de um diagnóstico, esta é a etapa que consome o retrato da organização e a ficha da iniciativa: boa parte das perguntas já tem resposta, e a entrevista vira confirmação em vez de descoberta.

Solução por área. Seis documentos de requisitos, um por área: interfaces, o que roda por trás (fluxos, inteligência e automação), fontes de dados, governança, segurança e plataformas. Cada um é gerado por um especialista que faz quatro a seis perguntas antes de escrever, e cada um declara quais camadas técnicas cobre. As seis áreas correspondem, de forma explícita, às oito camadas do desenho técnico que um bom diagnóstico entrega ("Arquitetura de Referência por Camada" [6], com as camadas detalhadas em [9]). É o ponto em que o diagnóstico deixa de ser insumo e vira estrutura do projeto.

Especificação técnica. O mesmo desdobramento por área, agora em nível de implementação, com um ciclo de enriquecimento que rebate cada documento contra os anteriores: toda história coberta, toda integração rastreada, todo componente vinculado ao código.

Plano. As especificações viram ciclos de entrega validados, com dependências e ordem de execução.

Desenvolvimento. O ciclo em que um assistente executa e outro confere, agora em escala de ciclo de entrega ("Harness Engine" [7]). Um planejador decompõe a entrega em ondas e classifica o que cada assistente precisa ler. Um coordenador despacha especialistas em paralelo por onda, respeitando uma lista do que cada um pode ler. Um avaliador julga o resultado em onze camadas: critérios de aceitação, testes, padrão de código, rastreabilidade de fonte e regressão em toda onda; segurança, orçamento de desempenho, regressão visual, conformidade de contrato e acessibilidade uma vez por ciclo; cobertura de documentação no encerramento. Achados são classificados por gravidade, e o ciclo só passa sem achados críticos ou maiores. Regressão em funcionalidade já pronta reabre a funcionalidade, com limite de três rodadas. Um modo encadeia todos os ciclos pendentes, pausando em achado maior e com teto global de iterações.

Encerramento. Documentação de produto para quem usa, relatório de aceitação e pacote técnico para quem mantém. Antes da aceitação, uma auditoria verifica se os documentos cobrem todas as camadas técnicas, e reporta o que está coberto, parcial, ausente ou não aplicável. É o relatório que volta ao diagnóstico como evidência.

O que fica na memória

A parte menos visível de um conjunto completo é a que mais decide a qualidade: os arquivos que todo assistente consulta antes de agir.

Um guia de estilo com tom e princípios. Rubricas de qualidade por área, que o avaliador aplica. Um registro de armadilhas conhecidas, curado, com teto de tamanho para não virar ruído. Uma tabela de roteamento que decide qual especialista atende cada combinação de área e tecnologia. Uma política de modelos que separa a decisão (papel e complexidade definem um nível abstrato: econômico, equilibrado ou capaz) da resolução (qual modelo concreto atende cada nível), de modo que trocar de fornecedor não exige reescrever assistentes ("model policy" [8]). É a regra de modelo por tarefa em forma de arquivo. E um registro das decisões técnicas com a fonte de cada uma.

Esse último item merece destaque. Um protocolo de consulta de fonte funciona como portão: antes de qualquer decisão técnica, o especialista consulta a base de conhecimento da organização; se ela não cobre, a documentação oficial da tecnologia; se ainda não cobre, declara que usou conhecimento prévio; a busca na web é o último recurso. Toda decisão carrega a origem rastreável, e um especialista que inventa padrão sem fonte gera achado no avaliador. É o antídoto contra a confiança fluente que modelos produzem quando não sabem.

Limites aplicados por mecanismo

A peça sobre a estrutura ao redor da ferramenta diferenciou limite por pedido de limite por mecanismo. Um conjunto completo materializa a diferença.

Um guarda de comandos bloqueia operações destrutivas antes de executarem. Um guarda de capacidades impede que um comando rode fora da etapa em que faz sentido. Permissões de controle de versão são verificadas antes de qualquer alteração. Execuções têm modo de ensaio, ponto de retorno e reversão. Cada etapa concluída atualiza o estado do projeto, registra auditoria e captura métricas por automação, não por lembrança. O resultado é que a pessoa opera com liberdade e o sistema impede o que não pode acontecer, sem depender de que alguém tenha escrito isso no pedido do dia. São as duas condições transversais de qualquer arquitetura séria, quem responde e quem pode tocar em quê, aplicadas em escala de arquivos e assistentes.

O que isso torna possível

Para uma empresa que acabou de decidir o que vai construir, o conjunto responde à pergunta da terça-feira com um caminho. Não é preciso desenhar o processo: ele existe, com estado, próximo passo e bloqueios visíveis. O diagnóstico entra na primeira etapa e sai, ao final, como relatório de cobertura e de aceitação. Entre os dois, cada decisão tem fonte, cada entrega tem conferência e cada limite é aplicado por mecanismo.

Para uma equipe com sistema já existente, um modo de entrada faz engenharia reversa do código, detecta tecnologia e integrações, infere funcionalidades e gera os artefatos retroativos marcados como importados, com validação humana ao fim. O caminho retoma na etapa de planejamento, respeitando as decisões herdadas. E para adicionar uma funcionalidade a um projeto em andamento, um modo incremental faz perguntas curtas, gera só o que falta e marca tudo o que tocou com um identificador de sessão, de modo que "o que entrou nesta rodada?" tem resposta.

Para um desenvolvedor que está começando, a lição não é adotar tudo de uma vez. É reconhecer que cada peça do conjunto é um degrau da escada descrita em A estrutura vale mais do que a ferramenta. Um arquivo de memória com o guia de estilo já muda o resultado. Um único ciclo com critérios escritos, como em A rotina de conferência que roda toda vez, já muda a confiança. Um guarda de comandos já muda a segurança. O conjunto completo é o destino, não o ponto de partida.

O que ele não é

Não é automação total. Há pausas obrigatórias em que a pessoa aprova antes de avançar, e o modo que encadeia tudo é opcional, com pausa em achado grave. Não é barato por acidente: é econômico por construção, porque documentos são quebrados por área, cada especialista lê só o que precisa e uma lista explícita limita o resto. Não é neutro em relação à organização que o mantém: o guia de estilo, as tecnologias preferidas e os padrões recomendados refletem escolhas, e uma empresa que adote a forma precisa colocar o próprio conteúdo nesses arquivos.

E não é estático. A implementação de referência registra tentativas com a lição destilada de cada erro, mede taxa de acerto por rodada e alimenta um ciclo de melhoria do próprio conjunto. É a observação da peça de abertura em escala de sistema: estrutura não nasce pronta, e a maturidade vem de versões, medição e ajuste.

O entregável

O que este artigo deixa: a organização de um conjunto completo em três tipos de capacidade, o caminho em seis momentos com o ponto exato em que o diagnóstico vira estrutura do projeto, os arquivos de memória que sustentam a qualidade, o protocolo de consulta de fonte, os limites por mecanismo e a régua para uma empresa ou um desenvolvedor decidirem por onde começar.

Na série

Esta é a peça 7 e última da série Da decisão à entrega. O artigo estruturante, Do diagnóstico à entrega, é a porta de entrada e explica como os entregáveis do diagnóstico viram componentes da execução. As peças anteriores são A estrutura vale mais do que a ferramenta, Conferir antes de entregar, Quem faz e quem confere, A rotina de conferência que roda toda vez, Muitas entregas ao mesmo tempo e O critério de sucesso vale mais do que o pedido.

Termos citados neste artigo

[1] "Lua Toolkit": implementação de referência de um conjunto completo de capacidades mantida pelo ecossistema Lua para os próprios projetos, construída sobre uma ferramenta de desenvolvimento assistido por inteligência artificial. Inspirada em métodos públicos de desenvolvimento dirigido por especificação, reescrita do zero para o contexto Lua. Na versão consultada, reúne 49 comandos, 40 assistentes especializados, 12 automações, 16 arquivos de memória e 34 modelos de artefato.

[2] "Skills": comandos invocáveis pelo nome, cada um com pré-requisitos, artefatos produzidos e sugestão de próximo passo, sempre sujeita à aprovação humana.

[3] "Subagentes": assistentes com janela de contexto própria, instruções próprias e integrações restritas, que devolvem apenas o resultado à conversa principal. Incluem especialistas por área e por tecnologia, validadores, avaliador, arquiteto e advogado do diabo.

[4] "Hooks": automações fixas acionadas por eventos (início de sessão, antes de executar comando, ao concluir etapa). Registram estado, auditoria e métricas, e bloqueiam operações indevidas.

[5] "Pipeline em 6 fases": caminho de 23 etapas, de requisitos a encerramento, com estado registrado em arquivo legível por máquina e por pessoa, e um comando que informa posição, próximo passo e bloqueios.

[6] "Arquitetura de Referência por Camada": entregável do Impulso Framework que avalia uma iniciativa em oito camadas técnicas. Na implementação de referência, uma matriz mapeia cada camada ao documento de requisitos, ao comando e ao especialista correspondentes, e uma auditoria verifica a cobertura antes da aceitação. Detalhada em Aprofundamento Técnico por dentro.

[7] "Harness Engine": o ciclo de desenvolvimento por ciclo de entrega, com planejador, coordenador e avaliador de onze camadas, classificação de achados por gravidade, limite de rodadas de refinamento e modo encadeado com pausa em achado grave.

[8] "Model policy": política que separa a decisão de modelo (papel e complexidade definem um nível abstrato: econômico, equilibrado ou capaz) da resolução (nível define o modelo concreto do fornecedor ativo), de modo que trocar de fornecedor altera um único arquivo. É a aplicação, em arquivo, da camada de Inteligência do framework.

[9] As oito camadas técnicas do framework, cada uma com peça própria: Interfaces, Workflows, Fontes de dados, Inteligência, Automação, Governança, Segurança e Plataformas. Governança e Segurança são transversais: atravessam as demais desde o primeiro dia.

Referências

Documentação oficial da Claude (Anthropic), consultada em setembro de 2026:

Building effective agents, sobre padrões de orquestração e o cuidado com a interface entre agente e ferramentas. https://www.anthropic.com/research/building-effective-agents

Create custom subagents, sobre contexto isolado, restrição de ferramentas e escolha de modelo por assistente. https://code.claude.com/docs/en/sub-agents

Skills, sobre empacotar capacidades reutilizáveis. https://code.claude.com/docs/en/skills

Hooks, sobre automações acionadas por eventos do ciclo de vida. https://code.claude.com/docs/en/hooks

Memory, sobre instruções persistentes de projeto. https://code.claude.com/docs/en/memory

Um ciclo prova que dá para confiar. Um conjunto completo prova que dá para manter.

Breakdown | Frente: Consulting | Série Da decisão à entrega, peça 7 de 7 | Proposições ancoradas: IA como amplificador, diagnóstico que produz ação, jornada progressiva | 1.860 palavras | Leitura: 9 minutos