diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..bf389d0a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Swoole-Compiler is an AOT (Ahead-of-Time) compiler that translates PHP source code to C++, then compiles it with GCC/Clang/MSVC into native binaries. It supports Linux (primary), macOS, and Windows.
+
+**Prerequisites**: PHP 8.2+, GCC 9+ (C++17), CMake 3.24+. The `swoole/phpx` extension must be compiled (see README.md).
+
+## Build & Test Commands
+
+```bash
+# Install PHP dependencies
+composer install
+
+# Compile a PHP project to a native binary
+php bin/compiler.php <path-to-project-or-file>
+
+# Run all PHPUnit tests
+./vendor/bin/phpunit
+
+# Run a single PHPUnit test class
+./vendor/bin/phpunit phpunit/src/AstNodeTypeTest.php
+
+# Run PHPT integration tests (all)
+php run-tests.php tests/aot/
+
+# Run a single PHPT test
+php run-tests.php tests/aot/arrays.phpt
+```
+
+## Architecture
+
+### Translation Pipeline
+
+The compiler follows a 4-stage pipeline, orchestrated by `src/Php/Translator.php` (the main entry point):
+
+1. **prepare()** — Scan PHP files, collect symbol declarations and dependencies, topological-sort for compilation order
+2. **convert()** — Parse PHP AST via `nikic/php-parser`, translate each node to C++ source code
+3. **compile()** — Invoke the platform C++ compiler (GCC/Clang/MSVC) on generated `.cc` files
+4. **build()** — Link object files into a native binary executable
+
+### Class Hierarchy
+
+```
+src/Core/Translator (abstract base — indent/output/mode helpers)
+ └─ src/Php/CompilerBase (core PHP→C++ translation logic)
+     ├─ uses traits: AstNodeType, FuncCallOptimizer, ClosureGenerator,
+     │    PlaceHolderGenerator, PropertyPromotion, MagicMethodDetector
+     └─ src/Php/Preprocessor (scanning, symbol tables, dependency sort, YAML config)
+         └─ src/Php/Translator (full pipeline: prepare→convert→compile→build)
+             └─ src/Php/CompilerTest (test-only subclass, used by PHPUnit tests)
+```
+
+### Key Components
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/Php/Entity/` | Data classes: `ClassDef`, `FunctionDef`, `MethodDef`, `PropertyDef`, `ConstantDef`, `InterfaceDef` |
+| `src/Php/Generator/` | Codegen helpers: `ClosureGenerator`, `PlaceHolderGenerator`, `PropertyPromotion`, `Utils` |
+| `src/Php/Backend/` | Compiler abstraction: `CompilerBackend` (abstract) → `Gcc`, `Clang`, `Msvc`. Factory pattern via `CompilerFactory` |
+| `src/Php/Platform/` | OS abstraction: `PlatformBase` → `Linux`, `Macos`, `Windows`. Factory via `PlatformFactory` |
+| `src/Php/Context/` | `ScopeContext` and `FunctionContext` for variable scoping and type tracking |
+| `src/Php/Exception/` | `SyntaxError`, `Unsupported`, `DynamicCall`, `PlaceHolder`, `Skip`, `Redo`, `TestError` |
+| `src/Php/Parser/` | Special-purpose parsers like `StdContainerParser` (C++ std container foreach support) |
+| `src/Php/Reflection.php` | Static helpers wrapping PHP reflection (internal class/function detection) |
+| `src/Php/Symbol.php` | Maps PHP operations to `phpx` C++ API symbol names |
+| `src/Php/FileScanner.php` | Recursive file discovery with extension filtering (supports `.php`, `.cpp`, `.c`, `.s`, `.m`, `.mm`) |
+| `src/Php/ArgInfo.php` | Generates C function argument info structures for internal function registration |
+| `src/Php/Extractor.php` | Extracts interfaces from PHP classes |
+| `src/Php/Visitor.php` | Base `NodeVisitorAbstract` extension (skeleton for custom AST visitors) |
+| `src/Python/Translator.php` | Python-to-C++ translator (separate from the PHP pipeline) |
+
+### Configuration
+
+- `project.yml` — per-project build config (name, build-mode, C++ standard, compiler flags, sources, resources/icon)
+- Command-line arguments and YAML config are merged in `Preprocessor`, with CLI taking highest priority
+
+### Generated Output
+
+Generated `.cc` and `.o` files land in `build/` directory. The compiled binary is named from `project.yml`'s `name` field (default: `app`).
+
+### Test Infrastructure
+
+- **PHPUnit tests** (`phpunit/src/`) — unit/integration tests for compiler internals. Bootstrap at `phpunit/bootstrap.php` defines a `BaseTest` class with an `exec()` helper that runs the compiler and expects a `TestError` exception containing a given string
+- **PHPT tests** (`tests/aot/`) — end-to-end tests using the standard PHPT format (`run-tests.php`). Each `.phpt` contains PHP source and expected output sections
+
+When writing new compiler tests, use `CompilerTest::create(ROOT_PATH)` (in `src/Php/CompilerTest.php`) which sets `forTest = true` to enable test-specific behavior without writing files to disk.