mirror of
https://github.com/codeflash-ai/codeflash.git
synced 2026-05-04 18:25:17 +00:00
Merge branch 'main' into update-extension-docs
This commit is contained in:
mashraf-222
GitHub
commit
83058129fc
3 changed files with 93 additions and 78 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -258,5 +258,4 @@ WARP.MD
|
|||
|
||||
.mcp.json
|
||||
.tessl/
|
||||
CLAUDE.md
|
||||
tessl.json
|
||||
|
|
|
|||
77
AGENTS.md
77
AGENTS.md
|
|
@ -1,77 +0,0 @@
|
|||
# CodeFlash AI Agent Instructions
|
||||
|
||||
## Project Overview
|
||||
|
||||
CodeFlash is an AI-powered Python code optimizer that automatically improves code performance while maintaining correctness.
|
||||
|
||||
## 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
|
||||
├── 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
|
||||
├── telemetry/ # Sentry, PostHog
|
||||
└── either.py # Functional error handling
|
||||
```
|
||||
|
||||
## Critical Development Patterns
|
||||
|
||||
### Use uv, NEVER pip
|
||||
**NEVER use `pip install` or `pip` commands.** This project uses `uv` exclusively for package management.
|
||||
```bash
|
||||
uv sync # Install dependencies (NOT pip install -r requirements.txt)
|
||||
uv sync --group dev # Dev dependencies (NOT pip install -e .)
|
||||
uv run pytest # Run commands (NOT python -m pytest)
|
||||
uv add package # Add packages (NOT pip install package)
|
||||
```
|
||||
|
||||
### Use libcst, not ast
|
||||
Always use `libcst` for code parsing/modification to preserve formatting.
|
||||
|
||||
### Use Either pattern for errors
|
||||
```python
|
||||
from codeflash.either import is_successful
|
||||
result = aiservice_client.call_llm(...)
|
||||
if is_successful(result):
|
||||
optimized_code = result.value
|
||||
else:
|
||||
error = result.error
|
||||
```
|
||||
|
||||
### Git worktree isolation
|
||||
Optimizations run in isolated worktrees:
|
||||
```python
|
||||
from codeflash.code_utils.git_worktree_utils import create_detached_worktree, remove_worktree
|
||||
```
|
||||
|
||||
## 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 (e.g., `fix: resolve base class dependency tracking`)
|
||||
|
||||
## Code Style & Conventions
|
||||
|
||||
- **Tooling**: Ruff for linting/formatting, mypy strict mode, pre-commit hooks
|
||||
- **Line length**: 120 characters
|
||||
- **Python**: 3.9+ syntax
|
||||
- **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)
|
||||
|
||||
# Agent Rules <!-- tessl-managed -->
|
||||
|
||||
@.tessl/RULES.md follow the [instructions](.tessl/RULES.md)
|
||||
93
CLAUDE.md
Normal file
93
CLAUDE.md
Normal file
|
|
@ -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)
|
||||
Loading…
Reference in a new issue