Templates de Prompts que Entregam Código

Um prompt descartável devolve-te código descartável. Um preciso devolve algo que podes mesmo fazer merge. A diferença entre os dois é quase sempre a especificidade. Instruções vagas geram output vago.

As dez receitas abaixo incorporam o detalhe que o Claude Code precisa para produzir trabalho que mandarias para revisão. Cada uma vem com o prompt, a razão por que resulta, algumas substituições para outras stacks e os erros que apanham quem chega a algo similar sem nenhuma estrutura.

Scaffolding de Projeto

App Web Full-Stack

claude "Create a React app with TypeScript and Tailwind CSS. It's a todo app with localStorage persistence. Include: add, edit, delete, mark complete, and filter by status (all/active/completed). Use a single TodoContext for state management. Make it mobile-responsive with min-width 320px support."

Por que resulta: Stack tecnológica, escolha de armazenamento, cada verbo CRUD, o modelo de estado e o tamanho de ecrã mínimo suportado estão todos escritos. O Claude para de adivinhar, por isso nada volta que precises de deitar fora depois.

Substituições:

• Next.js: troca "React app" por "Next.js 15 app using App Router and Server Components where possible"
• Vue: substitui a stack React/TypeScript por "Vue 3 with Composition API and TypeScript"
• Starter mais rico: acrescenta "Include dark mode toggle, keyboard shortcuts (Ctrl+N for new, Delete to remove), and export/import as JSON"

Onde as pessoas erram: Um simples "create a todo app" empurra o Claude para o que parece certo, que raramente corresponde ao teu repositório. "Make it look good" é pior do que nomear Tailwind, porque gosto não é uma especificação.

O que recebes de volta: três a cinco ficheiros. Uma árvore de componentes React, um context provider, interfaces TypeScript para o modelo todo, e um layout Tailwind responsivo. npm run dev corre-o na primeira tentativa.

API Backend com Autenticação

claude "Build an Express.js REST API with JWT authentication. Include: user registration (POST /auth/register), login (POST /auth/login), and a protected endpoint (GET /auth/me). Hash passwords with bcrypt (12 rounds). Use middleware for token verification. Add Zod validation for request bodies. Return consistent JSON error responses with status codes. Include a health check endpoint at GET /health."

Por que resulta: Escrever as rotas impede o Claude de inventar as suas. Nomear o número de rounds do bcrypt, a biblioteca de validação e a forma do erro significa que o output já parece código do teu projeto. Sem passe de limpeza.

Substituições:

• Fastify: substitui "Express.js" por "Fastify with @fastify/jwt plugin"
• Prisma: acrescenta "Use Prisma with PostgreSQL. Include a User model with id, email, passwordHash, createdAt fields"
• Sessões: troca "JWT authentication" por "express-session with Redis store for session management"

Onde as pessoas erram: Salta a linha de tratamento de erros e o Claude escreve apenas o caminho feliz. Registo e login funcionam com input limpo e explodem com qualquer coisa malformada.

Base de Dados e Camada de Dados

Geração de Schema

claude "Create a PostgreSQL schema for a multi-tenant SaaS app. Tables needed: organizations, users (belongs to organization), projects (belongs to organization), and tasks (belongs to project, assigned to user). Include: UUID primary keys, created_at/updated_at timestamps on all tables, proper foreign keys with ON DELETE CASCADE, a unique constraint on user email per organization, and indexes on all foreign key columns. Add 5 sample INSERT statements per table for testing."

Por que resulta: A palavra "multi-tenant" carrega o padrão de isolamento. Chamar as chaves UUID, timestamps, regras de cascade e o âmbito da restrição de email único elimina as revisões mais comuns. Pedir linhas de exemplo força o schema a carregar sem erros.

Substituições:

• MySQL: substitui "PostgreSQL" por "MySQL 8.0 using InnoDB engine"
• Migrações Prisma: acrescenta "Format as Prisma schema instead of raw SQL, and generate the initial migration"
• Log de auditoria: acrescenta "Include an events table with a JSONB payload column, indexed with GIN, for audit logging"

