claude-rust-todo-tutorial

By @copyleftdev · MIT-licensed · git clone https://github.com/copyleftdev/claude-rust-todo-tutorial

A working reference for building production-grade Claude Code artifacts around a real Rust project.

This repo is a tutorial. The target program is a small axum + sqlx + sqlite todo API in app/. The point isn't the todo app — it's the .claude/, gates/, sweeps/, and drift/ directories around it. They show how the six artifact classes fit together in a realistic codebase:

Class	Lives in	What it is
Hooks	.claude/hooks/	Synchronous guards around tool calls — block or inject context
Agents	.claude/agents/	Specialized subagents with scoped tool access
Commands	.claude/commands/	Reusable parameterized slash commands
Gates	gates/	Pre-commit/CI blockers — git enforces these
Sweeps	sweeps/	Periodic read-only diagnostics that produce proposals
Drifts	drift/	Detectors that reconcile two representations of the same reality

Read docs/00-intro.md through docs/07-putting-it-together.md end-to-end — each chapter is short and pairs with a deliberately-broken example in tutorial-bait/.

Quickstart

# One-time: commit the baseline so the freeze-applied-migrations hook has
# something to enforce.
git add . && git commit -m "chore: baseline"

# Boot the app against a local sqlite
make build
make run                   # http://localhost:3000
curl http://localhost:3000/health

# Run the full ship pre-flight
make check                 # fmt + clippy + tests
make gates                 # pre-commit gates
make drifts                # drift detectors
make sweeps                # weekly-ish sweeps

# Install the gates as a git pre-commit hook
make install-hooks

# Scripted walkthrough of every artifact class
make demo

Prerequisites

Required:

• Rust (stable toolchain)
• sqlite3
• jq
• git
• Claude Code (to exercise hooks/agents/commands)

Optional (unlocks more checks):

• sqlx-cli — migration tooling
• cargo-deny — license/advisory gate
• cargo-outdated + cargo-audit — dep sweep

Layout

.
├── app/                     # The target program — axum + sqlx + sqlite todo API
│   ├── src/{main,lib,db,error,handlers,models}.rs
│   ├── migrations/          # sqlx-style versioned migrations
│   ├── openapi.yaml         # API contract — cross-checked by drift detector
│   └── tests/integration.rs # Real-sqlite integration tests, no mocks
├── .claude/
│   ├── settings.json        # Hooks + permissions
│   ├── hooks/               # 5 hooks covering Pre/Post tool use, prompts, stop
│   ├── agents/              # reviewer, migration-safety, cve-triage, openapi-drift
│   └── commands/            # /ship, /new-endpoint, /new-migration, /review, ...
├── gates/                   # clippy, cargo-deny, migration-linear, openapi-lock
├── sweeps/                  # todo, deps+CVE, dead-query
├── drift/                   # schema-vs-migrations, openapi-vs-handlers, settings-drift
├── docs/                    # 8 chapters — read in order
├── tutorial-bait/           # Deliberately-broken scenarios to trip each artifact
└── CLAUDE.md                # Orientation for Claude working in this repo

Using this repo as a template

Strip app/ and swap it for your project. Keep .claude/, gates/, sweeps/, drift/ — adapt the specifics:

• guard-bash.sh: change the cargo matchers to whatever your build tool is.
• freeze-applied-migrations.sh: change the app/migrations/ glob to your migration dir.
• openapi-*.sh and openapi-drift.md: if you don't have an OpenAPI spec, drop these; add equivalents for whatever contract you version (protobuf, GraphQL schema, etc).
• deny.toml: adjust the allowed licenses to your org's list.
• cve-triage.md: the vulngraph MCP tooling is generic — it works for any Cargo.lock, npm package-lock.json, pyproject lockfile, etc.

License

MIT — see LICENSE. © 2026 copyleftdev.

Suggested GitHub topic tags

When you publish the repo, add these as Topics (About → settings gear) — each one has real discovery traffic on GitHub search:

claude-code   claude   anthropic   claude-agent-sdk   mcp   model-context-protocol
rust   axum   sqlx   sqlite   tokio
tutorial   ai-coding-assistant   agentic-workflows   llm-tools
subagents   slash-commands   hooks   devops

GitHub caps topics at 20. The ones highest-signal for search are: claude-code, claude, mcp, rust, axum, sqlx, tutorial, ai-coding-assistant. Keep those eight at minimum; the rest are optional depending on which audiences you want to pull from.