Do README ao AI Manifest: O Próximo Padrão dos Projetos de Software

Por décadas, os projetos de software foram estruturados sob a perspectiva de leitores humanos e ferramentas de automação tradicionais. Arquivos como README.md, package.json, Dockerfile e variáveis de ambiente .env definem como configurar, compilar, testar e distribuir um sistema.

Contudo, com a ascensão dos agentes autônomos de Inteligência Artificial integrados ao fluxo de desenvolvimento diário, surge uma nova necessidade metodológica: os repositórios de código precisam se autodescrever de forma operacional para IAs.

Embora o README.md continue indispensável para a integração de humanos, ele falha ao fornecer as restrições operacionais e os limites de atuação exigidos por um agente autônomo. O AI Manifest surge para preencher este gap: ele funciona como um contrato operacional explícito que dita arquitetura, políticas de permissão, stack tecnológica, padrões de qualidade e limites de segurança que governam as ações de agentes de IA dentro do ecossistema do projeto.

Premissas fundamentais

IMPORTANT

A eficácia operacional de uma IA em um repositório é inversamente proporcional à sua necessidade de inferir ou improvisar.

A especificação do AI Manifest baseia-se em sete premissas:

1. Natureza Declarativa: A documentação para humanos é predominantemente narrativa; o contexto para agentes de IA deve ser declarativo, resumido e estruturado.

2. Precedência da Arquitetura: O agente não deve inferir ou reinventar padrões arquiteturais; ele deve aderir estritamente às decisões documentadas do repositório.

3. Firewall Operacional: As permissões de alteração, leitura e execução de comandos pelo agente devem ser explícitas, determinísticas e restritivas.

4. Fonte Canônica da Verdade: O repositório deve conter um único ponto de referência central de contexto, evitando a dispersão de instruções em múltiplos arquivos proprietários de fornecedores.

5. Desacoplamento de IDEs: adapters de ferramentas específicas (ex. Claude, Cursor, Copilot) devem ser derivados do contexto canônico, e não poluidores da raiz do repositório.

6. Versionamento Nativo: O manifesto operacional deve evoluir e ser versionado em conjunto com o código-fonte (Context as Code).

7. Eficiência Cognitiva: O contexto do projeto precisa ser modular, leve e de fácil ingestão para reduzir o consumo de tokens e evitar alucinações.

O limite do README: o gap do desenvolvimento assistido

O arquivo README.md foi projetado para responder ao "como entender" e "como começar" de um desenvolvedor humano. Ele explica o propósito macro do sistema e ensina a instalar dependências.

No entanto, um agente de IA executa ações de modificação direta no código. Para operar com segurança e precisão, ele necessita de respostas para perguntas que o README.md normalmente omite:

• Quais padrões de nomenclatura exatos devem ser aplicados para novas classes ou componentes?
• Quais diretórios e arquivos são estritamente sensíveis (firewall lógico)?
• Quais comandos de sistema são seguros para execução e quais exigem aprovação humana?
• Quais decisões arquiteturais passadas delimitam a implementação atual?
• Como fragmentar tarefas complexas sem violar a consistência do projeto?

Sem essas diretrizes declarativas, a IA opera sob um viés probabilístico genérico, o que leva a improvisações e, consequentemente, a regressões ou bugs de arquitetura.

A proposta do AI Manifest

O AI Manifest centraliza e organiza todo o contexto operacional de IA em um diretório específico. A recomendação central de design é utilizar a pasta .ai/ na raiz do projeto devido à sua semântica limpa e facilidade de varredura por assistentes.

