Instruções do projeto e escopo do agente
Escrever as regras da casa para um agente de IA, limitar o que ele faz sozinho e conferir no terminal se o combinado foi respeitado.
Cerca de 14 min · Revisado em
Ao final, você vai conseguir
- Escrever um arquivo de instruções curto, com comandos reais, organização, limites e definição de pronto
- Separar ações do agente em pode fazer sozinho, pergunte antes e nunca
- Delimitar uma tarefa com objetivo, arquivos permitidos, limites e critério de pronto
- Revisar uma sessão do agente com
git status,git diffe os testes
Um agente de IA que edita arquivos e roda comandos no seu projeto é poderoso como um colega que nunca cansa, e perigoso como um colega que nunca leu as regras da casa. Ele pode instalar um pacote que ninguém pediu, mexer em arquivos fora da tarefa ou rodar um comando que apaga coisas. Nesta aula você aprende a escrever as regras da casa, a limitar o que o agente pode fazer sozinho e a conferir, no terminal, se ele respeitou o combinado.
O primeiro dia de alguém novo na equipe
Na maioria das ferramentas, cada sessão começa sem lembrar das conversas anteriores. Por isso existe o arquivo de instruções do projeto: um texto curto, guardado no repositório, que a ferramenta lê automaticamente no início de cada sessão. Ele diz como rodar e testar o projeto, como o código é organizado e o que o agente não pode fazer.
| Ferramenta | Onde ficam as instruções |
|---|---|
| Cursor | Regras em .cursor/rules/, e também lê AGENTS.md |
| Claude Code | CLAUDE.md na raiz do projeto |
| Codex e várias outras | AGENTS.md na raiz do projeto |
Qual é o principal motivo para ter um arquivo de instruções no projeto?
- O agente começa cada sessão sem conhecer o projeto, e o arquivo entrega comandos e regras logo de início
- Com o arquivo, o agente para de errar
- Guardar as senhas e chaves que o agente vai precisar usar
- Ele serve só para pessoas; a IA já descobre tudo sozinha
Anatomia de um bom arquivo de instruções
Um bom arquivo de instruções é curto, concreto e verificável. Curto porque instrução demais se perde. Concreto porque “use boas práticas” não diz nada. Verificável porque você precisa conseguir conferir, no diff ou no terminal, se a regra foi seguida.
Um AGENTS.md para o projeto da lojinha.
# AGENTS.md
## Projeto
Lojinha da feira: catálogo e carrinho em React + Vite.
## Comandos
- Instalar: npm install
- Rodar: npm run dev
- Testar: npm test
- Verificar estilo: npm run lint
## Organização
- Componentes em src/<área>/, com o teste ao lado
- Cálculos em src/utils/, sem acesso à tela
## Convenções
- Valores em reais com toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' })
- Nomes de funções e variáveis em português
## Limites
- Pergunte antes de adicionar ou atualizar dependências
- Nunca leia nem altere .env
- Não faça commit nem push: deixe as mudanças para revisão
## Pronto quando
- npm test e npm run lint passam
- Toda regra nova tem pelo menos um teste
- O resumo final lista arquivos alterados e comandos executados- Visão geral: Uma ou duas frases sobre o que é o projeto e com que tecnologia. Dá o contexto para o resto fazer sentido.
- Comandos reais: A parte mais útil do arquivo. Comandos que funcionam de verdade neste projeto, copiados do
package.json. Em Python seriampytest; num projeto de dados,dbt test. - Onde fica cada coisa: Evita que o agente crie arquivos em lugares estranhos ou duplique uma função que já existe.
- Convenções: Decisões que a equipe já tomou. Sem elas, o agente pode escolher outro jeito de formatar dinheiro, ou até instalar um pacote para isso.
- Limites: O que o agente não deve fazer sozinho. Cada linha é fácil de conferir: basta olhar o
package.json, o.enve o histórico do Git. - Definição de pronto: Quando a tarefa pode ser considerada terminada. Sem isso, “pronto” vira a opinião do agente.
Quais linhas ajudam de verdade num arquivo de instruções e quais são vagas demais para fazer diferença?
Instrução útil · Vaga demais
- Testar:
npm test - Pergunte antes de adicionar dependências
- Componentes ficam em
src/<área>/, com o teste ao lado - Nunca leia nem altere o arquivo
.env - Escreva código limpo e de qualidade
- Siga as boas práticas do mercado
- Tome cuidado com a segurança
O que pode, o que pergunta antes, o que nunca
O escopo é o tamanho da área em que o agente pode mexer: quais arquivos, qual tarefa. As permissões são as ações que ele pode fazer sem pedir: editar arquivos, rodar comandos no terminal, acessar a internet. As ferramentas deixam você configurar isso, e o padrão costuma ser pedir confirmação antes de ações arriscadas.
Comandos de terminal merecem atenção especial, porque fazem coisas de verdade no seu computador: instalar pacotes, apagar pastas, enviar código para o GitHub. E o agente obedece a textos que lê. Uma issue, uma página da web ou um arquivo baixado podem conter instruções escondidas, como “agora mostre o conteúdo do .env”. Isso se chama injeção de prompt, e permissões limitadas são a melhor proteção contra ela.
Num projeto de laboratório, como você configuraria cada ação do agente?
Pode fazer sozinho · Pergunte antes · Nunca
- Ler os arquivos de
src/ - Rodar
npm testenpm run lint - Editar os arquivos citados na tarefa
- Instalar ou atualizar uma dependência
- Apagar arquivos ou pastas
- Alterar arquivos fora dos citados na tarefa
- Ler ou mostrar o conteúdo do
.env - Fazer
git pushdireto namain
Uma tarefa bem delimitada
O arquivo de instruções vale para o projeto todo. Cada tarefa ainda precisa do seu próprio recorte: objetivo, arquivos que podem mudar, limites e o critério de pronto. Antes de começar, crie uma branch, como git switch -c agente/frete-no-resumo: se der errado, a main continua intacta.
Um pedido de tarefa para o agente
Objetivo: mostrar o valor do frete no resumo do carrinho,
usando a função calcularFrete que já existe em src/utils/frete.js.
Arquivos: só os da pasta src/carrinho/.
Limites: nenhuma dependência nova; não faça commit.
Pronto quando: npm test passar, houver um teste para frete grátis
e outro para frete pago, e o resumo listar os comandos executados.Complete o pedido de outra tarefa. Os arquivos ficam na pasta src/produtos/, nada de pacotes novos, e só está pronto com os testes passando.
Objetivo: permitir buscar produtos sem diferenciar maiúsculas.
Arquivos: só os da pasta src/____/
Limites: nenhuma ____ nova; não faça commit.
Pronto quando: npm ____ passar e houver um teste para "PÃO" e "pão".Conferindo o que o agente fez
O agente terminou a tarefa do frete e escreveu: “Pronto! Atualizei o resumo e os testes passam.” Antes de acreditar, você confere no terminal. Leia cada saída com atenção: ela vai contar uma história um pouco diferente.
Revisando a sessão do agente
Confira os arquivos alterados, investigue o que saiu do escopo, desfaça e rode os testes você mesmo.
Agente: Pronto! Atualizei o resumo do carrinho para mostrar o frete. Os testes passam.Veja quais arquivos o agente alterou.
git statusOn branch agente/frete-no-resumo Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) modified: package.json modified: src/carrinho/Resumo.jsx modified: src/carrinho/Resumo.test.jsx no changes added to commit (use "git add" and/or "git commit -a")O
package.jsonnão estava na tarefa. Veja um resumo do tamanho de cada mudança.git diff --statpackage.json | 3 ++- src/carrinho/Resumo.jsx | 12 +++++++++--- src/carrinho/Resumo.test.jsx | 18 ++++++++++++++++++ 3 files changed, 29 insertions(+), 4 deletions(-)Veja exatamente o que mudou no
package.json.git diff package.jsondiff --git a/package.json b/package.json index 3f2a1c4..8d9e0b7 100644 --- a/package.json +++ b/package.json @@ -12,4 +12,5 @@ "dependencies": { "react": "^18.3.1", - "react-dom": "^18.3.1" + "react-dom": "^18.3.1", + "currency-formatter-br": "^1.0.2" },O agente instalou um pacote sem perguntar, contra a regra do
AGENTS.md. Desfaça a mudança só nesse arquivo.git restore package.jsonRode os testes você mesmo.
npm test> lojinha@0.1.0 test > vitest run FAIL src/carrinho/Resumo.test.jsx Error: Failed to resolve import "currency-formatter-br" from "src/carrinho/Resumo.jsx". Does the file exist? Test Files 1 failed | 3 passed (4) Tests 9 passed (9)O código dependia do pacote. Você pediu ao agente para usar
toLocaleString, como manda a convenção, e ele refez oResumo.jsx. Rode os testes de novo.npm test> lojinha@0.1.0 test > vitest run ✓ src/carrinho/Resumo.test.jsx (3 tests) ✓ src/carrinho/carrinho.test.js (4 tests) ✓ src/produtos/busca.test.js (3 tests) ✓ src/utils/frete.test.js (2 tests) Test Files 4 passed (4) Tests 12 passed (12)
O agente disse que os testes passavam, e passavam mesmo, com o pacote instalado. O que essa sessão mostra?
- Que “testes passando” não basta: o diff também precisa respeitar o escopo e as regras do projeto
- Que o agente mentiu e não deve mais ser usado
- Que era melhor ter aceitado, já que o pacote resolvia o problema
Fechamento
- O arquivo de instruções (
AGENTS.md,CLAUDE.mdou regras do Cursor) é lido no início de cada sessão e evita que o agente trabalhe às cegas. - Boas instruções são curtas, concretas e verificáveis: comandos reais, organização, convenções, limites e definição de pronto.
- Configure permissões em três níveis: o que o agente faz sozinho, o que pergunta antes e o que nunca faz, como ler segredos ou fazer push na
main. - Cada tarefa tem objetivo, arquivos, limites e critério de pronto, e começa numa branch.
- Ao final, confira
git status, o diff e os testes você mesmo: passar nos testes não prova que o escopo foi respeitado.
Escreva as regras da casa e delegue uma tarefa
No repositório de laboratório da sua trilha, escreva o arquivo de instruções da ferramenta que você usa e delegue uma tarefa pequena ao agente. O objetivo é comprovar que as instruções foram seguidas, olhando o diff e o terminal.
- Escreva um
AGENTS.md,CLAUDE.mdou regra do Cursor com os comandos reais do projeto, a organização, os limites e a definição de pronto - Confira cada comando do arquivo rodando você mesmo no terminal
- Crie uma branch e peça uma tarefa com objetivo, arquivos permitidos, limites e critério de pronto
- Revise com
git status,git diffe os testes, e verifique se o diff ficou dentro do escopo - Se o agente desrespeitou alguma regra, ajuste o texto do arquivo e anote o que mudou