Testes

Setup de Testes Completo

claude "Set up Vitest with React Testing Library for this TypeScript React project. Create: a test for the Button component that checks rendering, click handling, disabled state, and loading state. An integration test for the LoginForm that mocks the auth API call, fills the form, submits, and verifies redirect on success and error message on failure. Add a test utility file with a renderWithProviders function that wraps components in the app's context providers. Add test and test:coverage scripts to package.json."

Por que resulta: Prompts de testes falham quando parecem "escreve testes para este componente." Aqui tens quatro casos nomeados para o teste unitário e dois fluxos end-to-end para o teste de integração. O ficheiro de helper partilhado é a peça que a maioria das pessoas salta, e é a que mantém os testes futuros consistentes.

Substituições:

• Playwright E2E: substitui o framework por "Set up Playwright for end-to-end testing. Include a test that navigates to the login page, fills credentials, submits, and verifies the dashboard loads"
• Testes de API: "Set up Supertest with Vitest for the Express API. Test the /auth/register endpoint with valid data, duplicate email, and missing required fields"

O que recebes de volta: um ficheiro de configuração, dois ou três ficheiros de teste que passam, um ficheiro de utilitários partilhados e scripts frescos no package.json. npm test fica verde imediatamente.

Refatoração

Decomposição de Componentes

claude "This UserDashboard component is 400 lines long. Refactor it by: extracting the stats cards into a StatsGrid component, the activity feed into an ActivityFeed component, and the sidebar navigation into a DashboardNav component. Keep the data fetching in UserDashboard and pass data down as props. Create TypeScript interfaces for all props. Preserve all existing functionality and don't change any CSS class names."

Por que resulta: Prompts de refatoração precisam de guardrails. "Refatora este componente" deixa o Claude mover o que quiser, e o comportamento muda silenciosamente. Indicar quais componentes filhos extrair, onde o fetching fica e quais classes CSS se mantêm significa que o novo código cai na tua app sem partir a UI nem os testes.

Substituições:

• Hook personalizado: "Extract the data fetching logic into a useUserDashboard custom hook. Return the loading state, error state, and all data objects. Keep the component purely presentational"
• Migração Zustand: "Move the local useState calls into a Zustand store. Export typed selectors for each piece of state. Keep the component renders identical"

Debugging

Caça de Bugs Estruturada

claude "Users report that the checkout form submits twice on slow connections. Investigate: check the form's onSubmit handler for missing event.preventDefault() or missing disabled state during submission. Check if the submit button lacks a loading/disabled state. Check for React StrictMode double-render issues. Check if the API call has retry logic that could cause duplicates. Propose a fix and add an idempotency safeguard."

Por que resulta: A maioria dos prompts de debugging lê "corrige este bug." Isso pede ao Claude para adivinhar, fazer grep e corrigir de uma vez, e normalmente prende-se à primeira história plausível. Esta versão entrega as quatro causas de raiz mais prováveis para um duplo submit e pede ao Claude para percorrer cada uma por ordem.

Substituições:

• Página lenta: "The dashboard takes 8 seconds to load. Investigate: check for N+1 queries in the API, unnecessary re-renders in React components, unoptimized images, and missing database indexes. Measure the time each fix saves"
• Saída de sessão: "Users are getting logged out randomly. Check: JWT expiration handling, refresh token rotation, cookie settings (SameSite, Secure, HttpOnly), and whether concurrent requests race on token refresh"

Revisão de Código e Qualidade

Revisão Pré-PR

claude "Review the changes in this branch for a PR. Check for: security issues (SQL injection, XSS, exposed secrets), missing error handling on async operations, TypeScript type safety (no 'any' types, proper null checks), accessibility on any new UI components (ARIA labels, keyboard navigation), and performance concerns (unnecessary re-renders, missing useMemo/useCallback). Format findings as a list with severity (critical/warning/info) and file location."

Por que resulta: "Revisa este código" gera notas superficiais. Indicar os cinco eixos de revisão e a forma do output produz um relatório que podes percorrer e executar imediatamente.

