CLAUDE.md File Configuration Guide

# Project Name

## Project Overview

[Brief description of project purpose, core features, and target users]

## Tech Stack

- Frontend: [Framework and main libraries]
- Backend: [Language and framework]
- Database: [Database type]
- Deployment: [Deployment platform]

## Project Structure

\```
project/
├── src/ # Source code
├── tests/ # Test files
├── docs/ # Documentation
└── scripts/ # Script files
\```

## Development Standards

[Project-specific coding standards]

## Important Notes

[Project-specific notes and limitations]

# CLAUDE.md - Project Configuration File

## General Rules (All projects must follow)

### Communication Language

- Always think and communicate in simplified Chinese
- Code comments in English, documentation in Chinese

### Documentation Management

- Formal documentation goes in `docs/` directory
- Discussion documents go in `discuss/` directory
- Keep README concise, detailed documentation separate

## Code Architecture Standards

### File Size Limits

- Python/JavaScript/TypeScript: No more than 300 lines per file
- Java/Go/Rust: No more than 400 lines per file
- No more than 8 files per folder
- Refactor or split when exceeding limits

### Code Quality Indicators

Avoid the following code smells:

1. **Rigidity**: System is difficult to change
2. **Redundancy**: Too much duplicate code
3. **Circular Dependencies**: Modules depend on each other
4. **Fragility**: Changes cause cascading problems
5. **Obscurity**: Code intent is unclear
6. **Data Clumps**: Data items always appear together
7. **Over-engineering**: Unnecessary complexity

## Tech Stack Constraints

### Frontend Tech Stack

- React 19+ (not 18 or lower)
- Next.js 15.4+ (not 14 or lower)
- Tailwind CSS v4 (not v3)
- TypeScript first, avoid JavaScript
- Forbidden to use CommonJS, only ES Modules

### Backend Tech Stack

- Node.js 18+
- Use TypeScript
- Express/Fastify as web framework
- Prisma as ORM

### Python Projects

- Use uv to manage dependencies (not pip/poetry/conda)
- Virtual environment directory name: `.venv`
- Strong type definitions, avoid using dict
- Keep project root directory clean

## Development Workflow

### Script Management

- All scripts in `scripts/` directory
- Use `.sh` scripts for start/stop operations
- Don't directly use npm/pnpm/python commands
- Script failures must be fixed immediately

### Log Management

- Configuration files output logs
- Unified output to `logs/` directory
- Include timestamps and log levels
- Separate error logs

### Testing Requirements

- Unit test coverage > 80%
- Critical features must have integration tests
- Test files in `tests/` directory
- Use CI/CD to run tests automatically

## Naming Conventions

### File Naming

- Components: PascalCase (e.g., UserProfile.tsx)
- Utility functions: camelCase (e.g., formatDate.ts)
- Constants files: UPPER_SNAKE_CASE (e.g., API_CONSTANTS.ts)
- Style files: kebab-case (e.g., user-profile.css)

### Variable Naming

- Variables/functions: camelCase
- Constants: UPPER_SNAKE_CASE
- Classes/interfaces: PascalCase
- Private properties: \_camelCase

## Git Workflow

### Branch Strategy

- main: Production environment code
- develop: Development environment code
- feature/\*: Feature branches
- hotfix/\*: Emergency fix branches

### Commit Conventions

- feat: New feature
- fix: Bug fix
- docs: Documentation update
- style: Code formatting adjustments
- refactor: Code refactoring
- test: Test related
- chore: Build/tool changes

## API Design Standards

### RESTful Principles

- GET: Retrieve resource
- POST: Create resource
- PUT: Update resource (full)
- PATCH: Update resource (partial)
- DELETE: Delete resource

### Response Format

\```json
{
"success": true,
"data": {},
"message": "Operation successful",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### Error Handling

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Error description",
"details": {}
}
}
\```

## Security Standards

### Sensitive Information

- Don't hardcode keys in code
- Use environment variables for configuration
- Don't commit `.env` files to Git
- Regularly update dependencies

### Data Validation

- Validate data on both frontend and backend
- Use schema validation libraries (e.g., zod)
- Use parameterized SQL queries
- Prevent XSS and CSRF attacks

## Performance Optimization

### Frontend Optimization

- Lazy loading for images
- Code splitting
- Caching strategy
- Virtual scrolling (for large lists)

### Backend Optimization

- Database query optimization
- Use caching (Redis)
- API response compression
- Concurrency control

## Deployment Configuration

### Environment Variables

- development: Development environment
- staging: Testing environment
- production: Production environment

### Containerization

- Use Docker for deployment
- Multi-stage builds to optimize image size
- Use docker-compose for service orchestration

## Monitoring and Logging

### Monitoring Metrics

- API response time
- Error rate
- Resource usage
- User behavior analytics

### Log Levels

- ERROR: Error information
- WARN: Warning information
- INFO: General information
- DEBUG: Debug information

## Special Notes

⚠️ **Important Reminders**:

1. Report code issues immediately when detected
2. Ask users when uncertain
3. Maintain clean and maintainable code
4. Follow established project standards

## React/Next.js Project Standards

### Component Standards

- Use function components + Hooks
- Component file same name as component
- One component per file
- Define Props with TypeScript interfaces

### State Management

- Simple state: useState
- Complex state: useReducer
- Global state: Context API / Zustand
- Server state: TanStack Query

### Styling Solution

- Tailwind CSS v4 primary
- CSS Modules as supplement
- Avoid inline styles
- Responsive design first

### Performance Optimization

- Use React.memo to avoid unnecessary renders
- useMemo/useCallback to optimize computations
- Dynamic imports for code splitting
- Use next/image component for images

## Python Project Standards

### Project Structure

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### Dependency Management

- Use uv to manage all dependencies
- pyproject.toml defines project configuration
- requirements.txt for production deployment
- requirements-dev.txt for development dependencies

### Type Annotations

- All functions must have type annotations
- Use dataclass to define data structures
- Use mypy for type checking
- Avoid using Any type

### Async Programming

- Prefer async/await
- Use asyncio to manage concurrency
- Use async drivers for database operations
- Use httpx for HTTP requests

## Microservices Architecture Standards

### Service Division

- Divide services by business domain
- Each service deployed independently
- Services communicate via API
- Share code through package management

### API Gateway

- Unified entry management
- Authentication and authorization
- Rate limiting and circuit breaking
- Request routing

### Service Communication

- HTTP/REST: Synchronous calls
- Message queue: Asynchronous communication
- gRPC: High-performance scenarios
- WebSocket: Real-time communication

### Data Management

- Each service has independent database
- Avoid cross-service transactions
- Use event-driven to maintain consistency
- Implement idempotent operations

> /init