RespostasPublicado14 fontes
Documentação para agentes de IA: menos regras universais, mais clareza sobre o que vale
Organize documentos pela função e pela fonte oficial de cada informação, não apenas por quem os escreveu. Mantenha planos concluídos fora do foco diário, mas preserve o histórico necessário para entender decisões e comprovar o trabalho.
Publicado porImagens geradas com GPT Image 2
Resposta de pesquisa
Principais conclusões
- Organize documentos pela função e pela fonte oficial de cada informação, não apenas por quem os escreveu.
- Mantenha planos concluídos fora do foco diário, mas preserve o histórico necessário para entender decisões e comprovar o trabalho.
- Trate compatibilidade entre agentes, limites de tamanho e regras de teste como contratos que precisam ser verificados — não como garantias dadas por uma pasta ou instrução.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/r4PONBDeiygm6rkyQ1INhTEQyyP2/images/C7AB80FC077AFBDCC74B/E16B680C3CF0FB35FFC8.png)
Prompt de IA
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"建议统一“信息职责、权威来源、生命周期和读取契约”，而不是强制所有项目采用同一套目录。BMAD 的任务治理与蓝图的知识分层可以结合，但计划保留、跨宿主加载、测试隔离和文档预算必须分别定义，不能由目录名称代替。\n\n 保留蓝图的职责分离，调整其绝对化规则。\n 借鉴 BMAD 的稳定身份、渐进细化、来源追溯和历史. Topic tags: general web, ai safety, openai, chatgpt, llm. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts
Organizar arquivos para agentes de IA não deveria começar pela escolha de uma árvore de pastas. O mais importante é combinar quatro coisas: para que serve cada documento, qual é a fonte oficial, por quanto tempo ele deve existir e em que situação precisa ser consultado.
Essa abordagem permite aproveitar práticas do BMAD e de fluxos como Ralph sem transformar um método específico em regra para todo projeto. Também ajuda a evitar que uma instrução importante desapareça quando um plano é resumido ou que uma convenção de arquivos seja confundida com uma garantia de compatibilidade entre ferramentas.
O que a organização do BMAD oferece
Na documentação local analisada, o BMAD se aproxima de um fluxo de trabalho e de um protocolo para guardar seus artefatos. A contribuição mais ampla não é uma estrutura de diretórios específica, mas alguns princípios de governança:
- Separar o método das personalizações. Manter as configurações próprias como ajustes pontuais, em vez de copiar todos os arquivos padrão, ajuda a evitar que atualizações futuras sejam encobertas.
- Vincular os artefatos ao trabalho que os originou. Iniciativas, épicos e tarefas menores podem formar uma hierarquia; requisitos, planos e retrospectivas ficam associados ao item correspondente. Planejamentos que atravessam repositórios podem ter um espaço próprio.
- Detalhar aos poucos. Uma tarefa pode existir primeiro como um item resumido e ganhar arquivos e critérios de aceitação quando isso for necessário. Assim, o projeto evita produzir antecipadamente detalhes que podem ficar desatualizados.
- Preservar planos e evidências. Um plano concluído pode guardar estado, contexto de implementação e observações de revisão. Apagá-lo pode dificultar a compreensão do que foi feito e até fazer uma tarefa parecer novamente pendente.
Em conjunto, esses princípios apontam para uma regra simples: cada artefato precisa ter um responsável, uma identidade reconhecível, um estado confiável e evidências que sustentem sua conclusão.
Uma estrutura útil não serve para todos os projetos
Uma proposta de organização por áreas de conhecimento e um método de entrega baseado em tarefas resolvem problemas diferentes. Não é preciso escolher um e descartar o outro.
- Projeto pequeno, com uma pessoa e trabalho sequencial: um foco de tarefa atual e documentos consultados conforme a área podem ser suficientes. Ainda assim, a visão da tarefa ativa deve apontar para o registro original, em vez de substituir o único histórico.
- Equipe, tarefas paralelas ou vários repositórios: identidades estáveis para tarefas e planos independentes ajudam a evitar conflitos. “Um plano ativo” pode significar o foco da sessão atual, sem exigir que toda a equipe compartilhe um único arquivo mutável.
- Agente nativo da plataforma: instruções curtas e uma rota clara para encontrar informações podem bastar; nem todo projeto precisa adotar um método completo.
- Fluxo personalizado: controladores, visualizações de estado e validações de evidência podem ser úteis, mas só devem ser tratados como recursos disponíveis quando realmente estiverem implementados.
O ponto é adaptar o nível de estrutura ao trabalho. Uma pasta bem nomeada, por si só, não garante que um agente carregue o documento nem que saiba qual versão é válida.
Cinco regras que vale rever
1. Não apague o contrato ao concluir uma tarefa
Resumos podem reduzir o material que aparece no dia a dia, mas não precisam substituir o registro original. O histórico pode sair da leitura padrão sem perder estado, autoria ou rastreabilidade.
2. Verifique a integração com cada agente
Convenções de arquivos não são universais. A documentação da OpenAI, por exemplo, distingue o AGENTS.md, que o Codex reconhece, de outros arquivos de fluxo de trabalho, cujos nomes e estruturas podem ser adaptados ao projeto.6 Portanto, compatibilidade deve ser testada em cada ambiente, não presumida por causa de uma instrução genérica.
3. Use limites de tamanho como orçamento, não como lei
Um número fixo de linhas não é uma garantia contra erros em todos os modelos e ferramentas. É mais útil observar quanto conteúdo é realmente carregado, quanto se repete e se a divisão dos documentos preserva dependências importantes.
4. Separe dados de teste de resultados de execução
Uma amostra fixa e reproduzível usada como fixture não é a mesma coisa que um log criado durante uma execução. Testes unitários, de integração, ponta a ponta e em ambientes reais também podem exigir configurações e cuidados diferentes.
5. Não misture “ignorado” com “proibido” ou “arquivado”
Um arquivo fora do controle de versão, um documento que o agente não consulta por padrão e um conteúdo cujo acesso é vedado são situações distintas. Se a equipe precisa recuperar evidências entre máquinas, a política de retenção e a política de acesso devem deixar isso claro.
O que as práticas de Ralph ajudam a explicar
Geoffrey Huntley descreve Ralph como um processo que trabalha em um repositório e trata uma tarefa por ciclo.14 Em um guia associado ao método, também aparece a ideia de organizar especificações por assunto e registrar no
AGENTS.md aprendizados operacionais sobre como construir e testar o projeto.11
A lição prática é trabalhar com tarefas delimitadas, especificações claras, contexto suficiente e retorno real de ferramentas. Isso não significa que todo projeto precise usar a mesma estrutura de pastas. Um exemplo oficial da OpenAI para tarefas complexas também apresenta planos detalhados e documentos vivos, sugerindo que uma entrada permanente enxuta pode coexistir com um plano completo para uma tarefa longa.5
Na prática:
- deixe as instruções permanentes concisas e amplie o plano conforme o risco e a duração do trabalho;
- organize especificações por assunto, mas facilite a descoberta de regras que atravessam várias áreas;
- ao reiniciar um ciclo, recupere o contexto necessário para a tarefa atual, sem tentar reproduzir todo o histórico da conversa;
- documente comandos de build e teste somente quando houver base para afirmar que funcionam, incluindo as condições relevantes do ambiente.
Dez princípios para uma documentação mais confiável
- Classifique pela função e pela autoridade. Uma informação não é correta só porque foi escrita por uma pessoa, nem temporária apenas porque foi gerada por uma ferramenta. Separe políticas, fatos verificados, propostas, estado de tarefa, evidências e rascunhos.
- Defina uma fonte oficial para cada fato importante. Índices e resumos podem repetir informações para facilitar a consulta, desde que apontem para a origem e indiquem quando aquela cópia pode ficar desatualizada.
- Registre o que o código não consegue explicar. Intenção, justificativas para decisões rejeitadas, restrições externas e responsabilidades entre componentes podem exigir documentação. Uma análise estática não prova, sozinha, uma regra de negócio nem a motivação histórica de uma decisão.
- Faça da entrada um guia, não uma enciclopédia. As rotas para documentos devem usar sinais observáveis — como caminho, interface ou tipo de tarefa — em vez de depender apenas de instruções vagas, como “consulte quando for complexo”.
- Diferencie regra, andamento e comprovação. A especificação diz o que precisa ser atendido; o estado indica o progresso; a evidência mostra por que se considera um requisito cumprido. Os três podem estar próximos, desde que sua autoridade esteja explícita.
- Ao resumir, preserve o que permite retomar o trabalho. Pendências, bloqueios, dependências, limites de autorização e localização das evidências não devem sumir na compactação.
- Mantenha o histórico rastreável e as regras atuais fáceis de identificar. Uma decisão pode ser substituída sem apagar a original: registre a relação entre elas e faça as especificações apontarem para a decisão vigente.
- Separe os testes dos resultados gerados. Respeite os locais de teste já adotados pelo ecossistema da linguagem e defina a retenção dos resultados conforme sensibilidade, volume e prazo.
- Automatize o que puder ser verificado mecanicamente. Formatação, caminhos protegidos e contratos determinísticos podem ser checados por ferramentas. Mover uma regra para um arquivo que ninguém lê não reduz o problema; uma verificação só substitui uma instrução quando realmente cobre o caso.
- Não confunda organização com autorização. Gerar documentos, executar comandos, enviar dados pela rede, fazer deploy e arquivar são ações diferentes. Uma pasta de rascunhos não é, por si só, uma barreira de segurança.
Uma sequência de evolução prudente é definir primeiro as responsabilidades e fontes oficiais, depois verificar como cada agente carrega os documentos, criar uma visão enxuta do trabalho ativo e só então ajustar limites de tamanho e retenção com base no uso real. Isso evita começar por uma migração ampla de diretórios antes de saber qual problema ela resolveria.
A conclusão central é direta: uma boa estrutura torna as informações certas fáceis de encontrar e as antigas fáceis de rastrear, sem confundir convenção com garantia.
Studio Global AI
Continue sua pesquisa
Esta página inclui uma resposta baseada na fonte que você pode continuar em Studio Global.
As pessoas também perguntam
Qual é a resposta curta para "Documentação para agentes de IA: menos regras universais, mais clareza sobre o que vale"?
Organize documentos pela função e pela fonte oficial de cada informação, não apenas por quem os escreveu.
Quais são os pontos-chave para validar primeiro?
Organize documentos pela função e pela fonte oficial de cada informação, não apenas por quem os escreveu. Mantenha planos concluídos fora do foco diário, mas preserve o histórico necessário para entender decisões e comprovar o trabalho.
O que devo fazer a seguir na prática?
Trate compatibilidade entre agentes, limites de tamanho e regras de teste como contratos que precisam ser verificados — não como garantias dadas por uma pasta ou instrução.
Fontes
developers.openai.comdevelopers.openai.com › cookbook › examplesdevelopers.openai.com
ghuntley.comRalph Wiggum as a "software engineer" - Geoffrey Huntley
github.comhow-to-ralph-wiggum/README.md at main - GitHub