Claude Code Mastery: My Complete Workflow

# Project: PromptLib

## Architecture
- Next.js 14 App Router with TypeScript strict mode
- Database: Postgres via Drizzle ORM (schema in src/db/schema.ts)
- Auth: NextAuth.js with GitHub + Google providers
- Styling: Tailwind CSS + shadcn/ui components
- API: Server actions preferred over API routes for mutations
- State: Zustand for client state, Tanstack Query for server state

## Directory Structure
- src/app/ — App Router pages and layouts
- src/components/ — Shared React components (PascalCase)
- src/lib/ — Utility functions and shared logic
- src/db/ — Database schema, migrations, and queries
- src/actions/ — Server actions (grouped by domain)
- src/hooks/ — Custom React hooks

## Conventions
- All components use named exports, no default exports
- Server components by default, "use client" only when necessary
- Error handling: use Result<T, E> pattern from src/lib/result.ts
- Database queries go through repository functions in src/db/queries/
- Zod schemas for ALL external input validation
- Tests live next to source files: Component.test.tsx

## Commands
- `pnpm dev` — development server
- `pnpm test` — run vitest
- `pnpm test:e2e` — run Playwright e2e tests
- `pnpm db:push` — push schema changes
- `pnpm db:generate` — generate migrations
- `pnpm lint` — ESLint + Prettier check
- `pnpm typecheck` — TypeScript compilation check

## Patterns to Follow
- See src/actions/prompts.ts for server action patterns
- See src/components/PromptCard.tsx for component patterns
- See src/db/queries/prompts.ts for database query patterns

## Things to Avoid
- No `any` types — use `unknown` and narrow
- No barrel exports (index.ts re-exports)
- No React.FC — use plain function declarations
- Don't use fetch for internal API calls — use server actions

CLAUDE.md                    # Global: monorepo structure, shared conventions
packages/api/CLAUDE.md       # API-specific: Hono routes, middleware chain
packages/web/CLAUDE.md       # Web-specific: Next.js patterns, component library
packages/shared/CLAUDE.md    # Shared: types, utilities, validation schemas

mkdir -p .claude/commands

<!-- .claude/commands/add-feature.md -->
I want to add a new feature. Here's the specification:

$ARGUMENTS

Follow these steps:
1. Read the existing patterns in the codebase first
2. Create the necessary types/schemas
3. Implement the database layer (if needed)
4. Implement the server actions
5. Create the UI components
6. Add tests for the critical path
7. Run the test suite and fix any failures
8. Run the type checker and fix any errors

<!-- .claude/commands/review.md -->
Review the changes I've made since the last commit. Specifically:

1. Read the git diff (staged and unstaged)
2. Check for bugs, security issues, and performance problems
3. Verify the changes follow the patterns in CLAUDE.md
4. Check that tests cover the new code paths
5. Suggest improvements, but distinguish between "must fix" and "nice to have"

Be direct. If the code is fine, say so. Don't invent problems.

<!-- .claude/commands/test-gen.md -->
Generate tests for: $ARGUMENTS

Steps:
1. Read the source file and understand its public API
2. Identify the critical paths and edge cases
3. Write tests using the patterns in the nearest existing test file
4. Focus on behavior, not implementation — test what the function does, not how
5. Include edge cases: empty inputs, null/undefined, boundary values, error paths
6. Run the tests to make sure they pass

mkdir -p .claude/skills

<!-- .claude/skills/add-migration.md -->
---
name: add-migration
description: Create a database migration for a schema change
args: description of the schema change
---

Create a Drizzle ORM migration for: $ARGUMENTS

Steps:
1. Read the current schema in src/db/schema.ts
2. Understand what change is needed
3. Generate the migration SQL
4. Create the migration file in src/db/migrations/
5. Update the schema.ts to reflect the new state
6. Run `pnpm db:push` to verify the migration applies cleanly
7. Run the test suite to catch any query breakage

<!-- .claude/skills/security-audit.md -->
---
name: security-audit
description: Run a security audit on changed files
args: optional file path to scope the audit
---

Perform a security audit on $ARGUMENTS (or all recently changed files if no argument).