Substituições:

• Só backend: troca acessibilidade e re-renders por "N+1 queries, missing rate limiting, and improper error propagation"
• Passagem de segurança: "Focus exclusively on security: check all user inputs, authentication boundaries, authorization checks, sensitive data handling, and dependency vulnerabilities"

Desenvolvimento de Funcionalidades

Build de Fatia Vertical

claude "Add a comment system to blog posts. Requirements: comments stored in a PostgreSQL comments table with id, post_id, author_name, content, created_at. API endpoints: GET /posts/:id/comments and POST /posts/:id/comments with Zod validation. React component showing threaded comments with a reply form. Optimistic UI update on new comment submission. Rate limit to 5 comments per minute per IP. Include the database migration."

Por que resulta: O prompt abrange toda a fatia. Tabela, API e UI num único pedido. Nomear o rendering optimista, o rate limit e o ficheiro de migração significa que o Claude escreve a funcionalidade como uma unidade acabada, não três fragmentos vagamente relacionados que expõem lacunas na hora de testar.

Substituições:

• Tempo real: "Add WebSocket support so new comments appear for all viewers without refreshing"
• Moderação: "Include an isApproved boolean field and an admin endpoint to approve/reject comments"

Infraestrutura e DevOps

Pipeline CI/CD

claude "Create a GitHub Actions workflow for this TypeScript monorepo. On push to main: run TypeScript type checking, run Vitest tests, build the Next.js app, and deploy to Vercel. On pull request: run type checking and tests only, post a preview deployment link as a PR comment. Cache node_modules between runs using pnpm lockfile hash. Fail fast if any step errors."

Por que resulta: Prompts de pipeline precisam de regras de branch escritas logo no início. Ao separar o que corre em main do que corre em PRs, indicar a chave de cache e nomear o comportamento de preview, o workflow funciona corretamente no primeiro push. Sem três rondas de "ah, acrescenta também isto."

Substituições:

• Docker: "Build and push a Docker image to GitHub Container Registry on main, tagged with the git SHA and 'latest'"
• Migrações: "Add a step that runs Prisma migrations against the staging database before deployment, with a rollback step if deployment fails"

Configuração e Ambiente

Auditoria de Configuração

claude "Audit this project's configuration. Check: tsconfig.json has strict mode enabled and proper path aliases. ESLint config catches unused imports, consistent formatting, and React hook dependency warnings. Package.json has correct scripts for dev, build, test, and lint. Environment variables are validated at startup (not just process.env access scattered through code). Flag any configuration that could cause silent failures in production."

Por que resulta: Bugs de configuração são os piores. Falham silenciosamente ou apenas às terças-feiras. Este prompt aponta o Claude para as quatro superfícies que importam e pergunta diretamente sobre modos de falha em produção.

Princípios de Utilização

As dez receitas resultam por três razões que vale a pena roubar.

Entrega a forma, não apenas o objetivo. "Create an API" é um objetivo. "Create Express endpoints at these routes with Zod validation and consistent error responses" é uma forma. O Claude trabalha a partir da forma e constrói para corresponder.

Nomeia as restrições logo no início. Qualquer restrição que deixes por dizer transforma-se numa cara ou coroa. Stack, tratamento de erros, estilos, suporte de browsers, motor de base de dados. Se importa, escreve. Se não escreves, o Claude escolhe o que parecer correto.

Escreve os requisitos aborrecidos. Rate limiting. Idempotência. Estados de carregamento. Error boundaries. Labels acessíveis. Estas são as linhas que separam uma demo de código real, e são as que a maioria dos prompts omite. Gastar algumas palavras extra nelas poupa horas de retrabalho depois.

Constrói a Tua Própria Biblioteca

As dez receitas cobrem padrões que aparecem em quase todos os projetos. A tua codebase tem a sua própria forma, porém, e os seus próprios pontos críticos. O retorno vem de manter uma biblioteca de templates própria. Quando uma execução do Claude Code produz algo limpo, guarda o prompt. Quando não produz, descobre qual peça da especificação estava em falta e acrescenta-a.