How to break a big feature into a tracked effort with Claude Code

FlowConcept

❯_

Do this with Claude CodeCopy a prompt that links the cckit docs so Claude learns the CLI, then follows these steps.

Copy as Markdown

Before you start

Install cckitQuickstart: your first lifecycle

This tutorial

Intermediate7 min readNeedscckit installed & initialized

What you’ll do: turn one goal that’s too big for a single PR into a tracked effort — a parent issue with a sub-issue for each independent piece. The parent issue is the plan, so the agent reads it instead of a separate doc. You build the pieces in parallel where they don’t touch the same files, then ship the whole thing as one pull request.

Steps

1. Ask Claude to make it an effort. Describe the goal and that it’s too big for one PR.

   Prompt to paste

   This work is too big for one PR — turn it into a tracked effort. Break it into a sub-task for each
   independent piece, size the work first, then build the pieces (in parallel where they don't touch
   the same files) and open a single PR for the whole effort once they're done.

2. cckit creates and runs the effort.

   cckit effort plan              # session-fit plan over open efforts
   cckit effort new "Auth rework" # parent issue + native sub-issues, all on the board
   cckit effort start <N>         # integration branch effort/<N> + worktree
   # …build sub-issues on the effort branch (sequential) or in worktrees (parallel)…
   cckit effort pr <N>            # ONE PR: effort/<N> → base branch
   cckit effort close <N>         # squash-merge, close parent + all subs, garbage-collect

3. Ship it as one PR. effort pr opens a single pull request for the whole effort; effort close squash-merges it and closes the parent and every sub-issue together.

How it works

cckit effort new fills the parent’s four-section body (Goal / Scope / For agents / Verification), applies the ctx/kind/priority/role/flow labels, and lints every title up front — so a bad sub name fails before anything is created. cckit reads the sub-issues’ blocked-by links and sorts them into waves: everything unblocked runs together, dependents wait their turn. Each effort also gets a memorable slug handle (effort/<N>-<slug>), so start, pr, and close accept the slug or the number interchangeably.

The number stays canonical

The slug is a convenience; the GitHub issue number is still what the sub-issues, PRs, and labels all point at. Pass a pure-digits argument and it’s always treated as the number.

Troubleshooting

A sub title was rejected. cckit lints every title up front (≤ 6 words, no jargon) and aborts the whole operation before creating a half-effort. Shorten the failing sub name and re-run — the detail belongs in the body, not the title.

Two sub-issues keep colliding. They touch the same files, so they belong in different waves. Add a blocked-by link between them; cckit will schedule the dependent one in a later wave.

Flags were treated as sub-issues. Pass --flow, --role, and --priority before the effort name, not after the sub list — the parser reads flags first, then everything else as sub-specs.

Related tutorials

Take a GitHub issue to a merged PR The single-issue lifecycle an effort is built from.

Run issues in parallel with a wave Fan a wave of sub-issues out into parallel work.

Run Claude Code unattended Drive the effort's waves overnight.