your-project/
├── CLAUDE.md                        # Session context — loaded at start
├── CLAUDE.local.md                  # Personal overrides (gitignored)
├── .mcp.json                        # MCP tool integrations (shared via git)
└── .claude/
    ├── settings.json                # Permissions, model, hooks config
    ├── settings.local.json          # Personal settings overrides (gitignored)
    ├── rules/
    │   ├── code-style.md            # Code formatting & style standards
    │   ├── testing.md               # Testing patterns & requirements
    │   └── api-conventions.md       # API design rules
    ├── commands/
    │   ├── review.md                # /project:review — full code review workflow
    │   └── fix-issue.md             # /project:fix-issue — issue resolution steps
    ├── skills/
    │   └── deploy/
    │       ├── SKILL.md             # Deployment procedures
    │       └── deploy-config.md     # Environment & config details
    ├── agents/
    │   ├── code-reviewer.md         # Dedicated review agent
    │   └── security-auditor.md      # Security-focused analysis agent
    └── hooks/
        └── validate-bash.sh         # Pre-execution bash validation

# Project: Acme API

## Overview
A REST API for the Acme SaaS platform. Handles auth, billing, and user management.

## Tech Stack
- Runtime: Node.js 20, TypeScript 5.3
- Framework: Fastify
- Database: PostgreSQL 15 + Prisma ORM
- Auth: JWT + refresh tokens
- Testing: Vitest + Supertest
- CI: GitHub Actions

## Architecture
- src/routes/       — Route handlers (thin, delegate to services)
- src/services/     — Business logic
- src/repositories/ — Database layer (Prisma calls only here)
- src/middleware/   — Auth, validation, error handling

## Key Commands
- `npm run dev`     — Start dev server (port 3000)
- `npm run test`    — Run full test suite
- `npm run lint`    — ESLint + Prettier check
- `npm run migrate` — Run pending DB migrations

## Conventions
- All routes must have Zod input validation
- Services never import from other services directly
- Every new endpoint requires an integration test
- No raw SQL — use Prisma query builder

## Current Focus
Refactoring the billing module to support usage-based pricing.

# Local Overrides — Sandipan

## Personal Preferences
- I prefer concise responses without extensive explanation unless asked
- When suggesting refactors, show the diff format, not just the new code
- My local DB runs on port 5433 (not the default 5432)

## Dev Environment
- Using Cursor as my editor — optimize suggestions for Cursor workflows
- Node version: 20.11.0 via nvm

## Current Task
Working on the PaymentWebhookHandler — focus suggestions here.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

{
  "model": "claude-opus-4-5",
  "permissions": {
    "allow": [
      "bash:npm run *",
      "bash:git status",
      "bash:git diff *",
      "bash:git log *",
      "read:**",
      "write:src/**",
      "write:tests/**"
    ],
    "deny": [
      "bash:git push *",
      "bash:rm -rf *",
      "bash:curl *",
      "write:.env*"
    ]
  },
  "hooks": {
    "preToolUse": ".claude/hooks/validate-bash.sh"
  }
}

# Code Style Rules

## TypeScript
- Explicit return types on all exported functions
- No `any` types — use `unknown` and narrow
- Prefer `const` over `let`; never use `var`
- Interfaces over type aliases for object shapes

## Naming
- Files: kebab-case (`user-service.ts`)
- Classes: PascalCase (`UserService`)
- Functions/variables: camelCase (`getUserById`)
- Constants: SCREAMING_SNAKE_CASE (`MAX_RETRY_COUNT`)

## Imports
- Group: external libs → internal modules → types
- No barrel imports from index files in the same module
- Absolute paths only (`@/services/user` not `../../services/user`)

## Error Handling
- Always use custom error classes from `src/errors/`
- Never swallow errors silently — log or rethrow
- Async functions must handle rejection

# Testing Standards

## Requirements
- Every new route: at minimum one integration test
- Every service function: unit test with mocked dependencies
- Test files colocated with source: `user-service.test.ts`

## Patterns
- Use `describe` blocks matching the function/class name
- Test names: "should [behavior] when [condition]"
- No test should depend on another test's state
- Use factories from `tests/factories/` for test data

## Coverage
- Services: 90% line coverage minimum
- Routes: 80% minimum
- Utils: 100% — they're pure functions

# API Conventions

## Endpoints
- RESTful naming: /users, /users/:id, /users/:id/orders
- Versioned: all endpoints under /api/v1/
- Plural resource names always

## Request/Response
- All inputs validated with Zod schemas
- Success: { data: T, meta?: PaginationMeta }
- Error: { error: { code: string, message: string, details?: unknown } }
- HTTP 422 for validation errors, 409 for conflicts, 404 for not found

## Auth
- JWT in Authorization: Bearer header
- Refresh token in httpOnly cookie
- All endpoints authenticated unless marked @public

# Code Review Workflow

You are performing a thorough code review. Follow these steps in order:

1. **Understand the change**
   - Run `git diff main` to see all changes
   - Identify what problem this change solves

2. **Check correctness**
   - Does the logic handle edge cases?
   - Are error cases handled explicitly?
   - Any off-by-one errors or null pointer risks?

3. **Check standards compliance**
   - Apply rules from .claude/rules/code-style.md
   - Apply rules from .claude/rules/testing.md
   - Are all new endpoints following api-conventions.md?

