Claude Code: Intermediate Tutorial

1. ~/.claude/CLAUDE.md              (User-level — all projects)
2. /project/CLAUDE.md               (Project-level — team shared)
   or /project/.claude/CLAUDE.md    (equivalent alternative location)
3. /project/subfolder/CLAUDE.md     (Loaded on demand when Claude reads files there)

# Global Preferences

## Style
- Use async/await over callbacks
- Prefer composition over inheritance
- Explicit type annotations on public APIs
- No commented-out code in commits

## Testing
- Always include edge cases
- Mock external services, never hit real APIs in tests

# Inventory Service

## Stack
Python 3.12, FastAPI, PostgreSQL, SQLAlchemy 2.0, Redis

## Commands
- make dev — Development server with hot reload
- make test — Run pytest with coverage
- make lint — Run ruff + mypy

## Conventions
- Routes in app/api/v1/
- Services in app/services/ (business logic)
- Models in app/models/ (SQLAlchemy)
- Schemas in app/schemas/ (Pydantic)

## Database
- Use async sessions everywhere
- Alembic for migrations
- Never raw SQL — use ORM

# API Layer Conventions

- All endpoints return Pydantic schemas
- Use dependency injection for services
- Authentication via OAuth2PasswordBearer
- Rate limiting on public endpoints
- Consistent error responses: {"detail": "message", "code": "ERROR_CODE"}

# Project Overview

## Architecture
For system architecture details, see @docs/ARCHITECTURE.md

## API Contracts
API documentation is in @docs/api/openapi.yaml
Claude should read this before modifying any API routes.

## Database Schema
Schema is in @app/models/
Read the relevant model file before any database changes.

## Deployment
Deployment instructions in @docs/DEPLOYMENT.md
Read before making infrastructure changes.

> spawn a subagent to explore how the payment service handles refunds
> use a subagent to find all usages of the deprecated sync_inventory function
> have a subagent research how other services handle retry logic

> /agents

# Less effective
> spawn subagent to read the auth files

# More effective
> spawn a subagent to understand how our auth module handles token refresh.
> I need to know this because I'm implementing "remember me" functionality
> and need to extend token lifetime for opted-in users.

> spawn subagent to explore how the notification service works

# Wait for report...

> based on that, how would I add email notifications alongside push?

# Get recommendation...

> [main agent] implement email notifications following the pattern
> described: add EmailChannel to NotificationService.send()

---
name: security-reviewer
description: Focused security audit agent
model: sonnet
tools: Read, Grep, Glob, Bash
---

You are a security-focused code reviewer. When analyzing code:

1. Check for injection vulnerabilities (SQL, command, LDAP)
2. Verify authentication and authorization patterns
3. Look for sensitive data exposure
4. Check input validation and sanitization
5. Review error handling (no stack traces to users)

Report findings with severity: CRITICAL, HIGH, MEDIUM, LOW

0-30%  ████████░░░░░░░░░░░░░░░░░░░░░░  Optimal
30-50% ████████████████░░░░░░░░░░░░░░  Good
50-70% ████████████████████████░░░░░░  Degraded
70%+   ████████████████████████████░░  Danger

# Completed the inventory sync feature? Start fresh.
/clear

# Don't explore in main context
> spawn subagent to find how error handling works across services

# Don't wait for problems
/compact focus on the decisions made and current implementation state

# Bad
> read all files in app/

# Good
> read @app/services/payment.py — I need to modify the refund logic

> create a context summary I can paste into a new session.
> include: what we're building, decisions made, current state, next steps.
> output as a single prompt I can paste.

> /resume

# Auto-generate name from content
> /rename

# Explicit name
> /rename "payment-service-refund-logic"

# Interactive picker
> /resume

# Resume most recent
claude --continue

# Resume specific session
claude --resume abc123

# Fork a session (branch off without affecting original)
claude --continue --fork-session

> /rewind

> /plan add rate limiting to all API endpoints

> I want to add a caching layer to the API. Before implementing,
> interview me about the requirements — ask about cache invalidation,
> TTLs, what should be cached, etc. Be thorough.

project/
├── docs/
│   └── specs/
│       ├── webhook-retry.md
│       └── inventory-sync.md
├── tasks/
│   └── current/
│       └── payment-refund-flow.md
└── ...

## Task Tracking
Active tasks and specs are in @docs/specs/ and @tasks/current/
Read relevant files before implementing.

.claude/skills/api-endpoint/
├── SKILL.md          # Main skill definition
├── template.py       # Template file
└── examples/
    └── sample.py     # Example output

---
name: api-endpoint
description: Generate a new FastAPI endpoint with tests
---

# API Endpoint Generator

When creating a new endpoint:

1. **Route handler** in `app/api/v1/`
   - Use dependency injection for services
   - Add OpenAPI documentation
   - Include request/response schemas

2. **Service method** in `app/services/`
   - Business logic only
   - Raise domain exceptions, not HTTP errors

3. **Tests** in `tests/api/`
   - Happy path
   - Validation errors
   - Authorization failures
   - Edge cases

## Template

See @template.py for the structure.

## Usage

/api-endpoint create-order
/api-endpoint list-invoices --pagination

# Remote HTTP server (recommended)
claude mcp add --transport http github https://api.github.com/mcp

# Local database connection
claude mcp add --transport stdio db -- \
  npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/mydb"

# List all servers
claude mcp list

# Get details
claude mcp get github

# Remove a server
claude mcp remove github

# In Claude Code: check status, authenticate
/mcp

# Add to project (shared with team)
claude mcp add --scope project --transport http github https://api.github.com/mcp

