diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6bccc3e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,179 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+RenderWorker is a Python-based video processing service that renders video content using FFmpeg. It operates as both a Flask web service and a standalone worker process, processing video rendering tasks with templates, effects, and various transformations.
+
+## Architecture
+
+The project uses a modern layered architecture with clear separation of concerns:
+
+### Core Components
+
+- **Services Layer** (`services/`): Main business logic with dependency injection
+  - `RenderService`: Handles video rendering operations
+  - `TemplateService`: Manages video templates and resources
+  - `TaskService`: Orchestrates the complete task lifecycle
+  
+- **Entity Layer** (`entity/`): Data models and domain logic
+  - `RenderTask`: Core data model for rendering tasks
+  - `FFmpegCommandBuilder`: Generates FFmpeg commands from tasks
+  - `effects/`: Pluggable effect processing system (zoom, speed, skip, tail, cameraShot)
+
+- **Configuration** (`config/`): Centralized configuration management
+  - Environment-based configuration with dataclasses
+  - FFmpeg, API, Storage, and Server configurations
+
+- **Utilities** (`util/`): Common utilities for API, OSS, FFmpeg operations
+
+### Entry Points
+
+- **Web Service**: `app.py` - Flask application serving HTTP endpoints
+- **Worker Process**: `index.py` - Long-running task processor that polls for work
+- **Legacy Compatibility**: Maintains backward compatibility with older `entity/ffmpeg.py` and `biz/` modules
+
+## Common Commands
+
+### Running the Application
+
+```bash
+# Web service mode (Flask API)
+python app.py
+
+# Worker mode (background task processor)  
+python index.py
+
+# Worker with template redownload
+python index.py redownload
+```
+
+### Development Setup
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Environment setup
+cp .env.example .env
+# Edit .env with your configuration
+```
+
+### Building
+
+```bash
+# Build standalone executable
+pyinstaller index.spec
+
+# Build updater
+pyinstaller updater_helper.spec
+```
+
+## Key Environment Variables
+
+Required configuration (see `.env.example`):
+- `API_ENDPOINT`: Backend API endpoint
+- `ACCESS_KEY`: Authentication key
+- `TEMPLATE_DIR`: Directory for template storage
+- `ENCODER_ARGS`: FFmpeg encoder arguments (default: "-c:v h264")
+- `VIDEO_ARGS`: Video processing arguments
+- `OTLP_ENDPOINT`: OpenTelemetry endpoint for monitoring
+
+## Architecture Patterns
+
+### Service Layer Pattern
+All new code should use the service layer:
+
+```python
+from services import DefaultRenderService, DefaultTemplateService, DefaultTaskService
+
+# Dependency injection
+render_service = DefaultRenderService()
+template_service = DefaultTemplateService()
+task_service = DefaultTaskService(render_service, template_service)
+
+# Process tasks
+success = task_service.process_task(task_info)
+```
+
+### Effect Processing System
+Video effects use a pluggable architecture:
+
+```python
+from entity.effects import registry
+from entity.effects.base import EffectProcessor
+
+# Get existing effect
+processor = registry.get_processor('zoom', '0,2.0,1.5')
+
+# Register new effect
+class MyEffect(EffectProcessor):
+    def validate_params(self) -> bool:
+        return True
+    
+    def generate_filter_args(self, video_input: str, effect_index: int):
+        return filter_args, output_stream
+        
+    def get_effect_name(self) -> str:
+        return "myeffect"
+
+registry.register('myeffect', MyEffect)
+```
+
+### Task Processing Flow
+
+1. **Task Reception**: API receives task via HTTP endpoint or polling
+2. **Template Resolution**: Template service downloads/loads video templates
+3. **Task Creation**: Task service creates RenderTask with effects and resources
+4. **Command Building**: FFmpegCommandBuilder generates FFmpeg commands
+5. **Execution**: RenderService executes FFmpeg with monitoring
+6. **Cleanup**: Temporary files cleaned, results uploaded
+
+## Backward Compatibility
+
+The codebase maintains compatibility with legacy components:
+- `biz.task.start_task()` - Main task entry point
+- `entity.ffmpeg.FfmpegTask` - Legacy task object (now simplified)
+- `template.get_template_def()` - Template access
+
+These should work but new development should use the service layer.
+
+## FFmpeg Integration
+
+The system generates complex FFmpeg commands for video processing:
+- Supports effects chaining (zoom, speed changes, cropping)
+- Handles multiple input files and concatenation
+- Manages audio processing and overlays
+- Supports LUT color grading and subtitle embedding
+
+## Monitoring and Telemetry
+
+- **OpenTelemetry**: Distributed tracing for request monitoring
+- **Structured Logging**: Detailed logs for debugging
+- **Error Handling**: Custom exception types (`RenderError`, `FFmpegError`, `TemplateError`)
+
+## File Organization
+
+- Configuration and environment variables → `config/`
+- Business logic and services → `services/`
+- Data models and domain objects → `entity/`
+- HTTP API and external integrations → `util/`
+- Legacy compatibility layer → `biz/`
+- Application entry points → `app.py`, `index.py`
+
+## Working with Templates
+
+Templates define video processing workflows:
+- Downloaded from remote API and cached locally
+- Support video parts, effects, overlays, and audio
+- Use placeholder system for dynamic content
+- Managed by `TemplateService` with automatic updates
+
+## Development Notes
+
+- The project recently underwent major architectural refactoring from monolithic to layered design
+- New features should use the services layer and effect processor system
+- Legacy code is maintained for compatibility but simplified
+- All video processing ultimately uses FFmpeg with generated command lines
+- The system supports both synchronous (web) and asynchronous (worker) operation modes
\ No newline at end of file