Claude Code Driver

Goal

What does the user actually want? Make it concrete and unambiguous. Strip filler, resolve pronouns, specify the deliverable.

Vague: "Add user updating" Concrete: "Add a PATCH /users/:id endpoint that updates email and display_name fields with input validation and proper error responses."

If the user's request is genuinely ambiguous (you can't tell what they mean even after careful reading), ask ONE clarifying question. Don't over-ask — if you can make a reasonable assumption, state it in the prompt as a default and tell Claude Code to flag if the assumption seems wrong based on the codebase.

Constraints

What must Claude Code respect or avoid? Think about:

• Existing patterns to follow ("match the style of existing route handlers")
• Things not to break ("don't modify the auth middleware")
• Compatibility requirements ("maintain backward compatibility with v1 API")
• Tech choices ("use the ORM already in the project, don't add raw SQL")

If the user doesn't specify constraints, use this default set:

- Follow patterns and conventions found in the existing codebase
- Don't refactor unrelated code
- Don't add new dependencies unless strictly necessary
- Maintain backward compatibility

Scope Boundary

Where should Claude Code focus, and where should it stop? This prevents scope creep — Claude Code is thorough and will sometimes want to "fix" things that aren't broken.

Good scope boundaries name directories, modules, or layers:

• "Only touch src/routes/, src/services/, and their corresponding test files"
• "Limit changes to the billing module and its direct dependencies"
• "Don't modify the database schema — work within the existing tables"

If the user doesn't specify scope, instruct Claude Code to determine scope from the codebase but stay conservative — change the minimum necessary.

Verification Instruction

How should Claude Code confirm the work is correct? This is the self-check step that catches mistakes before the user ever sees them.

Pick verification steps appropriate to the project:

• npm test / go test ./... / pytest — run existing tests
• npm run build / go build ./... — confirm it compiles
• npx tsc --noEmit — type-check without building
• npm run lint — style compliance
• Write new tests for the added functionality
• Run the specific test file related to the changed module

If you can't determine the project's test/build commands, instruct Claude Code to discover them from package.json scripts, Makefile, CI configs, etc.

Step 2: Choose the Invocation Mode

Mode A — One-Shot

Use for: small isolated changes, clear specifications, bug fixes with known cause, config changes, adding tests for existing code.

Signs it's a one-shot task:

• Touches 1-3 files
• User gave specific instructions
• Low risk of architectural misjudgment
• Clear verification path

Mode B — Plan-Checkpoint

Use for: new features, ambiguous requirements, changes that span multiple modules, refactors, anything where you'd want a human sanity-check before implementation.

Signs it needs plan-checkpoint:

• Touches 4+ files or multiple modules
• User's description is high-level ("add invoice generation")
• Architectural decisions are involved
• Getting it wrong would be expensive to undo

When in doubt, use plan-checkpoint. The cost of an extra round-trip is small compared to implementing the wrong thing.

Mode C — Follow-Up

Use for: incremental changes that build on a previous Claude Code session. Requires a session_id from a prior invocation.

Signs it's a follow-up:

• User is iterating on work Claude Code just did ("now add validation", "use bcrypt instead", "also handle the error case")
• A session_id exists from the prior invocation
• The prior session completed successfully (no timeout or error)

Do NOT use follow-up if:

• The request is unrelated to the prior session's work
• The prior session timed out or errored
• The user explicitly says "start over" or "from scratch"
• Quality has degraded after 5+ follow-up rounds — start a fresh session instead

Step 3: Construct and Send the Hand-Off Prompt

Read the appropriate template from the prompts/ directory:

• One-shot tasks: Read prompts/handoff-base.md
• Plan-checkpoint tasks: Read prompts/plan-checkpoint.md
• Bug fixes / hotfixes: Read prompts/hotfix.md
• Follow-up tasks: Read prompts/follow-up.md (requires existing session_id)

Fill in the template with the four components you extracted (or the streamlined follow-up components), then invoke Claude Code.

Invoking Claude Code

Use the scripts/invoke.sh script:

# Fresh session (one-shot, plan-checkpoint, hotfix)
bash <skill-path>/scripts/invoke.sh "<the-constructed-prompt>" [timeout_seconds]

# Resume an existing session (follow-up)
bash <skill-path>/scripts/invoke.sh "<the-constructed-prompt>" [timeout_seconds] <session_id>

Default timeout is 300 seconds (5 minutes). For larger tasks, increase to 600 or 900.

The script emits SESSION_ID=<uuid> to stderr on every successful invocation. Capture and store this value — you'll need it to resume the session for follow-up requests.

If you don't have access to the claude CLI, you can instead use a subagent (Task tool) with the constructed prompt. The subagent acts as Claude Code in this case — give it the full hand-off prompt and let it work autonomously. (Note: session continuity is not available in subagent mode.)