.ai/
├── manifest.md            # Contrato principal e indexador de regras
├── core/                  # Fonte canônica e regras de governança locais
│   ├── project.md         # Escopo de negócio e vocabulário do domínio
│   ├── stack.md           # Tecnologias oficiais e versões aceitas
│   ├── architecture.md    # Padrões de software e organização de pastas
│   ├── permissions.md     # O Firewall Operacional (políticas de acesso)
│   ├── guidelines.md      # Padrões de código e convenções estilísticas
│   ├── testing.md         # Estratégia de testes e validação
│   ├── git.md             # Padrões de ramificação, commits e Pull Requests
│   ├── commands.md        # Lista de comandos autorizados e restritos
│   └── risks.md           # Pontos de atenção e zonas críticas do sistema
├── project/               # Base de conhecimento específica do projeto
│   ├── spec/              # Especificações técnicas (fonte de verdade para implementação)
│   ├── context/           # Contextos técnicos - documentação viva por módulo (7 seções padrão)
│   ├── planning/          # Documentos estratégicos, backlog e revisões de fase
│   ├── memory/            # Snapshots de contexto da IA entre sessões
│   ├── product/           # Propostas de produto e exportações (PDFs)
│   ├── db/                # Diagramas de banco de dados e artefatos SQL
│   └── scripts/           # Scripts de automação acoplados a este projeto
├── shared/                # Capacidades e fluxos reutilizáveis
│   ├── skills/            # Procedimentos passo a passo (capacidades da IA)
│   ├── agents/            # Definições de papéis e personas de agentes
│   ├── workflows/         # Rotinas e automações sequenciais
│   └── rules/             # Regras compartilhadas entre múltiplos projetos
├── output/                # Artefatos gerados intencionalmente pela IA
├── temp/                  # Área transitória - não é fonte canônica
├── vendor/                # Dependências externas de contexto (somente leitura)
├── adapters/              # Configurações de tradução para IDEs específicas
│   ├── claude/            # Configurações para Claude Code / CLAUDE.md
│   ├── codex/             # Configurações para Codex (OpenAI) / AGENTS.md
│   ├── cursor/            # Configurações para Cursor (.cursorrules)
│   ├── copilot/           # Configurações para GitHub Copilot
│   └── windsurf/          # Configurações para Windsurf
├── decisions/             # Registro de Decisões Arquiteturais (ADRs)
│   ├── 0001-auth.md
│   └── 0002-billing.md
├── changelog.md           # Log ativo de alterações (< 500 linhas)
└── changelog/             # Governança e histórico rotacionado
    ├── README.md          # Regras de rotação e política de escrita
    └── YYYY-MM-DD.md      # Arquivos históricos gerados por rotação

Detalhamento dos arquivos principais do core

#### 1. manifest.md

É a regra zero. Funciona como ponto de entrada e contrato de inicialização da IA.

# AI Manifest

Este repositório autoriza assistência por agentes de IA, sob a condição de aderência estrita às regras do diretório `.ai/`.

Antes de propor ou modificar qualquer arquivo, o agente deve ler:
- `.ai/core/permissions.md` (prioridade máxima)
- `.ai/core/project.md`
- `.ai/core/architecture.md`

Em caso de ambiguidades de instrução, a política em `permissions.md` prevalece sobre qualquer outra regra.

#### 2. project.md

Descreve o domínio de negócio de forma concisa para evitar que a IA trate a aplicação como um CRUD genérico.

#### 3. stack.md

Define o ecossistema tecnológico formal do projeto. Impede que a IA sugira ou injete dependências inadequadas.

#### 4. architecture.md

Delimita as camadas do sistema e a separação de responsabilidades.

#### 5. permissions.md (O Firewall Operacional)

Garante a segurança da operação limitando o raio de ação das IAs. É o componente mais importante do manifesto.

#### 6. guidelines.md

Instrui sobre qualidade de código e convenções estilísticas recomendadas para o projeto.

O diretório core/ governa como a IA deve se comportar - suas regras, restrições e padrões operacionais. O diretório project/ contém o que o projeto é - seu conhecimento de domínio, especificações técnicas e histórico decisório.

Essa separação é intencional: um agente deve aplicar core/ como firewall antes de consultar project/. A mistura de conhecimento de domínio com regras de governança em um único diretório induz a IA a tratar restrições como sugestões e conteúdo como mandato.

context/: Documentação técnica viva

O subdiretório context/ contém os arquivos CONTEXT-.md - documentação estruturada e viva de cada módulo principal do sistema. Cada arquivo CONTEXT-.md segue obrigatoriamente 7 seções padronizadas: Overview, Main flow, Critical points, Tables involved, Routes involved, Files involved, e Methods involved.

output/ e temp/: Artefatos transitórios

• output/ - Artefatos gerados intencionalmente pela IA (relatórios, exports, rascunhos de código).
• temp/ - Área de staging transitória. Nunca deve ser usada como fonte canônica de verdade.

Para acelerar tarefas comuns sem redundância de instrução no prompt do usuário, o manifesto organiza capacidades reutilizáveis no diretório shared/, dividido em quatro subdiretórios: skills/, agents/, workflows/ e rules/.

