Claude Code Complete Tutorial

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

brew install claude-code

npm install -g @anthropic-ai/claude-code

claude doctor

claude

/init

~/.claude/settings.json

your-project/.claude/settings.json

your-project/.claude/mcp.json
~/.claude/mcp.json

{
  "env": {
    "ANTHROPIC_API_KEY": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  },
  "model": "sonnet",
  "alwaysThinkingEnabled": true,
  "permissions": {
    "allow": [
      "Bash(git commit:*)",
      "Bash(npm install:*)",
      "Bash(dotnet build:*)"
    ]
  },
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

claude

claude "Create a new branch and fix all lint errors"

claude -p "Analyze this project's dependencies and generate a report"

claude --dangerously-skip-permissions "Run the full test suite"

# Project Guide

This is a .NET 10-based Web API project providing a unified AI model interface aggregation platform.

## Architecture

- Backend: .NET 10 + Minimal APIs + Clean Architecture
- Database: PostgreSQL + Entity Framework Core
- Cache: Redis + FusionCache
- Message Queue: RabbitMQ
- Frontend: Next.js 16 + React 19 (web), Vite + React 19 (admin)
- Orchestration: .NET Aspire

## Code Conventions

- Define endpoints using Minimal APIs pattern (in `/Common/*EndpointExtensions.cs`)
- All business logic in Service layer (`src/Routin.ApiService/Services/`)
- Endpoints should never directly access DbContext, must go through Service layer
- All API responses automatically wrapped in `{data, code, error}` format
- Use async/await for asynchronous operations
- Follow REST API design standards
- Run tests and build checks before committing

## Response Wrapping

All `/api/*` endpoint responses are automatically wrapped:
- Success: `{data: {...}, code: 200, error: null}`
- Error: `{data: null, code: 4xx/5xx, error: {Status, Title, Detail}}`

`/v1/*` (OpenAI compatible) endpoints return raw responses, not wrapped.

## Testing

- Unit tests: xUnit
- Run tests: `dotnet test`
- Run API: `dotnet run --project Routin.AppHost`

## Common Commands

- Start full application (Aspire): `dotnet run --project Routin.AppHost`
- Build solution: `dotnet build Routin.slnx`
- Create migration: `dotnet ef migrations add MigrationName --project src/Routin.EntityFrameworkCore --startup-project src/Routin.ApiService`
- Apply migration: `dotnet ef database update --project src/Routin.EntityFrameworkCore --startup-project src/Routin.ApiService`
- Start Web frontend: `cd web && bun run dev`
- Start Admin frontend: `cd admin && bun run dev`

## Database Migration Notes

**Important**: Stop running application before creating or applying migrations to avoid file locking issues.

## Development Workflow

1. Stop all running services
2. Create feature branch: `git checkout -b feature/name`
3. Modify code and entities
4. Create migration (if entities were modified)
5. Apply migration to database
6. Start Aspire: `dotnet run --project Routin.AppHost`
7. Test functionality
8. Commit and create PR

## Known Issues

- EF Core migrations fail when app is running (file locking) - stop app first
- Redis and RabbitMQ must be running before startup (via docker-compose)
- Frontend uses shadcn/ui component library - never use browser native `alert()`, `confirm()`, `prompt()`, must use Dialog components

## Steps to Add New Features

### Adding New API Endpoints
1. Create extension method file in `src/Routin.ApiService/Common/`
2. Register in `Program.cs`: `app.Map*Endpoints()`
3. Endpoints automatically get response wrapping (via `ResponseWrapperFilter`)

### Adding New Services
1. Create Service class in `src/Routin.ApiService/Services/`
2. Register in `Program.cs` DI container: `AddScoped<IService, Service>()`
3. Services should never directly access DbContext in endpoints

### Adding Distributed Events
1. Define event DTO in `src/Routin.ApiService/Events/`
2. Implement `IDistributedEventHandler<TEvent>`
3. Register in `Program.cs`: `AddScoped<IDistributedEventHandler<TEvent>, THandler>()`
4. Publish events via `IDistributedEventBus.PublishAsync(event)`

---
name: review
description: Comprehensive code review including security analysis
---

Please perform a comprehensive review of the following code:

1. Check for potential security vulnerabilities (SQL injection, XSS, CSRF, etc.)
2. Evaluate code quality and maintainability
3. Check adherence to project coding standards
4. Provide specific improvement suggestions
5. Identify performance issues

After analysis, generate a detailed review report.

/review src/Services/UserService.cs

---
name: optimize
description: Performance analysis and optimization suggestions
---

Analyze the following code for performance bottlenecks and provide optimization solutions:

Focus on:
- Database query efficiency (N+1 problem, missing indexes)
- Memory usage (memory leaks, unnecessary object allocations)
- Algorithm complexity
- Concurrency handling
- Caching strategies

Provide specific optimized code implementations.

.claude/commands/
├── backend/
│   ├── migrations.md
│   ├── api.md
│   └── test.md
├── frontend/
│   ├── components.md
│   └── styles.md
└── deployment/
    ├── docker.md
    └── ci-cd.md

/backend/migrations Add new field to User table
/frontend/components Create login form component

# Method 1: Direct use of ultrathink
claude "ultrathink: Analyze this legacy system's architecture and propose a modernization plan"

# Method 2: Use think harder
claude "think harder about the best approach to refactor this authentication system"

# Method 3: In interactive mode
"Please ultrathink this problem: How to optimize this API's performance to reduce response time by 50%"

claude "ultrathink: Our e-commerce platform needs to handle high-concurrency orders.
Please analyze the following options and recommend the best solution:
1. Monolithic application + Redis cache
2. Microservices + Message queue
3. Serverless + Event-driven
Consider maintainability, cost, team skills, and scalability."

claude "ultrathink: This API endpoint has a response time of 3 seconds in production.
Please deeply analyze performance bottlenecks and provide specific optimization solutions.
src/Services/OrderService.cs"

claude "ultrathink: Conduct a comprehensive security audit of the entire authentication system.
Focus on:
- Security of JWT implementation
- Password storage and verification
- OAuth integration
- API permission control
- Potential OWASP Top 10 vulnerabilities"

claude "ultrathink: This is a newly inherited legacy project.
Please analyze codebase structure, identify technical debt, evaluate code quality,
and provide a refactoring roadmap."

# In plan mode
"ultrathink: Design a distributed caching system"

# Step 1: Enter plan mode (Shift+Tab twice)
"ultrathink: Analyze this project's architecture, identify improvement points"

# Claude generates detailed analysis report and recommendations

# Step 2: Exit plan mode (Shift+Tab twice)
"Based on the previous analysis, implement the top 3 most important improvements"

# Claude starts modifying code

# Add MCP server
claude mcp add my-database --scope user

# List configured servers
claude mcp list

# Remove server
claude mcp remove my-database

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "custom-api": {
      "transport": "http",
      "url": "https://your-mcp-server.com",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
    }
  }
}

