docs: add CLAUDE.md for future Claude Code instances

Add comprehensive documentation for Claude Code including project overview, core architecture, development commands, and key implementation details. Includes virtual environment requirement for running test scripts.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

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)