cc Prompt Design Patterns

# Claude Code Prompt Design Patterns

Patterns for designing the prompts that drive Claude Code work — initial prompts that kick off a session, session prompts that govern multi-turn work, autonomous prompts that run with less supervision, and subagent delegation prompts that hand work to specialist agents.

This reference is for DESIGN mode when the deliverable includes a CC prompt of any kind, and for EVOLVE mode when the friction is "the prompt isn't producing what we want." For environment design (CLAUDE.md, hooks, settings), see `cc-environment-design-patterns.md`. For Skills authoring, see `cc-skills-and-hooks-composition.md`.

---

## Table of contents

1. The four prompt classes — when each applies
2. Universal prompt principles (apply to all classes)
3. The Explore → Plan → Implement → Verify workflow
4. Initial prompt patterns
5. Session prompt patterns
6. Autonomous prompt patterns
7. Subagent delegation prompt patterns
8. Files-as-context: the spec-file pattern
9. The verification iron law
10. Output discipline for CC prompts

---

## 1. The four prompt classes — when each applies

| Class | Purpose | Typical length | Where it lives |
|---|---|---|---|
| **Initial prompt** | Kicks off a fresh session against a defined work scope | 50-300 words | Pasted into a fresh `claude` invocation; or stored at `prompts/{task-name}.md` and read in |
| **Session prompt** | Continues or refines work within an active session; includes context the session needs | 20-200 words | Typed in the active session |
| **Autonomous prompt** | Drives long-running, less-supervised work (overnight runs, multi-stage builds) | 100-500 words | Stored at `prompts/{run-name}.md`; invoked via headless mode or from an orchestrator |
| **Subagent delegation prompt** | Routes a specific subtask to a specialist agent | 30-150 words | Constructed by the parent session when it spawns a subagent |

The deployment plan in DESIGN mode should specify which prompt classes are needed and where they live. Most projects need at least an initial prompt template; many also need session and subagent prompt templates.

---

## 2. Universal prompt principles (apply to all classes)

These five principles appear across every authoritative source on CC prompt design (Anthropic primary docs, rosmur/claudecode-best-practices, obra/superpowers, alexop.dev, Shrivu Shankar). They apply to every prompt class.

**P1. Specific and actionable beats vague and aspirational.** "Run `npm test` before declaring done" beats "test your changes." "Use 2-space indentation" beats "format code properly." Vague prompts consume context tokens without changing behavior. **[Anthropic docs + practitioner consensus]**

**P2. Imperative form.** Direct instructions, not suggestions. "Edit X. Run Y. Verify Z." beats "You might want to consider editing X." The prompt is a directive, not a discussion. **[Anthropic docs]**

**P3. Critical instructions at the top.** Put the most important rules and behaviors first. Use `## Important` or `## Critical` headers. CC processes prompts top-to-bottom; buried critical instructions get less weight. **[Anthropic docs + Shrivu Shankar]**

**P4. Files-as-context, not transcript-dumps.** Reference files the agent should read (`@PLAN.md`, `@spec/api.md`) rather than pasting their content into the prompt. CC's tool calls fetch file contents on demand; pasting them duplicates context. **[12 convergence patterns; named anti-pattern across all 3 external research reports]**

**P5. Verification gates baked into the prompt.** Every prompt that produces output specifies how the output will be verified. "Edit X. Run `pytest tests/` and verify all tests pass before declaring done." Without verification gates, CC drifts toward implementation-first behavior and the "trust-then-verify gap" emerges. **[obra/superpowers verification-before-completion iron law]**

---

## 3. The Explore → Plan → Implement → Verify workflow

The canonical CC workflow named identically across Anthropic primary docs and every major practitioner source. Four phases:

**Phase 1 — Explore.** The agent surveys the codebase or context relevant to the task. In CC, this typically uses the Explore subagent (Haiku, read-only, cheap). The output is a context-grounded understanding, not a plan.

**Phase 2 — Plan.** The agent produces a written plan — what files will change, what's the approach, what's the verification strategy. CC supports a "plan mode" (Shift+Tab) that disables edit tools while planning. In plan mode, the user can edit the plan (Ctrl+G) before approving. The plan is an artifact (PLAN.md, SPEC.md), not a paragraph in chat.

**Phase 3 — Implement.** The agent executes the plan. The implementation should match the plan; deviation should surface as a plan revision, not a silent change.

**Phase 4 — Verify.** The agent runs the verification gates specified in the plan. Tests, lints, smoke checks, manual review hooks. The agent does not declare "done" until verification passes.

**The anti-pattern this prevents:** "vibe coding" — agent reads a vague request, jumps into edits, produces something that compiles but solves the wrong problem or breaks adjacent functionality. Plan-before-code is the single highest-leverage discipline in CC work. **[Anthropic primary docs + obra/superpowers + rosmur + coleam00 + shinpr — full convergence]**

**When to skip the plan:** Anthropic's own framing — "if you could describe the diff in one sentence, skip the plan." Trivial typo fixes, single-line config changes, or one-file refactors that have a clear shape don't warrant planning overhead. **[Anthropic docs — explicitly named exception]**

**Initial prompt template (workflow-aware):**