Kit operacional — contexto vivo sem superprompt

O problema do arquivo que tenta conter tudo

Um “Prompt Mestre” com arquitetura, segurança, pesquisa, agentes, testes, deploy e estilo parece conveniente. Depois de algumas semanas, possui centenas de linhas, regras contraditórias e detalhes que entram em toda tarefa — inclusive quando o pedido é corrigir uma palavra. O agente gasta atenção separando o relevante do ruído.

O kit comum desta edição resolve o problema por divulgação progressiva (progressive disclosure): o índice sempre ativo é curto; documentos especializados são carregados quando necessários; regras que podem ser provadas viram scripts ou CI.

Ao final, você deverá conseguir instalar o kit em um repositório, preencher os arquivos mínimos para o primeiro projeto e explicar por que cada informação está em seu lar canônico.

O que cada termo significa

• AGENTS.md: instruções duráveis do repositório para agentes. Funciona como índice operacional, não como enciclopédia.
• Context index: mapa que informa onde está cada fonte de verdade e quando consultá-la.
• Source of truth: artefato canônico que decide uma informação. Uma cópia não deve competir com ele.
• ADR (Architecture Decision Record): registro curto de uma decisão arquitetural difícil de reverter, com contexto e consequências.
• Handoff: estado vivo necessário para outra sessão continuar. Não é arquivo histórico infinito.
• Guardrail: limite que previne ou detecta desvio. Quando determinístico, deve ser executável.
• Living documentation: documentação mantida junto com a mudança que altera a realidade descrita.

A arquitetura do kit

AGENTS.md
└── docs/CONTEXT_INDEX.md
    ├── PRODUCT.md
    ├── ARCHITECTURE.md
    ├── DATA_CONTRACTS.md
    ├── SECURITY.md
    ├── TESTING.md
    ├── EVAL_STRATEGY.md
    ├── RELEASE.md
    ├── OPERATIONS.md
    ├── ADR/
    ├── handoffs/
    └── research/

O kit copiável está em kits/project-starter/common. Ele inclui também START_HERE.md, PROJECT_BRIEF.md, REPO_AUDIT.md, HANDOFF.md, DEFINITION_OF_DONE.md e templates de spec, ticket, protótipo, pesquisa, evidência e retrospectiva.

Passo 1 — auditar antes de instalar

Em repositório existente, leia arquivos de orientação, README, manifests, configurações, comandos e testes. Mapeie fontes de verdade, duplicatas, documentos mortos e áreas protegidas. Não crie ARCHITECTURE.md descrevendo uma arquitetura imaginária.

O resultado é REPO_AUDIT.md, com fatos observados, riscos, lacunas e perguntas. Em projeto novo, registre que o repositório está vazio e quais decisões ainda não existem.

Passo 2 — preencher somente o mínimo

Para o primeiro projeto, comece com:

1. PROJECT_BRIEF.md;
2. CONTEXT_INDEX.md;
3. TESTING.md;
4. DEFINITION_OF_DONE.md;
5. uma spec e um ticket vertical.

Crie os demais arquivos quando o projeto adquirir aquela responsabilidade. Um site estático sem banco não precisa fingir possuir contratos de persistência; DATA_CONTRACTS.md pode registrar “não aplicável nesta etapa” e o gatilho que o tornará necessário.

Passo 3 — manter AGENTS.md como mapa

Um bom arquivo responde rapidamente:

• onde estamos;
• o que não pode ser alterado;
• quais comandos verificam o trabalho;
• onde ler produto, arquitetura e segurança;
• o que significa terminar.

Detalhes de autenticação pertencem a SECURITY.md; o fluxo de deploy, a RELEASE.md; um procedimento repetido, a uma skill. A documentação atual do Codex recomenda manter AGENTS.md prático e conciso, apontando arquivos específicos quando cresce.

Passo 4 — classificar conhecimento

Informação	Lar
regra estável do repositório	AGENTS.md ou documento canônico apontado
requisito e jornada	PRODUCT.md ou spec
decisão difícil de reverter	ADR
procedimento repetível sob demanda	skill
regra determinística	teste, schema, lint, hook ou CI
estado da execução atual	handoff
evidência externa e temporal	pesquisa com fonte e data
preferência pessoal opcional	configuração ou memória, nunca única fonte obrigatória

