# Claude Code Efficiency Guide

This file is read automatically by Claude Code at the start of every session.
It teaches Claude to work efficiently on large codebases and avoid running out
of usage mid-task.

## Finding Errors in Large Codebases

When asked to find or fix errors, bugs, or issues across the codebase:

1. **Run the scanner first.** Execute: `python scan.py`
   This runs the project's linters, tests, and type checkers in seconds.
   It uses zero AI tokens — it's just running tools and collecting output.
2. **Read the scanner output.** It tells you exactly which files have errors
   and what the errors are, with line numbers.
3. **Go straight to fixing.** Only read the files the scanner identified.
   Do NOT read the entire codebase to "understand it" — that wastes tokens.

## Working on Large Tasks

When a task will touch more than 5 files or require significant changes:

### Plan before you code
Before writing any code, briefly list:
- Which files need to change
- What order to change them in
- How to verify each change

### Commit after each logical unit
Make a git commit after each meaningful piece of work. This creates save points.
If the session ends unexpectedly, the work so far is preserved.

### Stay focused
- Use grep/search to find what you need — don't read whole files for one function
- Read specific line ranges, not entire large files
- Don't re-read files you already read in this session
- Don't explore "for context" — go straight to the files that need changing

### If you're running low on usage
If you sense the task is too large to finish in this session:

1. **Commit everything done so far**
2. **Create `.claude-handoff.md`** in the repo root containing:
   - What was completed (with commit hashes if possible)
   - What still needs to be done, in order
   - Any gotchas, edge cases, or context the next session needs
   - Which files still need changes
3. **Tell the user** what was completed and that the handoff file is ready

The user can then start a new session and say:
"Continue the work described in .claude-handoff.md"

## Project-Specific Commands

Customize these for your project. Uncomment and edit as needed:

```
# Run tests:        npm test / pytest / cargo test / go test ./...
# Lint:             npm run lint / ruff check . / cargo clippy
# Build:            npm run build / cargo build / go build ./...
# Type check:       npx tsc --noEmit / mypy .
```