# repo-CLAUDE.md

Behavioral guidelines specific to this repo. Loaded after org-CLAUDE.md. Org rules apply here too and cannot be overridden.

**Example file** from a fictional Python services repo. Adapt the stack names, paths, and shared boundaries to your codebase. The structure of the rules matters more than the specifics.

**Tradeoff:** These guidelines reflect what has broken in this codebase before. They are stricter than the org defaults in places where past incidents earned the strictness.

## 1. Use the Stack This Repo Already Uses

**Match the existing toolchain. Do not introduce alternatives.**

- Tests use pytest. If you see unittest or nose in a file, flag it. Do not write new tests in those frameworks.
- Tests follow the `given_when_then` naming convention.
- HTTP calls go through `internal/http`. Direct use of `requests` or `httpx` is not allowed.
- Database access goes through `data/repositories/`. No raw SQL in business logic.
- Configuration reads from `config/settings.py`. Do not read environment variables anywhere else.

## 2. Surgical Changes in This Codebase

**Change the function with the bug and its direct callers. Stop there.**

- Do not refactor adjacent code, even if it looks improvable.
- Prefer extending an existing module over creating a new one. A new module requires a one-line justification in the PR description.
- If the task touches `data/repositories/`, run the integration test suite locally before opening the PR. The suite takes 8 minutes. Do not skip it.

## 3. Respect Shared Service Boundaries

**`services/billing/` is consumed by 3 other repos. Coordinate before changing its public interface.**

- Any change to the public API of `services/billing/` requires the consuming repo owners to be tagged on the PR before merge.
- Database migrations require platform team review. Open a draft PR with the migration first. Wait for review before writing code that depends on it.

## 4. Verify Before Implementing

**Prove the expected behavior before changing code.**

- For bug fixes, write a failing test that reproduces the bug first.
- For new behavior, write a test that defines the success criterion first.
- If no meaningful test can be written, ask what success looks like before changing code.

**For refactors, prove behavior stayed the same before changing structure.**

Run existing tests around the affected behavior first. If coverage is weak, add characterization tests before refactoring. Then refactor. After the change, run the same tests again.

Do not change behavior during a refactor unless the task explicitly asks for it.

If the refactor touches a shared surface, including an API contract, database access, authentication, payment, or PII handling, open a draft PR and request human review before merge.

## 5. When Engineer and Repo Files Conflict

**Repo rules win for anything affecting shared code. Engineer files cover personal workflow only.**

If an engineer-level rule appears to contradict a rule above, follow this file. Raise the conflict so the engineer's file can be corrected.