Configurando Claude-Craft em um Novo Projeto

Este tutorial passo a passo irá guiá-lo através da instalação do Claude-Craft em um projeto completamente novo. No final, você terá um ambiente de desenvolvimento totalmente configurado com assistência de IA.

Tempo necessário: ~10 minutos

---

Índice

1. Lista de Pré-requisitos
2. Criar o Diretório do Seu Projeto
3. Inicializar o Repositório Git
4. Escolher Sua Stack Tecnológica
5. Instalar o Claude-Craft
   • Método A: NPX (Sem Necessidade de Clone)
   • Método B: Makefile (Mais Controle)
6. Verificar a Instalação
7. Configurar o Contexto do Projeto
8. Primeiro Lançamento com Claude Code
9. Testar Sua Configuração
10. Solução de Problemas
11. Próximos Passos

---

1. Lista de Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado:

Obrigatório

• [ ] Terminal/Linha de Comando - Qualquer aplicativo de terminal
• [ ] Node.js 16+ - Necessário para instalação via NPX
• [ ] Git - Para controle de versão
• [ ] Claude Code - O assistente de codificação com IA

Verificar Seus Pré-requisitos

Abra seu terminal e execute estes comandos:

# Verificar versão do Node.js (deve ser 16 ou superior)
node --version

Saída esperada: v16.x.x ou superior (ex: v20.10.0)

# Verificar versão do Git
git --version

Saída esperada: git version 2.x.x (ex: git version 2.43.0)

# Verificar se Claude Code está instalado
claude --version

Saída esperada: Número da versão (ex: 1.0.x)

Instalar Pré-requisitos Faltantes

Se algum comando acima falhar:

Node.js: Baixe de nodejs.org ou use:

# macOS com Homebrew
brew install node

# Ubuntu/Debian
sudo apt install nodejs npm

Git: Baixe de git-scm.com ou use:

# macOS com Homebrew
brew install git

# Ubuntu/Debian
sudo apt install git

Claude Code: Siga o guia de instalação oficial

---

2. Criar o Diretório do Seu Projeto

Escolha onde você quer criar seu projeto e execute:

# Criar diretório do projeto
mkdir ~/meu-projeto

# Navegar para dentro
cd ~/meu-projeto

Verificação: Execute pwd para confirmar que você está no diretório correto:

pwd

Saída esperada: /home/seunome/meu-projeto (ou /Users/seunome/meu-projeto no macOS)

---

3. Inicializar o Repositório Git

Claude-Craft funciona melhor com projetos rastreados pelo Git:

# Inicializar repositório Git
git init

Saída esperada:

Initialized empty Git repository in /home/seunome/meu-projeto/.git/

Verificação: Verifique se a pasta .git existe:

ls -la

Você deve ver um diretório .git/ na saída.

---

4. Escolher Sua Stack Tecnológica

Claude-Craft suporta múltiplas stacks tecnológicas. Escolha a que corresponde ao seu projeto:

Stack	Ideal Para	Flag de Comando
Symfony	APIs PHP, Apps Web, Serviços Backend	--tech=symfony
Flutter	Apps móveis (iOS/Android)	--tech=flutter
Python	APIs, Serviços de dados, Backends ML	--tech=python
React	SPAs Web, Dashboards	--tech=react
React Native	Apps móveis multiplataforma	--tech=reactnative
Apenas Common	Qualquer projeto (regras genéricas)	--tech=common

Escolha seu idioma:

Idioma	Flag
Inglês	--lang=en
Francês	--lang=fr
Espanhol	--lang=es
Alemão	--lang=de
Português	--lang=pt

---

5. Instalar o Claude-Craft

Você tem dois métodos de instalação. Escolha o que se adapta às suas necessidades:

Método A: NPX (Sem Necessidade de Clone)

Ideal para: Configuração rápida, novos usuários, pipelines CI/CD

Este método baixa e executa o Claude-Craft diretamente sem clonar o repositório.

# Substitua 'symfony' pela sua stack tech e 'pt' pelo seu idioma
npx @the-bearded-bear/claude-craft install ~/meu-projeto --tech=symfony --lang=pt

Exemplo para um projeto Flutter em inglês:

npx @the-bearded-bear/claude-craft install ~/meu-projeto --tech=flutter --lang=en

Saída esperada:

Installing Claude-Craft rules...
  ✓ Common rules installed
  ✓ Symfony rules installed
  ✓ Agents installed
  ✓ Commands installed
  ✓ Templates installed
  ✓ Checklists installed
  ✓ CLAUDE.md generated

Installation complete! Run 'claude' in your project directory to start.

Se você ver um erro:

• npm ERR! 404 → Verifique sua conexão com a internet
• EACCES: permission denied → Execute com sudo ou corrija permissões do npm
• command not found: npx → Instale o Node.js primeiro

---

Método B: Makefile (Mais Controle)

Ideal para: Personalização, contribuidores do projeto, uso offline

Este método requer clonar o repositório do Claude-Craft primeiro.

Passo B.1: Clonar o Claude-Craft