# Add for yourself globally
claude mcp add --scope user --transport http sentry https://mcp.sentry.dev/mcp

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "cd $CLAUDE_PROJECT_DIR && ruff check --fix ."
        }]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "if": "Bash(git push *)",
          "command": "echo '{\"decision\": \"deny\", \"reason\": \"No pushing to remote. Commit locally only.\"}'"
        }]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "scripts/quality-gate.sh"
      }]
    }]
  }
}

#!/bin/bash
INPUT=$(cat)
stop_hook_active=$(echo "$INPUT" | jq -r '.stop_hook_active // false')

# CRITICAL: if we already blocked once, allow through to prevent infinite loop.
# stop_hook_active=true means Claude is retrying after a previous block.
if [ "$stop_hook_active" = "true" ]; then
    exit 0
fi

# Run your checks
if ! make lint 2>&1; then
    echo '{"decision": "block", "reason": "Linting errors found. Please fix them."}'
    exit 0
fi

if ! make test 2>&1; then
    echo '{"decision": "block", "reason": "Tests are failing. Please fix them."}'
    exit 0
fi

# All passed
exit 0

# Check deploy status every 5 minutes
> /loop 5m check if the deployment finished and tell me what happened

# Re-run a review skill every 20 minutes
> /loop 20m /review-pr 1234

# Default interval is 10 minutes
> /loop check the build

> remind me at 3pm to push the release branch
> in 45 minutes, check whether the integration tests passed

> what scheduled tasks do I have?
> cancel the deploy check job

# Quick model switching
alias cm='claude --model'
alias co='claude --model opus'
alias ch='claude --model haiku'

# Load architecture diagrams into context
alias cdiag='claude --append-system-prompt "$(cat docs/diagrams/*.md)"'

# Resume last session
alias cr='claude --continue'

# Quick one-shot prompts
alias cq='claude -p'

# Start with permission mode (e.g., plan mode)
alias cp='claude --permission-mode plan'

# Review changes before committing
git diff --staged | claude -p "review these changes for issues"

# Generate commit message
git diff --staged | claude -p "generate a conventional commit message for these changes"

# Quick code review
cat src/services/payment.py | claude -p "review this code for security issues"

# Claude creates/uses a worktree at <repo>/.claude/worktrees/<name>
claude -w hotfix

# Create worktree for the hotfix
git worktree add ../project-hotfix main

# Start Claude Code in the worktree directory
cd ../project-hotfix
claude

# Terminal 1: Feature work (main repo)
cd ~/projects/inventory-service
claude
> continue implementing the sync feature

# Terminal 2: Hotfix (separate worktree)
claude -w hotfix
> fix the critical bug in stock calculation

{
  "worktree": {
    "sparsePaths": [
      "services/payment/",
      "libs/shared/",
      "configs/"
    ]
  }
}

# Terminal 1: Main implementation
cd ~/projects/api
claude
> implement the refund endpoint

# Terminal 2: Writing tests in parallel
cd ~/projects/api
claude
> write integration tests for the payment service.
> focus on refund scenarios.

# Terminal 3: Documentation
cd ~/projects/api
claude
> update the API docs to reflect recent payment changes

<!-- PROJECT-STATUS.md -->
## Current Work

- [x] Refund endpoint (Terminal 1)
- [ ] Integration tests (Terminal 2)
- [ ] API docs (Terminal 3)

> create a mermaid diagram showing the data flow for payment processing

sequenceDiagram
    participant Client
    participant API
    participant PaymentService
    participant Stripe
    participant DB
    
    Client->>API: POST /payments
    API->>PaymentService: process_payment()
    PaymentService->>Stripe: create_charge()
    Stripe-->>PaymentService: charge_id
    PaymentService->>DB: save_transaction()
    DB-->>PaymentService: transaction_id
    PaymentService-->>API: PaymentResult
    API-->>Client: 201 Created

## Architecture

```mermaid
graph TD
    A[API Gateway] --> B[Auth Service]
    A --> C[Payment Service]
    A --> D[Inventory Service]
    C --> E[(PostgreSQL)]
    D --> E

### Keeping Diagrams Updated

Add a hook to regenerate diagrams on PR:

```bash
# As a Stop hook or CI step
claude -p "update @docs/diagrams/payment-flow.md to reflect current implementation"

# Configure via the settings interface
> /config

---
name: Concise Backend
description: Minimal output for experienced devs
keep-coding-instructions: true
---

Be extremely concise. No explanations unless asked.
Just make the changes and briefly state what you did.
Skip "Here's what I did" preambles.

## Backend Conventions
- All services use dependency injection
- Exceptions defined in app/exceptions.py
- Use structured logging (structlog)
- Async everywhere — no blocking calls

## Frontend Conventions
- Never use eslint-disable without approval
- All colors from tailwind.config.ts
- Components in PascalCase
- Hooks in use* format

> before refactoring, write comprehensive interface tests
> that will validate behavior is preserved.

> spawn subagent to explore [topic]
> /agents                           # Manage agents

/context                            # Check usage
/compact [focus]                    # Compress
/clear                              # Fresh start
/rewind                             # Go back (or Esc Esc)

/resume                             # List sessions
/rename "name"                      # Name session
claude --continue                   # Resume last
claude --continue --fork-session    # Fork session

claude mcp add ...                  # Add MCP server
/mcp                                # Manage MCPs

/loop 5m check the deploy           # Recurring prompt
/loop 10m has CI passed on PR 1234  # Poll for status
# "remind me at 3pm to push"        # One-shot reminder