Merge pull request #1121 from codeflash-ai/claude-MD

bring Claude.md in

Author: KRRT7

.gitignore

@@ -258,5 +258,4 @@ WARP.MD
 
 .mcp.json
 .tessl/
-CLAUDE.md
 tessl.json

AGENTS.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CodeFlash is an AI-powered Python code optimizer that automatically improves code performance while maintaining correctness. It uses LLMs to generate optimization candidates, verifies correctness through test execution, and benchmarks performance improvements.
+
+## Common Commands
+
+```bash
+# Package management (NEVER use pip)
+uv sync                          # Install dependencies
+uv sync --group dev              # Install dev dependencies
+uv add <package>                 # Add a package
+
+# Running tests
+uv run pytest tests/             # Run all tests
+uv run pytest tests/test_foo.py  # Run specific test file
+uv run pytest tests/test_foo.py::test_bar -v  # Run single test
+
+# Type checking and linting
+uv run mypy codeflash/           # Type check
+uv run ruff check codeflash/     # Lint
+uv run ruff format codeflash/    # Format
+
+# Pre-commit (run before committing)
+uv run pre-commit run --all-files
+
+# Running the CLI
+uv run codeflash --help
+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 Patterns
+
+**Either/Result pattern for errors:**
+```python
+from codeflash.either import is_successful, Success, Failure
+result = some_operation()
+if is_successful(result):
+    value = result.unwrap()
+else:
+    error = result.failure()
+```
+
+**Use libcst, not ast** - Always use `libcst` for code parsing/modification to preserve formatting.
+
+## Code Style
+
+- **Line length**: 120 characters
+- **Python**: 3.9+ syntax
+- **Tooling**: Ruff for linting/formatting, mypy strict mode, pre-commit hooks
+- **Comments**: Minimal - only explain "why", not "what"
+- **Docstrings**: Do not add unless explicitly requested
+- **Naming**: Prefer public functions (no leading underscore) - Python doesn't have true private functions
+- **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 <!-- tessl-managed -->
+
+@.tessl/RULES.md follow the [instructions](.tessl/RULES.md)