Claude Code: Anthropic’s command-line AI coding tool that understands your entire codebase, can read/write files, run commands, and iterate autonomously on complex tasks.
Before writing prompts, set up your project for Claude to understand.
# Project: MyApp
## Overview
A SaaS application for [specific purpose].
## Tech Stack
- Next.js 14 with App Router
- TypeScript (strict mode)
- Supabase for auth and database
- Tailwind CSS
- Shadcn/ui components
## Key Patterns
- Server Components by default
- API routes for mutations
- Zod for validation
- Parameterized queries only
## Security Requirements
- All endpoints require authentication
- Verify resource ownership before data access
- Never log sensitive data
- Use environment variables for all secrets
## Code Style
- Prefer composition over inheritance
- Keep functions small and focused
- Use early returns
- Minimal comments (code should be self-documenting)
## Directory Structure
/app - Next.js app router pages
/components - React components
/lib - Utilities and helpers
/types - TypeScript types
Claude reads this file and uses it as context for all operations.
.env.example
Maintain this so Claude knows what environment variables exist:
Be specific about functionality, not implementation:
1
2
3
4
5
6
Add user subscription management:
- Users can view their current plan
- Users can upgrade/downgrade plans
- Stripe handles payments
- Show billing history
- Cancel subscription option
Let Claude Explore
Claude reads your codebase, understands existing patterns, and asks clarifying questions. Answer them:
1
2
3
4
5
Q: How do you currently handle authentication?
A: NextAuth with Supabase adapter. See lib/auth.ts
Q: Should cancellation be immediate or end-of-period?
A: End of billing period
Review the Plan
Claude produces a step-by-step plan. Review it:
Does it match your vision?
Are there security considerations?
Does it use existing patterns?
Ask for changes if needed.
Exit and Execute
When satisfied, exit plan mode. Claude executes with full context from the planning session.
Add a payment history page. Follow the same pattern
as the existing OrderHistory page in app/orders/page.tsx.
Use the same table component and pagination approach.
Strategy 3: Security-Explicit Prompts
Always mention security for sensitive features:
1
2
3
4
5
Add profile update endpoint. Requirements:
- Only authenticated users
- Users can only update their own profile
- Validate input with Zod
- Return updated profile without password hash
Strategy 4: Incremental Building
Break large features into steps:
1
2
3
4
Step 1: Create the database schema for subscriptions
Step 2: Add Stripe webhook handling
Step 3: Create the subscription API routes
Step 4: Build the subscription management UI
Execute each step, verify it works, then continue.
Effective Workflows
Workflow: New Feature
1
2
3
4
5
6
7
1. Enter plan mode
2. Describe the feature
3. Answer Claude's questions
4. Review and approve plan
5. Execute
6. Test the result
7. Fix issues with specific prompts
Workflow: Bug Fix
1
2
3
4
5
6
1. Describe the bug with reproduction steps
2. Point to relevant files if known
3. Let Claude investigate
4. Review proposed fix
5. Test fix
6. Ask for additional edge case handling if needed
Workflow: Refactoring
1
2
3
4
5
6
1. Enter plan mode
2. Describe what you want refactored and why
3. Review plan for unintended changes
4. Execute in stages if large
5. Run tests after each stage
6. Verify behavior unchanged
Workflow: Code Review
1
2
3
4
5
6
7
Review the changes in [feature branch] for:
- Security vulnerabilities
- Performance issues
- Code quality problems
- Missing edge cases
Provide specific feedback with file/line references.
Working with Complex Codebases
The Exploration Phase
For new or unfamiliar codebases:
1
2
3
4
5
6
Explore this codebase and explain:
- Overall architecture
- Key patterns used
- How authentication works
- Database access patterns
- Main entry points
Claude reads files and builds understanding.
Targeted Reading
When you know what you need:
1
2
3
4
5
6
7
Read and explain:
- lib/auth.ts
- middleware.ts
- app/api/users/route.ts
I need to understand how authentication flows work
before adding a new protected endpoint.
Cross-File Operations
For changes spanning multiple files:
1
2
3
4
5
6
7
Rename the User model to Account across the entire codebase.
This includes:
- Database schema
- API routes
- Components
- Types
- Tests
Claude handles multi-file refactoring atomically.
Debugging with Claude
Error Messages
Copy the full error and ask:
1
2
3
4
5
6
I'm getting this error when running the app:
[paste full error with stack trace]
The feature was working before I added the subscription
management. Help me debug this.
Behavior Issues
Describe expected vs. actual:
1
2
3
4
5
6
Issue: User can see other users' invoices
Expected: GET /api/invoices returns only current user's invoices
Actual: Returns all invoices in database
The endpoint is in app/api/invoices/route.ts
FAQ
How long should I spend in plan mode?
For small features, 5-10 minutes. For large features, 30-60 minutes. The time invested in planning saves debugging time later.
Should I clear context between tasks?
Usually no. Claude’s understanding builds over a session. Clear context only when switching to completely unrelated work.
How do I handle when Claude makes mistakes?
Be specific about what’s wrong. “The endpoint returns all invoices instead of just the user’s invoices. Fix the query in app/api/invoices/route.ts.”
Claude Code vs Cursor - when to use which?
Claude Code for complex operations, refactoring, multi-file changes, and architectural work. Cursor for rapid iteration, autocomplete, and small edits.
Conclusion
Key Takeaways
Set up CLAUDE.md with project context, patterns, and security requirements
Use plan mode for non-trivial features to build context
Provide context before asking—reference files and existing patterns
Always mention security explicitly for sensitive features
Build incrementally—execute, verify, continue
Copy full error messages for debugging
Clear context only when switching to unrelated work
