User Guide

Part 1: Getting Started

What This Kit Does

The Claude Code Starter Kit is a scaffold template that supercharges Claude Code with battle-tested rules, automated enforcement, and on-demand tools. Think of it as a senior engineer's playbook, encoded into files that Claude reads and follows:

Decision Tree: Which Path Is Right for You?

Are you starting a brand new project?
├── YES → Use /new-project
│   ├── Full opinions (TypeScript, ports, quality gates)?  → /new-project my-app default
│   ├── Just AI tooling, zero coding opinions?             → /new-project my-app clean
│   ├── Building a Go API?                                 → /new-project my-api go
│   └── Building a Python API?                             → /new-project my-api python-api
│
├── NO → Do you have an existing project?
│   └── YES → /convert-project-to-starter-kit ~/projects/my-app
│
└── Want to customize the template itself?
    └── Clone the repo, modify commands/hooks/rules

Tutorial: Your First Project in 5 Minutes

/install-global

/new-project my-app clean          # Zero opinions
/new-project my-app default        # Full stack: Next.js + MongoDB + Tailwind

cd ~/projects/my-app
/setup                             # Configure .env interactively

claude

What Got Created

After /new-project my-app clean, here's what's in your project:

my-app/
├── .claude/
│   ├── commands/       ← 26 slash commands (16 project + 10 kit management)
│   ├── skills/         ← Auto-triggered expertise
│   ├── agents/         ← Specialist subagents
│   ├── hooks/          ← 9 enforcement scripts
│   └── settings.json   ← Hooks wired to lifecycle
├── project-docs/       ← ARCHITECTURE, INFRASTRUCTURE, DECISIONS
├── tests/              ← CHECKLIST, ISSUES_FOUND
├── CLAUDE.md           ← The rules Claude follows
├── CLAUDE.local.md     ← Your personal preferences (gitignored)
├── .env                ← Secrets (never committed)
├── .env.example        ← Template with placeholders
└── .gitignore          ← Includes .env, CLAUDE.local.md

Part 2: Daily Workflow

The Development Loop

When to /clear and Start Fresh

Working with Branches

Auto-branch is ON by default. Every command that modifies code automatically creates a feature branch when it detects you're on main. If Claude screws up — just delete the branch. Main was never touched.

# For parallel sessions in separate directories:
/worktree add-auth        # Creates branch + separate working directory
/worktree add-payments    # Another isolated workspace

Part 3: Commands Deep Dive

All 26 commands (16 project + 10 kit management) grouped by category with real examples.

Getting Started

Code Quality

Scaffolding

Infrastructure

Project Management

Meta

Part 4: Hook System Explained

Hooks are shell/python scripts that run automatically at specific lifecycle points. Unlike CLAUDE.md rules (suggestions), hooks are guaranteed to run.

The Lifecycle

┌─────────────────────────────────────────────┐
│  PreToolUse — BEFORE Claude uses a tool     │
│  Can BLOCK the action (exit code 2)         │
│                                             │
│  → block-secrets.py (Read/Edit/Write)       │
│  → check-rybbit.sh  (Bash - deploy)         │
│  → check-branch.sh  (Bash - git commit)     │
│  → check-ports.sh   (Bash - dev servers)    │
│  → check-e2e.sh     (Bash - git push)       │
├─────────────────────────────────────────────┤
│  PostToolUse — AFTER Claude uses a tool     │
│  Informational only                         │
│                                             │
│  → lint-on-save.sh   (Write)                │
├─────────────────────────────────────────────┤
│  Stop — When Claude FINISHES a turn         │
│  Can warn, typically doesn't block          │
│                                             │
│  → verify-no-secrets.sh                     │
│  → check-rulecatch.sh                       │
│  → check-env-sync.sh                        │
└─────────────────────────────────────────────┘

Each Hook Explained

Creating Custom Hooks

#!/bin/bash
# .claude/hooks/my-custom-hook.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null)

if echo "$COMMAND" | grep -q "something-dangerous"; then
    echo "BLOCKED: Reason for blocking" >&2
    exit 2  # Block the operation
fi
exit 0  # Allow

Wire it in .claude/settings.json under the appropriate lifecycle event and matcher.

Part 5: StrictDB Database Layer