claude "Connect to database, analyze Users table structure and optimize indexes"

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

claude "List all open PRs and summarize key changes"

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
  }
}

# Step 1: Screenshot your design (Figma, web page, etc.)

# macOS
Cmd+Ctrl+Shift+4

# Windows
Win+Shift+S

# Linux
Use your screenshot tool

# Step 2: Paste in Claude Code
Ctrl+V

# Step 3: Describe requirements
"Convert this design into a React component using Tailwind CSS"

# Paste design mockup screenshot
"Based on this design, create a login page:
- React 19 + TypeScript
- shadcn/ui components
- Responsive layout
- Form validation (react-hook-form + zod)"

# Paste incorrect UI screenshot
"This button's alignment is wrong, fix it"

# Paste chart or table screenshot
"Extract data from this chart and generate JSON format"

Level 1: Read-only (default)
├── Auto-allowed: echo, cat, ls commands
└── Requires permission: most operations

Level 2: Plan Mode
├── Analyze code only
└── No file modifications or command execution

Level 3: Auto-accept Edits
├── Bypass file edit permission prompts
└── Still asks for command execution

Level 4: Bypass All Permissions
├── Fully autonomous
└── Use cautiously - only for trusted tasks

# Plan mode (analyze only)
claude --mode plan

# Auto-accept edits
claude --acceptEdits

