Tabela de Conteúdo

Padronizando Ferramentas de IA em Repositórios

Agentes de IA para programação funcionam melhor quando entendem o seu projeto. Em vez de depender de cada contribuidor para configurar sua própria ferramenta, você pode commitar um pequeno conjunto de arquivos que qualquer agente de IA carrega automaticamente. Após trabalhar nessa padronização para a organização ComplyTime , quero compartilhar os resultados práticos: quais arquivos importam, por que cada um existe, como os agentes os consomem e como mantê-los.

O Problema

Sem padronização, cada contribuidor configura seu agente de IA de forma diferente. Padrões divergem, comandos são duplicados e o onboarding demora mais do que deveria. O agente não tem contexto sobre a arquitetura do projeto, padrões de código ou processo de revisão. Ele gera código plausível, mas desalinhado.

O objetivo é simples: um contribuidor clona o repositório, abre no seu agente de IA e tudo funciona. Sem configuração manual além de instalar a ferramenta.

Frameworks Spec-Driven: SpecKit e OpenSpec

Antes de entrar nos arquivos, é útil entender os dois frameworks de desenvolvimento spec-driven que moldaram essa padronização.

O SpecKit foi o primeiro framework adotado na organização. Ele fornece um fluxo de trabalho estruturado para desenvolvimento de funcionalidades: especificar requisitos, planejar a implementação, gerar tarefas e implementar passo a passo. O SpecKit usa a convenção de diretório .specify/ e tem o caminho da constitution fixado em .specify/memory/constitution.md. Seus comandos são prefixados com speckit.* e instalados via plugin.

O OpenSpec é a alternativa mais recente, projetado como o framework nativo de especificações para o OpenCode . Segue um fluxo spec-driven semelhante, mas usa sua própria estrutura de diretórios (openspec/) e convenções de comandos (prefixados com opsx-*). O OpenSpec é o framework recomendado pela organização a partir de agora.

Ambos os frameworks são agnósticos em relação ao agente: funcionam com OpenCode, Claude Code ou qualquer ferramenta de IA que suporte carregamento de comandos. Nenhum está vinculado a um agente específico. A decisão chave de design é que ambos compartilham a mesma constitution e podem coexistir no mesmo repositório. O SpecKit gera especificações em specs/, o OpenSpec gera em openspec/, e a numeração sequencial é coordenada entre ambos os diretórios, de forma que as funcionalidades formem uma linha do tempo cronológica unificada, independentemente de qual framework as criou.

O caminho da constitution em .specify/memory/constitution.md é um requisito do SpecKit (ele tem esse caminho fixado em seus comandos). O OpenSpec descobre a constitution no mesmo caminho por convenção. Isso não é infraestrutura de framework; é conteúdo específico do projeto que ambos os frameworks consomem. Movê-la quebraria o SpecKit sem beneficiar o OpenSpec, então o caminho permanece.

Como os Agentes Descobrem Esses Arquivos

Agentes de IA não sabem magicamente sobre o seu projeto. Eles dependem de caminhos de arquivo bem conhecidos e convenções de auto-descoberta para carregar contexto, comandos e skills. Entender esses mecanismos é essencial para que o conjunto de arquivos funcione.

AGENTS.md é lido automaticamente pelo OpenCode, Claude Code (via CLAUDE.md) e outros agentes que seguem a convenção de carregar um arquivo de contexto no nível raiz ao iniciar. Quando o agente entra em um repositório, ele lê o AGENTS.md primeiro para entender a estrutura do projeto, comandos disponíveis, restrições e convenções. Esse arquivo é a “primeira impressão” do agente sobre o seu projeto. Apenas o AGENTS.md, que é agnóstico em relação à ferramenta, deve ser commitado. Variantes específicas de ferramenta como CLAUDE.md são apenas locais e devem estar no gitignore.

.opencode/command/ é o caminho de auto-descoberta do OpenCode para comandos. Qualquer arquivo .md colocado aqui com frontmatter YAML se torna um comando invocável (ex.: /review_pr). O OpenCode escaneia esse diretório ao iniciar, sem necessidade de configuração. Comandos de framework (instalados pelos plugins do SpecKit ou OpenSpec) também ficam aqui, mas são excluídos do controle de versão via padrões no .gitignore, então apenas comandos específicos do projeto são commitados.

.agents/skills/ é o caminho agnóstico de auto-descoberta para skills. O OpenCode escaneia .agents/skills/, .opencode/skills/ e .claude/skills/ em busca de definições de skills. Ao commitar skills em .agents/skills/, elas ficam descobríveis por qualquer agente compatível sem acoplamento ao diretório de uma ferramenta específica.