Step 4: Handle the Result

For One-Shot (Mode A)

When Claude Code returns:

1. Check for success signals: Did tests pass? Did it build? Any error output?
2. Summarize for the user:
   • What files were changed/created (just names, not full diffs)
   • What was implemented (1-2 sentences)
   • Test/build results
   • Any concerns Claude Code flagged
3. If it failed: Show the specific error. Don't retry blindly — ask the user for direction. Common failure patterns:
   • Missing dependency → ask user if it's OK to install
   • Test failure in unrelated code → likely a pre-existing issue, flag it
   • Ambiguous requirement → Claude Code will usually say what confused it

For Plan-Checkpoint (Mode B)

Phase 1 — Plan:

1. Send the plan-phase prompt. Claude Code will explore the codebase and write a plan to PLAN.md (or output it directly).
2. Read the plan output.
3. Summarize it for the user in plain language:
   • What Claude Code discovered about the codebase (relevant patterns, tech stack details)
   • The proposed approach (numbered steps)
   • Any assumptions or open questions Claude Code raised
4. Ask: "Does this look right? Want to change anything?"

Phase 2 — Implement:

1. Incorporate any user feedback as additional constraints.
2. Send the implementation prompt using the session_id from Phase 1 (resume the session so Claude Code retains its codebase knowledge from exploration).
3. Summarize the result as in Mode A.

Result Summary Template

Keep summaries concise and scannable:

**Changes made:**
- Created `src/routes/invoices.ts` — new endpoint for PDF generation
- Modified `src/services/billing.ts` — added `generateInvoicePDF()` method
- Added `tests/routes/invoices.test.ts` — 4 test cases

**Verification:** All tests pass. Build succeeds. Lint clean.

**Note from Claude Code:** The existing `file-stream` helper doesn't support PDF content-type headers. Added a small extension — worth reviewing if you have opinions on how streaming should work in this project.

Step 5: Session Continuity

invoke.sh emits SESSION_ID=<uuid> to stderr after each successful invocation. Store this value and use it to maintain conversational continuity across follow-up requests.

When to Continue an Existing Session

Continue (pass session_id to invoke.sh) when ALL of these are true:

• The user's new request builds on prior work ("now add...", "also...", "change the X you just made")
• A session_id exists from the prior invocation
• The prior session completed successfully (no timeout, no error exit code)

When to Start Fresh

Start a fresh session (omit session_id) when ANY of these are true:

• The request is unrelated to the prior session
• The prior session timed out or exited with an error
• The user explicitly says "start over", "from scratch", or "new task"
• You've done 5+ follow-up rounds in the same session — quality may degrade; start fresh to reset context

Constructing Follow-Up Prompts

Use prompts/follow-up.md. Follow-up prompts are intentionally minimal because Claude Code already has full context from the resumed session. Only specify:

• What to change/add/adjust
• New constraints (if any changed)
• Verification steps

Do NOT repeat the original goal, scope, or constraints — Claude Code remembers them.

Plan-Checkpoint Session Continuity

For plan-checkpoint tasks (Mode B), Phase 2 should resume Phase 1's session. This is valuable because Claude Code spent Phase 1 exploring the codebase and building a mental model — resuming preserves all of that context, making implementation faster and more accurate.

Flow:

1. Phase 1: invoke.sh "<plan prompt>" 300 → captures SESSION_ID=abc123
2. User reviews plan, provides feedback
3. Phase 2: invoke.sh "<implement prompt>" 600 abc123 → resumes the session

Edge Cases

User provides a file or diff: Include it verbatim in the hand-off prompt under a "Context" section. Claude Code can use it as reference.

User points to a GitHub issue or PR: Extract the relevant details (title, description, key comments) and include them in the Goal section. Don't send Claude Code a raw URL — it may not have web access.

User says "just do it" or "you figure it out": Default to plan-checkpoint mode with generous scope. Better to check in once than to build the wrong thing.

Multiple tasks in one request: Break them into separate hand-offs. Run them sequentially. Summarize each result individually.

Claude Code asks a question mid-run: This shouldn't happen with a well-constructed prompt, but if it does, relay the question to the user, get the answer, and re-invoke with the answer included in the prompt.

The project has no tests: Set verification to build/compile only, and instruct Claude Code to write tests for the new code. Mention to the user that you've asked Claude Code to add tests.

Session expired or invalid: If invoke.sh fails when resuming a session (invalid session_id), fall back to a fresh session. Include a summary of what was done previously in the prompt so Claude Code has context.

Long follow-up chains: After 5+ follow-up rounds in the same session, Claude Code's context window may be saturated and output quality can degrade. Start a fresh session and include a brief summary of the work done so far in the new prompt.