Claude Code Development Estimation Workflow for Real Projects

Development estimation is not a game of guessing the exact number of days. In real projects, the useful estimate explains scope, assumptions, unknowns, risk, review time, and verification work so everyone can make the same decision with the same evidence.

The beginner mistake is estimating only the coding time. “Add one profile field” sounds small until it touches a database migration, API types, form validation, export files, audit logs, tests, release notes, and reviewer availability. A migration means a database schema or data change. It deserves special attention because code can be reverted quickly, but changed data is harder to undo.

Claude Code does not make estimates magically accurate. Its value is in reading the repository, finding the blast radius, naming assumptions, and forcing unknowns into a visible table. Use it to reduce overlooked work, not to invent confident dates.

This workflow matches the empirical mindset in the official Scrum Guide: make work transparent, inspect evidence, and adapt the plan. GitHub’s milestones docs are useful when you need to track a bundle of issues and PRs. Atlassian’s estimation guide is helpful for relative sizing. For Claude Code behavior, keep the overview and CLI reference open.

For adjacent ClaudeCodeLab reading, pair this with codebase navigation, the bug report template, and the code review checklist.

Separate The Estimate Inputs

Use five buckets before discussing dates.

Input	Plain meaning	What Claude Code can help with
scope	What is included and excluded	Changed files, related features, tests
assumptions	What must be true for the estimate	Product rules, permissions, release path
unknowns	What is not known yet	Missing files, questions, owners
risk buffer	Space for failure and waiting	Migration, auth, billing, review queue
evidence	Why the number is defensible	Past PRs, git history, test count

Avoid a single number such as “2 days.” A better answer is “low 1.5 days, likely 3 days, high 5 days if the CRM integration is in scope.” Ranges are not weakness. They show what you know and what can still move.

flowchart LR
  A["Request"] --> B["repo scan"]
  B --> C["task decomposition"]
  C --> D["assumptions table"]
  D --> E["risk register"]
  E --> F["estimate range"]
  F --> G["review prompt"]
  G --> H["client summary"]

Four Realistic Use Cases

The first case is a SaaS profile-field change. Adding phone_number may touch database schema, API validation, UI, search, CSV exports, audit logs, privacy behavior, and tests. If the field is personal data, log masking and delete/export rules become part of the estimate.

The second case is a legacy bug fix. “Filtering does not work” can involve stale query helpers, cache behavior, URL parameters, fixtures, and E2E checks. Before asking Claude Code to fix it, ask it to map the impact and verification route.

The third case is a consulting proposal or internal DX request. A client says “we need an admin screen,” but the real scope may include login, roles, audit trails, CSV import, notification rules, and an operations manual. Claude Code can read existing issues and code to reveal work that is missing from the initial request.

The fourth case is a monetized content or marketing site. A small MDX change can include page speed, internal links, OGP images, schema markup, localization, screenshots, and AdSense-friendly layout review. Publishing quality is larger than text editing.

Common Failure Modes

The first failure is sharing the first guess as a commitment. “Probably one day” is only a hope before the repo is scanned. Once that hope reaches a stakeholder, any better estimate looks like a delay.

The second failure is treating review and verification as free. Six hours of implementation can still require tests, review fixes, staging checks, release notes, and deployment coordination.

The third failure is hiding unknowns inside a vague buffer. “Add 30%” is not useful unless you name the reason: external API uncertainty, rollback design, reviewer queue, missing fixtures, or unclear product rules.

The fourth failure is trusting an AI number without evidence. If Claude Code says “3 days” but does not list files, past PRs, tests, and risks, the estimate is just polished prose.

Step 1: Run A Read-Only Repo Scan

Start with the repository shape. Do not edit files yet.

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

Then ask Claude Code for a read-only map.

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: Decompose The Task

Split work into reviewable units, not tiny fragments.

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

Good decomposition usually lands in DB, API, UI, tests, and release work. If one item is too large for one PR, split it before estimating.

Step 3: Build An Assumptions Table

Assumptions are where estimates later break. Make them explicit.

| 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: Create A Risk Register

A risk register is just a table of what can break the 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 |

Buffers are not padding for laziness. They are space for unknowns, failure, and queue time. Auth, billing, private data, deletion flows, and migrations usually need more explicit risk than UI-only work.

Step 5: Calculate A Range

This small script is copy-paste runnable and good enough for team discussion.

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

Do not treat the multiplier as truth. risk: 1.4 means “this area is uncertain.” If you change it, record why in the issue or PR.

Step 6: Review The Estimate Critically

Ask Claude Code to attack the estimate before a client sees it.

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.

The wording matters. If you ask for “make this nicer,” you get nicer prose. If you ask for critical review, you get useful friction.

Step 7: Write The Client Summary

Turn internal notes into a short decision document.

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

Put the estimate back into GitHub Issues or a milestone so actuals can be compared later.

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

The Actual result section is where a team learns. It turns the next estimate from opinion into evidence.

Consulting CTA

Estimation is a strong consulting topic because readers usually need help with their own repository, client language, and team rules. ClaudeCodeLab can help design estimation templates, Claude Code review prompts, PR checklists, and rollout rules for teams. If you need a workflow around your own issues or proposal process, send context through Claude Code training and consultation.

Hands-On Result

Masa tested this workflow on a small profile-field change. The first gut estimate was “half a day of UI work.” After repo scan, the real plan included DB schema, API validation, CSV export, audit logs, tests, and review queue time. The final client-ready range was 4-5 likely business days, with a high case of 7 days if CRM work appeared. Claude Code was useful not because it predicted the date, but because it exposed hidden files and unknowns early.