# Fully autonomous (CI/CD use)
claude --dangerously-skip-permissions

# Terminal 1: Backend API development
cd backend
claude "Implement REST endpoints for user management"

# Terminal 2: Frontend component development
cd web
claude "Create React components for user profile page"

# Terminal 3: Testing and documentation
cd docs
claude "Generate OpenAPI documentation for API endpoints"

# Terminal 4: Infrastructure
claude "Configure Docker Compose for production deployment"

---
name: backend
description: Backend API development expert
---

You are an assistant focused on backend API development.

Use:
- .NET 10 + Minimal APIs
- Entity Framework Core
- PostgreSQL
- Clean Architecture

Always follow the project's response wrapping pattern.

claude @backend "Implement payment interface"

# Step 1: Write tests
claude "Write complete unit tests for the user authentication module (xUnit + Moq),
including edge cases and exception handling"

# Step 2: Implement functionality
claude "Implement authentication module to pass these tests"

# Step 3: Verification
claude "Run test suite and fix any failing tests"

# Install GitHub App
/install-github-app

# Claude will now automatically review all PRs

claude "Review changes in PR #123, focus on security and performance"

claude "ultrathink: We need to choose a caching solution.
Compare Redis, Memcached, and in-memory caching.
Consider performance, reliability, cost, and operational complexity.
Generate an ADR document (Architecture Decision Record)."

# Create and apply migration
claude "Add EmailVerified and EmailVerificationToken fields to User entity,
create EF Core migration and apply to database"

# Claude will:
# 1. Modify entity class
# 2. Run dotnet ef migrations add
# 3. Review generated migration code
# 4. Run dotnet ef database update

claude "Scan entire codebase, identify code smells and technical debt.
Prioritize and refactor one by one."

claude "ultrathink: Analyze OrderService's performance bottlenecks:
1. Identify N+1 query problems
2. Evaluate memory usage
3. Check algorithm complexity
4. Provide specific optimized code"

# Install Claude Code CLI
curl -fsSL https://claude.ai/install.sh | bash

# Python
pip install anthropic-agent

# TypeScript/Node.js
npm install @anthropic-ai/agent

from anthropic_agent import Agent

# Create agent
agent = Agent(
    model="claude-opus-4-5",
    instructions="You are a professional code review assistant"
)

# Run agent
result = agent.run("Review this codebase and provide improvement suggestions")
print(result)

import { Agent } from "@anthropic-ai/agent";

const agent = new Agent({
    model: "claude-opus-4-5",
    instructions: "You are a professional code review assistant"
});

const result = await agent.run("Review this codebase");
console.log(result);

agent = Agent(
    model="claude-opus-4-5",
    instructions="""
    You are a financial analyst.
    Use external APIs to fetch stock data and perform portfolio analysis.
    """,
    mcp_servers=["finance-api"]
)

result = agent.run("Analyze my investment portfolio and provide optimization suggestions")

const supportAgent = new Agent({
    model: "claude-sonnet-4-5",
    instructions: `
    You are a customer support assistant.
    - Handle user requests
    - Collect necessary information
    - Escalate to human when necessary
    `,
    mcpServers: ["crm-system", "ticket-system"]
});

await supportAgent.run("Help user #12345 resolve login issue");

dev_agent = Agent(
    model="claude-opus-4-5",
    instructions="""
    You are a full-stack development assistant.
    Responsible for code review, refactoring, testing, and deployment.
    """,
    tools=["bash", "file_operations", "git"]
)

