AI-Native Engineers
Capítulo 1

Preparar o terreno

Criar o repositório no GitHub, clonar no terminal, abrir na ferramenta e preparar AGENTS.md, PLAN.md e README.md.

Criar o repositório no GitHub

O objetivo deste capítulo não é escrever código. É sair do zero absoluto e montar um projeto pronto para ser planejado e executado com agente.

Por isso, o começo é manual de propósito. Antes de envolver a IA, você mesmo cria o repositório no GitHub. Isso ajuda a entender onde o projeto nasce, qual é a URL oficial dele e como a sua pasta local vai se conectar ao remoto.

Abra o GitHub no navegador e siga este passo a passo:

  1. Clique em New repository.
  2. Escolha um nome curto e claro, como deezer-explorer.
  3. Adicione uma descrição simples do projeto.
  4. Marque Public se quiser publicar depois no GitHub Pages.
  5. Deixe Add a README file, Add .gitignore e Choose a license desmarcados. Vamos criar esses arquivos depois, já com o projeto aberto e com mais contexto.
  6. Clique em Create repository.
Exemplo simples

Nome: deezer-explorer
Descrição: Site para explorar artistas, álbuns e faixas usando a API do Deezer

✓ Checkpoint:

O repositório existe no GitHub e você consegue ver a URL de clone dele.

Clonar no terminal

Com o repositório criado, o próximo passo é trazer esse projeto para a sua máquina. No GitHub, clique em Code, copie a URL HTTPS e rode os comandos no terminal.

No terminal 
cd ~/projetos
git clone https://github.com/seu-usuario/deezer-explorer.git
cd deezer-explorer
git remote -v
git status

Se o repositório estiver vazio, isso é normal: o git clone vai criar a pasta e o git status pode mostrar algo como No commits yet. O importante aqui é confirmar que a pasta local está ligada ao repositório certo no GitHub.

✓ Checkpoint:

O repositório foi clonado no seu computador, git status funciona e git remote -v mostra o origin.

Abrir na ferramenta escolhida

Com a pasta local pronta, abra esse diretório na ferramenta em que você vai trabalhar: Cursor, Windsurf, VS Code, Claude Code ou outra parecida. O ponto importante aqui é abrir a raiz do projeto, não arquivos soltos.

✓ Checkpoint:

A pasta clonada está aberta na sua ferramenta e o agente consegue enxergar a raiz do projeto.

Criar os arquivos que guiam o projeto

Agora sim entra o fluxo normal. Antes de pedir interface, busca ou integração com API, vale registrar o contexto do projeto e a forma de trabalhar. Isso evita que o agente invente escopo cedo demais.

Para esse começo funcionar bem, peça um arquivo por vez. Primeiro o PLAN.md, porque ele vira a base dos próximos. Depois o README.md. Por último, peça o AGENTS.md ou CLAUDE.md, já usando os dois anteriores como contexto.

Nos blocos abaixo, troque os campos entre colchetes e clique em Copiar prompt. A ideia é você colar direto na ferramenta e receber um arquivo mais consistente, sem começar de um pedido genérico.

Aqui tem um detalhe importante: só o PLAN.md nasce como plano inicial e será refinado no próximo capítulo. O README.md e o AGENTS.md ou CLAUDE.md já devem sair úteis de verdade para o projeto real.

Os prompts abaixo já carregam este contexto do produto:

  • o produto se chama Deezer Explorer
  • é um site estático e responsivo
  • o usuário pesquisa artistas, vê álbuns e abre detalhes de álbum
  • a fonte de dados é a API pública do Deezer
  • os endpoints centrais são busca de artista, álbuns por artista e álbum por ID
  • esses endpoints públicos de catálogo funcionam sem login do usuário final
  • o deploy final será no GitHub Pages
  • o projeto precisa considerar o problema de CORS no browser
  • os arquivos de harness e operação devem ser escritos em inglês
Nota importante:

O portal de documentação do Deezer hoje pede login para aceitar os termos da Simple API, mas os endpoints públicos de catálogo usados neste projeto continuam funcionando sem autenticação do usuário final. O que exige token são endpoints de conta, como /user/me.

1. Prompt base para gerar o PLAN.md

Esse é o primeiro prompt. Ele define o escopo do produto, as restrições e a expectativa de planejamento sem pedir implementação ainda.

