# CLAUDE.md

## Project

Python project. Customize this section with your own description, layout,
and conventions.

**Typical layout:**
- `src/<package>/` or a top-level package directory — importable code
- `tests/` — pytest tests mirroring the package layout
- `pyproject.toml` — dependencies, tool config (ruff, pytest, coverage)

## Build & Test Commands

If the project has a Makefile, document targets here. Common pattern:

```bash
make test                   # run the pytest suite
make test FILE=tests/x.py   # one file
make coverage               # suite + coverage report
make lint                   # ruff across the tree
make typecheck              # mypy (if the project adopts it)
make fmt                    # ruff format / black
```

Direct equivalents: `python3 -m pytest`, `pytest tests/test_x.py::test_name`,
`ruff check .`, `ruff format --diff .`, `mypy src/`.

## Language Rules

See rule files in `.claude/rules/`:
- `python-testing.md` — pytest conventions and fixture discipline
- `verification.md` — verify-before-claim-done discipline

## Git Workflow

Commit conventions: see `.claude/rules/commits.md` (author identity,
no AI attribution, message format).

Pre-commit hook in `githooks/` scans for secrets, syntax-checks staged Python,
and runs `ruff` when it's installed. Activate on a fresh clone with
`git config core.hooksPath githooks`.

## Problem-Solving Approach

Investigate before fixing. When diagnosing a bug:
1. Read the relevant module and trace what actually happens
2. Identify the root cause, not a surface symptom
3. Write a failing test that captures the correct behavior
4. Fix, then re-run tests

## Testing Discipline

TDD is the default: write a failing test before any implementation. If you can't
write the test, you don't yet understand the change. Details in
`.claude/rules/python-testing.md`.

## Editing Discipline

A PostToolUse hook syntax-checks every Python file after Edit/Write/MultiEdit
and blocks on a parse error, then runs `ruff` when it's installed. The hook
covers `.py`, `.pyi`, and extensionless files with a python shebang.

Type checking is not enforced by the hook — it needs the whole package and its
dependencies resolved, which is a build-scale operation rather than a
per-keystroke one. Run it via `make typecheck`.

Formatting is likewise not enforced: a project picks its own line length and
quote style, so blocking on an unconfigured default would impose a contested
choice. Adopt one per project in `pyproject.toml`.

## What Not to Do

- Don't add features beyond what was asked
- Don't refactor surrounding code when fixing a bug
- Don't use a bare `except:` or swallow an exception without handling it
- Don't use a mutable default argument (`def f(xs=[])`)
- Don't add comments to code you didn't change
- Don't commit `.env` files, credentials, or API keys — the pre-commit hook
  catches common patterns but isn't a substitute for care