diff --git a/.claude/commands/command-code-review.md b/.claude/commands/command-code-review.md new file mode 100644 index 0000000..4274f1e --- /dev/null +++ b/.claude/commands/command-code-review.md @@ -0,0 +1,36 @@ +# Code Review Command + +Carefully perform a comprehensive code review of $ARGUMENTS. + +## Review Standards +Examples of excellent code that you should match the design/style/conventions of: +- `src/components/dashboard/SummaryCards.tsx` (React components) +- `src/utils/formatters.ts` (utility functions) +- `src/hooks/useExpenses.ts` (custom hooks) + +## Process +1. **First**: Read the example files above to understand our design patterns, naming conventions, and code style +2. **Second**: Analyze $ARGUMENTS against these standards +3. **Third**: Create detailed critique covering: + - Code structure and organization + - Adherence to established patterns + - Performance considerations + - Security implications + - Maintainability concerns + - Test coverage gaps + +## Output Requirements +- Save review as `ai-code-reviews/{filename}.review.md` for each file reviewed +- Include specific line references for issues +- Provide concrete suggestions for improvements +- Rate overall quality: Excellent/Good/Needs Improvement/Poor +- Estimate refactoring effort: Low/Medium/High + +## Review Checklist +- Follows project naming conventions +- Proper error handling implemented +- No hardcoded values, secrets, or magic numbers +- Appropriate comments and documentation +- Follows existing design principles and consistent with exemplars +- No obvious security vulnerabilities +- Performance optimizations considered diff --git a/.claude/commands/command-document-feature.md b/.claude/commands/command-document-feature.md new file mode 100644 index 0000000..4da3772 --- /dev/null +++ b/.claude/commands/command-document-feature.md @@ -0,0 +1,153 @@ +# Document Feature Command + +Generate paired developer and user documentation for the feature: **$ARGUMENTS**. + +## Inputs + +- `$ARGUMENTS` is the feature name in any form (e.g. `csv-export`, `csv export`, `CSV Export`). +- Slugify it to kebab-case → `` (e.g. `csv-export`). Use `` for all filenames and cross-links. + +## Process + +Follow these steps in order. Do not skip the confirmation gate. + +### 1. Discover the relevant code + +- Grep `src/` for the slug and obvious variants (singular/plural, words split on `-`, common synonyms). +- Glob `src/components/**`, `src/hooks/**`, `src/utils/**`, `src/app/**` for filename matches. +- Read each candidate to confirm it actually implements the feature (don't include incidental matches). + +### 2. Confirmation gate (REQUIRED) + +Present the candidate file list to the user as a numbered list and stop. Wait for them to confirm, edit, add, or remove files before writing any docs. Do **not** proceed autonomously. + +### 3. Classify scope + +Inspect the confirmed files and tag the feature as one of: + +- **frontend** — only `components/`, `hooks/`, client utilities, and `app/` pages with no network calls. +- **backend** — only `app/api/`, server actions, or utilities that make network/DB calls. +- **full-stack** — both. + +This project is intentionally client-only (see `CLAUDE.md`), so most features will be **frontend**. Use the scope tag to choose dev-doc section templates (see §6). + +### 4. Find cross-links + +- Scan existing `docs/dev/*.md` and `docs/user/*.md` for files whose title or first heading overlaps the feature topic. Link them under "Related docs" in both generated files. +- Reference the relevant rules from the root `CLAUDE.md` (quality gates, data model location, formatters) in the dev doc. + +### 5. Prepare output directories + +Create these only if missing (use `mkdir -p`): + +- `docs/dev/` +- `docs/user/` +- `docs/user/screenshots/` + +Do not create a screenshots PNG. Placeholders only — the user captures real screenshots later. + +### 6. Write the two files + +#### `docs/dev/-implementation.md` + +Use this skeleton. Omit sections that don't apply; never leave a section empty. + +```markdown +# — Implementation + +> **User-facing guide:** [How to ](../user/how-to-.md) +> **Scope:** + +## Overview +One paragraph: what this feature does and where it lives in the app. + +## Code map +| File | Role | +|---|---| +| `src/path/to/file.tsx:LINE` | … | +| … | … | + +## Data model +Link `src/types/expense.ts` (or the relevant type file) and quote the exact types this feature reads or writes. + +## +- Where state lives (hook / provider / local). +- How props flow. +- Key render decisions. + +## +- Route(s), method, request/response shape. +- Persistence target. +- Auth assumptions. + +## + +## Error handling +What can fail, what the user sees, where it's caught. + +## Quality gates +From `CLAUDE.md`: +- `npm run lint` — clean. +- `npx tsc --noEmit` — clean. +- `npm run build` — when touching routing/build-time code. +- Manual browser verification of the affected flow. + +## Gotchas +Non-obvious constraints, invariants, or workarounds. One bullet each. Omit if none. + +## Related docs +- [How to ](../user/how-to-.md) +- +``` + +#### `docs/user/how-to-.md` + +Use this skeleton. Keep language plain — no jargon, no code unless the user is expected to type it. + +```markdown +# How to + +> **Looking for technical details?** See [ — Implementation](../dev/-implementation.md). + +## What this lets you do +One or two sentences in user terms. + +## Before you start +Prerequisites the user needs (e.g. "at least one expense saved"). + +## Steps + +1. **** + ![Step 1 — ](./screenshots/-step-1.png) + + +2. **** + ![Step 2 — ](./screenshots/-step-2.png) + + + + +## If something goes wrong +- **** — . + +## Related guides +- [](./.md) +- [ — Implementation](../dev/-implementation.md) +``` + +### 7. Report + +In your final message to the user, include: + +- The two file paths written. +- The detected scope (frontend / backend / full-stack). +- Any cross-link candidates you found but were unsure about (so the user can confirm or reject). +- A reminder that screenshot placeholders are unresolved (``). + +## Hard rules + +- **Do not** edit any file under `src/`. +- **Do not** install dependencies, run the dev server, or launch Playwright. Screenshots are placeholders only. +- **Do not** commit. The project rule (see `CLAUDE.md`) is: never commit unless the user explicitly asks. +- **Do not** invent file paths, exports, or line numbers — every reference in the dev doc must come from a file you actually read. +- **Do not** skip the confirmation gate in §2, even if the discovery looks unambiguous. diff --git a/README.md b/README.md index f13665c..c06e143 100644 --- a/README.md +++ b/README.md @@ -1 +1,19 @@ -# claude-code \ No newline at end of file +# claude-code + +A small collection of custom slash commands for [Claude Code](https://claude.com/claude-code). + +## Commands + +Drop the files in `.claude/commands/` into your own project's `.claude/commands/` directory to use them. + +| Command | What it does | +|---|---| +| [`/command-code-review`](./.claude/commands/command-code-review.md) | Reviews a file against named exemplar files in your project. Writes the review to `ai-code-reviews/.review.md`, with line-referenced findings, an overall quality rating, and a refactoring effort estimate. | +| [`/command-document-feature`](./.claude/commands/command-document-feature.md) | Given a feature name, discovers the relevant source files (with a confirmation gate), detects whether the feature is frontend / backend / full-stack, and generates paired developer and user documentation under `docs/dev/` and `docs/user/`. User docs include per-step screenshot placeholders. | + +## Usage + +1. Copy the desired `.md` file into `.claude/commands/` at the root of your project. +2. Invoke it in Claude Code as `/`. For example, `command-document-feature.md` is invoked as `/command-document-feature csv-export`. + +Each command file contains instructions that Claude Code follows — you can edit the exemplar paths, doc skeletons, and rules to match your codebase before using.