Project & Planning Prompts

Use these before code exists or before a large change is allowed to touch the tree. Prefer Claude Code plan mode for every entry on this page; implementation comes only after you accept the plan. Deeper technique: Architecture & Research Prompts, New Project, Large Tasks.

Project init

Bootstrap a new repo with agent-readable structure, not a framework dump.

Inputs: <product one-liner>, <stack choices>, <monorepo or single package>, <CI target>

Initialize a new project for: <product one-liner>.

Stack (do not substitute): <stack choices>
Layout: <monorepo or single package>

Create only:
1. Minimal runnable skeleton (hello path that builds and starts).
2. CLAUDE.md with: project purpose, stack, commands (build/test/lint),
   directory map, non-negotiable conventions (list unknowns as TODOs).
3. README with setup + the same commands.
4. .gitignore appropriate to the stack.
5. Placeholder CI config targeting <CI target> that runs lint + test.

Rules:
- Do NOT add auth, ORM, UI kit, or "best practice" folders we didn't ask for.
- Do NOT invent product features beyond the hello path.
- List every assumption you made at the end.

Stop after the skeleton is runnable. Do not implement product logic.

Expected output: runnable skeleton, CLAUDE.md, README, CI stub, assumption list — no feature code.

Evaluate: Does CLAUDE.md name real commands that work? Are there zero speculative packages? Can a second session start from README alone?

Variations:

• Add AGENTS.md as a thin pointer to CLAUDE.md for multi-tool teams (CLAUDE.md & AGENTS.md).
• For greenfield SaaS, follow with MVP Build after init.

Product clarification

Turn a vague product idea into decisions a builder can execute without inventing scope.

Inputs: <raw idea>, <target user>, <must-ship-by constraint>, <known non-goals>

Clarify this product idea before any design or code.

Idea: <raw idea>
Primary user: <target user>
Hard constraint: <must-ship-by constraint>
Known non-goals: <known non-goals>

Ask me clarifying questions in batches of at most 5, highest-risk
ambiguity first. Do not propose architecture yet.

After I answer, produce:
1. Problem statement (3–5 sentences).
2. In-scope v1 behaviors (bullets, testable).
3. Explicit out-of-scope (bullets).
4. Open questions still unresolved.
5. Suggested next artifact: spec vs spike vs research note — pick one
   and justify in one line.

Do not write code. Do not invent requirements I didn't confirm.

Expected output: question batches, then a structured clarification doc with open questions called out.

Evaluate: Every v1 behavior is testable. Out-of-scope is longer than you expected. No silent feature invention.

Variations:

• Point at an existing competitor and ask for differentiation-only scope.
• Feed the output into Idea to Spec.

Architecture planning

Produce an architecture plan humans can reject before agents implement it.

Inputs: <spec path or paste>, <existing system constraints>, <scale assumptions>, <forbidden approaches>

Plan architecture for the following — plan mode only, no code.

Spec / requirements:
<spec path or paste>

Constraints from the existing system:
<existing system constraints>

Scale assumptions:
<scale assumptions>

Forbidden approaches:
<forbidden approaches>

Deliver:
1. Context diagram (components + trust boundaries) in mermaid.
2. Recommended approach with 3–5 key decisions and why.
3. Two rejected alternatives and the failure mode of each.
4. Data ownership: which component owns which writes.
5. Risks ranked by blast radius, with mitigation that is a process
   or test — not "be careful".
6. Implementation sequence (ordered slices a walking skeleton can follow).

Do not pick libraries unless the choice is load-bearing. Flag every
decision that should become an ADR.

Expected output: plan with diagram, decisions, rejected options, risks, ordered slices — no implementation.

Evaluate: Could you hand this to another engineer and get the same system? Are ADRs flagged where they should be (Decision Records)?

Variations:

• Constrain to "extend existing service X; no new deployable."
• Require explicit list of what must stay human-owned (What Not to Delegate).

Research before build

Force evidence gathering before the agent commits to an approach.

Inputs: <decision to research>, <codebase areas to inspect>, <external docs URLs if any>, <time box>

Research before we build. Do not write product code.

Decision under research: <decision to research>
Inspect first: <codebase areas to inspect>
External references (if useful): <external docs URLs if any>
Time box: <time box>

Process:
1. Inventory what already exists in-repo that touches this decision.
2. Summarize current behavior with file:line citations.
3. List candidate approaches (max 3) with fit to THIS codebase.
4. For each: cost to adopt, migration risk, test strategy.
5. Recommend one — or recommend a spike — with the evidence that
   changed your mind.

Output a research note only. If evidence is insufficient, say what
spike would resolve it (scope ≤ 1 day).

Expected output: research note with citations, ≤3 options, recommendation or spike proposal.

Evaluate: Citations resolve to real files. Recommendation is falsifiable. No "industry best practice" without repo evidence.

Variations:

• Restrict to read-only tools / no network if the answer must come from the repo alone.
• Use before any migration (Migration).

Ask questions first

Block implementation until high-risk unknowns are answered.

Inputs: <task summary>, <files likely involved>, <risk areas>

Task: <task summary>
Likely files: <files likely involved>
Risk areas I care about: <risk areas>

Before changing any code:
1. Read the listed files and their direct callers.
2. Ask me clarifying questions — max 7, ordered by blast radius.
3. For each question, state the default you would assume if I don't
   answer, and the failure mode of that default.

Do not implement. Do not "start with a draft." Wait for my answers.

Expected output: prioritized questions with stated defaults and failure modes.

