feat: add modular Claude Code rules in .claude/rules/

Split monolithic CLAUDE.md instructions into focused, topic-specific
rule files. Path-scoped rules for source code and tests only load when
working with matching files.

.claude/rules/architecture.md

@@ -0,0 +1,23 @@
+# Architecture
+
+```
+codeflash/
+├── main.py                 # CLI entry point
+├── cli_cmds/               # Command handling, console output (Rich)
+├── discovery/              # Find optimizable functions
+├── context/                # Extract code dependencies and imports
+├── optimization/           # Generate optimized code via AI
+│   ├── optimizer.py        # Main optimization orchestration
+│   └── function_optimizer.py  # Per-function optimization logic
+├── verification/           # Run deterministic tests (pytest plugin)
+├── benchmarking/           # Performance measurement
+├── github/                 # PR creation
+├── api/                    # AI service communication
+├── code_utils/             # Code parsing, git utilities
+├── models/                 # Pydantic models and types
+├── tracing/                # Function call tracing
+├── lsp/                    # IDE integration (Language Server Protocol)
+├── telemetry/              # Sentry, PostHog
+├── either.py               # Functional Result type for error handling
+└── result/                 # Result types and handling
+```

.claude/rules/code-style.md

@@ -0,0 +1,9 @@
+# Code Style
+
+- **Line length**: 120 characters
+- **Python**: 3.9+ syntax
+- **Tooling**: Ruff for linting/formatting, mypy strict mode, prek for pre-commit checks
+- **Comments**: Minimal - only explain "why", not "what"
+- **Docstrings**: Do not add unless explicitly requested
+- **Naming**: NEVER use leading underscores (`_function_name`) - Python has no true private functions, use public names
+- **Paths**: Always use absolute paths, handle encoding explicitly (UTF-8)

.claude/rules/git.md

@@ -0,0 +1,6 @@
+# Git Commits & Pull Requests
+
+- Use conventional commit format: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`
+- Keep commits atomic - one logical change per commit
+- Commit message body should be concise (1-2 sentences max)
+- PR titles should also use conventional format

.claude/rules/source-code.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "codeflash/**/*.py"
+---
+
+# Source Code Rules
+
+- Use libcst, not ast - always use `libcst` for code parsing/modification to preserve formatting.
+- NEVER use leading underscores for function names (e.g., `_helper`). Python has no true private functions. Always use public names.
+- Any new feature or bug fix that can be tested automatically must have test cases.
+- If changes affect existing test expectations, update the tests accordingly. Tests must always pass after changes.

.claude/rules/testing.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "tests/**"
+  - "codeflash/**/*test*.py"
+---
+
+# Testing Conventions
+
+- Code context extraction and replacement tests must always assert for full string equality, no substring matching.
+- Use pytest's `tmp_path` fixture for temp directories (it's a `Path` object).
+- Write temp files inside `tmp_path`, never use `NamedTemporaryFile` (causes Windows file contention).
+- Always call `.resolve()` on Path objects to ensure absolute paths and resolve symlinks.
+- Use `.as_posix()` when converting resolved paths to strings (normalizes to forward slashes).
+- Any new feature or bug fix that can be tested automatically must have test cases.
+- If changes affect existing test expectations, update the tests accordingly. Tests must always pass after changes.

.gitignore

@@ -258,6 +258,10 @@ WARP.MD
 .mcp.json
 .tessl/
 tessl.json
+
+# Claude Code - track shared rules, ignore local config
+.claude/*
+!.claude/rules/
 **/node_modules/**
 **/dist-nuitka/**
 **/.npmrc

CLAUDE.md

@@ -33,55 +33,6 @@ uv run codeflash init            # Initialize in a project
 uv run codeflash --all           # Optimize entire codebase
 ```
 
-## Architecture
-
-```
-codeflash/
-├── main.py                 # CLI entry point
-├── cli_cmds/               # Command handling, console output (Rich)
-├── discovery/              # Find optimizable functions
-├── context/                # Extract code dependencies and imports
-├── optimization/           # Generate optimized code via AI
-│   ├── optimizer.py        # Main optimization orchestration
-│   └── function_optimizer.py  # Per-function optimization logic
-├── verification/           # Run deterministic tests (pytest plugin)
-├── benchmarking/           # Performance measurement
-├── github/                 # PR creation
-├── api/                    # AI service communication
-├── code_utils/             # Code parsing, git utilities
-├── models/                 # Pydantic models and types
-├── tracing/                # Function call tracing
-├── lsp/                    # IDE integration (Language Server Protocol)
-├── telemetry/              # Sentry, PostHog
-├── either.py               # Functional Result type for error handling
-└── result/                 # Result types and handling
-```
-
-### Key Rules to follow
-
-- Use libcst, not ast - For Python, always use `libcst` for code parsing/modification to preserve formatting.
-- Code context extraction and replacement tests must always assert for full string equality, no substring matching.
-- Any new feature or bug fix that can be tested automatically must have test cases.
-- If changes affect existing test expectations, update the tests accordingly. Tests must always pass after changes.
-- NEVER use leading underscores for function names (e.g., `_helper`). Python has no true private functions. Always use public names.
-
-## Code Style
-
-- **Line length**: 120 characters
-- **Python**: 3.9+ syntax
-- **Tooling**: Ruff for linting/formatting, mypy strict mode, prek for pre-commit checks
-- **Comments**: Minimal - only explain "why", not "what"
-- **Docstrings**: Do not add unless explicitly requested
-- **Naming**: NEVER use leading underscores (`_function_name`) - Python has no true private functions, use public names
-- **Paths**: Always use absolute paths, handle encoding explicitly (UTF-8)
-
-## Git Commits & Pull Requests
-
-- Use conventional commit format: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`
-- Keep commits atomic - one logical change per commit
-- Commit message body should be concise (1-2 sentences max)
-- PR titles should also use conventional format
-
 <!-- Section below is auto-generated by `tessl install` - do not edit manually -->
 
 # Agent Rules <!-- tessl-managed -->