1# Project: My Awesome App
2 
3## Common Commands
4 
5- `npm run dev` - Start development server on port 3000
6- `npm test` - Run Jest tests
7- `npm run lint` - Run ESLint with auto-fix
8- `./scripts/deploy.sh` - Deploy to staging
9 
10## Architecture
11 
12- `/src/components` - React components (use TypeScript)
13- `/src/lib` - Utility functions and shared logic
14- `/src/app` - Next.js App Router pages
15- `/tests` - Jest unit tests
16 
17## Code Style
18 
19IMPORTANT: Always use TypeScript strict mode.
20IMPORTANT: Prefer functional components with hooks.
21YOU MUST: Add JSDoc comments to all exported functions.
22 
23## Testing
24 
25- Write tests BEFORE implementation (TDD)
26- Avoid mocks unless absolutely necessary
27- Test edge cases: empty arrays, null values, errors
28 
29## Repository Rules
30 
31- Branch naming: `feature/description` or `fix/description`
32- Commit messages: Use conventional commits (feat:, fix:, docs:)
33- PRs require 2 approvals before merge
34 
35## Environment Setup
36 
37- Node.js 18+
38- PostgreSQL 14+
39- Redis for caching
40 
41## Quirks & Warnings
42 
43- IMPORTANT: Auth tokens expire after 1 hour
44- Database migrations must be reversible
45- Never commit `.env` files

1# In your project directory
2claude
3 
4# Type this command
5/init
6 
7# Claude generates a CLAUDE.md based on your project structure

You: # Add the new deployment script to CLAUDE.md
 
Claude: [Automatically updates CLAUDE.md with deployment info]

IMPORTANT: Always validate user input
YOU MUST: Run tests before committing
NEVER: Use `any` type in TypeScript
CRITICAL: Check for null/undefined before accessing properties

Claude: I need permission to run bash commands.
You: [Check "Always allow" → Allow]

/permissions
# Interactive menu to configure allowed tools

1{
2  "allowedTools": ["read", "write", "edit", "bash", "grep"],
3  "autoApprove": {
4    "bash": ["npm install", "npm run dev", "git status"]
5  }
6}

1# In CLAUDE.md
2 
3## Custom Tools
4 
5- `./scripts/db-backup.sh` - Creates PostgreSQL backup
6  Usage: `./scripts/db-backup.sh [environment]`
7 
8- `analyze-bundle` - Custom npm script analyzing bundle size
9  Usage: `npm run analyze-bundle`
10 
11- `deployment-checker` - Checks if app is ready for deployment
12  Run: `deployment-checker --env production`

You: Use the deployment-checker tool and check if we're ready for production
 
Claude: [Runs `deployment-checker --help` first to understand usage, then executes with correct flags]

1# Fix GitHub Issue
2 
3Pull issue $ARGUMENTS from GitHub and:
41. Read the issue description and comments
52. Locate relevant code files
63. Propose a fix with explanation
74. Implement the fix with tests
85. Create a PR referencing the issue