Check for:
1. SQL injection vulnerabilities (raw query strings with user input)
2. XSS vulnerabilities (unescaped user content in HTML)
3. Authentication bypass (routes that should be protected but aren't)
4. Insecure direct object references (user can access another user's data)
5. Secrets in code (API keys, passwords, tokens)
6. Unsafe deserialization
7. Missing input validation at API boundaries

For each finding:
- Rate severity: Critical / High / Medium / Low
- Explain the vulnerability
- Provide the specific fix

<!-- ~/.claude/skills/explain-error.md -->
---
name: explain-error
description: Diagnose an error message with full context
---

Analyze this error: $ARGUMENTS

Don't just fix the immediate error. Explain:
1. What system state would cause this
2. Whether this is a symptom or the root cause
3. The minimal correct fix
4. Any related issues you spotted while investigating

I need to add real-time notifications to PromptLib. Users should get notified 
when someone comments on their prompt, stars it, or forks it.

Before writing any code, create a technical plan:
1. What components/files need to change?
2. What's the data model?
3. What's the notification delivery mechanism?
4. What are the edge cases?
5. What's the migration path for existing data?

Don't implement anything yet. Just give me the plan.

Good plan. Implement it with these adjustments:
- Use server-sent events instead of WebSocket (simpler, we don't need bidirectional)
- Store notifications in the existing Postgres database, not Redis
- Start with email notifications only, we'll add in-app later

Go ahead and implement. Run tests after each major step.

Migrate the API from Express to Hono. Here are the constraints:
- Keep the existing route structure and endpoint paths
- Port all middleware (auth, validation, rate limiting, error handling)
- Update the test files to use Hono's test client
- Update the Dockerfile and docker-compose.yml
- Run the full test suite after migration and fix any failures

Migrate one route file at a time, running tests after each to catch regressions early.

Enable TypeScript strict mode incrementally:
1. Turn on strict: true in tsconfig.json
2. Run tsc --noEmit and capture all errors
3. Fix errors file by file, starting with leaf modules (no dependencies)
4. After each file, run tsc --noEmit to verify error count decreases
5. Don't use @ts-ignore or any type assertions unless truly necessary
6. For complex type issues, add a TODO comment and move on

Review the changes in this branch compared to main:
1. git diff main...HEAD
2. For each changed file, read the full file (not just the diff) to understand context
3. Check for: bugs, security issues, missing error handling, performance problems
4. Verify that tests cover the changes
5. Check for consistency with existing patterns

Rate each finding as: 🔴 must fix, 🟡 should fix, 🟢 nice to have

Users report that saving a prompt with more than 10 tags silently drops 
tags beyond the 10th. The API returns 200 but the database only has 10 tags.

Find the root cause. Check:
1. The API validation layer (is there a limit?)
2. The database schema (is there a constraint?)
3. The server action that handles saving
4. The UI component that sends the data

Don't fix it yet — just find the cause and explain it.

Read src/actions/prompts.ts and its dependencies.

Generate tests that cover:
1. Happy path for each exported function
2. Error paths: invalid input, database errors, auth failures
3. Edge cases: empty arrays, very long strings, concurrent calls
4. Integration: test the full action → database → response chain

Use the testing patterns from src/actions/__tests__/users.test.ts as a reference.
Run the tests after writing them.

Let's checkpoint. Summarize:
1. What we've implemented so far
2. What decisions we've made
3. What's left to do
4. Any open questions

git checkout -b feat/notifications

We're on branch feat/notifications. Implement the notification system 
from our earlier plan. Make atomic commits after each logical unit of work 
with descriptive commit messages.

Before I open a PR, review everything on this branch:
1. git log main..HEAD — review commit messages
2. git diff main...HEAD — review all changes
3. Check for: console.logs, TODO comments, commented-out code, debug artifacts
4. Verify all tests pass
5. Run the linter and fix any issues
6. Suggest improvements to commit messages if needed

I've pulled main and have merge conflicts. The conflicting files are:
- src/db/schema.ts
- src/actions/prompts.ts

Resolve the conflicts by:
1. Reading both versions
2. Understanding the intent of each change
3. Merging them correctly (both changes should be preserved)
4. Running tests to verify the resolution

# .github/workflows/ci.yml — Claude Code's output gets the same treatment
name: CI
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm test:e2e

Add a GitHub Actions workflow that:
1. Runs on PRs to main
2. Type checks, lints, and runs all tests
3. Runs Playwright e2e tests
4. Checks for migration drift (schema matches migrations)
5. Posts a comment with test coverage diff