CLAUDE.md for CLI Tool
A command-line tool where the interface is the contract.
How to use this
Save it as CLAUDE.md in your repository root and replace the placeholders in angle brackets. Claude reads it before every task, so keep it short — the Playbooks table at the bottom is how you add detail without paying for it on every unrelated request.
The file
# <project name>
<What the tool does, in one line, as a user would describe it.>
## Commands
- `npm run build` — build
- `npm test` — tests
- `npm link` — install locally for manual testing
## Architecture
- `src/commands/` — one file per subcommand
- `src/lib/` — logic, importable and testable without the CLI layer
- `bin/` — entry point
## Conventions
IMPORTANT: the command surface is a public contract. Renaming a flag is a breaking change.
YOU MUST: exit non-zero on failure and write errors to stderr.
NEVER: print secrets, tokens or full environment dumps in output or logs.
- Every command supports `--help`.
- Anything long-running gets progress output, and respects `--quiet`.
## Verification
Tests pass, and `--help` works for every subcommand.
## Working with Claude Code
- Explore the relevant files before proposing a change.
- For anything non-trivial, plan first (Shift+Tab into plan mode) and let me review.
- Run the verification command below before telling me something works.
- Keep commits small and conventional (`feat:`, `fix:`, `docs:`, `chore:`).
## Playbooks
- Publishing a new version → read `.claude/playbooks/release.md` first
The playbooks it expects
The routing table points at files that don't exist yet. Create them as you need them — each one holds a procedure too long to sit in CLAUDE.md and too rare to justify the context cost.
.claude/playbooks/release.mdPublishing a new version
Other starting points
Next.js + Supabase
App Router, TypeScript, Tailwind and Supabase with row-level security.
R Data Analysis
Tidyverse analysis project with reproducible figures and a clear data pipeline.
Python Research Project
Analysis codebase with notebooks for exploration and modules for anything reused.
Python REST API
FastAPI service with typed schemas, tests and migrations.
Monorepo
Several packages in one repository, where knowing the boundaries matters most.
Need something else? Build one from scratch with the generator.