1claude
2 
3> /fix-github-issue 1234
4 
5[Claude automatically pulls issue #1234 and fixes it]

1You: Read src/auth/login.ts and src/lib/jwt.ts to understand our current authentication flow.
2 
3Claude: [Reads files, summarizes architecture]
4 
5You: Now read the tests in tests/auth/ to see what's already tested.
6 
7Claude: [Reviews tests, identifies gaps]

1You: I need to add OAuth support. Think through how to implement this.
2 
3Claude: [Activates extended thinking mode]
4 
5Let me think through this carefully...
6 
7Plan:
81. Add OAuth provider configuration (Google, GitHub)
92. Create OAuth callback handler
103. Store OAuth tokens securely
114. Integrate with existing JWT system
125. Update user model to support OAuth identities
136. Write tests for OAuth flow
147. Update documentation
15 
16Potential issues:
17- Token refresh logic needed
18- Handle account linking (OAuth + existing email/password)
19- Security: validate OAuth state parameter
20 
21Shall I proceed with this plan?

1You: Looks good! Start with step 1 - add OAuth provider configuration.
2 
3Claude: [Implements configuration system]
4 
5You: Good. Now step 2 - the callback handler.
6 
7Claude: [Implements handler]

1You: This looks great! Create a commit with an appropriate message.
2 
3Claude: [Runs git add, creates commit with descriptive message based on changes]
4 
5You: Now create a PR for review.
6 
7Claude: [Creates PR with summary, test plan, screenshots if applicable]

1You: I need a function that parses markdown frontmatter. Here are input/output examples:
2 
3Input:
4---
5title: Hello
6---
7# Content
8 
9Output:
10{ title: "Hello", content: "# Content" }
11 
12Write comprehensive test cases. IMPORTANT: Use TDD - write real tests, not mocks.
13 
14Claude: [Creates test file with multiple test cases covering edge cases]

1You: Run the tests to confirm they fail (since we haven't implemented yet).
2 
3Claude: [Runs tests, shows failures]
4 
5All 8 tests failing as expected. Ready to implement.

You: Commit the tests.
 
Claude: [Commits with message "test: Add tests for markdown frontmatter parser"]

1You: Now implement the parser. Run tests after each change.
2 
3Claude: [Writes initial implementation, runs tests]
4 
55/8 passing. Let me fix the edge case for empty frontmatter...
6 
7[Updates code, runs tests again]
8 
97/8 passing. The Unicode handling needs work...
10 
11[Final update]
12 
13All 8 tests passing!

1You: Launch a review agent to check if the code is overfitting to the tests.
2 
3Claude: [Launches subagent to review implementation]
4 
5Subagent: Code looks good, properly handles general cases beyond test examples.

You: Perfect! Commit the implementation.
 
Claude: [Commits with message "feat: Implement markdown frontmatter parser"]

1You: Here's a design mock [paste screenshot of Figma design]
2 
3Implement this dashboard component.
4 
5Claude: [Creates initial implementation]
6 
7You: [Take screenshot of result, paste it]
8 
9Close but the spacing is off. The cards should have 24px gap, not 16px.
10 
11Claude: [Updates spacing, rebuilds]
12 
13You: [Paste updated screenshot]
14 
15Better! Now the colors don't match. The blue should be #3B82F6.
16 
17Claude: [Fixes colors]
18 
19You: [Paste final screenshot]
20 
21Perfect! That matches the design.
22 
23Claude: Shall I commit this?
24 
25You: Yes, commit it.

claude --dangerously-skip-permissions

1# In a container or sandboxed environment
2claude --dangerously-skip-permissions
3 
4> Fix all ESLint errors in the src/ directory
5 
6[Claude autonomously fixes 127 lint errors across 34 files]
7 
8> git diff
9 
10[Review changes]
11 
12> Looks good! Commit with message "fix: Resolve ESLint errors"

1You: How does our logging system work?
2 
3Claude: [Searches codebase]
4 
5Your logging system uses Winston with a custom transport:
6 
71. src/lib/logger.ts - Core logger configuration
82. src/lib/transports/cloudwatch.ts - AWS CloudWatch integration
93. Environment variable LOG_LEVEL controls verbosity
10 
11All API routes use logger.info() for requests and logger.error() for errors.
12 
13Would you like me to show you specific files?

1You: I need to add a new API endpoint for user preferences. Show me the pattern I should follow.
2 
3Claude: Based on your existing API routes:
4 
51. Create src/app/api/preferences/route.ts
62. Use NextAuth for authentication (see api/profile/route.ts example)
73. Validate input with Zod schemas (pattern in api/users/route.ts)
84. Return typed responses using ApiResponse<T> helper
9 
10Here's a template following your conventions:
11[Shows code]

1New developer: Where should I start to understand the authentication system?
2 
3Claude: Welcome! Here's the auth system overview:
4 
5Entry points:
61. src/app/api/auth/[...nextauth]/route.ts - NextAuth configuration
72. src/middleware.ts - Route protection
83. src/lib/auth.ts - Auth utility functions
9 
10The flow:
111. User hits /api/login
122. Credentials validated against PostgreSQL
133. JWT generated (see src/lib/jwt.ts)
144. Token stored in HTTP-only cookie
155. Middleware checks token on protected routes
16 
17I'd recommend reading these files in this order...

1You: When did we switch from Express to Next.js? Why?
2 
3Claude: [Searches git history]
4 
5The migration happened in commit a3f8d92 on March 15, 2024:
6 
7"feat: Migrate from Express to Next.js 14"
8 
9From the commit message and code review:
10- Wanted better React integration
11- Needed server components for performance
12- SEO improvements with SSR
13 
14PR #234 has the full discussion.

1You: Create a commit for these changes.
2 
3Claude: [Analyzes diff, understands context]
4 
5Based on your changes:
6- Added OAuth Google provider
7- Updated user model schema
8- Added integration tests
9 
10Suggested commit message:
11feat(auth): Add Google OAuth authentication
12 
13- Implement OAuth 2.0 flow with Google
14- Extend user model to support OAuth identities
15- Add integration tests for OAuth flow
16- Update documentation with OAuth setup guide
17 
18Breaking change: User model now requires `authProvider` field
19 
20Sound good?

1You: I have merge conflicts in src/api/users.ts after rebasing. Fix them.
2 
3Claude: [Reads both versions, understands intent]
4 
5The conflict is between:
6- Your changes: Added email validation
7- Main branch: Added rate limiting
8 
9I can merge both features. Here's the resolution:
10[Shows resolved code]
11 
12Both features preserved. Should I complete the rebase?

1You: Create a PR for this feature branch.
2 
3Claude: [Analyzes commits and changes]
4 
5Title: Add real-time notifications with WebSockets
6 
7Description:
8## Summary
9- Implements WebSocket server for real-time updates
10- Adds notification center UI component
11- Includes online presence indicators
12 
13## Changes
14- src/server/websocket.ts - WebSocket server
15- src/components/NotificationCenter.tsx - UI
16- src/hooks/useNotifications.ts - React hook
17- tests/ - Full test coverage
18 
19## Test Plan
20- [x] WebSocket connections handling
21- [x] Reconnection logic on disconnect
22- [x] Multiple tabs synchronization
23- [x] Notification persistence
24 
25## Screenshots
26[Includes relevant screenshots]
27 
28PR created: #456

1You: The CI build is failing. Fix it.
2 
3Claude: [Checks CI logs]
4 
5The issue is:
6- TypeScript errors in src/components/Dashboard.tsx
7- Missing type for `user` prop
8- ESLint error: unused import
9 
10Fixing now...
11[Makes corrections]
12 
13Tests passing locally. Pushing fix...
14 
15Build should pass now.

1You: Review my data analysis notebook and suggest improvements.
2 
3Claude: [Reads notebook, including code, outputs, and visualizations]
4 
5Your analysis looks good! Suggestions:
6 
71. Cell 3: The correlation matrix is hard to read
8   → Use seaborn heatmap with annotations
9 
102. Cell 7: The model seems to be overfitting
11   → Training accuracy 98%, validation 76%
12   → Suggest adding dropout or reducing complexity
13 
143. Cell 12: The chart is functional but plain
15   → Would you like me to make it more aesthetically pleasing?
16 
17Shall I implement these improvements?

1You: Create a visualization of this sales data. Make it aesthetically pleasing - this is for a presentation.
2 
3Claude: [Creates polished visualization with]
4- Custom color palette
5- Proper labels and titles
6- Annotations for key points
7- Professional styling
8- High DPI for presentations
9 
10[Shows result in notebook output]

"Add tests for foo.py"
"Make this faster"
"Fix the bug"
"Improve the UI"

1"Write test cases for foo.py covering the scenario where users are logged out. Use real database calls, avoid mocks."
2 
3"Optimize the API endpoint /api/users - it's taking 3 seconds. Profile the database queries and add indexes if needed."
4 
5"Fix the bug where clicking 'Save' twice creates duplicate entries. The issue is in src/components/Form.tsx line 45."
6 
7"Improve the dashboard UI to match the design system: Use Tailwind's blue-600 for primary buttons, add 16px padding to cards, and ensure mobile responsiveness."

macOS: Cmd+Ctrl+Shift+4 → Select area → Ctrl+V in Claude
Drag-drop: Drag image file into Claude
File path: "Look at /path/to/screenshot.png"

1You: [Paste screenshot of broken layout]
2 
3The header is overlapping the content on mobile. Fix it.
4 
5Claude: [Analyzes screenshot]
6 
7I see the issue - the header has fixed positioning but no padding-top on the main content. Fixing now...

1You: [Paste Figma design]
2 
3Implement this product card component exactly as shown.
4 
5Claude: [Studies design carefully]
6 
7I'll implement with:
8- 24px border radius (as shown)
9- Shadow: 0 4px 6px rgba(0,0,0,0.1)
10- "Add to Cart" button: #3B82F6
11- Image height: 240px
12- 16px padding throughout
13 
14[Creates matching implementation]

"Look at the user authentication code"

"Look at sr[TAB] → src/au[TAB] → src/auth/login.ts"

Review these files for security issues:
- src/auth/[TAB]login.ts
- src/api/[TAB]users/route.ts
- src/lib/[TAB]jwt.ts

1/permissions
2 
3→ Add to URL allowlist:
4  - docs.nextjs.org
5  - react.dev
6  - developer.mozilla.org
7  - docs.anthropic.com

1You: Implement authentication following NextAuth.js docs:
2https://next-auth.js.org/getting-started/example
3 
4Claude: [Reads the documentation]
5 
6I'll implement NextAuth following their example:
71. Install next-auth
82. Create api/auth/[...nextauth]/route.ts
93. Add session provider
10...

1You: Think through how to implement real-time notifications.
2 
3Claude: [Provides detailed plan]
4 
5You: Actually, let's use Server-Sent Events instead of WebSockets - simpler for our use case.
6 
7Claude: Good point! Updated plan: [New approach]

1You: Add authentication to all API routes
2 
3Claude: [Starts modifying files]
4 
5You: [Press Escape]
6 
7Actually, wait - skip the admin routes, they have different auth.
8 
9Claude: [Stops, context preserved]
10 
11Got it. I'll skip api/admin/* routes and only auth the api/user/* routes.

1You: Undo those changes. I want to try a different approach with middleware instead.
2 
3Claude: [Reverts changes]
4 
5Ready for the middleware approach. What did you have in mind?

1You: [Finish auth implementation]
2 
3Great! That's done. /clear
4 
5Now let's work on something completely different - optimizing the database queries.
6 
7Claude: [Fresh context, focused on new task]

1You: Create a checklist for migrating our codebase from JavaScript to TypeScript.
2 
3Claude: Created migration-checklist.md:
4 
5## TypeScript Migration Checklist
6 
7### Phase 1: Setup
8- [ ] Install TypeScript and types
9- [ ] Create tsconfig.json
10- [ ] Configure build tools
11- [ ] Add lint rules
12 
13### Phase 2: Core Files (Priority)
14- [ ] src/lib/utils.js → utils.ts
15- [ ] src/lib/api.js → api.ts
16- [ ] src/lib/auth.js → auth.ts
17 
18### Phase 3: Components
19- [ ] src/components/Button.jsx → Button.tsx
20- [ ] src/components/Input.jsx → Input.tsx
21... [30 more components]
22 
23### Phase 4: Testing
24- [ ] Update test files to .ts
25- [ ] Add type tests
26- [ ] Verify no any types
27 
28Let's work through this systematically. Ready to start Phase 1?

1You: Yes, start Phase 1.
2 
3Claude: [Completes Phase 1, checks off items]
4 
5Phase 1 complete!  All items checked.
6 
7Ready for Phase 2?
8 
9You: Yes, do Phase 2 items 1-3.
10 
11Claude: [Migrates core files, updates checklist]

1You: Analyze this data:
2 
3id,name,sales
41,Alice,5000
52,Bob,3000
63,Carol,7000
7 
8Calculate total sales and average.
9 
10Claude: Total sales: $15,000, Average: $5,000

cat data.csv | claude -p "Analyze this sales data"

You: Read the data from sales-q4.csv and analyze trends
 
Claude: [Reads file, performs analysis]

You: Fetch the API docs from https://api.example.com/docs and implement a client
 
Claude: [Fetches docs, implements client]

1You: [Paste chart image]
2 
3What insights can you extract from this visualization?
4 
5Claude: [Analyzes visual data]

1You: Implement the user authentication system
2 
3Claude A: [Implements auth]
4 
5Done! Code in src/auth/

1You: Review the authentication code in src/auth/ for security issues
2 
3Claude B: [Reviews code]
4 
5Issues found:
61. Password hashing uses only 8 rounds - should be 12
72. No rate limiting on login endpoint
83. JWT tokens never expire
94. Missing CSRF protection

1You: Fix these security issues: [paste Claude B's findings]
2 
3Claude A: [Implements fixes]
4 
5All security issues resolved. Ready for final review.

1# Clone repo to multiple directories
2git clone git@github.com:you/project.git project-feature-a
3git clone git@github.com:you/project.git project-feature-b
4git clone git@github.com:you/project.git project-feature-c
5 
6# Separate branches
7cd project-feature-a && git checkout -b feature-a
8cd ../project-feature-b && git checkout -b feature-b
9cd ../project-feature-c && git checkout -b feature-c

1# Terminal 1
2cd project-feature-a && claude
3 
4# Terminal 2
5cd project-feature-b && claude
6 
7# Terminal 3
8cd project-feature-c && claude

Terminal 1: Implement OAuth authentication
Terminal 2: Build notification system
Terminal 3: Optimize database queries

1# Main repo
2cd my-project
3 
4# Create worktrees for features
5git worktree add ../project-feature-a feature-a
6git worktree add ../project-feature-b feature-b
7git worktree add ../project-feature-c feature-c

1# Terminal 1
2cd ../project-feature-a && claude
3 
4# Terminal 2
5cd ../project-feature-b && claude
6 
7# Terminal 3
8cd ../project-feature-c && claude

git worktree remove ../project-feature-a
git worktree remove ../project-feature-b
git worktree remove ../project-feature-c

claude -p "List all TypeScript files in src/ that handle user input or authentication"

src/api/login.ts
src/api/register.ts
src/components/LoginForm.tsx
... [997 more files]

1#!/bin/bash
2 
3while IFS= read -r file; do
4  echo "Analyzing $file..."
5 
6  claude -p "Review $file for security issues: SQL injection, XSS, CSRF, auth bypasses. Report any findings." --output-format stream-json > "analysis-$(basename $file).json"
7 
8done < files-to-analyze.txt

claude -p "Summarize all security findings from analysis-*.json files. Prioritize by severity."

command1 | claude -p "prompt" --json | command2

cat application.log | claude -p "Extract all errors and summarize by type" --json | jq '.summary'

curl api.example.com/data | claude -p "Convert to CSV format" --json | csvlook

cat schema.sql | claude -p "Generate TypeScript types from this schema" > types.ts

ls src/**/*.ts | claude -p "For each file, generate a test skeleton" --json > test-plan.json

claude -p "prompt" --verbose --json

You: /clear
 
Let's start over. [Rephrase request more clearly]

1You: Stop. Read the actual code in src/auth/login.ts first. Don't assume how it works.
2 
3Claude: [Reads file]
4 
5You're right, I was mistaken. The actual implementation...

You: IMPORTANT: Do NOT use the `any` type. YOU MUST use proper TypeScript types.
 
Claude: [Implements with proper types]

1You: think harder
2 
3This solution won't scale. Consider:
41. What happens with 1M users?
52. Database indexing strategy
63. Caching layer
74. Rate limiting
8 
9Propose a better architecture.
10 
11Claude: [Provides more thoughtful solution]

1# Last updated: 2025-01-15
2 
3## Recent Changes
4- Added new deployment process (see scripts/deploy.sh)
5- Switched to Prisma ORM (no more raw SQL)
6- New branching strategy: feature/* and fix/*

git add .claude/commands/
git commit -m "chore: Add Claude slash commands for common tasks"

1{
2  "allowedTools": ["read", "write", "edit", "bash", "grep"],
3  "autoApprove": {
4    "bash": ["npm install", "npm test", "git status"]
5  }
6}

1# In PR review
2You: Review this PR for:
3- Code quality issues
4- Potential bugs
5- Performance concerns
6- Security vulnerabilities
7- Missing tests
8 
9Claude: [Provides detailed review]

1cd your-project
2claude
3 
4> /init
5 
6# Edit the generated CLAUDE.md to include:
7# 1. Common commands
8# 2. Architecture overview
9# 3. Code style rules
10# 4. Testing guidelines

1. Ask Claude to write tests for a new feature
2. Verify tests fail
3. Have Claude implement until tests pass
4. Commit tests, then implementation

11. Find a UI you want to build
22. Share design screenshot with Claude
33. Implement
44. Share result screenshot
55. Iterate 3-4 times until perfect

1. Create .claude/commands/my-command.md
2. Write a useful prompt template
3. Test it: /my-command
4. Share with your team