.specify/memory/constitution.md não é auto-descoberta diretamente pelos agentes, mas é referenciada pelo AGENTS.md, por comandos (como o comando de revisão de PR) e por ambos os frameworks de especificação. O agente chega à constitution através dessas referências. Quando um comando diz “Leia .specify/memory/constitution.md para padrões de código”, o agente a carrega sob demanda em vez de carregá-la permanentemente no contexto.

O insight principal é que cada arquivo tem um mecanismo de descoberta específico: arquivos de contexto no nível raiz são lidos na inicialização, comandos e skills são auto-descobertos a partir de diretórios conhecidos, e a constitution é carregada sob demanda através de referências. Nenhuma configuração manual é necessária. O agente segue as convenções, e os arquivos estão lá.

O Conjunto de Arquivos

Aqui está o conjunto mínimo de arquivos commitados que alcança esse objetivo. Cada um tem um papel específico e um consumidor claro.

.specify/memory/constitution.md    # Padrões de código e governança
docs/AI_TOOLING.md                 # Guia de configuração legível por humanos
.agents/skills/                    # Conhecimento de domínio para o agente
.opencode/command/review_pr.md     # Comandos de IA específicos do projeto
AGENTS.md                          # Contexto do agente legível por máquina
.gitignore                         # Fronteira entre arquivos commitados e gerenciados pela ferramenta

1. Constitution (`.specify/memory/constitution.md`)

O que é: Um documento único que define os padrões de código, princípios arquiteturais, fluxo de trabalho de contribuição e regras de governança do seu projeto. Escrito em Markdown com linguagem RFC 2119 (MUST, SHOULD, MAY).

Por que existe: Agentes de IA precisam de regras autoritativas para seguir. Sem uma constitution, o agente adivinha estilo, nomenclatura, tratamento de erros e convenções de teste. Com uma, ele gera código que está em conformidade com os padrões reais do seu projeto, não com boas práticas genéricas.

Por que esse caminho: O caminho .specify/memory/constitution.md é um requisito do SpecKit. O SpecKit foi adotado primeiro na organização e tem esse caminho fixado em seus comandos. Quando o OpenSpec foi adicionado posteriormente, ele foi configurado para descobrir a constitution no mesmo local por convenção. O caminho é uma decisão do projeto, não uma dependência de framework: o arquivo é conteúdo de projeto commitado e consumido por ambos os frameworks. Se o seu projeto usa apenas o OpenSpec, você pode colocar a constitution em outro lugar, mas esse caminho funciona para ambos.

Como é consumido: Tanto o SpecKit quanto o OpenSpec referenciam a constitution ao gerar especificações, planos e código. Comandos de revisão de PR verificam o código em relação aos princípios da constitution. O agente a alcança através de referências no AGENTS.md e em comandos, carregando-a sob demanda.

Como manter: Trate-a como um documento versionado. Use versionamento semântico (MAJOR para mudanças de princípios, MINOR para novas seções, PATCH para correções de texto). Exija pelo menos dois revisores para alterações. Repositórios individuais podem estender a constitution organizacional, mas não devem relaxar suas diretivas MUST.

Exemplo de estrutura:

# Project Constitution

## Core Principles
### I. Single Source of Truth
Values used in multiple places MUST be centralized...

### II. Simplicity & Isolation
Functions MUST follow the Single Responsibility Principle...

## Coding Standards
### Python
- All code MUST use type hints
- Code MUST pass ruff linting
- Line length: 99 characters

### YAML / GitHub Actions
- Reusable workflows MUST use `reusable_` prefix
- All action references MUST be pinned to full commit SHAs

## Commit Messages
All commits MUST follow Conventional Commits...

2. Documentação de Ferramentas de IA (`docs/AI_TOOLING.md`)

O que é: Um guia legível por humanos que cobre como configurar ferramentas de IA no repositório, comandos disponíveis, como criar novos comandos e skills, e localizações dos arquivos-chave.

Por que existe: Nem toda informação deve estar embutida em arquivos legíveis por máquina. Contribuidores precisam de um ponto de entrada único para entender a configuração de ferramentas de IA, especialmente aqueles usando agentes diferentes do padrão. Esse arquivo deve levar menos de 3 minutos para ler.

