diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2a7c042
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,141 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **VBA Automated Testing and Precise Error Reporting System** that enables automated testing of VBA macros in Excel files with exact line-level error reporting using code weaving techniques. The system solves the fundamental problem of debugging VBA macros by providing precise error locations and automated testing capabilities.
+
+## Core Architecture
+
+The system uses a **code weaving pattern** to instrument VBA code at runtime:
+
+1. **CodeWeaver Class** (`vba_test_runner.py`): Parses VBA code, injects line number labels (10, 20, 30...) before executable code, and adds error handling with `On Error GoTo` statements. Generates source maps mapping line numbers to original source code.
+
+2. **LoggerInjector Class**: Manages test logging infrastructure by injecting a `TestLogger` module and `CallStack` class into the VBA project for tracking execution flow and capturing results.
+
+3. **TestRunner Class**: Coordinates the testing process - manages Excel application lifecycle, handles VBA code hot-swapping, executes macros, and ensures files remain unmodified (non-invasive).
+
+4. **TestResult Data Class**: Structured container for procedure results including error details, source code mapping, error location, and call chain information.
+
+### How Code Weaving Works
+
+The system:
+- Parses VBA code to identify all Sub/Function procedures
+- Injects numeric line labels (10, 20, 30...) before executable code (skipping declarations, comments, empty lines)
+- Adds `On Error GoTo` error handlers at procedure start
+- Uses VBA's `Erl()` function to capture the last executed line number
+- Maps line numbers back to original source code via Source Map
+- Hot-swaps module code in Excel memory (never saves to disk)
+
+### Error Detection Mechanism
+
+- Leverages VBA's `Erl()` function which returns the last executed line number label
+- Maintains a source map from injected line numbers to original source code
+- Tracks call chains through LogEntry/LogExit in the TestLogger
+- Displays exact error location with original source code context
+
+## Development Commands
+
+### Virtual Environment Requirement
+
+**IMPORTANT**: Always activate the virtual environment before running any test scripts. The project uses a virtual environment located at `.venv`:
+
+```bash
+# On Windows
+.venv\Scripts\activate
+
+# On Linux/Mac
+source .venv/bin/activate
+```
+
+Never run `vba_test_runner.py` or other Python scripts directly from the system Python environment. Always ensure the virtual environment is active first.
+
+### Install Dependencies
+```bash
+pip install xlwings pywin32
+```
+
+### Running Tests
+
+Test a single procedure:
+```bash
+python vba_test_runner.py demo.xlsm Module1 TestErrorProcedure
+```
+
+Test multiple procedures:
+```bash
+python vba_test_runner.py demo.xlsm Module1 TestErrorProcedure TestTypeMismatch TestSubscriptError
+```
+
+Full project testing (discovers and tests all procedures):
+```bash
+python vba_test_runner.py demo.xlsm --all
+```
+
+### Excel Configuration Requirement
+
+Before running tests, enable "Trust access to the VBA project object model" in Excel:
+- Open Excel > File > Options > Trust Center > Trust Center Settings
+- Go to Macro Settings
+- Check: "Trust access to the VBA project object model"
+- Restart Excel
+
+## Key Implementation Details
+
+### Line Number Label Rules
+- Use pure numbers without colons: `10`, `20`, `30`...
+- Only inject before executable code
+- Skip declaration blocks (Dim, Private, etc.)
+- Skip comments and empty lines
+- Skip existing On Error statements
+
+### Hot-Swap Non-Invasive Testing
+All code modifications happen in memory. The system:
+1. Reads original VBA code from Excel file
+2. Applies code weaving transformations
+3. Replaces module code in Excel's VBProject
+4. Executes tests
+5. Closes workbook with `SaveChanges=False`
+
+Original Excel files are never modified.
+
+### Procedure Filtering
+- Automatically excludes Worksheet_ and Workbook_ event procedures
+- Only processes standard modules and class modules (Type 1 and 2)
+- Supports both single procedure and full project testing modes
+
+### TestResult Structure
+```python
+@dataclass
+class TestResult:
+    procedure_name: str
+    success: bool
+    error_number: int = 0
+    error_description: str = ""
+    error_line: int = 0
+    source_code: str = ""
+    error_module: str = ""      # Module where error occurred
+    call_chain: str = ""         # Full call stack
+```
+
+## Main Entry Point
+
+```python
+if __name__ == "__main__":
+    main()  # Handles both single procedure and full project testing
+```
+
+Core methods:
+- `TestRunner.run_test()`: Execute a single test procedure
+- `TestRunner.run_all_tests()`: Discover and execute all testable procedures
+- `CodeWeaver.weave_procedure()`: Weave a single procedure
+- `CodeWeaver.weave_all_modules()`: Weave all modules in a project
+- `CodeWeaver.parse_modules()`: Parse all modules in a VBA project
+
+## Limitations
+
+- Only supports standard modules and class modules (not form modules)
+- Line number label conflicts possible if original code uses same numeric labels
+- Complex procedures with many GoTo statements may require additional handling
+- Requires Excel VBA project object model access (security setting)