# Clonar para um local permanente
git clone https://github.com/TheBeardedBearSAS/claude-craft.git ~/claude-craft

Saída esperada:

Cloning into '/home/seunome/claude-craft'...
remote: Enumerating objects: XXX, done.
...
Resolving deltas: 100% (XXX/XXX), done.

Passo B.2: Executar a Instalação

# Navegar para o diretório do Claude-Craft
cd ~/claude-craft

# Instalar regras no seu projeto
# Substitua 'symfony' pela sua tech e 'pt' pelo seu idioma
make install-symfony TARGET=~/meu-projeto LANG=pt

Exemplos para outras stacks:

# Flutter em inglês
make install-flutter TARGET=~/meu-projeto LANG=en

# React em francês
make install-react TARGET=~/meu-projeto LANG=fr

# Python em alemão
make install-python TARGET=~/meu-projeto LANG=de

# Apenas regras comuns (qualquer projeto)
make install-common TARGET=~/meu-projeto LANG=pt

Saída esperada:

Installing Symfony rules to /home/seunome/meu-projeto...
  Creating .claude directory...
  Copying rules... done
  Copying agents... done
  Copying commands... done
  Copying templates... done
  Copying checklists... done
  Generating CLAUDE.md... done

Installation complete!

---

6. Verificar a Instalação

Após a instalação, verifique se tudo está no lugar:

# Navegar para seu projeto
cd ~/meu-projeto

# Listar o diretório .claude
ls -la .claude/

Saída esperada:

total XX
drwxr-xr-x  8 user user 4096 Jan 12 10:00 .
drwxr-xr-x  3 user user 4096 Jan 12 10:00 ..
-rw-r--r--  1 user user 2048 Jan 12 10:00 CLAUDE.md
drwxr-xr-x  2 user user 4096 Jan 12 10:00 agents
drwxr-xr-x  2 user user 4096 Jan 12 10:00 checklists
drwxr-xr-x  4 user user 4096 Jan 12 10:00 commands
drwxr-xr-x  2 user user 4096 Jan 12 10:00 rules
drwxr-xr-x  2 user user 4096 Jan 12 10:00 templates

Verificar Cada Componente