Por que docs/ e não um diretório dedicado: Se você já tem um diretório docs/ para documentação do projeto, use-o. Criar um diretório dedicado ai/ para um único arquivo Markdown adiciona estrutura desnecessária. Siga a convenção que seu projeto já possui.

Como é consumido: Por humanos. Contribuidores o leem durante o onboarding ou ao criar novos comandos e skills. Ele contém links para a constitution e outros arquivos-chave.

Como manter: Atualize quando comandos, skills ou convenções de diretório mudarem. Mantenha curto. Se crescer além de uma página, provavelmente você está duplicando conteúdo que pertence à constitution ou a arquivos individuais de comando/skill.

3. Diretório de Skills (`.agents/skills/`)

O que é: Um diretório onde arquivos de conhecimento de domínio (skills) ficam. Cada skill é um subdiretório contendo um SKILL.md com frontmatter YAML.

Por que existe: Skills ensinam o agente como pensar sobre um domínio específico (ex.: “requisitos de conformidade OSCAL”, “padrões de tratamento de erros em Go”). Diferente de comandos (que definem um fluxo de trabalho), skills fornecem contexto persistente carregado na sessão do agente.

Por que .agents/skills/ e não .opencode/skills/: O caminho .agents/ é agnóstico em relação ao agente. O OpenCode, e potencialmente outras ferramentas compatíveis, descobrem skills a partir desse caminho. Usar um diretório específico de ferramenta (como .opencode/skills/) acopla seu projeto a um único agente.

Como é consumido: O agente de IA auto-descobre skills a partir desse diretório. Quando uma skill é ativada, o agente carrega seu conteúdo no contexto pela duração da sessão. Skills consomem tokens pela sessão inteira, então devem ser concisas (menos de 200 linhas).

Como manter: Comece com um diretório vazio (.gitkeep). Contribuidores adicionam skills via PR conforme os fluxos de trabalho amadurecem. Cada skill tem um name e description claros em seu frontmatter. Revise skills quanto à eficiência de tokens, conteúdo duplicado e alinhamento com a constitution.

Estrutura do arquivo de skill:

---
name: security-review
description: "Domain knowledge for security-focused code review"
---
# Security Review Patterns

## Input Validation
All external inputs MUST be validated before use in...

4. Comandos Específicos do Projeto (`.opencode/command/`)

O que é: Arquivos Markdown que definem templates de prompts reutilizáveis que o agente executa quando invocados. Cada arquivo é um comando com frontmatter YAML e instruções passo a passo.

Por que existe: Comandos codificam fluxos de trabalho específicos do projeto que seriam, de outra forma, prompts ad-hoc. Um comando de revisão de PR, por exemplo, garante que cada revisão siga o mesmo processo: verificar CI, executar ferramentas locais e então aplicar julgamento de IA. Sem comandos, cada contribuidor escreve seu próprio prompt, produzindo resultados inconsistentes.

Por que o gitignore seletivo importa: Esse diretório também contém comandos gerenciados pelo framework (como speckit.* ou opsx-*) que são instalados por plugins e não devem ser commitados. Use padrões no .gitignore para excluir comandos de framework mantendo os específicos do projeto:

.opencode/command/speckit.*
.opencode/command/opsx-*

Como é consumido: O agente de IA auto-descobre comandos a partir de .opencode/command/. Quando um usuário invoca /review_pr 42, o agente carrega review_pr.md e executa seus passos.

Como manter: Mantenha cada comando focado em um único fluxo de trabalho. Ao escrever comandos, delegue verificações determinísticas (lint, testes) para ferramentas primeiro, depois use IA para análise baseada em julgamento. Referencie a constitution em vez de copiar regras para dentro do comando. Isso previne divergências e economiza tokens.

5. Arquivo de Contexto do Agente (`AGENTS.md`)

O que é: Um arquivo Markdown legível por máquina na raiz do repositório que dá ao agente de IA contexto imediato sobre o projeto: estrutura de diretórios, comandos disponíveis, restrições e convenções.

Por que existe: Quando o agente abre um repositório, ele lê o AGENTS.md para entender o layout do projeto sem escanear toda a base de código. Isso reduz o uso de tokens e previne suposições alucinadas sobre a estrutura do projeto.

Como é consumido: Agentes de IA (OpenCode, Claude Code e outros) leem esse arquivo automaticamente ao entrar em um repositório. Ele fornece a “primeira impressão” do projeto.

