mirror of
https://github.com/codeflash-ai/codeflash-internal.git
synced 2026-05-04 18:25:18 +00:00
docs: restructure CLAUDE.md files into modular rules
Slim down CLAUDE.md files and move content into path-scoped .claude/rules/ files to reduce context bloat.
This commit is contained in:
Kevin Turcios
parent
e75d105b35
commit
c13835963c
10 changed files with 127 additions and 215 deletions
54
.claude/rules/aiservice.md
Normal file
54
.claude/rules/aiservice.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
paths:
|
||||
- "django/**"
|
||||
---
|
||||
# AIService (Django-Ninja Backend)
|
||||
|
||||
## Important
|
||||
|
||||
NEVER start, restart, or manage the dev server (uvicorn, nohup, background processes). The developer will run services manually.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
uv sync # Install dependencies
|
||||
uv run uvicorn aiservice.asgi:application --reload # Dev server
|
||||
uv run pytest # Run all tests
|
||||
uv run pytest tests/path/test_file.py::test_name -v # Single test
|
||||
uv run mypy . # Type check
|
||||
uv run ty check # Type check (ty)
|
||||
uv run ruff check . # Lint
|
||||
uv run ruff format . # Format
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
- All endpoints are `async def` — runs under ASGI via uvicorn
|
||||
- Django-Ninja with Pydantic schemas. APIs defined in `aiservice/urls.py`
|
||||
- Use Pydantic `BaseModel` or `ninja.Schema` for all request/response types
|
||||
- Use `aiservice/llm.py` for LLM calls — never call provider APIs directly
|
||||
- Prompts stored as `.md` files alongside their modules
|
||||
- Always use `libcst` for code transformation, never `ast` (preserves formatting)
|
||||
- Use `asyncio.TaskGroup` for concurrent operations
|
||||
|
||||
## Multi-Language Handlers
|
||||
|
||||
`core/languages/` has per-language modules registering via `core/registry`. Routers in `core/shared/` dispatch by `language` field. To add a language: create `core/languages/<lang>/`, register in `__init__.py`, implement protocol methods.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- No automatic exception handling — use `get_object_or_404` explicitly
|
||||
- Auth: `HttpBearer` before `django_auth` to avoid CSRF errors
|
||||
- Lazy imports in routers to avoid circular dependencies
|
||||
|
||||
## Testing
|
||||
|
||||
- Tests in `tests/` by feature: `optimizer/`, `testgen/`, `integration/`, `validators/`
|
||||
- `@pytest.mark.asyncio` for async tests
|
||||
- Factories: `create_optimizer_context()`, `create_refiner_context()`
|
||||
|
||||
## Style
|
||||
|
||||
- 120 char line length, Python 3.12+
|
||||
- Minimal comments — explain "why" not "what"
|
||||
- No docstrings unless requested
|
||||
15
.claude/rules/architecture.md
Normal file
15
.claude/rules/architecture.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
# Service Architecture
|
||||
|
||||
```
|
||||
VSC-Extension / CLI → cf-api (Express, :3001) → aiservice (Django-Ninja, :8000)
|
||||
cf-webapp (:3000) reads from the same PostgreSQL DB via Prisma
|
||||
```
|
||||
|
||||
## Glossary
|
||||
|
||||
- **Optimization Candidate** — LLM-generated code that may be faster
|
||||
- **Read-Write Context** — code the LLM can modify
|
||||
- **Read-Only Context** — code provided as info only (not modified)
|
||||
- **Tracer** — collects input args for a Python function at runtime
|
||||
- **Replay Test** — reruns traced inputs to verify behavior
|
||||
- **Comparator** — compares two Python objects for equality
|
||||
13
.claude/rules/cf-webapp.md
Normal file
13
.claude/rules/cf-webapp.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
paths:
|
||||
- "js/cf-webapp/**"
|
||||
---
|
||||
# Next.js Patterns (cf-webapp)
|
||||
|
||||
- Default to server components. `"use client"` only for interactivity/state/browser APIs. Push client boundaries as low in the tree as possible
|
||||
- Server actions go in files with `"use server"` at the top — never define inside client components
|
||||
- Props passed from server → client must be JSON-serializable (no functions or class instances)
|
||||
- Prisma queries go in server components. Client components fetch via API or receive data as props
|
||||
- Path alias: `@/*` → `./src/*`
|
||||
- Tree-sitter WASM files in `public/` built by `postinstall` — don't delete
|
||||
- `@codeflash-ai/common` must be in `transpilePackages` (top-level await)
|
||||
4
.claude/rules/git.md
Normal file
4
.claude/rules/git.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
# Git
|
||||
|
||||
- Always create a new branch from `main` — never commit directly to `main`
|
||||
- Conventional commits: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`
|
||||
27
.claude/rules/js-packages.md
Normal file
27
.claude/rules/js-packages.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
paths:
|
||||
- "js/**"
|
||||
---
|
||||
# JS/TS Packages
|
||||
|
||||
NEVER start, restart, or manage dev servers (npm run dev, node, nohup, background processes). The developer will run services manually.
|
||||
|
||||
All use ESLint + Prettier. Run commands from each package directory.
|
||||
|
||||
## Prisma
|
||||
|
||||
Schema lives in `common/prisma/schema.prisma`, shared by cf-api and cf-webapp. `common` is CommonJS — use `require`-style imports when working with it directly. Published as `@codeflash-ai/common` to GitHub Packages.
|
||||
|
||||
## Package Gotchas
|
||||
|
||||
### cf-api
|
||||
- Webhook routes MUST be registered before body parser (raw body needed for signature verification)
|
||||
- `instrument.ts` must be imported first in entry point (Sentry init)
|
||||
- Tests use dependency injection: `setXxxDependencies()` / `resetXxxDependencies()`
|
||||
|
||||
### VSC-Extension
|
||||
- **Different prettier config**: 80 width + semicolons (vs 100/no-semi elsewhere)
|
||||
- npm workspaces for local `@codeflash/*` packages
|
||||
- Sidebar is a separate Vite/React app embedded via webview postMessage
|
||||
- `acquireVsCodeApi()` called once per session — store and reuse
|
||||
- esbuild excludes `vscode` module (provided by runtime)
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
---
|
||||
paths:
|
||||
- "js/cf-webapp/**"
|
||||
---
|
||||
# Next.js Patterns (cf-webapp)
|
||||
|
||||
- Default to server components. Only use `"use client"` when the component needs interactivity, state, or browser-only APIs. Push client boundaries as low in the tree as possible.
|
||||
- Server actions go in files with `"use server"` at the top — never define them inside client components.
|
||||
- Props passed from server → client components must be JSON-serializable (no functions or class instances).
|
||||
- Use the `@/*` path alias for imports, not relative paths.
|
||||
- Prisma queries go in server components. Client components fetch via API or receive data as props.
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
---
|
||||
paths:
|
||||
- "django/**/*.py"
|
||||
---
|
||||
# Python Patterns (aiservice)
|
||||
|
||||
- Always use `libcst` for code transformation, never `ast` (preserves formatting and comments)
|
||||
- All endpoints are async — use `async def` and `asyncio.TaskGroup` for concurrency
|
||||
- Use Pydantic `BaseModel` or `ninja.Schema` for all request/response types
|
||||
- Use `call_llm()` from `aiservice/llm.py` for all LLM calls — never call OpenAI/Anthropic APIs directly
|
||||
- Django-Ninja has no built-in exception handling — use `get_object_or_404` and custom error responses explicitly
|
||||
46
CLAUDE.md
46
CLAUDE.md
|
|
@ -1,45 +1,5 @@
|
|||
# Claude Code Instructions
|
||||
# Codeflash Internal
|
||||
|
||||
## Monorepo Structure
|
||||
Monorepo: `django/aiservice` (Python backend), `js/` (cf-api, cf-webapp, common, VSC-Extension), `cli/`, `deployment/`, `experiments/`.
|
||||
|
||||
```
|
||||
codeflash-internal/
|
||||
├── django/aiservice/ # Python backend — Django-Ninja API for LLM optimization
|
||||
├── js/
|
||||
│ ├── cf-api/ # Express API — GitHub webhooks, PR analysis, DB ops
|
||||
│ ├── cf-webapp/ # Next.js 14 — Dashboard UI
|
||||
│ ├── common/ # Shared library — Prisma schema, types, integrations
|
||||
│ └── VSC-Extension/ # VS Code extension — in-editor optimization
|
||||
├── cli/ # Java/Gradle — sample code-to-optimize for testing
|
||||
├── deployment/ # Unified Docker container (on-prem) + Azure configs
|
||||
└── experiments/ # R&D — Jupyter notebooks, analysis scripts
|
||||
```
|
||||
|
||||
## Service Architecture
|
||||
|
||||
```
|
||||
VSC-Extension / CLI → cf-api (Express, :3001) → aiservice (Django-Ninja, :8000)
|
||||
cf-webapp (:3000) reads from the same PostgreSQL DB via Prisma
|
||||
```
|
||||
|
||||
## Shared Tooling
|
||||
|
||||
- **Python**: Use `uv` for dependency management and script execution. Never use `pip`.
|
||||
- **JavaScript**: Use `npm` for all JS packages.
|
||||
- **Pre-commit**: `uv run prek run --all-files` from repo root.
|
||||
|
||||
## Git Commits
|
||||
|
||||
- **Always create a new branch from `main` before starting any new work** — never commit directly to `main` or reuse an existing feature branch for unrelated changes
|
||||
- Use conventional commit format: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`
|
||||
|
||||
## Glossary
|
||||
|
||||
- **Function to Optimize** — target function for optimization
|
||||
- **Optimization Candidate** — LLM-generated code that may be faster
|
||||
- **Read-Write Context** — code the LLM can modify
|
||||
- **Read-Only Context** — code provided as info only (not modified)
|
||||
- **Tracer** — collects input args for a Python function at runtime
|
||||
- **Replay Test** — reruns traced inputs to verify behavior
|
||||
- **Inspired Regression Test** — new tests generated by the LLM from existing tests + function code
|
||||
- **Comparator** — compares two Python objects for equality
|
||||
Pre-commit: `uv run prek run --all-files` from repo root.
|
||||
|
|
|
|||
|
|
@ -1,73 +1,3 @@
|
|||
# AIService — Claude Code Instructions
|
||||
# AIService
|
||||
|
||||
## Project Overview
|
||||
|
||||
Django-Ninja backend powering CodeFlash's AI-driven code optimization. Handles LLM interactions, test generation, and optimization workflows. Runs under ASGI via uvicorn — all endpoints must be `async def`.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
uv sync
|
||||
uv sync --group dev
|
||||
|
||||
# Run development server
|
||||
uv run uvicorn aiservice.asgi:application --reload
|
||||
|
||||
# Run all tests
|
||||
uv run pytest
|
||||
|
||||
# Run a single test file
|
||||
uv run pytest tests/optimizer/test_optimizer.py
|
||||
|
||||
# Run a specific test
|
||||
uv run pytest tests/optimizer/test_optimizer.py::test_function_name -v
|
||||
|
||||
# Type checking
|
||||
uv run mypy .
|
||||
uv run ty check
|
||||
|
||||
# Linting (auto-fixes enabled)
|
||||
uv run ruff check .
|
||||
uv run ruff format .
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
All REST endpoints use Django-Ninja with type-safe Pydantic schemas. APIs are defined in `aiservice/urls.py`. Always use `aiservice/llm.py` for LLM calls — never call provider APIs directly.
|
||||
|
||||
LLM prompts are stored as `.md` files alongside their modules (e.g., `optimizer/system_prompt.md`).
|
||||
|
||||
### Multi-Language Handler System
|
||||
|
||||
`core/languages/` has per-language modules (python, js_ts, java) that register handlers via `core/registry`. Each handler implements protocols from `core/protocols/`. Routers in `core/shared/` dispatch to the correct handler based on the `language` field in the request schema.
|
||||
|
||||
To add a new language: create a handler in `core/languages/<lang>/`, register it in `__init__.py`, implement the required protocol methods.
|
||||
|
||||
## Key Patterns
|
||||
|
||||
- **libcst, not ast**: Always use `libcst` to preserve formatting when modifying code.
|
||||
- **Pydantic schemas**: All request/response models use Pydantic BaseModel or ninja.Schema.
|
||||
- **Async + TaskGroup**: Most endpoints are async. Use `asyncio.TaskGroup` for concurrent operations.
|
||||
- **Context classes**: Optimizer and testgen use context classes (`BaseOptimizerContext`, `BaseTestGenContext`) to manage state and prompts.
|
||||
- **Lazy imports in routers**: Routers use imports inside function bodies to avoid circular dependencies.
|
||||
|
||||
## Django-Ninja Gotchas
|
||||
|
||||
- No automatic exception handling like DRF — use `get_object_or_404` explicitly.
|
||||
- Error handling requires custom code (no built-in exception-to-response mapping).
|
||||
- Auth: `HttpBearer` must come before `django_auth` in auth lists to avoid CSRF errors.
|
||||
|
||||
## Testing
|
||||
|
||||
- Tests live in `tests/` organized by feature: `optimizer/`, `testgen/`, `integration/`, `validators/`
|
||||
- Root `conftest.py` for shared fixtures
|
||||
- Use `@pytest.mark.asyncio` for async endpoint tests
|
||||
- Helper factories in test files: `create_optimizer_context()`, `create_refiner_context()`
|
||||
|
||||
## Code Style
|
||||
|
||||
- **Line length**: 120 characters
|
||||
- **Python**: 3.12+ syntax
|
||||
- **Comments**: Minimal — explain "why", not "what"
|
||||
- **Docstrings**: Don't add unless explicitly requested
|
||||
Django-Ninja backend for CodeFlash's AI-driven code optimization. See `.claude/rules/aiservice.md` for patterns and conventions.
|
||||
|
|
|
|||
87
js/CLAUDE.md
87
js/CLAUDE.md
|
|
@ -1,81 +1,12 @@
|
|||
# JS Packages — Claude Code Instructions
|
||||
# JS Packages
|
||||
|
||||
## Overview
|
||||
Four TypeScript packages: cf-api, cf-webapp, common, VSC-Extension. See `.claude/rules/js-packages.md` for patterns and gotchas.
|
||||
|
||||
Four TypeScript packages. All use ESLint + Prettier. Run commands from each package directory.
|
||||
## Commands (run from each package directory)
|
||||
|
||||
## Commands
|
||||
|
||||
### cf-api (Express API — GitHub webhooks, PR analysis, DB ops)
|
||||
```bash
|
||||
npm run dev # Development server
|
||||
npm run build # Compile TypeScript
|
||||
npm test # Jest tests
|
||||
npm run lint # ESLint
|
||||
npm run type-check # TypeScript check
|
||||
npm run format # Prettier format
|
||||
npm run prisma:generate # Generate Prisma client
|
||||
npm run prisma:migrate # Run DB migrations
|
||||
```
|
||||
|
||||
### cf-webapp (Next.js dashboard UI)
|
||||
```bash
|
||||
npm run dev # Next.js dev server
|
||||
npm run build # Production build
|
||||
npm test # Vitest tests
|
||||
npm run lint # ESLint
|
||||
npm run type-check # TypeScript check
|
||||
npm run format # Prettier format
|
||||
```
|
||||
|
||||
### common (Shared Prisma schema, types, integrations)
|
||||
```bash
|
||||
npm run build # Generate Prisma + compile TypeScript
|
||||
npm run clean # Remove dist/
|
||||
npm run format # Prettier format
|
||||
```
|
||||
|
||||
### VSC-Extension (VS Code extension for in-editor optimization)
|
||||
```bash
|
||||
npm run dev # Watch mode (esbuild + tsc)
|
||||
npm run build # Full build (type-check + lint + bundle)
|
||||
npm run package # Production VSIX build
|
||||
npm test # VS Code test runner
|
||||
npm run lint # ESLint
|
||||
npm run check-types # TypeScript check
|
||||
npm run format # Prettier format
|
||||
```
|
||||
|
||||
## Key Patterns
|
||||
|
||||
- **Prisma schema** lives in `common/` and is shared by `cf-api` and `cf-webapp`
|
||||
- **TypeScript** is used in all packages. `cf-webapp` and `VSC-Extension` use strict mode.
|
||||
- **Formatting**: Prettier for all JS/TS code, ESLint for linting
|
||||
|
||||
## Inter-Package Dependencies
|
||||
|
||||
`common` is published to GitHub Packages as `@codeflash-ai/common`. Both `cf-api` and `cf-webapp` depend on it for Prisma client and shared types. `common` uses **CommonJS** (not ESM) — use `require`-style imports when working with it directly.
|
||||
|
||||
## Package-Specific Gotchas
|
||||
|
||||
### cf-api
|
||||
- Webhook routes MUST be registered before body parser (need raw body for signature verification)
|
||||
- `instrument.ts` must be imported first in entry point (Sentry initialization)
|
||||
- Tests use dependency injection: `setXxxDependencies()` / `resetXxxDependencies()` per endpoint
|
||||
|
||||
### cf-webapp
|
||||
- Default to server components. Only add `"use client"` for interactivity, state, or browser-only APIs.
|
||||
- Path alias: `@/*` maps to `./src/*` — use it instead of relative paths
|
||||
- Tree-sitter WASM files in `public/` are built by `postinstall` — don't delete them
|
||||
- `@codeflash-ai/common` must be in `transpilePackages` (uses top-level await)
|
||||
|
||||
### common
|
||||
- Prisma schema is in `prisma/schema.prisma`, not `src/`
|
||||
- Must run `npx prisma generate` before using — this is done automatically in the build script
|
||||
|
||||
### VSC-Extension
|
||||
- **Different prettier config**: 80 width + semicolons (vs 100/no-semi in other packages)
|
||||
- Uses npm workspaces for local `@codeflash/*` packages (types, shared, sidebar-webview)
|
||||
- Sidebar is a separate Vite/React app embedded via webview postMessage
|
||||
- `acquireVsCodeApi()` can only be called once per session — store and reuse the reference
|
||||
- esbuild excludes `vscode` module from bundle (it's provided by the runtime)
|
||||
| Package | Dev | Build | Test | Lint | Format |
|
||||
|---------|-----|-------|------|------|--------|
|
||||
| cf-api | `npm run dev` | `npm run build` | `npm test` | `npm run lint` | `npm run format` |
|
||||
| cf-webapp | `npm run dev` | `npm run build` | `npm test` | `npm run lint` | `npm run format` |
|
||||
| common | — | `npm run build` | — | — | `npm run format` |
|
||||
| VSC-Extension | `npm run dev` | `npm run build` | `npm test` | `npm run lint` | `npm run format` |
|
||||
|
|
|
|||
Loading…
Reference in a new issue