Claude Code Complete Guide

# Project: My Awesome App

## Tech Stack
- Language: TypeScript (strict mode)
- Framework: Next.js 14 with App Router
- Database: PostgreSQL + Prisma
- Testing: Vitest for unit, Playwright for E2E

## Project Structure
src/
├── app/           # Next.js app router pages
├── components/    # React components
├── lib/           # Shared utilities
└── server/        # API routes and server logic

## Code Conventions
- Use functional components with hooks
- Prefer `type` over `interface` for TypeScript
- Use absolute imports with @/ prefix
- Co-locate test files with source (.test.ts)

## Common Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run unit tests
- `pnpm lint` - Run ESLint + Prettier
- `pnpm build` - Production build

## Important Notes
- Auth uses NextAuth with GitHub provider
- All API routes need rate limiting middleware
- Images served via Cloudinary CDN

## Do NOT
- Use `any` type without a comment explaining why
- Push directly to main branch
- Skip tests before committing
- Use npm (we use pnpm)

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"],
      "description": "Live documentation lookup for libraries"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "."],
      "description": "Enhanced file system access"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      },
      "description": "GitHub issue and PR management"
    }
  }
}

Replace ghp_your_token_here with your GitHub personal access token.

File: .claude/commands/git-push.md

Check the current git status and diff of staged changes.

Based on the changes, create a commit message following conventional commits format:
- feat: for new features
- fix: for bug fixes
- docs: for documentation
- refactor: for code refactoring
- test: for adding tests
- chore: for maintenance tasks

The commit message should be concise but descriptive.
Include a body if the changes are complex.

Then commit the changes and push to the current branch.
If the remote branch doesn't exist, create it with --set-upstream.

Usage: Stage your changes with git add, then run /project:git-push

File: .claude/commands/pr.md

Create a pull request for the current branch.

Steps:
1. Run `git status` to see what branch we're on
2. Get the list of commits not yet in main: `git log main..HEAD --oneline`
3. Generate a clear PR title from the branch name and commits
4. Write a comprehensive description with:
   - ## What Changed (summary of commits)
   - ## Why (infer motivation from commit messages and code)
   - ## How to Test (suggest specific test steps)
   - ## Screenshots (if UI changes, remind to add them)

5. Use `gh pr create` with the title and body

If gh CLI is not installed, tell me how to install it with:
`brew install gh` and `gh auth login`

Usage: After pushing your branch, run /project:pr

File: .claude/commands/review.md

Review the staged changes (run `git diff --cached`) for issues:

## Review Checklist

### 🐛 Bugs & Logic Errors
- Incorrect logic, off-by-one errors
- Missing null/undefined checks
- Unhandled edge cases
- Race conditions

### 🔒 Security Issues
- SQL injection vulnerabilities
- XSS attack vectors
- Hardcoded secrets or API keys
- Missing authentication/authorization checks
- Insecure data handling

### ⚡ Performance
- N+1 query problems
- Unnecessary loops or iterations
- Memory leaks
- Missing indexes for database queries

### 📝 Code Quality
- Poor naming that obscures intent
- Dead or unreachable code
- Missing error handling
- Violations of project conventions

## Output Format
For each issue found:
📍 **File:line** — Brief description
   ↳ Suggested fix

Only report REAL issues. Don't flag style preferences or nitpicks.
If everything looks good, say so briefly.

Usage: Stage changes, run /project:review, then fix issues before committing

File: .claude/commands/test-gen.md

Generate comprehensive tests for: $ARGUMENTS

Steps:
1. Read and understand the file's code
2. Identify all public functions/methods/exports
3. For each function, generate tests covering:
   - Happy path (normal expected usage)
   - Edge cases (empty inputs, boundaries, null/undefined)
   - Error cases (invalid inputs, failure modes)

Use the testing framework already in the project (check package.json).
Co-locate test files with the source (e.g., utils.ts → utils.test.ts).

Follow existing test patterns in the codebase if any exist.
Write clear test descriptions that explain what's being tested.

Usage: /project:test-gen src/utils/validation.ts

File: .claude/agents/your-agent-name.md

---
name: your-agent-name
description: One-line description shown in agent list
tools: Read, Grep, Glob
---

# Agent Role

Describe who this agent is and their expertise.
Example: "You are a senior security engineer specializing in web application security."

# Task Instructions

Explain what the agent should do when invoked:
1. First, do this...
2. Then check for...
3. Finally, report...

# Output Format

Specify how findings should be formatted:
- Use bullet points for issues
- Include file paths and line numbers
- Provide severity levels

# Constraints

List any limitations:
- Don't suggest changes outside scope of review
- Focus only on security issues, not style

---
name: skill-name
description: Brief description shown when Claude scans available skills
---

# Skill Name

Extended description of what this skill does.

## When to Use

Activate this skill when the user asks to:
- First matching phrase
- Second matching phrase
- Third matching phrase

## Prerequisites

List any requirements:
- Required npm packages: `package1`, `package2`
- Required Python packages: `package1`
- Environment variables: `API_KEY`

## How It Works

Step-by-step instructions Claude follows:
1. First, gather information by...
2. Then, process the data by...
3. Finally, generate output by...

## Output Format

Describe what the skill produces:
- File format and location
- Structure and content
- Validation criteria

## Examples

### Example 1: Basic Usage
Input: "Create a component called UserCard"
Output: Creates `src/components/UserCard.tsx`

### Example 2: Advanced Usage
Input: "Create a form component with validation"
Output: Creates component with Zod schema

{
  "hooks": {
    "postFileWrite": [
      {
        "pattern": "*.ts",
        "command": "npx prettier --write $FILE"
      },
      {
        "pattern": "*.tsx",
        "command": "npx prettier --write $FILE"
      }
    ],
    "preCommit": [
      {
        "command": "npm run lint"
      },
      {
        "command": "npm run test -- --run"
      }
    ]
  }
}