Como manter: Derive-o automaticamente da constitution e dos planos de funcionalidades quando possível. Ferramentas como update-agent-context.sh podem regenerá-lo durante fluxos de planejamento. Adicione seções específicas do projeto manualmente (como explicações da estrutura de diretórios) entre marcadores designados. Arquivos de contexto de agente específicos de ferramenta (ex.: CLAUDE.md) devem estar no gitignore, e apenas o AGENTS.md, agnóstico em relação à ferramenta, deve ser commitado.

6. Gitignore (`.gitignore`)

O que é: A fronteira entre conteúdo específico do projeto commitado e arquivos gerenciados pela ferramenta.

Por que existe: Ferramentas de IA e frameworks de especificação instalam scripts, templates, comandos e plugins localmente. Estes nunca devem ser commitados. Sem padrões explícitos no gitignore, contribuidores acidentalmente commitam arquivos gerenciados pela ferramenta, criando carga de manutenção e conflitos de versão.

Padrões-chave para incluir:

# Infraestrutura de framework (gerenciada pela ferramenta)
.specify/scripts
.specify/templates

# Comandos de framework (gerenciados por plugin, não específicos do projeto)
.opencode/command/speckit.*
.opencode/command/opsx-*

# Artefatos de plugin
.opencode/node_modules/
.opencode/package.json

# Diretórios específicos de ferramenta (apenas local)
.claude/
.cursor/

# Contexto de agente específico de ferramenta (apenas local)
CLAUDE.md

O Princípio da Fronteira

A decisão de design mais importante é a fronteira entre o que você commita e o que fica no gitignore:

Commitado (específico do projeto)	Gitignore (gerenciado pela ferramenta)
Constitution	Scripts e templates de framework
Comandos específicos do projeto	Comandos de framework
Diretório de skills	Artefatos de plugin (node_modules, etc.)
Contexto do agente (AGENTS.md)	Contexto específico de ferramenta (CLAUDE.md)
Documentação de ferramentas de IA	Diretórios específicos de ferramenta (.claude/, .cursor/)

Essa fronteira garante que:

Contribuidores usando diferentes ferramentas de IA compartilhem os mesmos padrões
Atualizações de framework não exijam mudanças no repositório
Personalizações específicas do projeto sejam versionadas e revisáveis

Distribuição Organizacional

Se você gerencia múltiplos repositórios, pode distribuir esses arquivos a partir de um repositório central de infraestrutura usando um mecanismo de sincronização. Os arquivos que fazem sentido sincronizar entre todos os repos são:

Constitution (padrões de governança)
Documentação de ferramentas de IA (guia de configuração)
Estrutura do diretório de skills (.gitkeep vazio)
Comandos específicos do projeto (como revisão de PR)

Cada repositório alvo herda a configuração de ferramentas de IA da organização automaticamente. Repos individuais podem adicionar seus próprios comandos e skills sem conflitar com a base sincronizada.

Primeiros Passos

Para implementar isso no seu repositório:

Crie a constitution: Comece com seus padrões de código existentes. Formalize-os com linguagem MUST/SHOULD/MAY. Coloque em um caminho bem conhecido.
Adicione a documentação: Crie docs/AI_TOOLING.md (ou equivalente) explicando a configuração e arquivos-chave.
Configure o diretório de skills: Crie .agents/skills/.gitkeep. Adicione skills depois conforme os fluxos de trabalho amadureçam.
Escreva seu primeiro comando: Comece com um comando de revisão de PR ou um comando de geração de código específico para o seu projeto.
Crie o AGENTS.md: Documente a estrutura do projeto, comandos disponíveis e restrições.
Configure o .gitignore: Adicione padrões para infraestrutura de framework, artefatos de plugin e diretórios específicos de ferramenta.
Teste o fluxo: Clone o repositório do zero, abra no seu agente de IA e verifique se os comandos são descobertos, a constitution está acessível e o contexto do agente é carregado.

Conclusão

O valor de padronizar ferramentas de IA não está nos arquivos individuais. Está no contrato que eles criam: um entendimento compartilhado entre o seu projeto e qualquer agente de IA que entre nele. A constitution define as regras. Comandos codificam os fluxos de trabalho. Skills fornecem o conhecimento de domínio. O contexto do agente dá a primeira impressão. E o gitignore impõe a fronteira entre o que o seu projeto possui e o que cada ferramenta gerencia.

A configuração é pequena (6 arquivos), a manutenção é baixa (atualize quando os padrões mudarem), e o retorno é imediato: cada contribuidor, independentemente de qual ferramenta de IA use, recebe assistência consistente e alinhada ao projeto desde o primeiro clone.