• agents/ (Personas de Agentes): Definem papéis e escopos de responsabilidade para agentes especializados.
• rules/ (Regras Compartilhadas): Regras de comportamento reutilizáveis entre múltiplos projetos da organização.
• skills/ (Habilidades Procedimentais): Guia passo a passo de como executar tarefas técnicas repetitivas.
• workflows/ (Fluxos de Processo): Rituais operacionais do ciclo de desenvolvimento.

Resolução de conflitos e precedência

Em cenários complexos onde regras do time, da empresa ou da IA colidem, a árvore de precedência é executada de forma determinística de cima para baixo:

1. permissions.md (Regra de segurança local do repositório)
   └── 2. architecture.md (Padrão arquitetural do repositório)
       └── 3. decisions/ (Decisões arquiteturais históricas locais)
           └── 4. stack.md (Stack tecnológica local)
               └── 5. guidelines.md (Padrões de estilo locais)
                   └── 6. Regras Corporativas (Diretrizes globais da empresa)
                       └── 7. Preferências Pessoais (Configurações do desenvolvedor)

Abstração por IDEs: a camada de adapters

Provedores de IA utilizam arquivos de instrução proprietários na raiz do repositório (CLAUDE.md, AGENTS.md, .cursorrules). O padrão resolve isso com dois níveis:

1. Arquivo index na raiz - arquivo mínimo exigido pelo agente; aponta para os arquivos canônicos em .ai/.

2. Arquivo canônico no adapter - conteúdo completo de contexto e convenções em .ai/adapters/<ide>/.

Governança do changelog: log rotation

O arquivo .ai/changelog.md cresce continuamente. Inspirado no logrotate de servidores Linux, o padrão define uma política de rotação automática: quando atinge 500 linhas, move o histórico antigo para .ai/changelog/YYYY-MM-DD.md, preservando as últimas ~50 linhas no ativo.

Análise de riscos e mitigações

• Risco de Obsolescência: Valide a consistência das regras no pipeline de CI/CD.
• Excesso de Especificação: Foque em limites e restrições, não em microgerenciamento.
• Injeção de Contexto Malicioso: Realize revisões de segurança e assine digitalmente dependências corporativas.
• Dispersão em Governança: Use core/ exclusivamente para regras comportamentais da IA e project/ para conhecimento do domínio.

Roadmap conceitual e referências técnicas

graph TD
    F1[Fase 1: Convenção Manual] --> F2[Fase 2: Templates Estruturados]
    F2 --> F3[Fase 3: Geração de Adapters]
    F3 --> F4[Fase 4: Linter de Contexto]
    F4 --> F5[Fase 5: Integração em Runtime]

Referências incluem o Model Context Protocol (MCP), MCP Roots e Resources, documentações de Claude Code, GitHub Copilot e arquiteturas de computação privada.

A Daggadol é pioneira na implementação do padrão AI Manifest (.ai/manifest.md), auxiliando empresas de tecnologia a transformar repositórios legados em ambientes AI-First altamente governados. Oferecemos:

• Implementação do AI Manifest (.ai/): Estruturação dos diretórios core/, project/, shared/ e permissions.md sob medida para o seu produto.
• Configuração de Firewall Operacional: Definição determinística de zonas livres, restritas e proibidas para prevenção de alucinações e alterações indevidas por agentes de IA.
• Automação de Log Rotation e Adapters: Integração de rotinas de rotação de changelog e sincronização com IDEs como Claude Code, Cursor, Copilot e Windsurf.

O README.md foi projetado para um ecossistema onde humanos detinham o monopólio da escrita e alteração de código. No novo paradigma de engenharia assistida, o projeto exige uma camada de governança transparente e acionável para inteligências artificiais.

O AI Manifest não é apenas um guia estático de documentação. É um contrato de convivência e produtividade entre o engenheiro humano e o agente de inteligência artificial. No futuro do desenvolvimento de software, o diferencial de um projeto não será apenas a qualidade do código produzido, mas o quão bem estruturado ele está para que a IA colabore com máxima eficiência e mínima supervisão.

A Daggadol ajuda empresas a adotar IA no desenvolvimento de software com segurança e eficiência, incluindo a especificação do AI Manifest e governança de repositórios AI-first. Se quiser levar essa abordagem para o seu time, fale com a gente.