Your exploration session is the worst one to implement the solution.
You've spent an hour exploring a codebase with Claude. You ask it to implement the fix—and it repeats mistakes, forgets what you discussed, or gets confused. LLMs anchor to their own outputs, repeat errors, and degrade at 20% context fill.
The fix: explore in one session, execute in a fresh one.
-- DISCOVER --
You: "Explore src/api/client.ts. What retry patterns exist?"
Claude: [reads files, finds no retry logic, suggests axios-retry]
You: "Plan the implementation. Ask questions, don't assume. Walk me through it."
Claude: [asks about error handling, walks through approach step by step]
-- DISTILL --
You: "/handoff-prompt-to add retry logic using axios-retry"
Claude: → writes .ai-reference/prompts/add-retry.md
-- REFLECT (same window) --
You: "/reflect"
Claude: → [reviews prompts, updates with any fixes needed]
-- EXECUTE (new terminal) --
You: claude → paste entire .ai-reference/prompts/add-retry.md as first message
Claude: [reads spec, implements, spawns verification sub-agents, fixes issues, reports done]
-- LEARN --
You: [if agent made mistakes, add to CLAUDE.md: "Use date-fns, not moment"]
That's the whole workflow. Discover messy, execute clean. Prompt files are portable—paste into Claude Code, Cursor, or any agent.
| Phase | What | Commands |
|---|---|---|
| Bootstrap | Persistent project context loaded at session start | CLAUDE.md (auto-loaded) |
| Discover | Explore, plan, discuss; use sub-agents for parallel research | Natural language |
| Distill | Generate clean spec(s) for fresh execution | /handoff-prompt-to, /pair-prompt-to |
| Reflect | Verify prompts capture discussion + match codebase | /reflect |
| Execute | New terminal + claude runs the distilled prompt(s) |
(paste prompt) |
| Learn | Capture agent mistakes in CLAUDE.md for future sessions |
Manual |
What happens in the fresh window: Paste the entire prompt file as your first message. The agent treats it as a spec—no special formatting needed. It reads the task, implements, spawns verification sub-agents (tests, behavior, code quality), fixes issues, reports done. No hand-holding required.
# 1. Install the custom commands (download the 3 command files from this gist)
mkdir -p your-project/.claude/commands
# Copy handoff-prompt-to.md, pair-prompt-to.md, reflect.md to .claude/commands/
# 2. Try it
cd your-project && claude
> /handoff-prompt-to add error logging to auth.ts
→ .ai-reference/prompts/1736345678-add-error-logging.md
> /reflect
→ [reviews and updates prompt if needed]
# 3. Execute in fresh window
# Open new terminal, start claude, paste the ENTIRE prompt file as your first message:
> claude
> [paste entire contents of .ai-reference/prompts/1736345678-add-error-logging.md]
→ Agent treats it as a spec, implements, verifies, reports doneCustom commands from this gist: /handoff-prompt-to, /pair-prompt-to, /reflect
Built-in: /compact, /clear, /context, sub-agents
Workflow phase: Bootstrap — Auto-loaded at session start.
Persistent context that survives across sessions. Primary use: capture agent mistakes so they don't repeat.
~/.claude/CLAUDE.md # Global
./CLAUDE.md # Project root (highest priority)
# CLAUDE.md
## Commands
- `pnpm test` — run tests
- `pnpm build` — build project
## Gotchas (learned from agent mistakes)
- Use date-fns, NOT moment.js
- Auth tokens go in headers, not query params
- Run `go generate ./...` after interface changesKeep it short. Add mistakes as you discover them.
Reusable prompt templates stored as markdown files.
.claude/commands/ # Project-scoped (committed to repo)
~/.claude/commands/ # User-scoped (all projects)
| Phase | Command | Purpose | Source |
|---|---|---|---|
| Distill | /handoff-prompt-to |
Generate autonomous prompt(s) - auto-splits if large | view |
| Distill | /pair-prompt-to |
Generate collaborative pair programming prompt | view |
| Reflect | /reflect |
Verify prompts capture discussion + match codebase | view |
When to use each:
START: You have a task to implement
├─ Is it trivial? (single file, obvious change, low complexity)
│ └─ YES → Execute directly, or Plan mode (shift+tab twice → refine plan → auto-accept)
│
├─ Is it high-stakes or do you want step-by-step control?
│ └─ YES → /pair-prompt-to → /reflect → new window
│ └─ NO → /handoff-prompt-to → /reflect → new window
│
└─ Is your context full mid-task?
├─ Want to preserve exact decisions in a prompt file → /handoff-prompt-to continue
└─ Want to stay in this session, just need room → /compact (summarizes history)
Key rule: Always /reflect after distilling, before switching to a fresh window.
Generates complete spec(s) for a fresh Claude session. Auto-decomposes large tasks.
> /handoff-prompt-to add retry logic to API client
→ Single file: .ai-reference/prompts/1736345678-add-retry.md
> /handoff-prompt-to implement auth system with JWT, refresh tokens, OAuth
→ Task scope requires decomposition. Generating 4 prompt files.
→ .ai-reference/prompts/auth-system/00-index.md
→ .ai-reference/prompts/auth-system/01-jwt-service.md
→ .ai-reference/prompts/auth-system/02-refresh-tokens.md
→ .ai-reference/prompts/auth-system/03-oauth.md
Scope analysis: The command analyzes coupling to decide whether to split:
- Keep together: Code that shares files, types, or dependencies—shared context improves quality
- Split apart: Independent concerns that don't need shared context—each gets its own prompt with explicit interface definitions
Rule of thumb: Work stays together unless it touches 20+ files or spans clearly independent features.
Every prompt includes: verification sub-agents, interface definitions for decomposed tasks, definition of done checklist. See command source for full structure.
Parallel execution: For decomposed tasks, the index file shows which prompts can run in parallel. Open multiple terminal windows, start claude in each, and paste independent prompts simultaneously. Serialize only when prerequisites require it.
Generates a prompt for pair programming—the agent works with you, seeking approval at each step.
> /pair-prompt-to redesign the caching layer
→ .ai-reference/prompts/pairing-caching-redesign.md
Generated prompt enforces: explain before coding, wait for approval at each step, ask don't assume.
Validates prompts against your conversation and the codebase. Run in the same window after /handoff-prompt-to or /pair-prompt-to.
> /reflect
→ [Reviews and directly updates prompts with any fixes needed]
Checks: Did we capture all decisions? Are file paths accurate? Do decomposed tasks align? Are interfaces consistent across decomposed tasks?
Unlike outputting a verdict, /reflect directly updates the prompt files with any refinements needed—fixing stale paths, adding missing context, correcting interface definitions. Review the changes before executing.
# .claude/commands/fix-issue.md
---
description: Fix a GitHub issue by number
allowed-tools: Read, Write, Bash, Grep
---
Fix GitHub issue: $ARGUMENTS
1. Fetch issue details with `gh issue view $ARGUMENTS`
2. Search codebase for relevant files
3. Implement the fix
4. Write tests/fix-issue 1234
/project:fix-issue 1234 # Explicit namespaceSubdirectories create namespaces visible in /help:
.claude/commands/frontend/component.md → /component (project:frontend)
.claude/commands/backend/test.md → /test (project:backend)
Slash commands work best for deterministic, repeatable workflows. For exploratory tasks, use natural language.
Workflow phases: Discover (research) and Execute (verification) — The context firewall.
Sub-agents are isolated instances with their own context windows. Explicitly request parallel work—Claude won't distribute automatically:
"Use 4 parallel sub-agents to explore each directory"
"Have a sub-agent run the tests while I continue"
Each returns results to your main session. Define custom sub-agents or use built-ins (Explore, Plan, Task).
.claude/agents/ # Project-scoped
~/.claude/agents/ # User-scoped
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Code quality and security analysis
tools: Read, Grep, Glob, Bash
model: claude-sonnet-4-5-20250929
---
You are an expert code reviewer.
## Priority Order
1. Logic errors and bugs
2. Security vulnerabilities
3. Performance issues
4. Maintainability
## Output
- Severity-ranked summary
- file:line references
- Concrete fixes with code snippets# Automatic (Claude selects based on context)
"Review the auth module for security issues"
# Explicit
"Use the code-reviewer subagent to analyze src/auth/"- Explore — Fast codebase search
- Plan — Architecture planning
- Task — General-purpose execution (underlying mechanism for all sub-agents)
Sub-agents preserve your main context window. Each gets its own fresh context, preventing quality degradation on complex tasks.
Explore this codebase using 4 parallel tasks:
- Task 1: Analyze cmd/ for entrypoint patterns
- Task 2: Review internal/domain/ for business logic
- Task 3: Examine internal/infra/ for external integrations
- Task 4: Check test coverage patterns
Each task should return a summary only.
- Max ~10 concurrent agents
- Sub-agents cannot spawn sub-agents (no infinite nesting)
- Serialize write operations to avoid conflicts
- Claude defaults to sequential—explicitly request parallelization
Sub-agents preserve your main context by returning summaries and discarding intermediate work.
Between cycles — When distilling is overkill.
When to use /compact instead of distilling: You're mid-exploration, context is filling up, but you haven't reached a decision point worth capturing. You just need more room to keep exploring. Use /compact to summarize and continue in the same session. Use /handoff-prompt-to when you've made decisions worth preserving as artifacts.
Summarizes conversation history to reclaim context capacity.
/compact # Default
/compact Focus on auth implementation # Guided
/compact Preserve: DB schema, API contracts # Explicit retention| Command | Effect |
|---|---|
/compact |
Summarize and compress |
/clear |
Wipe completely |
/context |
Show current usage |
claude -c |
Continue most recent session |
claude -r |
Resume by session ID |
Triggers at ~95% utilization. Don't rely on it—manual compaction at logical breakpoints preserves more nuance.
/context # Check utilization
/compact Retain: feature scope, test strategy, blockers| Situation | Action |
|---|---|
| Mid-task, context getting full | /compact with explicit retention |
| Task complete, starting related work | /clear or new window |
| Long collaborative session, context full | /handoff-prompt-to or /pair-prompt-to continuation |
| Need to preserve exact decisions made | Distill to prompt file, then fresh window |
For complex tasks spanning multiple sessions: use distillation commands to capture decisions as artifacts, then execute in fresh windows. This preserves nuance better than /compact.
"Skeptically" power word. Adding "skeptically" to any validation request overrides Claude's default agreeable behavior. Without it, Claude tends to validate your assumptions rather than challenge them. The /reflect command includes this by design. Use it elsewhere: "Skeptically review this implementation for edge cases."
Explicit parallelism. Claude defaults to sequential execution. For parallel work, be explicit: "Use 4 parallel sub-agents" or "Launch these 3 tasks concurrently." Think goroutine orchestration—you're the scheduler.
Prompts are portable. Distilled prompts work with any coding agent (Cursor, Windsurf, Copilot). They can also be reviewed by another agent against the codebase to validate the approach before execution.
When to re-run /reflect:
- After code changes if reusing a saved prompt
- For prompts from another session or teammate
- Before parallel execution of decomposed tasks
Continuation prompts. When context fills mid-task: /handoff-prompt-to continue from Phase 3 (storage layer). The command captures prior decisions scoped to remaining work.
Force fresh perspective. For code review, spawn a sub-agent rather than reviewing in the same session. The reviewing agent won't have the author's blind spots.
Verification via sub-agents. Include in your prompts: "Spawn a sub-agent to run tests and fix failures before reporting done." Fresh context catches mistakes the implementing agent is blind to. Works for writing tests too.
Verification is the multiplier. Give Claude a way to prove its work—tests, browser checks, script execution—and quality jumps 2-3x. The handoff prompts bake this in with three verification sub-agents (tests, behavior, code quality). Don't skip it.
| Feature | Location | Trigger |
|---|---|---|
| CLAUDE.md | ./CLAUDE.md, ~/.claude/CLAUDE.md |
Auto-loaded |
| Slash Commands | .claude/commands/*.md |
/command |
| Sub-Agents | .claude/agents/*.md |
Explicit request required |
| Parallel Tasks | N/A | Natural language |
| Compact | Built-in | /compact |
| Context | Built-in | /context |
Advanced features (Browser Control, MCP, --dangerously-skip-permissions): See advanced-features.md
Workflow phase: Learn — The Execute phase feeds back into Bootstrap.
-
Capture lessons learned: Did you discover a new gotcha, edge case, or dependency? A command that always needs to run? A pattern that worked well?
-
Update
CLAUDE.mdimmediately: Don't trust your memory. The next session—whether yours or a teammate's—should inherit this knowledge automatically. -
Discard the session: Once lessons are persisted, the context has served its purpose. Use
/clearor close the window.
- Commands that weren't obvious (
TEST_DB_URLmust be set,go generateafter interface changes) - Gotchas that caused debugging time
- Patterns that the agent got wrong and needed correction
- Dependencies between components that aren't obvious from the code
Commit CLAUDE.md to your repo. The whole team contributes—anytime someone sees Claude make a mistake, they add it. This is "Compounding Engineering": every future session starts smarter than the last, for everyone.
For automated enforcement, see GitHub Action (@.claude) in advanced features.
SHAMELESS PLUG: I'm currently in between contracts and looking for new offers. If you are looking for an AI-native software developer who loves Agentic Coding, team-leading and education, and providing LLM-based solutions, please reach out through my LinkedIn
January 2026