Passo 5 — validar mecanicamente

O manifesto do kit declara tipo de artefato, risco, nível S0–S3, pacotes exigidos, critérios, comandos e portões de aprovação. O validador confere arquivos obrigatórios, valores permitidos, referências e orçamento de linhas.

O alvo de 80–220 linhas ajuda arquivos frequentemente carregados; acima de 300 linhas gera falha no kit comum, exceto referência declarada. Isso não mede qualidade editorial. Um arquivo de 40 linhas pode estar errado e um manual de 500 pode ser adequado — desde que não seja injetado sempre.

Passo 6 — handoff e continuidade

Um handoff registra:

• objetivo e escopo atual;
• o que foi concluído com evidência;
• decisões e arquivos canônicos;
• checks executados e resultados;
• riscos e bloqueios;
• próximo passo exato.

Não copie toda a conversa. A próxima sessão deve conseguir continuar sem reinterpretar ruído, mas também não deve confiar em uma declaração sem arquivo ou saída verificável.

Passo 7 — aprendizado durável

Depois de uma falha, escolha o artefato correto:

• bug reproduzível → teste de regressão;
• regra sempre relevante → instrução curta;
• procedimento recorrente → skill;
• decisão arquitetural → ADR;
• permissão perigosa → política e controle;
• lacuna temporal → pesquisa revisada;
• estado temporário → handoff.

“Adicionar ao prompt” é apenas uma das opções e frequentemente não é a melhor.

Percurso guiado pelos documentos

Imagine que você recebeu uma aplicação de manutenção e precisa acrescentar prioridade às ordens. Não preencha todos os modelos. Abra START_HERE.md, classifique a tarefa e siga os ponteiros necessários.

1. REPO_AUDIT.md: descubra comandos, frameworks, testes e fontes reais. Se já existe documento equivalente, registre-o; não crie concorrente.
2. PROJECT_BRIEF.md: descreva pessoa, problema, valor, restrições e o que ficará fora da primeira entrega.
3. PRODUCT.md: registre jornada e regra de negócio. “Prioridade imediata exige motivo” pertence aqui.
4. DATA_CONTRACTS.md: defina valores, obrigatoriedade, compatibilidade e resposta de erro para frontend e API concordarem.
5. SECURITY.md: identifique quem pode alterar prioridade, abusos relevantes e aprovação necessária.
6. TESTING.md e EVAL_STRATEGY.md: converta critérios em provas antes da mudança.
7. HANDOFF.md: ao interromper, registre arquivos, checks, evidências, bloqueios e próximo passo.

ARCHITECTURE.md, RELEASE.md e OPERATIONS.md entram quando a mudança afeta fronteiras, entrega ou execução. Progressive disclosure não esconde documentos; carrega detalhe quando ele influencia a decisão presente.

Exemplo de contexto mínimo para um agente

Objetivo: supervisor classifica uma OS como normal, alta ou imediata.
Regra: prioridade imediata exige motivo; técnico pode visualizar, não alterar.
Contrato: PATCH /orders/{id}/priority com version para concorrência otimista.
Prova: testes de papel, motivo obrigatório, conflito de versão e auditoria.
Fora de escopo: recalcular automaticamente prioridade com IA.
Pare quando: critérios passam, revisão não encontra falha crítica e evidências estão registradas.

O bloco aponta para decisões registradas; não as substitui. O agente consulta detalhes sob demanda e não precisa receber o repositório inteiro em cada turno.

Quando criar ADR, skill, hook ou MCP

Use ADR para decisão importante e cara de reverter, como escolher o ERP como fonte oficial. Crie skill para procedimento repetível que exige julgamento e recursos, como auditar um capítulo. Crie teste, hook ou CI para regra determinística, como rejeitar ID duplicado. Use MCP quando o agente precisa de contexto ou ações externas vivas por interface padronizada; um manual estático não precisa virar servidor.

Esses mecanismos não são níveis obrigatórios. Transformar toda regra em prompt enfraquece enforcement; toda referência em MCP amplia operação e ataque; toda decisão em skill cria pacotes genéricos difíceis de acionar.

Ciclo de vida e conflitos

Documentação viva não é reescrita automática sem revisão. Cada arquivo precisa de responsável, evento de revisão e ligação com prova. Quando código e documento divergem, registre o conflito, descubra a fonte autorizada e corrija a causa.

