CHAOS
Context for Human-AI Organization of Systems
CHAOS (Context for Human-AI Organization of Systems) é uma convenção aberta para organizar o conhecimento necessário para compreender, desenvolver, manter e evoluir sistemas de software.
A proposta é estabelecer uma fonte de contexto persistente, estruturada e independente de modelos, IDEs ou ferramentas de desenvolvimento.
O código contém a implementação. O CHAOS contém o contexto necessário para compreender e evoluir o sistema.
Isso inclui decisões arquiteturais, regras de negócio, contratos, integrações, responsabilidades e restrições que nem sempre podem ser identificadas apenas pela leitura do código.
1. Por que utilizar CHAOS?
Agentes de programação conseguem investigar repositórios e interpretar implementações existentes. Entretanto, nem sempre conseguem determinar por que uma arquitetura foi escolhida, quais comportamentos são intencionais ou quais decisões precisam ser preservadas.
Essas informações frequentemente estão distribuídas entre documentos, tickets, conversas e o conhecimento dos desenvolvedores.
O CHAOS estabelece uma estrutura para tornar esse conhecimento acessível e persistente.
O objetivo não é produzir mais documentação, mas evitar que cada novo desenvolvedor ou agente precise reconstruir o entendimento do sistema a partir do zero.
Isso também reduz a dependência de históricos de conversas e facilita o trabalho com diferentes agentes no mesmo projeto.
2. Como o CHAOS organiza o contexto
A convenção utiliza três elementos principais:
project/
├── README.md
├── AGENTS.md
└── .chaos/
| Elemento | Responsabilidade |
|---|---|
README.md |
Ponto de entrada para humanos: visão geral, instalação e utilização |
AGENTS.md |
Ponto de entrada para agentes: instruções e localização do contexto |
.chaos/ |
Fonte canônica do conhecimento sobre o sistema |
Estrutura ilustrativa: os pontos de entrada direcionam humanos e agentes para o conhecimento do sistema.
Quando um contrato ou uma especificação já possui uma fonte oficial no projeto, como uma definição OpenAPI, o CHAOS pode referenciá-la em vez de duplicar seu conteúdo.
O AGENTS.md deve permanecer objetivo. Sua responsabilidade é orientar o agente sobre onde encontrar as informações necessárias, não reproduzir toda a documentação.
A estrutura interna de .chaos/ é definida conforme as características do projeto.
Por exemplo:
.chaos/
├── architecture/
│ └── system-boundaries.md
├── business/
│ └── order-lifecycle.md
├── features/
│ └── checkout.md
├── contracts/
│ └── public-api.md
└── integrations/
└── payment-provider.md
Essas categorias são ilustrativas. Não existe necessidade de criar diretórios ou documentos para conceitos que o projeto não possui.
Referência: CHAOS — Repositório oficial
3. Contexto não é uma cópia do código
Uma das regras centrais do CHAOS é registrar conhecimento relevante para compreender o sistema, sem reproduzir sua implementação.
Considere uma aplicação de ecommerce que utiliza Stripe.
O código pode mostrar como os pagamentos são criados, mas o CHAOS pode estabelecer que:
- O backend é responsável pela criação dos pagamentos.
- O frontend não pode criar cobranças diretamente.
- Webhooks podem ser entregues mais de uma vez.
- Um pedido somente pode ser marcado como pago após a confirmação do backend.
- Outros serviços dependem desse comportamento.
Essas informações orientam os agentes durante modificações e ajudam a evitar implementações tecnicamente válidas que violem regras do sistema.
O CHAOS também estabelece o princípio de uma única fonte canônica por conceito. Quando uma informação é compartilhada, os demais documentos devem referenciá-la em vez de manter cópias independentes.
4. Contexto compartilhado entre projetos
Em sistemas compostos por múltiplos repositórios, parte do conhecimento pertence a um projeto específico, enquanto outra parte precisa ser compartilhada.
O CHAOS permite separar essas responsabilidades:
company-api/
├── AGENTS.md
└── .chaos/
company-app/
├── AGENTS.md
└── .chaos/
company-admin/
├── AGENTS.md
└── .chaos/
company-shared-chaos/
├── contracts/
├── integrations/
├── branding/
└── shared/
Cada repositório mantém seu contexto local.
Contratos entre aplicações, regras compartilhadas, integrações e outros conhecimentos comuns podem ser mantidos em um repositório CHAOS compartilhado.
Por exemplo, se a API altera um contrato utilizado pelo aplicativo e pelo painel administrativo, os agentes devem consultar a mesma especificação canônica antes de modificar seus respectivos projetos.
Isso evita que diferentes agentes implementem interpretações incompatíveis da mesma regra.
5. Como os agentes utilizam e mantêm o CHAOS
O fluxo esperado é simples:
- O agente consulta
AGENTS.md. - Identifica quais documentos de
.chaos/são relevantes para a tarefa. - Consulta o contexto compartilhado quando necessário.
- Investiga o código e executa o trabalho.
- Atualiza o CHAOS quando houver mudanças no comportamento canônico, nos contratos ou nas decisões do sistema.
Não é necessário carregar todos os documentos em cada execução.
O agente deve recuperar somente o contexto necessário, reduzindo leituras desnecessárias e consumo de tokens.
Atualização do conhecimento
A documentação precisa acompanhar a evolução do sistema.
Se uma implementação modifica um contrato ou uma regra de negócio, a alteração correspondente no CHAOS deve fazer parte da entrega.
O histórico dessas mudanças permanece no Git. O CHAOS mantém a descrição atual do sistema.
Da mesma forma, checkpoints, tickets e registros temporários de execução não devem ser confundidos com conhecimento canônico.
6. CHAOS e skills possuem responsabilidades diferentes
Skills representam capacidades ou procedimentos que um agente pode utilizar.
O CHAOS descreve o sistema no qual essas capacidades serão aplicadas.
Por exemplo, um agente pode possuir conhecimento para implementar integrações de pagamento. O CHAOS informa quais serviços são responsáveis pelos pagamentos naquele projeto e quais restrições devem ser respeitadas.
Skills fornecem capacidades. CHAOS fornece contexto.
O agente pode utilizar essas informações para determinar quais ferramentas, skills ou conhecimentos são necessários para executar determinada tarefa.
O CHAOS não exige a criação de skills para procedimentos que o agente já domina.
7. Como implementar CHAOS em um projeto existente
O repositório oficial disponibiliza um prompt para orientar um agente na implantação da convenção.
O processo é dividido em duas fases.
Primeira fase — diagnóstico e planejamento
O agente investiga o repositório, identifica arquitetura, regras, contratos, integrações e documentação existente.
Depois, apresenta a estrutura proposta, a responsabilidade de cada documento, possíveis informações compartilhadas e inconsistências encontradas.
Nenhum arquivo deve ser modificado antes da aprovação do plano.
Segunda fase — implementação
Após a aprovação, o agente cria ou atualiza README.md, AGENTS.md e .chaos/, organiza as informações canônicas e verifica a consistência entre documentação, código e contratos.
O prompt também orienta a não inventar requisitos, não duplicar informações e não incluir credenciais ou dados sensíveis.
A adoção pode começar por um único repositório e evoluir para um contexto compartilhado conforme a necessidade.
Para começar: CHAOS — Repositório oficial
Prompt de implantação: CHAOS Implementation Starter Prompt
Exemplo de projeto: CHAOS Example
Conclusão
O CHAOS propõe que o conhecimento necessário para compreender um sistema faça parte do próprio sistema, em uma estrutura organizada e acessível a humanos e agentes de IA.
Com pontos de entrada definidos, contexto canônico e informações compartilhadas entre repositórios, diferentes agentes podem trabalhar sobre uma mesma referência técnica sem depender de conversas anteriores ou de um fornecedor específico.
O agente pode mudar. O contexto do sistema deve permanecer acessível, consistente e atualizado.
Leituras complementares
Fontes externas
- AGENTS.md — convenção para instruções de agentes
- Architecture Decision Records (ADR)
- C4 Model — visualização de arquitetura
Artigos relacionados
- Arquitetura, engenharia e documentação de contexto
- Memória e continuidade do trabalho com agentes de IA
- Padronização de projetos para desenvolvimento com agentes de IA
- Harnesses, skills, ferramentas e MCP
- Proteção de contexto e dados sensíveis