Claude
4005de673d
When the user pastes a specific error (stack trace, build failure, "failed to execute X"), Claude now follows the error directly to the relevant files instead of exploring the whole codebase. https://claude.ai/code/session_01Fzv8baXnEVVhnrffAb3Ucc
80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# 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.
|
|
|
|
## When the User Pastes an Error Message
|
|
|
|
The user often arrives with a specific error they hit — a build failure, a
|
|
runtime crash, a stack trace, a "failed to execute X" message. When this happens:
|
|
|
|
1. **Read the error carefully.** The file names, line numbers, and error type
|
|
are already in the message. Don't go searching the whole codebase.
|
|
2. **Go directly to the file(s) mentioned in the error.** Read only those files,
|
|
and only the relevant sections (the function or area around the line number).
|
|
3. **Trace the cause.** If the error references an import, a missing variable,
|
|
or a function call, grep for that specific symbol — don't read surrounding
|
|
files "for context."
|
|
4. **Fix it, verify, commit.** After fixing, run the project's build/test
|
|
command (see Project-Specific Commands below) to confirm the fix works.
|
|
|
|
The key rule: **the error message IS your roadmap. Follow it, don't explore.**
|
|
|
|
## Finding Errors Across the Codebase
|
|
|
|
When asked to find or fix errors broadly (not a specific error message):
|
|
|
|
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 .
|
|
```
|