Workflow Prático — Claude Code e Cursor na Produção

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Verificar
claude --version

cd seu-projeto

# Criar CLAUDE.md na raiz
claude init

# Criar estrutura de regras
mkdir -p .claude/rules .claude/skills

# Projeto: Meu SaaS

## Stack
- TypeScript, Next.js 16, React 19, Tailwind CSS v4
- Go 1.23 backend (Gin), MongoDB, Redis

## Convenções
- 2 espaços de indentação, aspas simples, trailing commas
- Componentes em PascalCase, arquivos em kebab-case
- Sempre usar <Link> do Next.js para navegação interna
- Sempre usar Vitest (nunca Jest) para testes

## Comandos
- pnpm dev: servidor de desenvolvimento
- pnpm lint:fix: corrige lint + formatação
- pnpm vitest run: roda testes unitários
- pnpm build: build de produção

## Após TAMBEM alteração de código:
1. pnpm lint:fix
2. pnpm format
3. pnpm vitest run
4. Se tudo passar, commit com Conventional Commits

## NUNCA commitar se:
- Qualquer teste falhar
- Lint tiver erros
- TypeScript tiver erros de tipo

## Estrutura
- src/app/ — rotas Next.js (App Router)
- src/components/ — componentes React
- src/lib/ — utilitários e helpers
- src/__tests__/ — testes unitários
- backend/api/ — API Go (Gin + MongoDB)
- content/docs/ — conteúdo MDX (Fumadocs)
- specs/ — especificações de features

# Criar spec para a feature
cat > specs/nova-feature.md << 'EOF'
# Spec: Sistema de Notificações

## Objetivo
Notificar usuários quando há atualizações relevantes.

## Endpoints
### GET /api/notifications
- Input: { page: number, limit: number }
- Output: { items: Notification[], total: number, page: number }
- Auth: obrigatório (JWT)

### PATCH /api/notifications/:id/read
- Input: { }
- Output: { success: boolean }
- Auth: obrigatório

## Testes esperados
- [ ] Lista notificações paginadas
- [ ] Retorna 401 sem autenticação
- [ ] Marca notificação como lida
- [ ] Retorna 404 se notificação não existe
EOF

# Prompt para gerar testes
claude -p "Read specs/nova-feature.md and generate Vitest tests.
Write tests to src/__tests__/notifications.test.ts.
Do NOT implement the endpoint. Only write tests."

pnpm vitest run src/__tests__/notifications.test.ts
# Todos devem falhar (endpoint não existe ainda)

# Prompt para implementar
claude -p "Read specs/nova-feature.md and src/__tests__/notifications.test.ts.
Implement the notification endpoints so all tests pass.
Do NOT modify the tests.
After implementing, run: pnpm vitest run src/__tests__/notifications.test.ts
If any test fails, fix the implementation until all pass."

pnpm lint:fix && pnpm format && pnpm vitest run

claude -p "Run git status, review the changes, and commit with a
Conventional Commits message. Include the spec file in the commit."

I need to implement the billing module (specs/billing.md).

Please:
1. First, spawn subagents to read and understand:
   - specs/billing.md (the spec)
   - src/db/schema.ts (current database schema)
   - src/models/user.ts (user model)
   - src/middleware/auth.ts (auth middleware)

2. After understanding the codebase, create a fix_plan.md with tasks

3. Implement one task at a time:
   - Write tests first
   - Implement until tests pass
   - Run pnpm lint:fix && pnpm vitest run
   - Commit if green

4. Update fix_plan.md after each task

@specs/auth.md @src/db/schema.ts @src/middleware/auth.ts

Implement the authentication module described in @specs/auth.md.

Requirements:
- Use the existing database schema from @src/db/schema.ts
- Follow the auth middleware pattern from @src/middleware/auth.ts
- Write tests for each endpoint BEFORE implementing
- Run lint:fix and vitest after each endpoint
- Commit after all tests pass

// .claude/settings.json
{
  "hooks": {
    "onEdit": "pnpm lint:fix",
    "onCommit": "pnpm vitest run",
    "onFinish": "pnpm build"
  }
}

.claude/skills/
├── commit/
│   └── SKILL.md        # Como fazer commits
├── test/
│   └── SKILL.md        # Como rodar testes
└── deploy/
    └── SKILL.md        # Como fazer deploy

# Skill: Commit

## Trigger
When the user says "commit" or stages changes.

## Steps
1. Run `git status` and `git diff --cached`
2. Analyze changes and draft a commit message
3. Follow Conventional Commits: feat:, fix:, refactor:, chore:
4. Subject line ≤ 50 chars
5. Body only when "why" isn't obvious
6. Run `pnpm lint:fix` before committing
7. Run `pnpm vitest run` before committing
8. If tests fail, fix before committing