codeflash/CLAUDE.md

# CLAUDE.md

## Project Overview

CodeFlash is an AI-powered code optimizer that automatically improves performance while maintaining correctness. It supports Python, JavaScript, TypeScript, Java with more languages planned. It uses LLMs to generate optimization candidates, verifies correctness through test execution, and benchmarks performance improvements.

## Optimization Pipeline

```
Discovery → Ranking → Context Extraction → Test Gen + Optimization → Baseline → Candidate Evaluation → PR
```

1. **Discovery** (`discovery/`): Find optimizable functions across the codebase
2. **Ranking** (`benchmarking/function_ranker.py`): Rank functions by addressable time using trace data
3. **Context** (`languages/<lang>/context/`): Extract code dependencies (read-writable code + read-only imports)
4. **Optimization** (`optimization/`, `api/`): Generate candidates via AI service, run in parallel with test generation
5. **Verification** (`verification/`): Run candidates against tests, compare outputs via custom pytest plugin
6. **Benchmarking** (`benchmarking/`): Measure performance, select best candidate by speedup
7. **Result** (`result/`, `github/`): Create PR with winning optimization

# Instructions
- **Bug fix workflow** — follow these steps in order, do not skip ahead:
  1. Read the relevant code to understand the bug
  2. Write a test that reproduces the bug (run it to confirm it fails)
  3. Spawn subagents (using the Agent tool) to attempt the fix — each subagent should apply a fix and run the test to prove it passes
  4. Review the subagent results, pick the best fix, and apply it
  5. Never jump straight to writing a fix yourself — always go through steps 1-4
- Everything that can be tested should have tests.

<!-- Section below is auto-generated by `tessl install` - do not edit manually -->

# Agent Rules <!-- tessl-managed -->

@.tessl/RULES.md follow the [instructions](.tessl/RULES.md)

@AGENTS.md