Fluxo de estimativa de desenvolvimento com Claude Code para projetos reais

Estimativa de desenvolvimento não é adivinhar o número exato de dias. Em projetos reais, uma boa estimativa explica escopo, premissas, incógnitas, riscos, tempo de revisão e verificação para que produto, engenharia e cliente decidam com a mesma evidência.

O erro de iniciante é estimar só o tempo de codar. “Adicionar um campo de telefone ao perfil” parece pequeno, mas pode tocar migration de banco, tipos da API, validação de formulário, exportações CSV, logs de auditoria, testes, release notes e disponibilidade de revisores. Migration significa mudança de schema ou dados. Ela precisa de atenção própria porque dados nem sempre voltam tão facilmente quanto código.

Claude Code não torna a estimativa magicamente precisa. O valor está em ler o repositório, mostrar o raio de impacto, colocar premissas e incógnitas em tabelas e deixar riscos visíveis. Não use para inventar datas seguras; use para reduzir trabalho oculto.

Esse fluxo combina com o empirismo do Scrum Guide: transparência, inspeção e adaptação. Para acompanhar grupos de issues e PRs, veja a documentação de GitHub milestones. Para estimativa relativa, a guia da Atlassian ajuda. Para Claude Code, mantenha o overview e a CLI reference como fonte.

No ClaudeCodeLab, leia também navegação em codebase, o template de bug report e a checklist de code review.

Separe Os Insumos Da Estimativa

Antes de falar em datas, separe cinco insumos.

Insumo	Significado simples	Como Claude Code ajuda
scope	O que entra e o que fica fora	Arquivos, features relacionadas, testes
assumptions	O que precisa ser verdade	Regras de produto, permissões, release
unknowns	O que ainda não sabemos	Arquivos, perguntas, responsáveis
risk buffer	Espaço para falha e espera	Migration, auth, billing, fila de review
evidence	Por que o número é defensável	PRs antigas, git history, testes

Evite dizer só “2 dias”. Melhor: “baixo 1,5 dia, provável 3 dias, alto 5 dias se CRM entrar no escopo”. Um intervalo não é fraqueza. É uma forma honesta de mostrar o que é conhecido e o que ainda pode mudar.

flowchart LR
  A["Pedido"] --> B["repo scan"]
  B --> C["decomposição"]
  C --> D["tabela de premissas"]
  D --> E["registro de riscos"]
  E --> F["intervalo"]
  F --> G["prompt de revisão"]
  G --> H["resumo ao cliente"]

Quatro Casos De Uso Realistas

O primeiro caso é uma mudança de campo em SaaS. Adicionar phone_number pode afetar schema de banco, validação da API, UI, busca, exportação CSV, audit logs, privacidade e testes. Se for dado pessoal, mascaramento de logs e regras de exclusão/exportação entram na estimativa.

O segundo caso é bug em tela legada. “O filtro não funciona” pode envolver query helpers antigos, cache, parâmetros de URL, fixtures e E2E. Antes de pedir correção, peça ao Claude Code para mapear impacto e verificação.

O terceiro caso é proposta de consultoria ou pedido interno de DX. O cliente diz “precisamos de um admin”, mas o escopo real pode incluir login, papéis, auditoria, CSV, notificações, transferência de permissões e manual operacional. Claude Code pode ler issues e código existentes para revelar trabalho que não apareceu no pedido inicial.

O quarto caso é site de conteúdo monetizado. Uma pequena alteração em MDX pode incluir performance, links internos, OGP, dados estruturados, localização, screenshots e revisão de layout para AdSense. Qualidade de publicação é maior do que editar texto.

Falhas Comuns

A primeira falha é compartilhar a primeira intuição como compromisso. “Provavelmente um dia” é desejo antes do repo scan. Quando esse desejo chega ao stakeholder, uma estimativa realista parece atraso.

A segunda falha é tratar revisão e verificação como grátis. Seis horas de implementação ainda podem exigir testes, ajustes de review, staging, release notes e coordenação de deploy.

A terceira falha é esconder incógnitas em um buffer vago. “Somar 30%” não ajuda sem nomear o motivo: API externa incerta, rollback não desenhado, fila de revisores, fixtures ausentes ou regra de produto ambígua.

A quarta falha é confiar em número de IA sem evidência. Se Claude Code diz “3 dias” sem listar arquivos, PRs passadas, testes e riscos, a estimativa é só texto bem escrito.

Step 1: Repo Scan Somente Leitura

Comece pela forma do repositório. Ainda não edite.

git status --short
git branch --show-current
git rev-parse --show-toplevel

rg --files \
  -g '!*node_modules*' \
  -g '!dist' \
  -g '!build' \
  -g '!coverage' \
  -g '!*.lock' \
  | sort \
  | head -200

find . -maxdepth 3 \( \
  -name package.json -o \
  -name pyproject.toml -o \
  -name go.mod -o \
  -name Cargo.toml -o \
  -name AGENTS.md -o \
  -name CLAUDE.md -o \
  -name README.md \
\) -print

Depois peça um mapa somente leitura.

claude -p "
Run a read-only repo scan.
Do not edit, create files, or add dependencies.

Return:
1. apps, packages, and services
2. runtime, test, and build entrypoints
3. generated folders to ignore
4. 10 files that must be read for this estimate
5. reasons this task cannot yet be estimated
"

Step 2: Decomponha A Tarefa

Divida em unidades revisáveis e verificáveis.

claude -p "
Task: Let users add, view, and edit a phone number on their profile.

Break this into reviewable work items.
For each item include:
- name
- likely files
- implementation work
- test work
- definition of done
- size: small, medium, or large

