Claude Code Power User Guide
Battle-tested prompts, CLAUDE.md rules, and workflow tricks from 338 sessions
This is the post I wish I'd read before my first session. No theory, no hype — just the specific things that make Claude Code dramatically more effective.
The Prompts That Work
Front-load vault conventions to eliminate correction loops
Across 15+ vault-related sessions, I frequently had to correct Claude about placing action items in project files vs meeting notes, routing decisions correctly, and checking for existing person notes before creating duplicates. Adding a vault conventions section to CLAUDE.md with explicit routing rules would eliminate these correction cycles entirely. My vault has clear structure — Claude just needs to be told once.
Read my vault's CLAUDE.md and the folder structure. Before creating any new file, always check if a matching file already exists. Action items go in project files, not meeting notes. Decisions go in project files. Meeting notes should only contain summary, attendees, and discussion points.
Break long sessions into focused tasks
Sessions where I drove 5+ different tasks (vault updates + deployments + research) had more partially-achieved outcomes than focused sessions. My most successful pattern is the focused flow: implement → review → PR → deploy. When I chain many unrelated tasks, Claude loses context and makes more mistakes. Consider starting fresh sessions for unrelated work streams.
Let's focus on one thing: I need to [specific task]. Don't plan ahead for other work — just complete this task, verify it works, and we'll move on.
Verify data assumptions before implementing features
The Wrapped feature built around a non-existent JSON file, the Google Ads overclaimed campaign status, and Azure quota issues all stem from Claude assuming rather than checking. For features that depend on external data or APIs, ask Claude to first verify the actual data format or system state before writing code. This one habit would have prevented at least 5 major reverts.
Before implementing anything, first check: what does the actual data/API response look like? Read the relevant files, run a test command, or show me what we're working with. Don't assume the format — verify it.
Front-load context to avoid wrong_approach (51 incidents)
My #1 friction type is 'wrong_approach' at 51 occurrences — more than buggy_code. This often happens when Claude doesn't understand my project structure and makes incorrect assumptions about where code lives or how components interact. A 2-3 line context dump at the start of each session dramatically reduces this. My CLAUDE.md should contain my project's key architectural decisions so Claude never has to guess.
Before starting, read CLAUDE.md and the project structure. This is a Next.js app with App Router. The dashboard is at /app/dashboard, API routes are in /app/api, and Supabase is our database. Now implement [task].
Demand working code, not plans
At least 4 sessions failed (not_achieved) because Claude spent the entire time reading files and writing plans without producing code. I've already been interrupting these — but I can prevent it entirely by being explicit upfront. The pattern is especially bad on creative/greenfield tasks (Remotion videos, blog sites) where Claude defaults to over-analysis. My 'excessive_planning' friction confirms this is a recurring issue.
Implement this now — no planning phase. Start writing code in the first file within 60 seconds. If you need to understand the codebase, read files as you go, don't batch all reading upfront.
Add 'no planning mode' guardrails for implementation tasks
At least 5 sessions were rated 'not_achieved' or 'slightly_helpful' because Claude spent 8+ minutes reading files and writing plans without producing code. This is my most consistent frustration pattern. When I already know what I want, be direct about skipping the exploration phase. My best sessions are the ones where Claude starts coding immediately — like the Calendly connector (12 files, 1,352 lines in one session).
Skip planning. I already know what I want. Start implementing immediately: [describe feature]. If you hit a blocker, ask me — don't spend time exploring the codebase.
Front-load deployment verification
Multiple sessions had post-push friction: Vercel env vars with trailing newlines causing 500 errors, migrations failing silently, build failures from server/client component mismatches. I deploy frequently (21 deployment sessions), so adding a pre-deployment checklist prompt would save significant debugging time. The Stripe Connect session and MCP endpoint 500 error are prime examples of issues caught too late.
Before we push this PR, run through a deployment checklist: 1) Verify the build passes locally, 2) Check if any new env vars are needed, 3) Verify any Supabase migrations will apply cleanly, 4) Confirm no server/client component boundary violations.
Features You're Probably Not Using
Custom Skills
Reusable prompts for repetitive workflows triggered by a single /command.
I have highly repetitive workflows: processing meeting transcripts into vault notes, creating PRs with code review, and deploying. I already built a weekly report skill — extend this pattern to my other common flows like /meeting, /pr, and /deploy to avoid re-explaining conventions each session.
mkdir -p .claude/skills/meeting && cat > .claude/skills/meeting/SKILL.md << 'EOF'
# Process Meeting Transcript
1. Read the provided transcript
2. Check existing project files in vault for related projects
3. Create meeting note in Meetings/ with attendees, summary, and references
4. Route action items to their respective PROJECT files (never leave in meeting note)
5. Route decisions to their respective PROJECT files
6. Update People/ notes with any new context about attendees
7. Update the project hub if any new projects are mentioned
EOF
Hooks
Auto-run shell commands at lifecycle events like pre-commit or post-edit.
With 56 buggy code friction events and TypeScript as my primary language, auto-running tsc --noEmit or npm run build after edits would catch type errors and build failures before I have to point them out. This eliminates the back-and-forth debugging cycles that eat my time.
// Add to .claude/settings.json
{
"hooks": {
"postToolUse": [
{
"matcher": "Edit|Write",
"command": "npx tsc --noEmit --pretty 2>&1 | head -20",
"timeout": 15000
}
]
}
}
Headless Mode
Run Claude non-interactively for automated tasks from scripts or CI.
I have 25 deployment sessions and 11 create-PR sessions — these follow predictable patterns. Headless mode lets I script my deploy and PR workflows so I can kick them off with a single command instead of interactive back-and-forth.
# Quick PR creation script - save as scripts/create-pr.sh
#!/bin/bash
claude -p "Run the test suite, fix any failures, then create a PR to main with a descriptive title and body summarizing all changes since the last PR" --allowedTools "Bash,Read,Edit,Write,Grep"
Task Agents
Claude spawns focused sub-agents for parallel exploration or complex work.
My architecture audit session already used 8 parallel sub-agents successfully. With 42 bug-fix sessions and complex multi-file changes (98 success events), I could use task agents more deliberately — e.g., 'use an agent to investigate the root cause while I describe the symptoms' or for parallel exploration of large codebases before implementation.
Try prompting: "Use a task agent to explore all the MCP tool handlers and list any that don't properly await async database operations, while you start fixing the ones I already know about in the simulator service."
CLAUDE.md: The Most Underrated Feature
Your CLAUDE.md file is loaded at the start of every session. It's the single highest-leverage thing you can configure. Here are the rules I'd add based on 338 sessions of friction data:
Add this rule: When asked to implement a feature, START CODING IMMEDIATELY. Do not spend more than 2 minutes reading files and planning before producing actual code. If you need to explore, do it incrementally while building.
Why it matters: Multiple sessions (5+) were derailed by Claude spending entire sessions in planning/exploration loops without producing any code, leading to user interruption and 'not_achieved' outcomes.
Add this rule: This is a Next.js + TypeScript + Supabase project deployed on Vercel. Always ensure files with JSX use .tsx extension. Always run npx tsc --noEmit before committing to catch type errors. Do not use cookies().delete() in Server Components — use Server Actions or Route Handlers for cookie mutations.
Why it matters: Recurring friction across sessions: .ts vs .tsx rename issues, type errors surfacing after implementation, and a production error from cookie deletion in a Server Component — all preventable with upfront guardrails.
Add this rule: When deploying to Vercel or setting env vars via CLI, always confirm the correct Vercel project is linked first with vercel link. Trim all environment variable values with .trim() to prevent trailing newline issues.
Why it matters: Multiple sessions hit friction from Vercel CLI linking to the wrong project and from trailing newlines in env vars causing 500 errors in production.
Add this rule: When working with Supabase migrations, always verify migrations actually executed (not ghost-applied) by checking the actual database state after running them. If Supabase CLI isn't authenticated for cloud push, tell the user immediately rather than proceeding with local-only changes.
Why it matters: A critical bug fix appeared complete but the migration was ghost-applied (recorded but never executed), requiring a repair migration. Supabase auth issues blocked deploys in multiple sessions.
Add this rule: For git push operations: try SSH first, then HTTPS with gh auth setup-git as fallback. Always push to the correct branch (main vs feature branch). Never push to a feature branch that has already been merged.
Why it matters: Multiple sessions had git push friction — SSH/HTTPS failures, and one session accidentally pushed to an already-merged feature branch instead of main.
Add this rule: When using sub-agents/Task tool for parallel work, limit to 4-5 concurrent agents max. Summarize sub-agent results concisely rather than feeding full outputs back into the main context.
Why it matters: A session dispatching 11+ parallel sub-agents overwhelmed the context window, causing every response to be truncated with 'Prompt is too long' errors.
Add this rule: Never screenshot localhost URLs — always use the production/deployed URL. Never include hardcoded API keys or secrets in committed code. Always check for sensitive data before committing.
Why it matters: Sessions hit friction from attempting to screenshot localhost (redirected to login) and from a hardcoded API key nearly being committed in a 62-file commit.
Add this rule: When asked to implement something, START CODING IMMEDIATELY. Do not spend more than 2 minutes reading files and planning before producing actual code. If you need to explore, do it incrementally alongside implementation, not as a separate phase.
Why it matters: Multiple sessions (Remotion video, dev blog, demo page) failed because Claude spent 8+ minutes in planning/exploration loops without producing any output before the user interrupted.
Add this rule: Always run npm run build (or equivalent) and verify no TypeScript/build errors before reporting a task as complete. Never say 'all set up' or 'done' without verifying the build passes.
Why it matters: Repeated friction from buggy code shipping (55 instances) — build failures from server/client component mismatches, type errors, missing env vars, and unawaited async calls that required user-reported bug fixes.
Add this rule: When creating meeting notes or organizing information across multiple project files, ask upfront which projects each item belongs to rather than guessing and requiring manual corrections.
Why it matters: Claude repeatedly misplaced action items and decisions into wrong project files, requiring multiple correction rounds from the user.
Add this rule: After completing git operations (push, cherry-pick, merge), always confirm the push actually went through by running git log --oneline -3 on the target branch. Don't assume a cherry-pick was pushed just because it was applied locally.
Why it matters: User had to ask twice about pushing to main because Claude didn't push the cherry-pick, and there were multiple git workflow gaps across 32 git_operations sessions.
Add this rule: This is a TypeScript/Next.js project. Key rules:
- Never import client-only functions in Server Components
- Always use
awaiton async database operations (especially in serverless/Vercel) - Use
.tsxextension for files containing JSX - Check that
useSearchParams()is wrapped in Suspense for Next.js prerendering
Why it matters: These exact TypeScript/Next.js bugs recurred across multiple sessions — server component imports, unawaited Supabase inserts causing data loss on Vercel, .ts/.tsx extension issues, and useSearchParams prerender failures.
Add this rule: Never overclaim completion status. If only 1 of 3 items is done, say '1 of 3 completed' — not 'all set up'. Be precise about what is actually working vs. what still needs attention.
Why it matters: Claude overclaimed campaign status in Google Ads session and gave conflicting answers on Stripe Connect setup, eroding user trust and requiring corrections.
Add this rule: When I ask a simple question or request a quick edit, do NOT escalate into full architecture planning, file creation, or plan mode. Ask first if I want a deeper exploration.
Why it matters: Multiple sessions show Claude over-expanding simple questions into full architecture plans or multi-file workflows, leading to user interruptions and frustration.
Add this rule: For Obsidian vault updates: action items and decisions belong in their respective PROJECT files, not in meeting notes. Meeting notes should reference projects but not duplicate structured data.
Why it matters: Across multiple vault sessions, Claude repeatedly placed action items and decisions in meeting notes instead of project files, requiring manual correction each time.
Add this rule: When creating meeting notes or processing transcripts, always cross-reference existing project files and people notes before writing. Route information to the correct existing file rather than creating duplicates or misplacing content.
Why it matters: Multiple sessions required the user to correct Claude for misplacing content, creating duplicate person notes, or failing to check existing vault structure before writing.
Add this rule: Prefer action over planning. When I give you a task, start implementing immediately unless it's genuinely ambiguous. Don't enter plan mode or lengthy exploration for straightforward requests.
Why it matters: Several sessions show the user interrupting Claude's planning/exploration loops — the user clearly prefers fast execution over structured multi-step planning for known tasks.
Add this rule: This project primarily uses TypeScript. Always write TypeScript (not JavaScript) for new files. Follow existing type patterns in the codebase.
Why it matters: TypeScript dominates the codebase at 4139 file touches vs 110 JavaScript — codifying this prevents Claude from defaulting to JS in new files.
Add this rule: After implementing changes, always build/compile to verify before committing. Don't claim something is working without confirming it builds and type-checks cleanly.
Why it matters: Buggy code was the #1 friction point (56 occurrences) alongside wrong approach (54), often because Claude didn't verify builds before declaring completion.
Add this rule: When I say 'push' or 'create PR', actually push the commits to the remote. Don't stop at local commits — complete the full git operation I requested.
Why it matters: Git operations are the second most common goal (32 sessions), and friction occurred when Claude didn't follow through on pushes (e.g., cherry-pick not pushed, user asking twice).
The One-Minute Setup That Prevents Most Problems
If you only do one thing from this post, do this: add a pre-commit hook that runs your type checker. Most of the bugs Claude ships are type errors that would be caught instantly.
// .claude/settings.json
{
"hooks": {
"preCommit": {
"command": "npx tsc --noEmit && npm run build"
}
}
}
This single change would have prevented the majority of my 53 buggy code incidents.