CLAUDE.md templates and examples

# Invoice chaser

A SaaS that emails polite payment reminders for overdue freelance invoices.
Read docs/PRD.md before planning. Build only what is in its MVP scope.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (http://localhost:3000)
- Test: `pnpm test`
- Lint and typecheck: `pnpm lint && pnpm tsc --noEmit`
- DB migration: `pnpm db:migrate` (never edit a migration that has already run)

## Structure
- `app/`: routes (App Router). Server components by default.
- `app/api/`: route handlers. Webhooks live in `app/api/webhooks/`.
- `lib/db.ts`: the only database client. Import it; don't create another.
- `lib/stripe.ts`: Stripe client and price IDs.
- `emails/`: email templates.

## Conventions
- TypeScript strict. No `any`.
- Add `"use client"` only to components that need state or browser APIs.
- Validate every request body with zod before it touches the database.
- Money is stored in cents as integers.

## Rules
- Run lint, typecheck and tests before saying a task is done.
- Ask before adding a dependency.
- Verify the Stripe signature on every webhook before reading the payload.
- Never commit secrets. Env vars live in `.env.local`, documented in `.env.example`.

## Gotchas
- Stripe can send the same webhook event more than once. Handlers must be idempotent (check the event ID).

# csvdiff

A command line tool that shows row-level differences between two CSV files.
Read docs/PRD.md before planning. Build only what is in its MVP scope.

## Commands
- Install: `uv sync`
- Run: `uv run csvdiff a.csv b.csv`
- Test: `uv run pytest`
- Lint and format: `uv run ruff check . && uv run ruff format .`
- Typecheck: `uv run mypy src`

## Structure
- `src/csvdiff/cli.py`: argument parsing only. No logic here.
- `src/csvdiff/core.py`: the diff logic, pure functions.
- `tests/`: one test file per module. Fixtures in `tests/data/`.

## Conventions
- Python 3.12. Type hints on every function.
- Standard library first. Ask before adding a dependency.
- Errors go to stderr with a non-zero exit code. Output goes to stdout so it can be piped.

## Rules
- Write a failing test before fixing a bug.
- Run pytest, ruff and mypy before saying a task is done.
- Don't change the output format without asking: people pipe it into other tools.

## Gotchas
- Large files: stream rows, never load a whole file into memory.

# Tab timer

A Chrome extension that shows how long each tab has been open and closes stale ones on request.
Read docs/PRD.md before planning. Build only what is in its MVP scope.

## Commands
- Install: `npm install`
- Build: `npm run build` (outputs to `dist/`)
- Watch: `npm run dev`, then load `dist/` at chrome://extensions with Developer mode on
- Test: `npm test`

## Structure
- `src/background.ts`: the service worker. Event listeners only.
- `src/content.ts`: runs in web pages. Keep it small.
- `src/popup/`: the popup UI.
- `manifest.json`: Manifest V3.

## Conventions
- Manifest V3 only. No background pages, no remote code.
- The service worker can stop at any time: keep state in `chrome.storage`, not in variables.
- Messages between scripts use one typed message format defined in `src/messages.ts`.

## Rules
- Ask before adding a permission to manifest.json. Every permission shows a warning to users and slows store review.
- Never load scripts from a CDN. Chrome Web Store policy blocks remotely hosted code.
- Run the build and tests before saying a task is done.

## Gotchas
- A listener registered inside an async callback may never fire after the worker restarts. Register listeners at the top level.

# linear-lite MCP

An MCP server that lets an AI agent search, create and close issues in a small issue tracker.
Read docs/PRD.md before planning. Build only what is in its MVP scope.

## Commands
- Install: `npm install`
- Build: `npm run build`
- Test: `npm test`
- Try it: `npx @modelcontextprotocol/inspector node dist/index.js`

## Structure
- `src/index.ts`: server setup and transport (stdio).
- `src/tools/`: one file per tool, each exporting its schema and handler.
- `src/api.ts`: the only HTTP client for the tracker's API.

## Conventions
- Uses the official `@modelcontextprotocol/sdk` package.
- Every tool has a zod input schema and a one-line description written for the model.
- Tool names are verbs: `search_issues`, `create_issue`, `close_issue`.
- Return short, structured text. Don't dump raw API responses.

## Rules
- With stdio transport, never write to stdout except through the SDK. Logs go to stderr.
- Tools that change data must say so in their description.
- Read the API key from an env var. Never hard-code it or log it.
- Run the build and tests before saying a task is done.

## Gotchas
- A stray `console.log` corrupts the stdio stream and the client disconnects without a clear error.

# Plant water log

An iOS and Android app that reminds you when each plant needs water.
Read docs/PRD.md before planning. Build only what is in its MVP scope.

## Commands
- Install: `npx expo install` (use this, not npm install, for native packages)
- Dev: `npx expo start`
- Test: `npm test`
- Typecheck: `npx tsc --noEmit`

## Structure
- `app/`: screens (Expo Router, file-based routes).
- `components/`: shared UI.
- `lib/storage.ts`: local data. The only place that reads or writes it.
- `lib/notifications.ts`: scheduling reminders.

## Conventions
- TypeScript strict.
- Works offline. Local storage is the source of truth; there is no backend in v1.
- Styles with StyleSheet. Respect the safe area on every screen.

## Rules
- Ask before adding a package with native code. It may need a new development build.
- Test on both iOS and Android before saying a UI task is done.
- Don't touch `ios/` or `android/` folders by hand if they exist; change app.json instead.

## Gotchas
- Scheduled notifications need permission first. Ask at the moment the user sets their first reminder, not on launch.