claude-howto: Instructions file for Claude Code

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 (renders Mermaid with Pele — needs Node.js >= 20; the pinned bundle downloads once, then works offline)
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 doc checks on .md changes: markdown-lint, cross-references, mermaid-syntax, link-check, markdown-rendering. All must pass. The EPUB build is not a pre-commit hook — it runs in CI only (build-epub job in .github/workflows/test.yml), because it is a slow full-book build; the mermaid-syntax hook already renders every diagram with the same Pele bundle.

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 render with Pele. The pre-commit mermaid hooks get Node.js 22 from pre-commit and run strict, so they fail instead of skipping; the first run needs network to download Node.js and the pinned Pele bundle (offline: SKIP=mermaid,vietnamese-mermaid,japanese-mermaid). Run by hand, scripts/check_mermaid.py only warns without Node.js >= 20, and fails under --strict or in CI. A broken EPUB build is usually invalid Mermaid, a missing Node.js >= 20, or a failed bundle download.
• 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.