# CLAUDE.md

Behavioral guidelines for {{PROJECT_NAME}}. Pair with [ATLAS.md](ATLAS.md) and [SKILL.md](.agents/skill/{{PROJECT_NAME}}/SKILL.md).

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.

If you write 200 lines and it could be 50, rewrite it.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.

The test: every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

| Vague | Concrete |
|---|---|
| "Add validation" | "Write tests for invalid inputs, then make them pass" |
| "Fix the bug" | "Write a test that reproduces it, then make it pass" |
| "Refactor X" | "Existing tests pass before and after" |

## 5. ATLAS hygiene

- Read [`ATLAS.md`](ATLAS.md) §0 before exploring.
- Cite [`SKILL.md`](.agents/skill/{{PROJECT_NAME}}/SKILL.md) anchors in commit messages.
- Update ATLAS.md in the same commit as structural changes.
- No AI-assistant attribution in commits.

---

**Working when:** fewer unnecessary diff changes, fewer rewrites from overcomplication, clarifying questions come before implementation rather than after mistakes.

*Inspired by Karpathy's [behavioral-LLM-guidelines](https://github.com/multica-ai/andrej-karpathy-skills). Part of [ATLAS](https://github.com/Abbasi-Alain/atlas).*
