Claude Code Power-User Tips#

CLAUDE.md authoring#

CLAUDE.md is the highest-leverage investment in Claude Code. A good one turns Claude from a generic assistant into a teammate who already knows your project.

What to include#

# Project: <name>

## Stack (one line per component)
- Python 3.12, FastAPI, SQLAlchemy 2.0
- Postgres 16, Redis, Celery
- Deployed to AWS ECS via GitHub Actions

## Commands
- `make test` — run full test suite (pytest + mypy + ruff)
- `make dev` — start dev server with hot reload
- `make migration name=<name>` — create Alembic migration

## Key conventions
- Use `structlog` for all logging — no print()
- API responses always wrap in `{"data": ..., "meta": ...}`
- All public functions need docstrings and type hints
- Test files mirror source structure: `src/users/service.py` → `tests/users/test_service.py`

## Do not touch
- `alembic/versions/` — only `make migration` should create files here
- `config/production.yaml` — readonly; edit `config/development.yaml` instead

## Architecture notes
- `src/core/` — shared utilities, auth, logging config
- `src/api/` — FastAPI routers only; business logic goes in `src/services/`
- Tasks run in Celery workers in `src/workers/`

What not to include#

• Long prose explanations — Claude reads the code
• Boilerplate docs that repeat what’s in README
• File lists — Claude reads the directory tree
• Implementation details that live in the code

[!TIP] Think of CLAUDE.md as “things a new teammate would need to know in the first 30 minutes that they couldn’t figure out from the code alone.”

Team vs personal CLAUDE.md#

Commit CLAUDE.md to the repo for shared conventions. Use ~/.claude/CLAUDE.md for personal preferences (style, tone, shorthand). Subdir CLAUDE.md files are great for component-specific overrides:

project/
├── CLAUDE.md               # project-wide
├── frontend/
│   └── CLAUDE.md          # React conventions, component library notes
└── ml/
    └── CLAUDE.md          # Python conventions, GPU notes

Custom skills (slash commands)#

Skills let you encode repeatable workflows as named commands.

PR review skill#

# ~/.claude/commands/pr-review.md

Review the current git diff (staged + unstaged) as if it were a pull request.

Check for:
1. **Security** — hardcoded secrets, injection vulnerabilities, unvalidated input
2. **Correctness** — edge cases, null handling, off-by-one errors
3. **Performance** — N+1 queries, unnecessary loops, missing indexes
4. **Style** — consistency with surrounding code

Format:
- One section per category
- Flag only real issues, not style preferences
- For each issue: file:line, severity (Critical/Warning/Info), and a one-line fix suggestion

Deploy checklist skill#

# .claude/commands/predeploy.md

Run the pre-deploy checklist for this project:
1. Run `make test` — report pass/fail
2. Run `make lint` — report any violations
3. Check for any TODO/FIXME/HACK comments added in this branch vs main: `git diff main --unified=0 | grep -E '(TODO|FIXME|HACK)'`
4. Check that CHANGELOG.md has an entry for today's date
5. Report a final go/no-go with a one-line summary per check.

Quick refactor skill with arguments#

# ~/.claude/commands/extract.md

Extract the function or block described by "$ARGUMENTS" into its own well-named helper function.
Place the helper just above the call site. Add type hints. Do not change behavior.

Usage: /extract the date-parsing logic in process_invoice()

Multi-step workflow patterns#

Parallel research + write#

Claude Code supports multi-agent subagents. For large tasks, explicitly ask for parallel work:

> I need to add Redis caching to the user service. Research the existing 
  service patterns and our Redis config in parallel, then write the 
  implementation.

Iterative refinement#

> Step 1: write a first draft of the migration script
> Step 2: critique it for edge cases  
> Step 3: fix the issues you found

Breaking work into explicit steps produces better results than one large prompt because Claude can revise with full context.

Verification loop#

> Write the feature, then run `make test` and fix any failures before 
  reporting done.

This pattern — write → test → fix loop — is more reliable than asking Claude to write perfect code in one shot.

Cost control#

Model selection#

# Use Haiku for a quick summary task
claude --model claude-haiku-4-5-20251001 -p "Summarize the changes in the last 5 commits"

Scope your prompts#

# High cost — Claude reads entire codebase
> Refactor the project to use TypeScript

# Lower cost — explicit scope
> Refactor src/api/users.js to TypeScript. Keep the same exports.

Use /compact proactively#

Don’t wait for the context warning. Run /compact after completing a logical unit of work. This keeps the context window lean and reduces token usage on subsequent turns.

Check session cost#

> /cost

Output:

Session cost: $0.23
  Input tokens:  48,320
  Output tokens: 6,140
  Cache hits:    31,200 (saves ~$0.09)

Prompt caching in headless mode#

When running Claude non-interactively with a large system prompt, add caching:

# First call writes cache; subsequent calls are ~90% cheaper
claude -p "Analyze this file for security vulnerabilities" < src/auth.py

Claude Code automatically uses prompt caching for repeated system prompts and tool definitions within a session.

Headless scripting patterns#

Pre-commit hook#

#!/bin/bash
# .git/hooks/pre-commit

STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|ts|js)$')
if [ -z "$STAGED" ]; then exit 0; fi

echo "$STAGED" | xargs cat | claude --allowedTools "" -p \
  "Review this code for security issues and obvious bugs. 
   If any Critical issues found, exit 1 and describe them. 
   If clean, output 'OK' and exit 0." \
  --output-format json | python3 -c "
import json, sys
r = json.load(sys.stdin)
text = r.get('result', '')
if 'Critical' in text:
    print(text)
    sys.exit(1)
print('Pre-commit check: OK')
"

CI code review#

# .github/workflows/ai-review.yml
- name: AI code review
  run: |
    git diff origin/main...HEAD | claude --allowedTools "" \
      -p "Review this diff for security vulnerabilities only. 
          Output JSON: {\"issues\": [{\"file\": \"\", \"line\": 0, \"desc\": \"\"}]}" \
      --output-format json > review.json
    python3 -c "
    import json
    r = json.load(open('review.json'))
    issues = r.get('issues', [])
    if issues:
        for i in issues: print(f'{i[\"file\"]}:{i[\"line\"]} {i[\"desc\"]}')
        exit(1)
    "

Automated documentation#

#!/bin/bash
# Generate API docs from source
for file in src/api/*.py; do
  claude --allowedTools "Read" \
    -p "Generate Markdown API documentation for this file. 
        Cover each public function: purpose, parameters, return value, example." \
    --output-format text < "$file" > "docs/api/$(basename $file .py).md"
done

Keyboard shortcuts reference#

Troubleshooting#

Claude keeps asking for permission for the same tools#

Add them to the allow list in settings.json:

{"permissions": {"allow": ["Bash(npm test:npm run lint)"]}}

Context fills up fast on large repos#

1. Add a .claudeignore file (same syntax as .gitignore) to exclude generated files, build outputs, and large assets.
2. Use explicit file paths in prompts instead of broad descriptions.
3. Run /compact more aggressively.

Slow on first run per session#

Claude Code re-reads CLAUDE.md files and does directory scanning at session start. This is normal. Subsequent turns within the same session are faster because context is already loaded.

Hooks not firing#

1. Check file is executable: chmod +x /path/to/hook.sh
2. Use absolute paths in settings.json — ~ is not expanded in all contexts
3. Test manually: CLAUDE_TOOL_NAME="Bash" CLAUDE_TOOL_INPUT='{"command":"ls"}' bash /path/to/hook.sh