Série de aprendizado de IA · Lição 3 de 4
Toda sessão nova de IA começa sem memória do seu repositório. Se as convenções vivem só na cabeça de alguém — ou em um documento que ninguém relê —, o modelo as quebra sem avisar, e a quebra parece código funcionando até deixar de funcionar.
Status: roteiro. A demonstração na tela ainda não foi gravada — este post é o plano que ela vai seguir, e recebe a demonstração real quando a lição for ao ar.
| Lição | Foco | Pergunta que responde |
|---|---|---|
| 1 — Uso de modelos | Nível de modelo, contexto, tokens | De qual modelo esta tarefa precisa? |
| 2 — Prompt, projeto e contexto | Estrutura do prompt, contexto permanente | O que vai na frente do modelo? |
| 3 — Documentação, regras e skills | Estrutura do repositório | Como um repositório se mantém consistente entre sessões? |
| 4 — Cortando custo | Medição, alavancas, limites | Como gastar menos sem perder qualidade? |
O que você vai conseguir fazer
- Dar a um repositório três coisas distintas: documentação em que ele consiga navegar, regras que precisa seguir e skills que pode reutilizar
- Classificar qualquer orientação na camada certa entre as três
- Transformar uma regra escrita em uma verificação que falha quando a regra é quebrada
Continua as lições 1 e 2: o contexto permanente da lição 2 era um único bloco de instruções. Esta lição o divide em camadas com funções diferentes, para que cada sessão carregue só o que precisa — a ideia de custo de contexto da lição 1, aplicada na escala do repositório.
Fora do escopo: medir ou cortar gastos (lição 4) e construir uma aplicação completa. O que é construído na tela é pequeno de propósito — o assunto é a estrutura em volta.
As três camadas
| Camada | Contém | Carregada | Falha quando falta |
|---|---|---|---|
| Documentação | Fatos — o que existe e como funciona | Quando relevante | O assistente redescobre o sistema, devagar e de forma inconsistente |
| Regras | Restrições sempre válidas e proibições, com o porquê | Em toda sessão | As convenções se desviam, uma sessão nova depois da outra |
| Skills | Procedimentos repetíveis para tarefas específicas | Sob demanda (depende da ferramenta) | O mesmo procedimento é colado de novo em cada prompt |
Documentação — encontrável, um responsável por fato
- Um índice, um fato com responsável claro por tema e uma tabela de impacto de mudanças
- A documentação continua encontrável e não fica desatualizada sem aviso quando o que ela descreve muda
Regras — curtas, sempre carregadas, com motivos
- O arquivo sempre carregado declara as proibições — e cita o porquê, não só o quê
- Qualquer coisa mais longa vai em um documento vinculado, não no arquivo que toda sessão paga para carregar
Skills — procedimentos carregados só quando necessário
- Uma skill é um procedimento reutilizável que o assistente carrega quando surge uma tarefa específica e repetível
- O repositório do exemplo prático não tem hoje um diretório de skills no nível do projeto, então a skill é construída ao vivo — não preparada para a demo
O exemplo prático
A lição roda sobre um repositório real, usado no dia a dia, não um brinquedo feito para a lição. Cinco padrões, cada um com uma função distinta:
Arquivo de entrada — lido primeiro
- Um arquivo diz o que é o projeto, o que fazer e o que não fazer — antes de qualquer outra coisa
- Quando mais de um agente de IA trabalha no repositório, ele é espelhado no ponto de entrada esperado por cada agente, para que nenhum leia uma cópia desatualizada ou parcial
Regra garantida por teste — mais forte que prosa
- Uma regra verificada por um teste vale mais do que uma regra que vive em um parágrafo que alguém pode pular
- Este blog faz isso com as traduções: categoria e data precisam continuar idênticas byte a byte entre idiomas, e
npm run check:translationsfalha se não estiverem
Fila de decisões — autorizado antes de começar
- O trabalho é escrito e aprovado antes de começar
- Nenhum agente deduz o escopo de uma mensagem de chat vaga
Índice de impacto de mudanças — "se você mudar X…"
- Uma tabela que diz quais documentos ficam desatualizados quando um arquivo específico muda
- A conexão é consultada, não redescoberta depois que algo quebra
Definição de pronto — varia conforme a mudança
- O que conta como verificado depende do tipo de mudança
- Uma edição de documentação precisa de outra prova que uma migração de schema
▶ show code▼ hide code
# Rules File — Skeleton
## What this project is
One paragraph. Link to README for everything else.
## Never
- Edit generated or vendored directories (why: overwritten on update)
- Commit secrets or expose them via public env vars (why: shipped to the browser)
- Mark work done without the check for its change type (why: see Definition of Done)
## Where things live
- Architecture → docs/ARCHITECTURE.md
- Change impact → docs/CHANGE_IMPACT.md
- Definition of done → docs/DONE.md
Na tela
- Primeiro, o modo de falha — uma sessão nova faz uma mudança que viola uma convenção que ninguém escreveu onde o modelo pudesse encontrar
- Estrutura da documentação — índice, um responsável por fato, tabela de impacto de mudanças
- Regras — o que vai no arquivo sempre carregado e o que vai em um documento vinculado
- Aplicação — uma regra escrita vira um teste, quebrado de propósito, depois corrigido
- Uma skill, construída ao vivo — para uma tarefa que realmente se repete, depois comparada com trabalhar sem ela
- Exercício de classificação — orientações reais classificadas em documentação, regras ou skills, incluindo uma classificada errado de propósito e corrigida
Em qual camada isso vai?
▶ show code▼ hide code
# Sorting Guidance
Is it a fact about how the system works? → Documentation
Is it always true, and does breaking it hurt? → Rules (with the why)
Is it a procedure you repeat for a specific task? → Skill
Can a test check it? → Also write the test
Verifique antes de confiar
- Que cada arquivo e caminho do exemplo prático ainda existe e ainda diz o que é afirmado — repositórios se desviam, e esta lição se apoia em caminhos reais
- Como a ferramenta demonstrada chama um arquivo de regras e uma skill, onde cada um fica e como cada um é carregado
- Se as skills são carregadas sob demanda ou sempre nessa ferramenta — o segmento de skill ao vivo depende disso
- Se a orientação de tamanho do arquivo de regras ainda bate com a recomendação atual do provedor
- Que a skill construída ao vivo é realmente reutilizada depois, e não um objeto de cena da demo
Perguntas frequentes
"Não posso colocar tudo no arquivo de regras?" Pode, e toda sessão paga por isso. Arquivos de regras longos são lidos por cima pelas pessoas e diluídos para os modelos. Mantenha as regras curtas; vincule o resto.
"Como sei que uma regra está sendo seguida de verdade?" Escreva uma verificação que falhe quando ela não for. Regra sem verificação é sugestão.
"Quando um prompt vira uma skill?" Na terceira vez que você cola o mesmo procedimento. Salve uma vez e carregue quando a tarefa aparecer.
Próxima: lição 4
A lição 4 vem por último de propósito. Ela usa tudo o que as três primeiras ensinam — escolha de modelo, qualidade do prompt e do contexto, e estrutura do repositório — como alavancas para cortar o custo de um workflow de IA.