Antes de adicionar, procure duplicatas. Melhore o lar canônico e atualize ponteiros. Antes de remover, preserve decisões históricas necessárias em ADR ou migração. O objetivo é reduzir contradição, não maximizar Markdown.

O manifesto declara arquivos, limites e validação. O build falha quando um documento some ou surge Markdown não declarado. A arquitetura de contexto deixa de depender apenas de disciplina humana.

Como era e como funciona atualmente

O primeiro padrão de uso de assistentes era concentrar instruções em um “prompt mestre”. Ele podia ser útil para uma tarefa isolada, mas misturava regra estável, descrição do produto, procedimento, estado temporário e pesquisa. Quando algo mudava, surgiam cópias divergentes; quando o texto crescia, detalhes importantes competiam por atenção.

A arquitetura atual usa um índice curto e fontes de verdade modulares. Regras sempre relevantes ficam próximas do agente; decisões de produto e engenharia têm lares próprios; procedimentos sob demanda viram skills; estado temporário fica no handoff; checks determinísticos são executados por ferramentas. O modelo recebe o contexto necessário para a etapa, com ponteiros para aprofundar.

Isso não obriga todo projeto a criar quinze documentos vazios. Um repositório pequeno pode começar com START_HERE.md, PROJECT_BRIEF.md, TESTING.md e DEFINITION_OF_DONE.md. Outros arquivos entram quando existe decisão correspondente. Criar estrutura sem conteúdo produz falsa organização; deixar tudo na conversa produz perda de memória. O kit oferece opções e um caminho de crescimento, não uma cerimônia fixa.

Também não existe uma linha universal de 300 linhas que determine qualidade. O teto operacional do kit é um sinal para revisar responsabilidade e frequência de carregamento. Um manual profundo pode ser longo; um arquivo lido em toda execução precisa ser enxuto. O critério é manter informação localizável, não satisfazer uma contagem por si só.

Exemplo: sistema de manutenção

O PROJECT_BRIEF.md afirma que o primeiro objetivo é registrar observação sintética. PRODUCT.md descreve a jornada. DATA_CONTRACTS.md define WorkOrder e Note. TESTING.md liga vazio, persistência e teclado aos testes. SECURITY.md proíbe dados reais e ações externas. A spec define a fatia; o ticket limita a implementação; EVAL_STRATEGY.md descreve navegador e estados.

Quando o ERP entrar, uma ADR poderá registrar por que a integração usa API oficial. Não reescreva o histórico no AGENTS.md.

Falhas e diagnóstico

Sintoma	Causa	Correção
docs discordam do código	duas fontes de verdade	escolher canônica e gerar/validar derivadas
agente não encontra comando	índice incompleto	adicionar comando real ao mapa
toda tarefa lê segurança inteira	divulgação ruim	apontar gatilhos e seções específicas
handoff vira diário	mistura estado e história	manter apenas estado vivo; arquivar decisão em ADR
regra crítica só está em texto	controle interpretativo	converter para check mecânico
skill genérica demais	múltiplos jobs e triggers	dividir por objetivo verificável

Exercício e critérios de aceite

Copie o kit para uma pasta temporária. Preencha PROJECT_BRIEF.md, CONTEXT_INDEX.md, TESTING.md, DEFINITION_OF_DONE.md, uma spec e um ticket. Execute o validador do kit.

Aceite:

• todos os placeholders obrigatórios foram substituídos;
• nenhuma credencial ou dado real foi incluído;
• cada critério aponta uma prova;
• AGENTS.md apenas orienta e aponta;
• nenhum arquivo operacional ultrapassa o teto sem exceção registrada;
• uma pessoa encontra produto, segurança, testes e próximo passo em menos de dois saltos;
• o validador termina com código zero.

Recuperação ativa

Por que AGENTS.md não deve conter tudo? Onde fica uma decisão arquitetural? O que diferencia handoff de memória? Quando texto deve virar teste? Por que o orçamento de linhas é guideline e guardrail operacional, não nota de qualidade? Qual é o conjunto mínimo para iniciar?

Você concluiu o Volume comum quando consegue iniciar uma fatia pequena, escolher S0–S3, preparar sua avaliação e deixar contexto suficiente para outra pessoa ou agente continuar com evidência.