Prompt pronto para copiar
Você vai me ajudar a iniciar um projeto real do zero. Neste momento eu quero apenas um PLAN.md inicial, honesto e útil. Não quero implementação ainda.

CONTEXTO DO PRODUTO
- Nome do repositório: [NOME_DO_REPO]
- Nome de trabalho do produto: Deezer Explorer
- O que vamos construir: um site estático e responsivo onde a pessoa digita o nome de um artista, escolhe um resultado, vê a discografia em cards com capa e abre um álbum para ver tracklist, data de lançamento e capa
- Fonte de dados: API pública do Deezer
- Endpoints obrigatórios da v1:
  - GET /search/artist?q=...
  - GET /artist/{id}/albums
  - GET /album/{id}
- Fluxo principal do usuário:
  1. abrir o site
  2. pesquisar um artista
  3. ver resultados de artistas
  4. escolher um artista
  5. ver a lista de álbuns com capas
  6. abrir um álbum
  7. ver tracklist, capa e data
- Publicação final: GitHub Pages
- Restrições reais do projeto:
  - sem backend próprio
  - sem autenticação
  - sem banco de dados
  - mobile-first e responsivo
  - acessível o suficiente para navegação por teclado
  - poucas dependências
  - precisamos considerar o problema de CORS no browser
  - o repositório está no começo e pode estar quase vazio
- Ferramenta em uso: [FERRAMENTA_ESCOLHIDA]

TAREFA
Crie um arquivo PLAN.md na raiz do projeto.

O PLAN.md deve incluir:
- resumo objetivo do produto
- escopo exato da v1
- uma stack inicial concreta, escolhendo uma única direção técnica em vez de listar várias opções
- justificativa curta para essa stack
- plano de implementação em fases pequenas e testáveis
- para cada fase: objetivo, entregáveis, critérios de aceite, validação manual, riscos e decisões abertas
- uma nota sobre publicação no GitHub Pages
- uma seção curta de “fora de escopo por enquanto”

REGRAS IMPORTANTES
- escreva o arquivo em inglês
- seja específico e evite frases genéricas
- não invente funcionalidades além do escopo descrito
- não implemente código
- este é um plano inicial: ele pode ser refinado depois, mas já precisa ser coerente e executável
- gere apenas o conteúdo final do PLAN.md

2. Prompt base para gerar o README.md

Depois de revisar o PLAN.md que foi gerado e ele fizer sentido para você, peça ao agente para criar o README.md. Aqui o plano já vira fonte para evitar README inventado.

Prompt pronto para copiar
Use o PLAN.md já existente no repositório como fonte principal de verdade.

CONTEXTO DO PRODUTO
- Nome do repositório: [NOME_DO_REPO]
- Produto: Deezer Explorer
- O produto final é um site estático e responsivo para pesquisar artistas, listar álbuns e abrir detalhes de um álbum usando a API pública do Deezer
- Publicação final: GitHub Pages
- Estado atual do repositório: começo do projeto, com PLAN.md inicial já criado e revisado
- Ferramenta em uso: [FERRAMENTA_ESCOLHIDA]

TAREFA
Crie um README.md real para este repositório no estado atual dele.

O README.md deve ser útil para alguém que abrir o repositório agora e precisa entender:
- o que este projeto é
- o que ele vai entregar na v1
- qual é o fluxo principal do usuário
- quais endpoints da API do Deezer são centrais para o projeto
- qual stack foi escolhida no PLAN.md
- qual é o estado atual do repositório neste momento
- como o projeto deve ser desenvolvido localmente
- como a publicação no GitHub Pages deve funcionar
- quais riscos e limitações já são conhecidos
- quais são os próximos passos imediatos

REGRAS IMPORTANTES
- escreva o arquivo em inglês
- faça um README real, não um placeholder
- use o PLAN.md como base para stack, escopo e fases
- se a implementação ainda não começou, deixe isso explícito na seção de status em vez de fingir que o produto já existe
- não invente funcionalidades fora do escopo
- não encha o arquivo com texto genérico de template
- gere apenas o conteúdo final do README.md

3. Prompt base para gerar o AGENTS.md ou CLAUDE.md

