AGENT.md, CLAUDE.md & Skills Complete Guide: Mastering AI Coding Assistants

my-project/
  CLAUDE.md          # Project-wide settings
  src/
    CLAUDE.md        # src-specific settings
    components/
      CLAUDE.md      # Component-specific settings
  backend/
    CLAUDE.md        # Backend-specific settings

# Project Overview

Project purpose, tech stack, architecture overview

# Tech Stack

- Language: TypeScript 5.x
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL + Prisma ORM
- Testing: Vitest + Testing Library

# Project Structure

src/
app/ # Next.js App Router
components/ # React components
lib/ # Utility functions
types/ # TypeScript types

# Coding Standards

- Functions max 50 lines
- No `any` type
- JSDoc required for all functions
- Components use named exports only

# Testing Requirements

- All utility functions: unit tests required
- API routes: integration tests required
- Coverage 80% or higher

# Git Conventions

- Follow Conventional Commits
- Max 200 lines per PR

# Forbidden Patterns

- No console.log in production code
- No any type
- No hardcoded URLs

# Project Structure

src/
app/ # Next.js App Router - pages and layouts
(auth)/ # Route group requiring authentication
(public)/ # Public route group
api/ # API Route Handlers
components/ # Reusable React components
ui/ # Base UI components (shadcn/ui)
features/ # Feature components (auth, dashboard, etc.)
lib/ # Pure utility functions (no framework deps)
hooks/ # Custom React Hooks
stores/ # Zustand state management
types/ # TypeScript type definitions
server/ # Server-only code (DB, external APIs)

# Forbidden Patterns

## Types

- No `any` type → use `unknown` or a specific type
- No `@ts-ignore` → fix the root cause of the type error
- No `as any` type casting

## Code Quality

- No `console.log` or `console.debug` in production code → use logger
- No incomplete code left with TODO comments (TODOs require issue links)
- No magic numbers → extract to named constants

## Architecture

- No direct fetch calls in components → use custom hooks or server actions
- No direct DB queries in client components
- No hardcoded URLs → use environment variables

## Security

- No raw user input in SQL → use Prisma ORM
- No secrets exposed on the client
- No admin API endpoints without authentication

## Performance

- No useEffect dependency arrays that cause infinite loops
- No client-side filtering of large datasets → filter at DB level

# Before Creating New Code

Before writing new code, always check:

1. Is there already an implementation in src/lib/?
2. Is there a similar custom hook in src/hooks/?
3. Is there a reusable component in src/components/ui/?
4. Is there a reusable server action in src/server/?

Duplicate implementations severely degrade codebase maintainability.

.claude/
  commands/
    commit.md
    pr-description.md
    test.md
    review.md
    docs.md
    refactor.md
    security-check.md
    performance-check.md

Analyze the current staged changes and write a commit message
in Conventional Commits format. Write in English.

Format:
type(scope): subject

body (optional, explains why and what impact)

footer (optional, Breaking Change or issue number)

Type selection guide:

- feat: new feature
- fix: bug fix
- refactor: code improvement without behavior change
- test: add/modify tests
- docs: documentation changes
- chore: build/config changes
- perf: performance improvement

Use the changed module/component name as scope.
Subject: 50 chars or less, imperative mood.

Analyze the changes in the current branch and write a PR description.

## Summary

- (key changes as bullet points)

## Motivation

(explain why this change is needed)

## How to Test

- [ ] (verification checklist)

## Screenshots

(indicate if screenshots needed for UI changes)

## Notes

(anything reviewers should know)

Write unit tests for the selected code.
Use Vitest + Testing Library.

Include:

1. Happy path (normal case)
2. Boundary value tests
3. Error cases (exception handling)
4. Edge cases (null, undefined, empty arrays, etc.)

Test naming: "should [expected behavior] when [condition]" format
Minimize mocks; stay as close to the real implementation as possible.

Review this code. Analyze from the following perspectives
and label each item with severity (Critical/Major/Minor):

1. Bug potential
   - Logic errors, unhandled edge cases, race conditions

2. Security vulnerabilities
   - Auth/authz errors, injection vulnerabilities, sensitive data exposure

3. Performance issues
   - Unnecessary re-renders, N+1 queries, memory leaks

4. Readability improvements
   - Complex logic, unclear variable names, duplicate code

5. Testability
   - Dependency injection, pure function usage, ease of mocking

Include improved code examples for each issue found.

Write JSDoc documentation for this code.

For each function/class/type:

- @description: Feature description (2-3 sentences)
- @param: Type, description, and example value for each parameter
- @returns: Return value type and description
- @throws: Possible exceptions
- @example: Real usage code example

Include algorithm explanations for complex business logic.

Refactor this code.

Goals:

- Eliminate duplication (DRY principle)
- Improve readability (reduce complexity)
- Apply SOLID principles
- Improve testability

Constraints:

- Do not change existing behavior
- Maintain public API (function signatures, module interfaces)
- Refactor incrementally (don't change too much at once)

Show before/after comparisons and explain the reason for each change.

Audit this code for security vulnerabilities using OWASP Top 10 as the baseline.

Check specifically for:

1. Injection (SQL, Command, XSS)
2. Authentication/authorization errors
3. Sensitive data exposure
4. Security misconfiguration
5. Use of components with known vulnerabilities

For each vulnerability:

- Risk level (High/Medium/Low)
- Attack scenario description
- Fix method and code example

Analyze performance issues in this code.

Check:

1. Algorithm complexity (time/space)
2. Unnecessary recomputation (memoization candidates)
3. Database query optimization (N+1, index usage)
4. Network request optimization (batching, caching)
5. Rendering optimization (for React components)

Include improved example code for each issue.

# E-Commerce Platform

## Overview

B2C e-commerce platform. Consists of customer shopping,
order management, and admin dashboard.
500K MAU, processing 5K orders per day.

## Tech Stack

- Next.js 15 (App Router, RSC)
- TypeScript 5.x (strict mode)
- PostgreSQL 16 + Prisma ORM
- Redis (sessions, cache)
- Stripe (payments)
- Vercel (deployment)

## Domain Model

- User: customer account, supports multiple shipping addresses
- Product: SKU-based inventory management, category tree
- Order: Draft → Pending → Confirmed → Shipped → Delivered → Cancelled
- Cart: Redis-based, supports unauthenticated users (session-based)

## Architecture Rules

- Server components query DB directly (Prisma)
- Client-side API calls go through /api routes
- Complex business logic lives in src/server/services/
- Payment-related code must be server-side only

## Forbidden

- Using Prisma directly in client components
- Calculating payment amounts on the client (must be server-side)
- any type
- Hardcoded prices or discount rates

# Order Service

## Overview

Order processing microservice. gRPC for internal communication,
REST for external exposure. Target: 500 TPS.

## Tech Stack

- Go 1.23
- Fiber (HTTP), gRPC (internal)
- PostgreSQL + sqlc (type-safe queries)
- Redis (distributed lock, cache)
- OpenTelemetry (distributed tracing)

## Code Style

- Errors must propagate upward (use errors.Wrap)
- All DB queries include context (ctx param required)
- Logging: zerolog structured logs only
- Define interfaces first, implement later

## Project Layout (Standard Go Layout)

cmd/ # main packages
internal/ # code not exported externally
domain/ # domain models and interfaces
service/ # business logic
repository/ # DB access layer
handler/ # HTTP/gRPC handlers
pkg/ # utilities that can be exported

## Forbidden

- No panics without recover
- No context.Background() directly in handlers
- No global state
- No goroutine leak patterns

# Payment Service

## Overview

Payment processing service. PCI-DSS compliance required.
Kafka event-driven async processing.

## Tech Stack

- Java 21 (leveraging Virtual Threads)
- Spring Boot 3.x
- Spring Data JPA + Hibernate
- Apache Kafka (event streaming)
- Vault (secret management)

## Architecture

Hexagonal Architecture (Ports & Adapters):

- domain/: pure domain models (no dependencies)
- application/: use cases, port interfaces
- infrastructure/: adapters (DB, Kafka, external APIs)
- interfaces/: controllers, DTOs

## Rules

- Domain layer must have zero Spring dependencies
- All monetary values use BigDecimal (never double or float)
- Apply Circuit Breaker pattern for external payment API calls
- Saga pattern with compensating transactions for distributed transactions

## Forbidden

- Using double instead of BigDecimal for monetary calculations
- Logging payment information without masking
- Missing timeouts on synchronous payment API calls

Write a payment processing function

[Background] This is an e-commerce platform that processes payments with Stripe.
Payment-related logic currently lives in src/server/services/payment.ts.

[Constraints]
- Amounts must always be calculated server-side (never trust client input)
- On payment failure, retry up to 3 times with exponential backoff
- All payment events must be saved to an audit log

[Request]
Write a processCheckout function that creates a Stripe Payment Intent
during cart checkout. Use TypeScript and async/await.

Step 1: "Design the database schema for the user authentication system"
Step 2: "Write the Prisma model based on this schema"
Step 3: "Implement the login business logic in a service layer"
Step 4: "Create the API route handler that uses this service"
Step 5: "Write tests for each layer"

Our project writes API routes with this pattern:

[Example]
export async function GET(req: NextRequest) {
  try {
    const session = await getServerSession(authOptions)
    if (!session) return unauthorized()

    const data = await getUserData(session.user.id)
    return ok(data)
  } catch (error) {
    logger.error('Failed to get user data', { error })
    return internalError()
  }
}

Using this pattern, write an API route that retrieves a list of orders.

Implement a product search feature.

Never:
- Fetch all data on the client side and filter it there (performance issue)
- Insert search terms directly into SQL (injection vulnerability)
- Perform a full DB scan on every request without caching search results

Analyze whether this code has performance issues.
Before starting the analysis, proceed in this order:
1. Explain what the code is doing
2. Analyze time/space complexity
3. Identify potential bottlenecks
4. Suggest improvements

Error occurs → Collect context → Ask AI for analysis → Validate solution

Context collection checklist:
- Full error message (with stack trace)
- Input values at the time of the error
- Recently changed code (git diff)
- Relevant logs (30 lines before/after the error)
- Environment info (dev/staging/prod)

When requesting AI help:
"This error occurred. Analyze 3 possible causes
and tell me how to debug each one."

# Team AI Usage Guidelines

## Permitted Use

- Code generation and refactoring
- Writing test code
- Documentation and comments
- Debugging assistance
- Code review assistance

## Areas Always Requiring Human Review

- Security-related code (auth, authz, encryption)
- Payment and financial processing logic
- Personal data handling code
- Architecture-level decisions

## Managing AI-Generated Code

- All AI-generated code must be reviewed and understood before committing
- "The AI made it so it must be correct" is forbidden
- Ask the AI to explain code you don't understand

# First workspace
git worktree add ../project-feature-a feature/payment-v2

# Second workspace (different directory, different branch)
git worktree add ../project-feature-b feature/user-profile-v2

# List worktrees
git worktree list