Evaluate: Defaults are explicit (not "I'll figure it out"). At least one question would have changed the design if answered differently.

Variations:

• Cap to 3 questions for small tasks.
• Require questions only about data integrity / auth / money paths.

Plan before coding

Standard Claude Code plan-mode gate for a scoped change.

Inputs: <task>, <spec or acceptance criteria>, <pattern files>, <out of scope>

Plan only — do not edit files yet.

Task: <task>
Acceptance / spec: <spec or acceptance criteria>
Follow patterns in: <pattern files>
Out of scope: <out of scope>

Produce a plan with:
1. Files to read first (ordered).
2. Files to create/modify (ordered) with one-line intent each.
3. Behavior changes vs refactors (separate lists).
4. Tests to add or update, mapped to acceptance criteria.
5. Risks / unknowns that should stop the plan if unresolved.
6. Rollback story if the change ships broken.

After I approve the plan, implement exactly that plan — no drive-by
refactors, no extra files.

Expected output: ordered plan tied to acceptance criteria; implementation only after approval.

Evaluate: File list is minimal. Every acceptance criterion maps to a test. Unknowns are blockers, not footnotes.

Variations:

• Add "diff budget: ≤ N files / ≤ M LOC."
• Require a dry-run of commands (test, lint) in the plan.

Large task decomposition

Break a multi-day effort into agent-sized slices with frozen interfaces.

Inputs: <epic description or spec path>, <deadline or capacity>, <team constraints>

Decompose this into agent-sized implementation slices.

Epic: <epic description or spec path>
Capacity: <deadline or capacity>
Constraints: <team constraints>

Rules for slices:
- Each slice is completable in one focused session (≤ ~half day).
- Each slice has: goal, inputs, outputs, acceptance, out-of-scope,
  and the interface contracts it must not break.
- Prefer vertical slices that leave the system shippable.
- Call out which slices can run in parallel (disjoint files) vs must
  be serial.
- Identify the walking-skeleton slice that must go first.

Output a numbered slice list + dependency graph (mermaid).
Do not implement.

Expected output: ordered/parallelizable slices with contracts and a dependency graph.

Evaluate: First slice is a walking skeleton. Parallel slices don't share write ownership. No slice is "do the whole feature."

Variations:

• Map slices to PR-sized units for Reviewing AI PRs.
• Tag each slice with human review mandatory vs agent-ok.

Sprint / task breakdown

Turn a milestone into tickets an agent (or human) can pick without re-deriving scope.

Inputs: <milestone goal>, <repo areas>, <definition of done>, <estimate unit>

Break this milestone into concrete tasks for our board.

Milestone: <milestone goal>
Repo areas involved: <repo areas>
Definition of done: <definition of done>
Estimate unit: <estimate unit>

For each task provide:
- Title (verb + object)
- Description (what / why)
- Acceptance criteria (testable bullets)
- Dependencies (task IDs)
- Suggested agent mode: plan-only | implement | review | research
- Estimate in <estimate unit>
- Risk tag: data | auth | perf | none

Do not invent product scope beyond the milestone. Flag gaps that
need a product decision before engineering starts.

Expected output: task list with DoD, deps, agent mode, estimates, risk tags.

Evaluate: Every task has testable acceptance. Gaps are product decisions, not "TBD engineering." Estimates aren't all identical.

Variations:

• Output as markdown table for Linear/Jira paste.
• Split "spike" tasks from "build" tasks explicitly.

Context reset

Restart a polluted session with a compact, durable brief.

Inputs: <goal remaining>, <decisions already made>, <files that matter>, <what failed>

We are resetting context. Ignore prior chat except what I paste here.

Remaining goal: <goal remaining>
Decisions already locked:
<decisions already made>
Authoritative files:
<files that matter>
What already failed / do not retry:
<what failed>

Confirm you understand by restating:
1. Goal
2. Locked decisions
3. First three actions you will take
4. What you will NOT do

Then wait for my "go" before editing.

Expected output: restatement + proposed next actions; no edits until go.

Evaluate: Restatement matches your locks. Failed approaches are not proposed again. Scope didn't expand.

Variations:

• Point at a handoff note file instead of pasting.
• Use after compaction thrash (Recovery).

Agent handoff

Generate a handoff another session or teammate can execute cold.

Inputs: <current goal>, <branch>, <done so far>, <next slice>, <known landmines>

Write a handoff note for the next agent/session. No code changes.

Current goal: <current goal>
Branch: <branch>
Done so far:
<done so far>
Next slice to implement:
<next slice>
Known landmines:
<known landmines>

Handoff must include:
1. One-paragraph situation.
2. Exact commands to verify current state (test/lint/run).
3. Files that are source of truth (paths).
4. Locked decisions (bullets).
5. Next concrete steps (ordered, ≤ 7).
6. Explicit "do not" list.
7. Open questions for the human.

Write it as markdown suitable to commit under docs/handoffs/ or paste
into the next session opener.

Expected output: self-contained handoff markdown with verify commands and do-not list.

Evaluate: A stranger could continue without reading the chat. Verify commands are real. Locked decisions aren't reopened.

Variations:

• Emit both human-facing and agent-facing sections.
• Pair with Agent Management — Handoff note.

Related

• New Project — full init playbook
• Idea to Spec — escalate clarification into a committed spec
• Large Tasks — decomposition at playbook depth
• Architecture & Research Prompts — why these patterns work
• Recovery — when planning sessions go sideways
• Prompts vs Specs — lifespan of what you just wrote