Flujo de estimación de desarrollo con Claude Code para proyectos reales

Estimar desarrollo no consiste en adivinar el número exacto de días. En un proyecto real, una buena estimación explica alcance, supuestos, incógnitas, riesgos, revisión y verificación para que producto, ingeniería y cliente decidan con la misma evidencia.

El error de principiante es estimar solo el tiempo de escribir código. “Añadir un campo de teléfono al perfil” parece pequeño, pero puede tocar una migración de base de datos, tipos de API, validación de formularios, exportaciones CSV, logs de auditoría, tests, notas de release y disponibilidad de revisores. Una migración cambia el esquema o los datos de la base de datos; merece una línea propia porque los datos no siempre se revierten tan fácil como el código.

Claude Code no convierte la estimación en una predicción perfecta. Su valor es leer el repositorio, exponer el radio de impacto, poner supuestos e incógnitas en tablas y hacer visibles los riesgos. No lo uses para inventar una fecha segura; úsalo para reducir trabajo oculto.

Este enfoque encaja con el empirismo del Scrum Guide: transparencia, inspección y adaptación. Para seguir grupos de issues y PRs, revisa la documentación de GitHub milestones. Para estimación relativa, la guía de Atlassian sobre estimaciones también ayuda. Para Claude Code, mantén cerca el overview y la CLI reference.

Como lectura relacionada de ClaudeCodeLab, combina este artículo con navegación de codebases, la plantilla de bug report y la checklist de code review.

Separa Los Insumos De La Estimación

Antes de hablar de fechas, separa cinco insumos.

Insumo	Significado simple	Cómo ayuda Claude Code
scope	Qué entra y qué no entra	Archivos, funciones relacionadas, tests
assumptions	Qué debe ser cierto	Reglas de producto, permisos, release
unknowns	Qué falta confirmar	Archivos, preguntas, responsables
risk buffer	Margen para fallos y espera	Migración, auth, billing, cola de review
evidence	Por qué el número se sostiene	PRs pasados, git history, tests

Evita un único “2 días”. Es mejor decir “bajo: 1,5 días; probable: 3 días; alto: 5 días si CRM entra en scope”. Un rango no es falta de profesionalidad. Es una forma honesta de mostrar qué se sabe y qué todavía puede cambiar.

flowchart LR
  A["Solicitud"] --> B["repo scan"]
  B --> C["descomposición"]
  C --> D["tabla de supuestos"]
  D --> E["registro de riesgos"]
  E --> F["rango de estimación"]
  F --> G["prompt de revisión"]
  G --> H["resumen para cliente"]

Cuatro Casos De Uso Realistas

El primer caso es un cambio de campo en un SaaS. Añadir phone_number puede afectar schema de base de datos, validación de API, UI, búsqueda, CSV, audit logs, privacidad y tests. Si el dato es personal, también entran en la estimación el enmascarado en logs y las reglas de borrado o exportación.

El segundo caso es un bug en una pantalla legacy. “El filtro no funciona” puede implicar helpers de query antiguos, caché, parámetros de URL, fixtures y E2E. Antes de pedirle a Claude Code que arregle el bug, pídele que dibuje impacto y verificación.

El tercer caso es una propuesta de consultoría o una solicitud interna de DX. El cliente dice “necesitamos un admin”, pero el alcance real puede incluir login, roles, auditoría, CSV, notificaciones, traspaso de permisos y manual de operación. Claude Code puede leer issues y código existentes para detectar trabajo no escrito en la solicitud.

El cuarto caso es un sitio de contenido monetizado. Un cambio pequeño en MDX puede incluir velocidad, enlaces internos, OGP, datos estructurados, localización, capturas y revisión de layout para AdSense. Calidad de publicación no es solo editar texto.

Fallos Frecuentes

El primer fallo es comunicar la primera intuición como compromiso. “Seguramente un día” es un deseo antes de leer el repositorio. Cuando ese deseo llega al stakeholder, una estimación más realista parece retraso.

El segundo fallo es tratar revisión y verificación como gratis. Seis horas de implementación pueden necesitar tests, ajustes de review, staging, release notes y coordinación de deploy.

El tercer fallo es esconder incógnitas en un buffer vago. “Sumar 30%” no ayuda si no nombras la causa: API externa sin confirmar, rollback sin diseñar, cola de reviewers, fixtures faltantes o reglas de producto ambiguas.

El cuarto fallo es confiar en un número de IA sin evidencia. Si Claude Code dice “3 días” pero no lista archivos, PRs pasados, tests y riesgos, la estimación es solo prosa pulida.

Step 1: Repo Scan De Solo Lectura

Empieza por la forma del repositorio. No edites todavía.

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

Después pide a Claude Code un mapa de solo lectura.

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: Divide La Tarea

Divide en unidades que puedan revisarse y verificarse.

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 aparecerán DB, API, UI, tests y release. Si un bloque no cabe en un PR, divídelo antes de estimar.

Step 3: Tabla De Supuestos

Los supuestos son donde se rompen los planes. Escríbelos.

| 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 Riesgos

Un registro de riesgos es una tabla con lo que puede romper el plan.

| 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 |

El buffer no es relleno para trabajar lento. Es espacio para incertidumbre, fallos y cola de espera. Autenticación, cobros, datos privados, borrado y migraciones requieren más riesgo explícito que un cambio solo de UI.

Step 5: Calcula Un Rango

Este script se puede copiar y ejecutar tal cual.

// 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

No trates el multiplicador como verdad. risk: 1.4 significa “esta parte tiene incertidumbre”. Si lo cambias, deja el motivo en el issue o PR.

Step 6: Revisión Crítica

Antes de enviarlo al cliente, haz que Claude Code lo critique.

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.

La instrucción importa. Si pides “hazlo más bonito”, obtienes texto bonito. Si pides revisión crítica, obtienes fricción útil.

Step 7: Resumen Para Cliente

Convierte las notas internas en un documento breve de decisión.

# 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.

Regresa la estimación a GitHub Issues o a un milestone para comparar con el resultado real.

## 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:

La sección Actual result convierte la siguiente estimación en evidencia, no en opinión.

CTA De Consultoría

La estimación conecta bien con consultoría porque cada lector necesita adaptar el flujo a su repositorio, sus clientes y sus reglas de equipo. ClaudeCodeLab puede ayudar a diseñar plantillas de estimación, prompts de revisión para Claude Code, checklists de PR y reglas de adopción. Si quieres conectarlo con tus issues o propuestas, envía contexto desde formación y consultoría de Claude Code.

Resultado Probado

Masa probó este flujo en un cambio pequeño de campo de perfil. La intuición inicial era “medio día de UI”. Tras el repo scan aparecieron schema de DB, validación de API, CSV, audit logs, tests y cola de revisión. El rango listo para cliente fue 4-5 días laborables probables, con un caso alto de 7 días si aparecía CRM. Claude Code fue útil no por predecir la fecha, sino por mostrar archivos ocultos e incógnitas pronto.