Also list out-of-scope items.
Separate guessed product rules as assumptions.
"

Normalmente aparecem DB, API, UI, testes e release. Se um item não cabe em um PR, divida antes de estimar.

Step 3: Tabela De Premissas

Premissas são onde o plano costuma quebrar. Escreva.

| ID | Assumption | Why it matters | Owner | Confirm by |
| --- | --- | --- | --- | --- |
| A1 | Phone number is optional | Required fields change validation and migration | PM | 2026-06-05 |
| A2 | Web only, no mobile app change | Mobile release adds review and store delay | PM | 2026-06-05 |
| A3 | Existing user rows stay null | Backfill work is not included | Tech lead | 2026-06-06 |

claude -p "
Review this assumptions table.
Find assumptions that could break the estimate.
Add missing owners, deadlines, and questions.
Move anything risky into a risk register.
"

Step 4: Registro De Riscos

Um registro de riscos lista o que pode quebrar o plano.

| Risk | Trigger | Impact | Mitigation | Buffer |
| --- | --- | --- | --- | --- |
| DB rollback is unclear | migration changes existing rows | High | dry-run and rollback plan | 0.5-1 day |
| External CRM stores phone | CRM field mapping appears | Medium | check integration owner | 0.5 day |
| Review queue is full | no reviewer within 24h | Medium | book review slot early | 1 day |
| Test data is missing | no edge-case users | Medium | create fixtures first | 0.5 day |

Buffer não é folga para trabalhar devagar. É espaço para incerteza, falha e espera. Autenticação, cobrança, dados privados, fluxos de exclusão e migrations precisam de risco mais explícito do que uma mudança só de UI.

Step 5: Calcule Um Intervalo

Este script pode ser copiado e executado.

// estimate-range.mjs
const tasks = [
  { name: "Repo scan and design check", hours: 2, risk: 1.1 },
  { name: "DB migration and schema", hours: 4, risk: 1.4 },
  { name: "API contract and validation", hours: 5, risk: 1.2 },
  { name: "Profile UI update", hours: 6, risk: 1.2 },
  { name: "Tests and fixtures", hours: 5, risk: 1.3 },
  { name: "Review fixes and release note", hours: 3, risk: 1.2 },
];

const base = tasks.reduce((sum, task) => sum + task.hours, 0);
const likely = tasks.reduce((sum, task) => sum + task.hours * task.risk, 0);
const low = Math.max(base * 0.8, base - 4);
const high = likely * 1.35;

const day = 6;
const format = (hours) => `${hours.toFixed(1)}h / ${(hours / day).toFixed(1)}d`;

console.log(`Low:    ${format(low)}`);
console.log(`Likely: ${format(likely)}`);
console.log(`High:   ${format(high)}`);

node estimate-range.mjs

Não trate o multiplicador como verdade. risk: 1.4 significa “esta parte é incerta”. Se mudar, registre o motivo no issue ou PR.

Step 6: Revisão Crítica

Antes de enviar ao cliente, peça ao Claude Code para criticar.

You are a critical project estimation reviewer.

Review this estimate before I share it with a client.
Find:
1. hidden scope
2. weak assumptions
3. missing tests
4. missing rollout or rollback work
5. fake precision
6. tasks that should be split

Return findings first.
Then provide a revised low / likely / high range.
Do not make the estimate look more certain than the evidence supports.

O pedido importa. “Deixe mais bonito” gera texto bonito. “Revise criticamente” gera atrito útil.

Step 7: Resumo Para O Cliente

Transforme notas internas em documento curto de decisão.

# Development Estimate Summary

## Scope
- Add optional phone number to user profile.
- Update DB schema, API validation, profile UI, and tests.
- Include release note and manual verification.

## Not included
- SMS notification.
- Mobile app release.
- Historical data backfill.
- CRM integration changes unless confirmed.

## Estimate
- Low: 3 business days
- Likely: 4-5 business days
- High: 7 business days if CRM or migration rollback work expands

## Assumptions
- Phone number is optional.
- Web only.
- Existing users can keep the value empty.

## Risks
- DB rollback plan must be reviewed before implementation.
- Reviewer availability may add one calendar day.

## Next decision
- Confirm whether CRM and mobile app are in scope by 2026-06-05.

Coloque a estimativa em GitHub Issues ou milestone para comparar com o real depois.

## Estimate
- Low:
- Likely:
- High:
- Confidence: Low / Medium / High

## Scope
- [ ]

## Out of scope
- [ ]

## Assumptions
- [ ]

## Risks
- [ ]

## Verification
- [ ] Unit tests:
- [ ] Integration tests:
- [ ] Manual check:

## Actual result
- Started:
- Merged:
- Extra work found:
- What to adjust next time:

A seção Actual result transforma a próxima estimativa em aprendizado, não opinião.

CTA De Consultoria

Estimativa funciona bem como tema de consultoria porque cada leitor precisa adaptar o fluxo ao próprio repositório, linguagem com cliente e regras de equipe. ClaudeCodeLab pode ajudar com templates de estimativa, prompts de revisão para Claude Code, checklists de PR e regras de rollout. Para conectar isso aos seus issues ou propostas, envie contexto por treinamento e consultoria Claude Code.

Resultado Testado

Masa testou este fluxo em uma pequena mudança de campo de perfil. A intuição inicial era “meio dia de UI”. Depois do repo scan, surgiram schema de DB, validação da API, export CSV, audit logs, testes e fila de review. O intervalo pronto para cliente virou 4-5 dias úteis prováveis, com caso alto de 7 dias se CRM aparecesse. Claude Code foi útil não por prever a data, mas por revelar arquivos escondidos e incógnitas cedo.