CLAUDE.md

Tutorial 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.

See also .claude/CLAUDE.md for stack/commands and STYLE_GUIDE.md for lesson structure.

Critical commands

# Quality gate (also runs on commit via pre-commit hooks)
pre-commit run --all-files

# Tests
pytest scripts/tests/ -v

# EPUB build (calls Kroki.io API to render Mermaid — needs network)
uv run scripts/build_epub.py

# Python tooling
ruff check scripts/ && ruff format scripts/
mypy scripts/ --ignore-missing-imports
bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/

Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-check, build-epub (on .md changes). All must pass.

Architecture map

01- … 10- — tutorial modules. Numbered prefix = learning order, not alphabetical. Do not reorganize.
Each module: README.md + copy-paste templates (.md, .json, .sh).
scripts/ — utilities (EPUB builder, link/mermaid/cross-ref validators). Not the product.
02-memory/*.md — CLAUDE.md templates users copy into their own projects. Don't confuse with this file.
openspec/ — spec-driven change proposals.

Hard rules

YOU MUST NOT commit or push without explicit user request.
YOU MUST NOT add Co-Authored-By: Claude to any commit message.
Always activate .venv before running Python scripts (check venv/, .venv/, env/).
Internal links use relative paths (e.g. 01-slash-commands/README.md); anchors use #heading-name.
Code fences must declare a language (bash, python, json, …) — the cross-reference check fails otherwise.
External URLs must be reachable and stable. No ephemeral links.
Mermaid diagrams must parse (validated pre-commit). Broken EPUB build is usually invalid Mermaid or no network to Kroki.
Commit format: type(scope): subject where scope matches the module folder (e.g. feat(slash-commands):, docs(memory):, fix(README):).
Do not reorganize the 01-–10- numbering. The order is the curriculum.

Workflow preferences

For lesson edits, follow STYLE_GUIDE.md for structure/naming/diagrams.
Small fixes → minimal diff. Don't rewrite a section to fix a typo.
When adding a module page: README + templates first, then update root README.md index and LEARNING-ROADMAP.md if order/timing changes.
Tutorial > library: prioritize clear explanations and copy-paste examples over reusable abstractions.
If a quality check fails, fix the underlying issue. Don't bypass with --no-verify.

Token Efficiency

Never re-read files you just wrote or edited. You know the contents.
Never re-run commands to "verify" unless the outcome was uncertain.
Don't echo back large blocks of code or file contents unless asked.
Batch related edits into single operations. Don't make 5 edits when 1 handles it.
Skip confirmations like "I'll continue..." Just do it.
If a task needs 1 tool call, don't use 3. Plan before acting.
Do not summarize what you just did unless the result is ambiguous or you need additional input.

3.1 KiB Raw Permalink Blame History Unescape Escape