CLAUDE.md

1# CLAUDE.md
2 
3Tutorial repo. Output is markdown in numbered modules `01-` through `10-`, not an app. Scripts in `scripts/` exist only to validate docs and build the EPUB.
4 
5See also `.claude/CLAUDE.md` for stack/commands and `STYLE_GUIDE.md` for lesson structure.
6 
7## Critical commands
8 
9```bash
10# Quality gate (also runs on commit via pre-commit hooks)
11pre-commit run --all-files
12 
13# Tests
14pytest scripts/tests/ -v
15 
16# EPUB build (calls Kroki.io API to render Mermaid — needs network)
17uv run scripts/build_epub.py
18 
19# Python tooling
20ruff check scripts/ && ruff format scripts/
21mypy scripts/ --ignore-missing-imports
22bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
23```
24 
25Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-check, build-epub (on `.md` changes). All must pass.
26 
27## Architecture map
28 
29- `01-` … `10-` — tutorial modules. **Numbered prefix = learning order**, not alphabetical. Do not reorganize.
30- Each module: `README.md` + copy-paste templates (`.md`, `.json`, `.sh`).
31- `scripts/` — utilities (EPUB builder, link/mermaid/cross-ref validators). Not the product.
32- `02-memory/*.md` — CLAUDE.md templates users copy into their own projects. Don't confuse with this file.
33- `openspec/` — spec-driven change proposals.
34 
35## Hard rules
36 
37- **YOU MUST NOT commit or push without explicit user request.**
38- **YOU MUST NOT add `Co-Authored-By: Claude`** to any commit message.
39- Always activate `.venv` before running Python scripts (check `venv/`, `.venv/`, `env/`).
40- Internal links use **relative paths** (e.g. `01-slash-commands/README.md`); anchors use `#heading-name`.
41- Code fences **must** declare a language (`bash`, `python`, `json`, …) — the cross-reference check fails otherwise.
42- External URLs must be reachable and stable. No ephemeral links.
43- Mermaid diagrams must parse (validated pre-commit). Broken EPUB build is usually invalid Mermaid or no network to Kroki.
44- Commit format: `type(scope): subject` where `scope` matches the module folder (e.g. `feat(slash-commands):`, `docs(memory):`, `fix(README):`).
45- Do not reorganize the `01-`–`10-` numbering. The order is the curriculum.
46 
47## Workflow preferences
48 
49- For lesson edits, follow `STYLE_GUIDE.md` for structure/naming/diagrams.
50- Small fixes → minimal diff. Don't rewrite a section to fix a typo.
51- When adding a module page: README + templates first, then update root `README.md` index and `LEARNING-ROADMAP.md` if order/timing changes.
52- Tutorial > library: prioritize clear explanations and copy-paste examples over reusable abstractions.
53- If a quality check fails, fix the underlying issue. Don't bypass with `--no-verify`.
54 
55## Token Efficiency
56- Never re-read files you just wrote or edited. You know the contents.
57- Never re-run commands to "verify" unless the outcome was uncertain.
58- Don't echo back large blocks of code or file contents unless asked.
59- Batch related edits into single operations. Don't make 5 edits when 1 handles it.
60- Skip confirmations like "I'll continue..." Just do it.
61- If a task needs 1 tool call, don't use 3. Plan before acting.
62- Do not summarize what you just did unless the result is ambiguous or you need additional input.
63