From ee5871d3d31cf681243fa2a5c524525a29ecaeda Mon Sep 17 00:00:00 2001 From: Kevin Turcios Date: Fri, 6 Feb 2026 02:12:27 -0500 Subject: [PATCH] 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 | 23 ++++++++++++++++ .claude/rules/code-style.md | 9 +++++++ .claude/rules/git.md | 6 +++++ .claude/rules/source-code.md | 11 ++++++++ .claude/rules/testing.md | 15 +++++++++++ .gitignore | 4 +++ CLAUDE.md | 49 ----------------------------------- 7 files changed, 68 insertions(+), 49 deletions(-) create mode 100644 .claude/rules/architecture.md create mode 100644 .claude/rules/code-style.md create mode 100644 .claude/rules/git.md create mode 100644 .claude/rules/source-code.md create mode 100644 .claude/rules/testing.md diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md new file mode 100644 index 000000000..a12144452 --- /dev/null +++ b/.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 +``` diff --git a/.claude/rules/code-style.md b/.claude/rules/code-style.md new file mode 100644 index 000000000..fcad0f253 --- /dev/null +++ b/.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) diff --git a/.claude/rules/git.md b/.claude/rules/git.md new file mode 100644 index 000000000..058e8ca80 --- /dev/null +++ b/.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 diff --git a/.claude/rules/source-code.md b/.claude/rules/source-code.md new file mode 100644 index 000000000..be7c74059 --- /dev/null +++ b/.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. diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md new file mode 100644 index 000000000..809a4ea91 --- /dev/null +++ b/.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. diff --git a/.gitignore b/.gitignore index 99219de86..b80ab3816 100644 --- a/.gitignore +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index 94ca7e6e0..fdc1b943b 100644 --- a/CLAUDE.md +++ b/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 - # Agent Rules