Por último, peça o arquivo de operação do agente. Como ele vem depois do plano e do README, fica muito mais fácil gerar regras coerentes com o projeto real.

Prompt pronto para copiar
Use o PLAN.md e o README.md já existentes como fonte principal de verdade.

CONTEXTO DO PRODUTO
- Nome do repositório: [NOME_DO_REPO]
- Produto: Deezer Explorer
- O produto final é um site estático e responsivo para pesquisar artistas, listar álbuns e abrir detalhes de um álbum usando a API pública do Deezer
- Publicação final: GitHub Pages
- Ferramenta em uso: [FERRAMENTA_ESCOLHIDA]

TAREFA
Crie o arquivo de operação do agente na raiz do projeto.

REGRAS DE NOME DO ARQUIVO
- se eu estiver usando Claude Code, o arquivo deve se chamar CLAUDE.md
- em qualquer outra ferramenta, o arquivo deve se chamar AGENTS.md

O arquivo precisa ser realmente útil para o trabalho diário neste repositório e deve incluir:
- visão geral concreta do projeto
- objetivos e escopo atual da v1
- quais arquivos são fonte de verdade do projeto
- como o agente deve usar PLAN.md e README.md antes de propor mudanças
- comandos principais do projeto se eles já existirem; se ainda não existirem, isso deve ser dito de forma explícita
- padrões de qualidade e validação
- regras para atualizar PLAN.md e README.md quando decisões mudarem
- regras para propor mudanças em fases pequenas
- o que não deve ser inventado, alterado ou assumido sem alinhamento

REGRAS IMPORTANTES
- escreva o arquivo em inglês
- faça um documento real de operação, não um template genérico
- use PLAN.md e README.md como base
- não invente stack, comandos ou fluxo que contradigam os arquivos existentes
- gere apenas o conteúdo final do arquivo correto: AGENTS.md ou CLAUDE.md

⚠️ Leia cada arquivo assim que ele for gerado. Se tiver comando que não existe, escopo inventado ou decisão técnica que você não entende, pare e corrija o agente. Esse cuidado economiza muita correção depois.

Bônus: instalar e autenticar o GitHub CLI

Esse passo é opcional, mas vale muito a pena. O GitHub CLI (gh) permite acessar GitHub direto do terminal: autenticar sua conta, abrir repositórios, ver issues, trabalhar com PRs e dar mais autonomia ao agente quando ele estiver operando no projeto.

Os caminhos mais comuns de instalação são:

  • macOS: brew install gh
  • Windows: winget install --id GitHub.cli
  • Linux: usar os pacotes oficiais da sua distribuição na documentação do GitHub CLI
Autenticação no terminal 
gh auth login
gh auth status

No fluxo interativo, a sequência mais comum é:

  1. Escolher GitHub.com.
  2. Escolher HTTPS como protocolo do Git.
  3. Selecionar autenticação via navegador.
  4. Concluir o login no browser quando o GitHub abrir.
Opcional depois do login 
gh auth setup-git

Esse comando configura o Git para usar as credenciais do GitHub CLI. Se der certo, o gh auth status deve mostrar sua conta autenticada.

Se você terminou este capítulo, já fez o essencial do setup: criou o repositório remoto, conectou a cópia local, abriu o projeto na ferramenta e deixou registradas as regras e o plano inicial. No próximo capítulo, vamos usar essa base para detalhar o PLAN.md e quebrar a execução em fases pequenas.

✓ Checkpoint:

PLAN.md, README.md e AGENTS.md ou CLAUDE.md existem, foram lidos e fazem sentido para você.

Antes de sair deste capítulo

Salve o que foi feito até aqui no Git antes de avançar. Isso ajuda você a manter progresso, histórico e pontos seguros de retorno.

git add .
git commit -m "[resuma o que foi feito neste capitulo]"
git push

Troque a mensagem do commit por um resumo curto e real do que mudou neste capítulo.

Capítulo 1

0 de 3 checkpoints

Complete todos os checkpoints para desbloquear o próximo capítulo.

Próximo: Planejar com o agente →
← Voltar para a visão geral

Quer se aprofundar?

Artigos

Documentação

Comunidade

Pergunte, responda, destrave

Use este espaço para fazer perguntas sobre a sessão, compartilhar exemplos e ajudar outras pessoas a entenderem o tema.