cchb: Instructions file for Claude Code

CLAUDE.md

Common Commands

make verify                                  # cargo fmt --check + clippy (all-targets, -D warnings) + test
cargo test <name>                            # run tests matching a name substring
cargo clippy --all-targets -- -D warnings    # the exact clippy gate used by verify/release
make release BUMP=patch|minor|major          # bump Cargo.toml, commit, tag vX.Y.Z, push

• make release requires an interactive TTY and refuses non-interactive runs. It runs the quality gates, commits the bump (including Cargo.lock), tags, and pushes; the Release workflow then builds binaries for three targets, creates the GitHub Release, publishes to crates.io, and updates the Homebrew tap.
• Release precondition (ADR-0004): the tag must equal Cargo.toml's version — CI's verify-version job fails the release otherwise.
• Project structure: see "Module Architecture" in docs/SPECIFICATION.md. Reference it there; do not duplicate it in this file.

Development Rules

Context First

• Always read docs/ directory first to understand the current specification and project context before starting any work
• This ensures all changes are aligned with the documented design

Specification Changes

• When any specification change occurs, always update docs/SPECIFICATION.md first
• Confirm the updated specification with the user before proceeding with implementation
• Do not implement changes that deviate from the documented specification without approval

Development Methodology

• Follow TDD (Test-Driven Development) strictly, regardless of change size
  1. Write failing tests first (Red)
  2. Run cargo test to confirm the tests fail (Red confirmation)
  3. Implement minimum code to pass tests (Green)
  4. Run cargo test to confirm the tests pass (Green confirmation)
  5. Refactor while keeping tests green (Refactor)
• Never skip writing tests before implementation
• Never skip confirming test failure/success at each step
• "Obviously correct" is not an excuse to skip the cycle