4. **Check test coverage**
   - Run `npm test -- --coverage` and report gaps
   - Are happy path AND error paths tested?

5. **Security check**
   - Any user input used without sanitization?
   - Any secrets or credentials hardcoded?
   - Auth checks present on all new endpoints?

6. **Output**
   Provide a structured review with sections:
   - ✅ What's good
   - ⚠️ Minor issues (suggestions)
   - ❌ Must fix before merge

# Fix GitHub Issue Workflow

Given an issue number, follow these steps:

1. Fetch the issue: use GitHub MCP to get issue #$ARGUMENTS
2. Understand the bug — read related source files
3. Reproduce: identify the code path causing the issue
4. Fix: make the minimal change that resolves the issue
5. Test: write a test that would have caught this bug
6. Commit: `git commit -m "fix: [issue title] (#$ARGUMENTS)"`
7. Summary: explain what was wrong and what you changed

# Deployment Skill

## When to activate
Load this skill when the user mentions: deploy, deployment, release, production, staging, rollback.

## Deployment Process

### Pre-deploy checklist
- [ ] All tests passing (`npm test`)
- [ ] No TypeScript errors (`npm run type-check`)
- [ ] Migrations reviewed and tested
- [ ] Feature flags configured for gradual rollout

### Deploy to staging
```bash
gh workflow run deploy.yml -f environment=staging -f version=$(git rev-parse HEAD)

gh workflow run deploy.yml -f environment=production -f version=$(git rev-parse HEAD)

# Get previous stable version
git log --oneline -10
# Trigger rollback
gh workflow run rollback.yml -f version=<previous-sha>

Claude won't load deployment procedures when you're writing unit tests. It loads them when context signals a deployment task. This keeps the context window efficient.

---

### 8. .claude/agents/ — Specialized Sub-Agents

**Isolated context. Custom tools. Specific roles.**

Agents are specialized Claude instances with their own context windows, system prompts, and tool access. They handle focused tasks without polluting the main conversation.

**`.claude/agents/code-reviewer.md`**
```markdown
---
name: code-reviewer
description: Performs thorough code reviews. Invoke when reviewing PRs or checking code quality.
model: claude-opus-4-5
tools:
  - read
  - bash
---

You are a senior engineer specializing in code review.

Your focus areas:
- Correctness and edge case handling
- Security vulnerabilities (injection, auth bypass, data exposure)
- Performance implications (N+1 queries, unnecessary allocations)
- Maintainability (naming, complexity, coupling)
- Test coverage and test quality

You are direct. You flag real issues clearly. You don't pad reviews with excessive praise.
Format: use ✅ ⚠️ ❌ to categorize findings.

---
name: security-auditor
description: Security-focused code analysis. Invoke for security reviews before major releases.
model: claude-opus-4-5
tools:
  - read
  - bash
---

You are a security engineer performing a threat-focused audit.

Check for:
- Injection vulnerabilities (SQL, command, LDAP)
- Authentication and authorization flaws
- Insecure data exposure (logging PII, unencrypted storage)
- Dependency vulnerabilities (`npm audit`)
- Secrets in code or git history
- OWASP Top 10 issues

Report severity: CRITICAL / HIGH / MEDIUM / LOW.
For each issue: describe the vulnerability, show the affected code, explain the attack vector, recommend the fix.

#!/bin/bash
# Pre-execution hook — validates bash commands before Claude runs them

COMMAND="$1"

# Block destructive git operations
if echo "$COMMAND" | grep -qE "git push|git force|git reset --hard"; then
  echo "BLOCKED: Direct git push/force operations require manual execution."
  exit 1
fi

# Block production environment access
if echo "$COMMAND" | grep -qE "NODE_ENV=production|--env production"; then
  echo "BLOCKED: Production commands must be run through CI/CD pipeline."
  exit 1
fi

# Block deletion of critical files
if echo "$COMMAND" | grep -qE "rm -rf|rmdir /s"; then
  echo "BLOCKED: Recursive deletion requires manual confirmation."
  exit 1
fi

# Block direct database mutations in production
if echo "$COMMAND" | grep -qE "psql.*production|prisma migrate.*production"; then
  echo "BLOCKED: Production database operations require DBA approval."
  exit 1
fi

# Allow everything else
exit 0

Developer: "Review the PR for the new payment webhook handler"

Claude:
1. Loads CLAUDE.md → understands it's a Fastify/Prisma project
2. Loads CLAUDE.local.md → knows to show diff format, use port 5433
3. MCP GitHub connection → fetches the PR diff automatically
4. Loads .claude/rules/code-style.md → applies TypeScript standards
5. Loads .claude/rules/api-conventions.md → checks endpoint structure
6. Invokes code-reviewer agent → isolated, focused review context
7. Hook: validate-bash.sh → validates any commands before running
8. Output: structured review with ✅ ⚠️ ❌ findings

Total prompting required from developer: one sentence.

mkdir -p .claude/{rules,commands,skills,agents,hooks}

# Create the essential files
touch CLAUDE.md
touch CLAUDE.local.md
echo "CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore

touch .mcp.json
touch .claude/settings.json
touch .claude/rules/code-style.md
touch .claude/rules/testing.md
touch .claude/commands/review.md
touch .claude/hooks/validate-bash.sh
chmod +x .claude/hooks/validate-bash.sh