dev_agent.run("Refactor authentication system and add unit tests")

from anthropic_agent import Agent, Orchestrator

# Create orchestrator
orchestrator = Orchestrator()

# Define subagents
backend_agent = Agent(
    model="claude-sonnet-4-5",
    instructions="Focus on backend API development"
)

frontend_agent = Agent(
    model="claude-sonnet-4-5",
    instructions="Focus on frontend component development"
)

infra_agent = Agent(
    model="claude-sonnet-4-5",
    instructions="Focus on infrastructure and deployment"
)

# Parallel execution
results = orchestrator.run_parallel([
    (backend_agent, "Implement user management API"),
    (frontend_agent, "Create user interface"),
    (infra_agent, "Configure CI/CD pipeline")
])

claude "Convert all service methods in src/Services/ directory to async pattern,
use async/await, ensure proper exception handling, update all callers"

claude "Generate complete unit tests for UserService.cs:
- Use xUnit and Moq
- Cover all public methods
- Include normal and exception flows
- Test boundary conditions and null handling
- Naming convention: MethodName_Scenario_ExpectedBehavior"

claude "Create a complete user management API:
- CRUD operations
- Use Minimal APIs pattern
- Follow project's ResponseWrapper pattern
- Add JWT authentication
- Include input validation (FluentValidation)
- Add Swagger documentation comments"

claude "ultrathink: Analyze database queries in OrderService.cs.
Identify N+1 problems, optimize query performance using Include and ThenInclude.
Add performance logging for monitoring."

claude "Create new branch feature/email-verification,
commit current changes, push to remote, and create PR"

claude "Create multi-stage Dockerfile for building .NET API application.
Create docker-compose.yml including:
- API service
- PostgreSQL
- Redis
- RabbitMQ
Include health checks and environment variable configuration."

claude "ultrathink: Conduct security audit of entire application.
Check OWASP Top 10 vulnerabilities:
1. SQL injection
2. XSS
3. CSRF
4. Authentication flaws
5. Authorization issues
6. Sensitive data exposure
7. Security misconfiguration
8. Dependency vulnerabilities
Generate detailed security report and remediation suggestions."

claude "Add detailed Serilog structured logging to PaymentService.cs:
- Method entry/exit
- Parameter logging
- Execution time measurement
- Exception details
- Use log levels (Information, Warning, Error)"

claude "Scan all service classes in Services directory,
add corresponding AddScoped registration in Program.cs.
Follow interface-implementation pattern (IService, Service)."

claude "Scan src/ directory, generate API documentation (Markdown format):
- All public endpoints
- Request/response formats
- Authentication requirements
- Usage examples (curl commands)
- Error code explanations"

# Clear existing credentials and re-authenticate
rm -rf ~/.claude/auth
claude

# Check MCP server configuration
claude mcp list

# Test specific server
npx @modelcontextprotocol/server-postgres

# System health check
claude doctor

# View configuration
cat ~/.claude/settings.json

# View logs
tail -f ~/.claude/logs/claude.log

# Clear cache
rm -rf ~/.claude/cache

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash

      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review this PR's changes, check for security vulnerabilities, code quality, and best practices" > review.md

      - name: Post Review Comment
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });

name: Auto Fix Lint Errors

on:
  push:
    branches: [develop]

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash

      - name: Fix Lint Errors
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --dangerously-skip-permissions "Fix all lint errors"

      - name: Commit Changes
        run: |
          git config user.name "Claude Code Bot"
          git config user.email "bot@example.com"
          git add .
          git commit -m "chore: auto-fix lint errors" || echo "No changes"
          git push

ANTHROPIC_BASE_URL=https://routin.ai/
ANTHROPIC_API_KEY=your-meteor-platform-api-key

{
  "env": {
    "ANTHROPIC_API_KEY": "your-meteor-api-key",
    "ANTHROPIC_BASE_URL": "https://routin.ai/"
  },
  "model": "sonnet"
}

# Test connection
claude -p "hello world"