Skip to content

QUICKSTART.md

Latest commit

 

History

History
214 lines (149 loc) · 9.93 KB

QUICKSTART.md

File metadata and controls

214 lines (149 loc) · 9.93 KB

Quickstart

New project? Follow Steps 1–5 / Projeto novo? Siga os Passos 1–5. Existing project? Jump to Existing project / Projeto existente

Prerequisites / Pré-requisitos

  • Claude Code installed / instalado (npm install -g @anthropic-ai/claude-code)
  • GitHub CLI authenticated / autenticado (gh auth login)
  • Git configured / Git configurado

Step 1 — Create the project from the template / Passo 1 — Criar o projeto a partir do template

gh repo create my-project --template [OWNER]/template-claude-code-open --clone
cd my-project

Manual clone / Clonar manualmente:

git clone https://github.com/[OWNER]/template-claude-code-open.git my-project
cd my-project
rm -rf .git && git init
gh repo create my-project --source=. --push

Step 2 — Open Claude Code / Passo 2 — Abrir o Claude Code

claude

Step 3 — Automatic onboarding (/project-init) / Passo 3 — Onboarding automático

Claude detects that MEMORY.md is empty and starts /project-init automatically. / Claude detecta que MEMORY.md está vazio e inicia /project-init automaticamente.

First, Claude asks for your language preference (asked once, in both languages): / Primeiro, Claude pede sua preferência de idioma (perguntado uma vez, nos dois idiomas):

What language do you prefer to work in?
Qual idioma você prefere para trabalhar?

1 — English
2 — Português

From that point on, everything — questions, responses, generated files — will be in the chosen language. / A partir daí, tudo — perguntas, respostas, arquivos gerados — será no idioma escolhido.

Then you answer 7 conversational questions — one at a time: / Em seguida você responde 7 perguntas conversacionais — uma por vez:

# Question / Pergunta Example / Exemplo
0 Language preference / Preferência de idioma 1 (English) or/ou 2 (Português)
1 Project slug and name / Slug e nome do projeto my-api / "B2B order REST API"
2 Tech stack / Stack tecnológica Node.js + Fastify + PostgreSQL + Redis
3 Non-negotiable rules / Regras inegociáveis "Always PNPM, never alter migrations"
4 Team size / Tamanho do time "Team of 3"
5 MCP integrations / Integrações MCP GitHub, PostgreSQL
6 Library documentation / Documentação de libs Fastify, Prisma, Vitest
7 Initial state / Estado inicial "Starting from scratch"

What is configured automatically / O que é configurado automaticamente:

  • MEMORY.md filled with project context / preenchido com contexto do projeto
  • CLAUDE.md updated with the real name and rules / atualizado com nome e regras reais
  • AGENTS.md generated as universal mirror of CLAUDE.md / gerado como espelho universal do CLAUDE.md
  • references.md populated with official lib links / populado com links oficiais das libs
  • README_MCP.md created with integration setup instructions (if integrations were specified / se integrações foram especificadas)
  • All files committed to git: chore: initialize project [slug] from template

Step 4 — Create the first spec / Passo 4 — Criar a primeira spec

/spec-create user-authentication

Claude creates .claude/specs/feature-auth.md and updates specs/INDEX.md.

Step 5 — Seal the project / Passo 5 — Selar o projeto

/project-seal

Commits all spec files and finalizes the transition from template to real project. After this, the git history reflects your project — not the blank template. / Commita todos os arquivos de spec e finaliza a transição do template para o projeto real. Após isso, o histórico do git reflete o seu projeto — não o template em branco.

Step 6 — Start implementing / Passo 6 — Começar a implementar

implement the feature-auth spec
implemente a spec feature-auth

Claude reads the spec, checks memory and lessons, and delivers code following the project rules. / Claude lê a spec, verifica a memória e lições, e entrega código seguindo as regras do projeto.

Definition of Done / Definição de Pronto: a spec is only marked as done when behavior is validated, tests pass, the TDD cycle (Red → Green → Refactor) is verified and the "Verification" section is filled with real evidence. / uma spec só é marcada como done quando o comportamento está validado, os testes passam, o ciclo TDD (Red → Green → Refactor) está verificado e a seção "Verification" está preenchida com evidência real. "Looks right" is not done. / "Parece certo" não é pronto.

TDD Red/Green/Refactor — mandatory cycle / ciclo obrigatório