Why StrictDB Exists

Reading Data

import { StrictDB } from 'strictdb';

const db = StrictDB.getInstance();

// Single document (works with MongoDB, PostgreSQL, SQLite, etc.)
const user = await db.queryOne<User>('users', { email: 'test@example.com' });

// Filtered query with options (filter, then options object)
const recentOrders = await db.queryMany<Order>('orders',
  { userId, status: 'active' },
  { sort: { createdAt: -1 }, limit: 20 },
);

// Join across collections/tables
const userWithOrders = await db.queryWithLookup<UserWithOrders>('users', {
  match: { _id: userId },
  lookup: { from: 'orders', localField: '_id', foreignField: 'userId', as: 'orders' },
  unwind: 'orders',
});

// Count
const total = await db.count('users', { role: 'admin' });

Writing Data

import { StrictDB } from 'strictdb';

const db = StrictDB.getInstance();

await db.insertOne('users', { email, name, createdAt: new Date() });
await db.insertMany('events', batchOfEvents);

// Use $inc for counters — NEVER read-modify-write
await db.updateOne<Stats>('stats', { date }, { $inc: { pageViews: 1 } }, true);

// Batch operations (array of typed operations)
await db.batch([
  { operation: 'updateOne', collection: 'sessions', filter: { sessionId }, update: { $inc: { events: 1 } } },
  { operation: 'deleteOne', collection: 'tokens', filter: { token: expiredToken } },
]);

await db.deleteOne('tokens', { token: expiredToken });

AI-First Discovery

import { StrictDB } from 'strictdb';

const db = StrictDB.getInstance();

// Discover schema — fields, indexes, document count
const schema = await db.describe('users');

// Dry-run validation — catches errors before execution
const check = await db.validate('users', { doc: { email: 'test@test.com' } });

// See the native query that would run
const plan = await db.explain('users', { filter: { role: 'admin' }, limit: 50 });

Graceful Shutdown

import { StrictDB } from 'strictdb';

const db = StrictDB.getInstance();

// Closes all database connections (MongoDB, PostgreSQL, SQLite, etc.)
process.on('SIGTERM', () => db.gracefulShutdown(0));
process.on('SIGINT', () => db.gracefulShutdown(0));
process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', err);
  db.gracefulShutdown(1);
});

Part 6: CLAUDE.md Customization

Team File vs Personal File

Adding Your Own Rules

Use strong language — Claude responds to NEVER and ALWAYS more consistently than “try to” or “prefer”:

### Rule 11: Always Use Relative Imports

- NEVER use absolute paths in imports
- ALWAYS use relative paths from the current file
- This prevents path mapping issues across environments

The Feedback Loop

Every mistake is a missing rule. Don't just fix bugs — fix the rules that allowed the bug. The file is checked into git, so the whole team benefits.

Part 7: Testing

Test Infrastructure

pnpm test:unit        # Run once
pnpm test:unit:watch  # Watch mode
pnpm test:coverage    # With coverage

pnpm test:e2e         # Full run
pnpm test:e2e:headed  # Visible browser
pnpm test:e2e:ui      # Debug UI

The 3-Assertion Minimum

// CORRECT — 3 explicit assertions
await expect(page).toHaveURL('/dashboard');              // 1. URL
await expect(page.locator('h1')).toBeVisible();         // 2. Element
await expect(page.locator('[data-testid="user"]'))
  .toContainText('test@example.com');                   // 3. Data

// WRONG — passes even if broken
await page.goto('/dashboard');
// no assertions!

Test Ports

Tests run on separate ports so you can develop and test simultaneously:

Part 8: Deployment

Pre-Deployment Checklist

Docker Multi-Stage Build

# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

# Stage 2: Production
FROM node:20-alpine AS runner
WORKDIR /app
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 appuser
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Docker Push Gate

Enable with docker_test_before_push = true in claude-mastery-project.conf. When enabled, no docker push is allowed until: build → run → wait 5s → verify running → health check 200 → clean logs → cleanup → push.

Part 9: Troubleshooting

Part 10: FAQ

Credits

This user guide is part of the Claude Code Starter Kit by TheDecipherist.

Based on the Claude Code Mastery Guide series (V1–V5).

← Back to the main documentation