# Contar regras (deve ser 15-25 dependendo da stack)
ls .claude/rules/*.md | wc -l

# Contar agentes (deve ser 5-12)
ls .claude/agents/*.md | wc -l

# Contar comandos (deve ter subdiretórios)
ls .claude/commands/

Se faltarem arquivos:

• Execute novamente o comando de instalação
• Verifique se você tem permissões de escrita no diretório
• Veja a seção Solução de Problemas

---

7. Configurar o Contexto do Projeto

O arquivo mais importante para personalizar é o contexto do seu projeto. Isso informa ao Claude sobre SEU projeto específico.

Opção A: Configuração Interativa (Recomendada)

Use o comando integrado para detectar automaticamente sua stack e responder perguntas direcionadas:

# Iniciar Claude Code
claude

# Executar o comando de configuração
/common:setup-project-context

O comando irá:

1. Auto-detectar sua stack técnica, framework, banco de dados e CI/CD
2. Fazer perguntas para informações faltantes (tipo de app, domínio, usuários, conformidade)
3. Gerar um arquivo .claude/rules/00-project-context.md completo
4. Sugerir próximos passos (agentes para executar, seções para completar)

Modos disponíveis:

• (padrão) - Detecção equilibrada + perguntas essenciais
• --auto - Detecção máxima, perguntas mínimas
• --full - Questionário completo incluindo objetivos e glossário

Opção B: Configuração Manual

Se preferir configurar manualmente, abra o arquivo diretamente:

# Abrir no seu editor (substitua 'nano' por 'code', 'vim', etc.)
nano .claude/rules/00-project-context.md

Seções para Personalizar

Encontre e atualize estas seções:

## Visão Geral do Projeto
- **Nome**: [Nome do seu projeto]
- **Descrição**: [O que seu projeto faz?]
- **Tipo**: [API / App Web / App Móvel / CLI / Biblioteca]

## Stack Técnica
- **Framework**: [ex: Symfony 7.0, Flutter 3.16]
- **Versão da Linguagem**: [ex: PHP 8.3, Dart 3.2]
- **Banco de Dados**: [ex: PostgreSQL 16, MySQL 8]

## Convenções da Equipe
- **Estilo de Código**: [ex: PSR-12, Effective Dart]
- **Estratégia de Branches**: [ex: GitFlow, Trunk-based]
- **Formato de Commits**: [ex: Conventional Commits]

## Regras Específicas do Projeto
- [Adicione quaisquer regras personalizadas para seu projeto]

Exemplo: API de E-commerce

## Visão Geral do Projeto
- **Nome**: ShopAPI
- **Descrição**: API RESTful para plataforma de e-commerce
- **Tipo**: API

## Stack Técnica
- **Framework**: Symfony 7.0 com API Platform
- **Versão da Linguagem**: PHP 8.3
- **Banco de Dados**: PostgreSQL 16

## Convenções da Equipe
- **Estilo de Código**: PSR-12
- **Estratégia de Branches**: GitFlow
- **Formato de Commits**: Conventional Commits

## Regras Específicas do Projeto
- Todos os preços devem ser armazenados em centavos (inteiro)
- Usar UUID v7 para todos os identificadores de entidades
- Exclusão suave obrigatória para todas as entidades

Salve o arquivo quando terminar (no nano: Ctrl+O, depois Enter, depois Ctrl+X).

---

8. Primeiro Lançamento com Claude Code

Agora vamos iniciar o Claude Code e verificar se tudo funciona:

# Certifique-se de estar no diretório do seu projeto
cd ~/meu-projeto

# Lançar Claude Code
claude

Você deve ver o Claude Code iniciar com um prompt.

Testar se as Regras Estão Ativas

Digite esta mensagem para o Claude:

Quais regras e diretrizes você está seguindo para este projeto?

Claude deve responder mencionando:

• Contexto do projeto de 00-project-context.md
• Regras de arquitetura
• Requisitos de testes
• Diretrizes específicas da tecnologia

Se Claude não mencionar suas regras:

• Certifique-se de estar na raiz do projeto (não em um subdiretório)
• Verifique se o diretório .claude/ existe
• Reinicie o Claude Code

---

9. Testar Sua Configuração

Execute estes testes rápidos para verificar se tudo funciona:

Teste 1: Verificar Comandos Disponíveis

Pergunte ao Claude:

Liste todos os comandos slash disponíveis para este projeto

Esperado: Claude deve listar comandos como /common:analyze-feature, /{tech}:generate-crud, etc.

Teste 2: Usar um Agente

Tente invocar um agente:

@tdd-coach Ajude-me a entender como escrever testes para este projeto

Esperado: Claude deve responder como o agente TDD Coach com orientação sobre testes.

Teste 3: Executar um Comando

Tente um comando simples:

/common:pre-commit-check

Esperado: Claude deve executar uma verificação de qualidade pré-commit (pode reportar sem alterações se o projeto estiver vazio).

Checklist de Validação

• [ ] Claude Code inicia sem erros
• [ ] Claude menciona as regras do projeto quando perguntado
• [ ] Comandos slash são reconhecidos
• [ ] Agentes respondem com conhecimento especializado
• [ ] Contexto do projeto é refletido nas respostas

---

10. Solução de Problemas

Problemas de Instalação

Problema: Permission denied durante a instalação

# Solução 1: Corrigir permissões do diretório
chmod 755 ~/meu-projeto

# Solução 2: Executar com sudo (não recomendado para npm)
sudo npx @the-bearded-bear/claude-craft install ...

Problema: Command not found: npx

# Solução: Instalar Node.js
brew install node  # macOS
sudo apt install nodejs npm  # Ubuntu/Debian

Problema: ENOENT: no such file or directory

# Solução: Criar o diretório de destino primeiro
mkdir -p ~/meu-projeto

Problemas em Tempo de Execução

Problema: Claude não vê as regras

• Verifique se você está na raiz do projeto: pwd
• Verifique se .claude/ existe: ls -la .claude/
• Reinicie o Claude Code: saia e execute claude novamente

Problema: Comandos não reconhecidos

• Verifique o diretório de comandos: ls .claude/commands/
• Verifique permissões de arquivos: ls -la .claude/commands/*.md

Problema: Agentes não respondem

• Verifique o diretório de agentes: ls .claude/agents/
• Use a sintaxe correta: @nome-agente mensagem

Obter Ajuda

Se ainda estiver travado:

1. Consulte o Guia de Solução de Problemas
2. Pesquise nos GitHub Issues
3. Abra uma nova issue com sua mensagem de erro

---

11. Próximos Passos

Parabéns! Seu ambiente Claude-Craft está pronto. Aqui está o que vem a seguir:

Próximos Passos Imediatos

1. Commite sua configuração:

   git add .claude/
   git commit -m "feat: add Claude-Craft configuration"

2. Comece a construir seu projeto com assistência de IA

3. Leia o Guia de Desenvolvimento de Funcionalidades para aprender o fluxo de trabalho TDD

Leituras Recomendadas

Guia	Descrição
Desenvolvimento de Funcionalidades	Fluxo TDD com agentes e comandos
Correção de Bugs	Diagnóstico e testes de regressão
Referência de Ferramentas	Utilitários Multi-conta, StatusLine
Adicionar a Projeto Existente	Para seus outros projetos

Cartão de Referência Rápida

# Lançar Claude Code
claude

# Agentes comuns
@api-designer      # Design de API
@database-architect # Schema de banco de dados
@tdd-coach         # Ajuda com testes
@{tech}-reviewer   # Revisão de código

# Comandos comuns
/common:analyze-feature     # Analisar requisitos
/{tech}:generate-crud       # Gerar código CRUD
/common:pre-commit-check    # Verificação de qualidade
/common:security-audit      # Auditoria de segurança

---

← Anterior: Gestão do Backlog | Próximo: Adicionar a Projeto Existente →