I · Conhecimento
Guidelines
As regras da casa. Um arquivo que a IA lê antes de qualquer tarefa: linguagem, padrões, estrutura de pastas e o que ela nunca deve fazer.
Evita: estilos diferentes a cada conversa e decisões repetidas.
# AGENTS.md
## Sempre
- Conteúdo em português do Brasil
- Um CSS por página, sem frameworks
## Nunca
- Estilos inline
- Apagar arquivos sem confirmar
I · Conhecimento
Especificações
Sua ideia escrita de um jeito que a IA consegue executar: objetivo, público, telas, regras e critério de pronto. Antes do código, o plano.
Evita: a IA "completar" sua ideia com suposições erradas.
# feature-agendamento.md
Objetivo: cliente marca horário sozinho
Telas: calendário, confirmação
Regra: sem horários duplicados
Pronto quando: teste de conflito passa
I · Conhecimento
Memória
Decisões, aprendizados e histórico do projeto registrados em arquivos. A próxima sessão começa de onde a anterior parou, não do zero.
Evita: explicar o projeto inteiro de novo toda manhã.
# decisions/003-banco.md
Decisão: SQLite no MVP
Motivo: zero custo, fácil de testar
Revisar quando: passar de 1.000 usuários
I · Conhecimento
Contexto
A janela de contexto é a mesa de trabalho da IA, e ela tem tamanho. Você aprende a colocar na mesa só o que importa para a tarefa atual.
Evita: respostas piores e gasto de tokens com coisa irrelevante.
// em vez de colar tudo:
@specs/agendamento.md
@src/calendario.js
"Implemente a regra de conflito."
II · Capacidade
Skills
Pacotes de instrução que só entram em cena quando são úteis. A skill de formulários carrega quando você mexe em formulário, e só aí.
Evita: um prompt gigante carregado em toda mensagem.
# skills/formularios/SKILL.md
name: formularios
description: validar e enviar forms
---
1. Validar no cliente e no servidor
2. Mensagens de erro acessíveis
II · Capacidade
MCP
O Model Context Protocol é a tomada universal: conecta a IA ao banco de dados, ao navegador, ao GitHub, à documentação oficial. Ela consulta em vez de chutar.
Evita: a IA supor como está o seu banco ou a sua API.
// mcp_config.json
{ "servers": {
"banco": { "command": "mcp-sqlite" },
"docs": { "command": "mcp-docs" } } }
II · Capacidade
Subagentes
O agente principal delega tarefas paralelas (pesquisar, revisar, testar no navegador) para agentes menores, que voltam só com o resultado.
Evita: poluir a conversa principal com milhares de linhas de pesquisa.
principal → subagente "revisor"
tarefa: checar acessibilidade da página
retorno: 3 problemas, 3 correções
// contexto principal intacto
II · Capacidade
Hooks & permissões
Ações automáticas antes ou depois de cada passo (formatar, rodar teste) e limites claros do que a IA pode executar sem pedir sua autorização.
Evita: comandos destrutivos e chaves de API expostas.
// hooks.json
"depois_de_editar": "npm test"
"bloquear": ["rm -rf", "git push --force"]
"pedir_aprovação": ["deploy"]
III · Feedback
Testes
O único jeito objetivo de saber se funcionou. A IA escreve o teste, roda, lê o erro e corrige antes de dizer que terminou.
Evita: o "agora está funcionando" que não está.
✓ agenda horário livre
✓ bloqueia horário duplicado
✗ envia e-mail de confirmação
→ corrigindo e rodando de novo…
III · Feedback
Revisão humana
Você continua sendo quem decide. Aprende a ler um plano, revisar uma alteração, testar no navegador e dizer "sim", "não" ou "assim não".
Evita: depender cegamente da IA em decisões que são suas.
Plano proposto: 4 passos
[✓] 1. criar tabela
[✓] 2. tela de calendário
[✗] 3. login social ← fora do MVP
[✓] 4. teste de conflito