diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..afa92dcf
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+**Testing and Compliance:**
+- `make test` - Run full test suite with coverage and PEP8 compliance
+- `make test-core` - Run only core library tests
+- `make comply` - Run both ruff and mypy compliance checks
+- `make comply-ruff` - Run ruff linting
+- `make comply-ruff-fix` - Auto-fix ruff issues
+- `make comply-mypy` - Run mypy type checking
+- `pdm run pytest --cov=cement tests/` - Direct pytest execution
+- `pdm run pytest --cov=cement.core tests/core` - Test only core components
+
+**Development Environment:**
+- `make dev` - Start Docker development environment (recommended)
+- `pdm venv create && pdm install` - Set up local development environment
+- `pdm run cement --help` - Run the cement CLI
+
+**Documentation:**
+- `make docs` - Build Sphinx documentation
+
+**Build and Distribution:**
+- `pdm build` - Build distribution packages
+
+## Architecture Overview
+
+Cement is a CLI application framework built around a handler/interface pattern with the following core concepts:
+
+**Core Application (`cement.core.foundation.App`):**
+- The main `App` class in `cement/core/foundation.py` is the central orchestrator
+- Uses a Meta class pattern for configuration
+- Manages lifecycle through setup(), run(), and close() methods
+- Supports signal handling and application reloading
+
+**Handler System:**
+- Interface/Handler pattern where interfaces define contracts and handlers provide implementations
+- Core handlers: arg, config, log, output, cache, controller, extension, plugin, template
+- Handlers are registered and resolved through `HandlerManager`
+- Located in `cement/core/` with corresponding modules (arg.py, config.py, etc.)
+
+**Extensions System:**
+- Extensions in `cement/ext/` provide additional functionality
+- Examples: ext_yaml.py, ext_jinja2.py, ext_argparse.py, etc.
+- Optional dependencies managed through pyproject.toml extras
+
+**CLI Structure:**
+- Main CLI application in `cement/cli/main.py`
+- Uses CementApp class that extends core App
+- Includes code generation templates in `cement/cli/templates/`
+
+**Controllers:**
+- MVC-style controllers handle command routing
+- Base controller pattern in controllers/base.py files
+- Support nested sub-commands and argument parsing
+
+## Key Development Practices
+
+- 100% test coverage required (pytest with coverage reporting)
+- 100% PEP8 compliance enforced via ruff
+- Type annotation compliance via mypy
+- Docker-first development approach
+- PDM for dependency management
+- Zero external dependencies for core framework (optional for extensions)
+
+## Testing Notes
+
+- Tests located in `tests/` directory mirroring source structure
+- Core tests can run independently via `make test-core`
+- Coverage reports generated in `coverage-report/` directory
+- Tests must pass on Python 3.8+ (see docker containers for multiple versions)
+
+## Extension Development
+
+When working with extensions:
+- Check `cement/ext/` for existing extension patterns
+- Optional dependencies declared in pyproject.toml under `[project.optional-dependencies]`
+- Extensions follow naming pattern `ext_<name>.py`
+- Must implement proper interface contracts
\ No newline at end of file