Every issue (feature, bugfix, improvement) follows the TDD cycle: / Toda issue segue o ciclo TDD:

  1. Red — write the test before production code / escreva o teste antes do código de produção
  2. Green — implement the minimum code to pass / implemente o mínimo para passar
  3. Refactor — improve without breaking tests / melhore sem quebrar os testes

The spec template (specs/_template.md) includes a dedicated checklist for the TDD cycle. The Definition of Done requires the TDD cycle to be verified. / O template de spec inclui um checklist dedicado para o ciclo TDD. A Definição de Pronto exige que o ciclo TDD seja verificado.

AGENTS.md — universal compatibility / compatibilidade universal

The AGENTS.md at the root is a mirror of CLAUDE.md for tools that don't recognize the Claude Code format: / O AGENTS.md na raiz é um espelho do CLAUDE.md para ferramentas que não reconhecem o formato Claude Code:

Tool / Ferramenta Recognizes / Reconhece
Claude Code CLAUDE.md
Cursor AGENTS.md (.cursorrules)
Windsurf AGENTS.md
Copilot AGENTS.md (.github/copilot-instructions.md)

project-init generates both CLAUDE.md and AGENTS.md automatically. CLAUDE.md is the source of truth — keep them in sync if editing manually.

Daily flow / Fluxo diário

# Start of session / Início de sessão
git pull

# End of session / Fim de sessão — commit context together with code / commitar contexto junto com o código
git add .claude/memory/ .claude/specs/ .claude/agent-memory/
git commit -m "chore(context): update memory/specs"
git push

# Optional / Opcional — enable auto-commit at session end / habilitar auto-commit ao fim da sessão:
cp .claude/settings.local.json.example .claude/settings.local.json

Useful commands / Comandos úteis

What to do / O que fazer Command / Comando
New project onboarding / Onboarding de projeto novo /project-init
Seal template after first spec / Selar template após primeira spec /project-seal
Start new feature / Iniciar nova feature /spec-create [feature]
Investigate and fix a bug / Investigar e corrigir bug /bugfix [description]
Review before opening PR / Revisar antes de abrir PR /pr-review
Format commit message / Formatar mensagem de commit /commit
Analyze code without modifying / Analisar código sem modificar "use the code-reviewer agent on module [X]"
Map the codebase / Mapear o codebase "use the researcher agent for [question]"
Plan a feature before coding / Planejar feature antes de codar "use the planner agent for [feature]"

Existing project / Projeto existente

Have a project with existing code and want to add this structure? / Tem um projeto com código existente e quer adicionar esta estrutura?

Step 1 — Add the structure / Passo 1 — Adicionar a estrutura

At the root of your existing project / Na raiz do seu projeto existente:

Linux/Mac:

gh repo clone [OWNER]/template-claude-code-open /tmp/cc-template -- --depth=1 --quiet && bash /tmp/cc-template/adopt.sh; rm -rf /tmp/cc-template
claude

Windows (PowerShell):

gh repo clone [OWNER]/template-claude-code-open $env:TEMP\cc-template -- --depth=1 --quiet
powershell -ExecutionPolicy Bypass -File "$env:TEMP\cc-template\adopt.ps1"
Remove-Item "$env:TEMP\cc-template" -Recurse -Force
claude

The script adds .claude/, CLAUDE.md and AGENTS.md without touching your existing code. / O script adiciona .claude/, CLAUDE.md e AGENTS.md sem tocar no seu código existente.

Step 2 — Run /project-adopt / Passo 2 — Executar /project-adopt

/project-adopt

What happens / O que acontece: Claude uses the researcher agent to map the codebase before asking any questions — reads config files, git log, directory structure and existing conventions. Arrives at the interview already with answers to the obvious questions. / Claude usa o agente researcher para mapear o codebase antes de perguntar qualquer coisa — lê arquivos de config, git log, estrutura e convenções existentes. Chega na entrevista já com respostas para as perguntas óbvias.

/project-init /project-adopt
When to use / Quando usar Blank project / Projeto em branco Project with existing code / Projeto com código existente
Protocol / Protocolo Defines conventions / Define convenções Discovers conventions / Descobre convenções
First action / Primeira ação Asks questions / Faz perguntas Maps the codebase / Mapeia o codebase
Specs created / Specs criadas None — starts empty / Nenhuma For in-progress features / Para features em andamento

Next steps / Próximos passos