Claude Code: دليل استخدام CLAUDE.md

# CLAUDE.md

## Project Overview
[One-line description of what the project is and does]

## Tech Stack
[Language, framework, database, toolchain]

## Common Commands
[Build, test, deploy, dev commands]

## Code Conventions
[Naming standards, file organization, style requirements]

## Constraints and Limitations
[What not to do, what must be done]

## Known Issues
[Technical debt and pitfalls requiring special attention]

# CLAUDE.md

## Project Overview
SaaS billing platform backend, handling subscription management, invoice generation, and payment integration.

## Tech Stack
- Node.js 20 + TypeScript 5.3
- Express 4.18 + middleware chain
- Prisma 5.x (PostgreSQL)
- Redis (cache + queue)
- Jest + Supertest (testing)

## Common Commands
- `npm run dev` — Start dev server (port 3000)
- `npm test` — Run all tests
- `npm run lint` — ESLint check
- `npx prisma migrate dev` — Database migration

## Code Conventions
- Service layer only handles business logic, no direct HTTP object access
- Controller layer handles request/response transformation
- All database operations via Repository pattern
- Errors use AppError class with statusCode and code
- API response format: `{ success: boolean, data: T, error?: string }`

## Constraints
- ❌ Never use pg client directly, must use Prisma
- ❌ Never access req/res in Service layer
- ❌ Never hardcode secrets and credentials
- ✅ Every API endpoint must have integration tests
- ✅ All amounts use cents (integer), avoid floating point errors

## Known Issues
- PaymentService.processRefund has concurrency issue (see ISSUE-342)
- InvoiceService.generatePDF performs poorly with many items (see ISSUE-156)

~/.claude/CLAUDE.md          # Global: Personal preferences
project-root/CLAUDE.md       # Project: Team conventions
project-root/src/api/CLAUDE.md  # Directory: Local instructions

<!-- ~/.claude/CLAUDE.md -->
# Global Preferences

## Code Style
- Use TypeScript strict mode
- Prefer const, avoid let
- Functions no longer than 20 lines
- Add JSDoc comments

## Testing Preferences
- Use describe/it style
- Each test independent, no execution order dependency
- Mock external dependencies, not internal modules

<!-- src/api/CLAUDE.md -->
# API Module Conventions

## Route Registration
- All routes registered centrally in index.ts
- Middleware order: auth → rateLimit → validate → handler

## Response Format
- Success: { success: true, data: T }
- Failure: { success: false, error: { code, message } }

## Prohibited
- ❌ Don't write business logic directly in handlers
- ❌ Don't skip parameter validation

> Update CLAUDE.md based on recent code changes

Claude Code:
  → Reading recent commits
  → Changes detected: Express → Fastify, added Redis, Jest → Vitest
  → Updating CLAUDE.md with current tech stack and commands
  CLAUDE.md updated ✓