The Definitive Starting Point
for Claude Code Projects

What's Included

Everything you need to start a Claude Code project the right way — security, automation, documentation, and testing all pre-configured.

MDD Workflow NEW

Manual-First Development — the built-in methodology that turns Claude Code from a code generator into a development partner. Every feature starts with documentation. Every fix starts with an audit.

What is MDD?

Most people prompt Claude Code like this: "fix the bug in my auth system." Claude reads 40 files, burns through context trying to understand your architecture, and produces something that technically compiles but misses the bigger picture.

MDD flips this. You write structured documentation first, then Claude reads one doc instead of 40 files. It gets the full picture in 200 tokens instead of 20,000. Every phase reads the output of the previous phase, compressing context further at each step.

The Workflow

Usage

One command, three modes:

# Build a new feature (Document → Test skeletons → Implement → Verify)
/mdd add user authentication with JWT tokens

# Audit existing code (Read → Notes → Report → Fix)
/mdd audit
/mdd audit database    # audit a specific section

# Check MDD status (docs, tests, findings, quality gates)
/mdd status

Build Mode — New Features

When you run /mdd <feature description>, Claude follows a structured 6-phase process:

1. Understand — Reads your architecture, existing docs, asks all questions upfront
2. Document — Creates a numbered MDD doc in .mdd/docs/ with full YAML frontmatter
3. Test Skeletons — Generates failing tests from the documentation (Doc → Test → Code)
4. Plan — Presents named steps with time estimates, waits for your approval
5. Implement — Builds code until tests pass, reports progress per step
6. Verify — Full test suite, typecheck, documentation updated

Tests are generated before code. They define the finish line. If a test fails, the implementation gets fixed — not the test.

Audit Mode — Existing Code

When you run /mdd audit, Claude runs a complete security and quality audit:

1. Scope — Reads all .mdd/docs/ files, builds the feature map
2. Read + Notes — Reads all source files, writes notes every 2 features (survives context compaction)
3. Analyze — Reads only the notes (not source code again), produces findings report
4. Present — Shows top issues with severity, estimated fix time, asks what to fix
5. Fix — Applies fixes from the report, writes tests, updates documentation

The .mdd/ Directory

All MDD artifacts live in a single dotfile directory, gitignored by default:

.mdd/
├── docs/                        # Feature documentation (one per feature)
│   ├── 01-project-scaffolding.md
│   ├── 02-profile-system.md
│   └── ...
└── audits/                      # Audit artifacts
    ├── notes-2026-03-01.md      # Raw reading notes
    ├── report-2026-03-01.md     # Structured findings
    └── results-2026-03-01.md    # Before/after summary

Real Results: Self-Audit

We used MDD to audit this starter kit — the same methodology the kit teaches. Here's what happened:

Why It Works

The problem with Claude Code isn't intelligence — it's context. A 200K token window sounds huge until you're reading 40 files and burning 80% of context on comprehension before writing a single line of output.

MDD makes each phase a context compressor: documentation compresses 40 files into 1 doc, raw notes compress all source code into a single file, the audit report compresses notes into severity-rated findings. By the time Claude writes code, it's working from a 300-line report — not a 40,000-line codebase. It's not problem-solving. It's pattern-matching.

The Incremental Write Trick

The most important technical detail: when Claude reads files during an audit, context will compact. If your findings are only in Claude's memory, they're gone.

Instead, Claude writes notes to disk every 2 features. If context compacts, it reads the tail of the notes file and picks up where it left off. We've run this pattern across 6 complete audit cycles. Zero data loss.

After processing every 2 features, immediately append your notes to
.mdd/audits/notes.md. If context compacts, read the TAIL of the notes
file and continue from where you left off.

Featured Packages

Four open-source npm packages by TheDecipherist — the same developer behind this starter kit — are integrated into project profiles. All are MIT-licensed.

claude mcp add classmcp -- npx -y classmcp@latest

claude mcp add strictdb-mcp -- npx -y strictdb-mcp@latest

pnpm add -D classpresso

pnpm add tersejson

What Is This?

Three Ways to Use It

Learning Path

Progress through these phases at your own pace. Each builds on the previous one.

First 5 Minutes

/install-global                    # One-time: install global Claude config
/new-project my-app clean          # Scaffold a project (or: default for full stack)
cd ~/projects/my-app               # Enter your new project
/setup                             # Configure .env interactively
pnpm install && pnpm dev           # Start building

First Feature (MDD Workflow)

/mdd add user authentication       # Claude interviews you, writes docs, generates
                                    # test skeletons, presents a plan, then builds

Use /help to see all 27 commands at any time.

Quick Start

# Clone the starter kit
git clone https://github.com/TheDecipherist/claude-code-mastery-project-starter-kit my-project
cd my-project

# Remove git history and start fresh
rm -rf .git
git init

# Copy your .env
cp .env.example .env

# Run the install command — smart merges into existing config
/install-global

cp global-claude-md/CLAUDE.md ~/.claude/CLAUDE.md
cp global-claude-md/settings.json ~/.claude/settings.json
mkdir -p ~/.claude/hooks
cp .claude/hooks/block-secrets.py ~/.claude/hooks/
cp .claude/hooks/verify-no-secrets.sh ~/.claude/hooks/
cp .claude/hooks/check-rulecatch.sh ~/.claude/hooks/

claude

Troubleshooting

Project Structure

project/
├── CLAUDE.md                    # Project instructions (customize this!)
├── CLAUDE.local.md              # Personal overrides (gitignored)
├── .claude/
│   ├── settings.json            # Hooks configuration
│   ├── commands/
│   │   ├── help.md              # /help — list all commands, skills, and agents
│   │   ├── quickstart.md        # /quickstart — interactive first-run walkthrough
│   │   ├── review.md            # /review — code review
│   │   ├── commit.md            # /commit — smart commit
│   │   ├── progress.md          # /progress — project status
│   │   ├── test-plan.md         # /test-plan — generate test plan
│   │   ├── architecture.md      # /architecture — show system design
│   │   ├── new-project.md       # /new-project — scaffold new project
│   │   ├── security-check.md    # /security-check — scan for secrets
│   │   ├── optimize-docker.md   # /optimize-docker — Docker best practices
│   │   ├── create-e2e.md        # /create-e2e — generate E2E tests
│   │   ├── create-api.md        # /create-api — scaffold API endpoints
│   │   ├── worktree.md          # /worktree — isolated task branches
│   │   ├── what-is-my-ai-doing.md # /what-is-my-ai-doing — live AI monitor
│   │   ├── setup.md             # /setup — interactive .env configuration
│   │   ├── refactor.md          # /refactor — audit + refactor against all rules
│   │   ├── install-global.md    # /install-global — merge global config into ~/.claude/
│   │   ├── diagram.md           # /diagram — generate diagrams from actual code
│   │   ├── set-project-profile-default.md # /set-project-profile-default — set default profile
│   │   ├── add-project-setup.md  # /add-project-setup — create a named profile
│   │   ├── projects-created.md   # /projects-created — list all created projects
│   │   ├── remove-project.md     # /remove-project — remove a project from registry
│   │   ├── convert-project-to-starter-kit.md # /convert-project-to-starter-kit — merge into existing project
│   │   ├── update-project.md      # /update-project — update a project with latest starter kit
│   │   ├── add-feature.md         # /add-feature — add capabilities post-scaffolding
│   │   └── show-user-guide.md    # /show-user-guide — open the User Guide in browser
│   ├── skills/
│   │   ├── code-review/SKILL.md # Triggered code review checklist
│   │   └── create-service/SKILL.md # Service scaffolding template
│   ├── agents/
│   │   ├── code-reviewer.md     # Read-only review subagent
│   │   └── test-writer.md       # Test writing subagent
│   └── hooks/
│       ├── block-secrets.py     # PreToolUse: block sensitive files
│       ├── check-rybbit.sh      # PreToolUse: block deploy without Rybbit
│       ├── check-branch.sh      # PreToolUse: block commits on main
│       ├── check-ports.sh       # PreToolUse: block if port in use
│       ├── check-e2e.sh         # PreToolUse: block push without E2E tests
│       ├── lint-on-save.sh      # PostToolUse: lint after writes
│       ├── verify-no-secrets.sh # Stop: check for secrets
│       ├── check-rulecatch.sh   # Stop: report RuleCatch violations
│       └── check-env-sync.sh    # Stop: warn on .env/.env.example drift
├── project-docs/
│   ├── ARCHITECTURE.md          # System overview (authoritative)
│   ├── INFRASTRUCTURE.md        # Deployment details
│   └── DECISIONS.md             # Architectural decision records
├── docs/                        # GitHub Pages site
│   └── user-guide.html          # Interactive User Guide (HTML)
├── src/
│   ├── handlers/                # Business logic
│   ├── adapters/                # External service adapters
│   └── types/                   # Shared TypeScript types
├── scripts/
│   ├── db-query.ts              # Test Query Master — dev/test query index
│   ├── queries/                 # Individual dev/test query files
│   ├── build-content.ts         # Markdown → HTML article builder
│   └── content.config.json      # Article registry (SEO metadata)
├── content/                     # Markdown source files for articles
├── tests/
│   ├── CHECKLIST.md             # Master test tracker
│   ├── ISSUES_FOUND.md          # User-guided testing log
│   ├── e2e/                     # Playwright E2E tests
│   ├── unit/                    # Vitest unit tests
│   └── integration/             # Integration tests
├── global-claude-md/            # Copy to ~/.claude/ (one-time setup)
│   ├── CLAUDE.md                # Global security gatekeeper
│   └── settings.json            # Global hooks config
├── USER_GUIDE.md                # Comprehensive User Guide (Markdown)
├── .env.example
├── .gitignore
├── .dockerignore
├── package.json                 # All npm scripts (dev, test, db:query, etc.)
├── claude-mastery-project.conf  # /new-project profiles + global root_dir
├── playwright.config.ts         # E2E test config (test ports, webServer)
├── vitest.config.ts             # Unit/integration test config
├── tsconfig.json
└── README.md

Key Concepts

CLAUDE.md — The Rulebook

The CLAUDE.md file is where you define the rules Claude Code must follow. These aren't suggestions — they're the operating manual for every session. Here are the critical rules included in this starter kit:

CORRECT: /api/v1/users
WRONG:   /api/users

// CORRECT — explicit success criteria
await expect(page).toHaveURL('/dashboard');
await expect(page.locator('h1')).toContainText('Welcome');

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

// CORRECT — independent operations run in parallel
const [users, products, orders] = await Promise.all([
  getUsers(),
  getProducts(),
  getOrders(),
]);

// WRONG — sequential when they don't depend on each other
const users = await getUsers();
const products = await getProducts();  // waits unnecessarily
const orders = await getOrders();      // waits unnecessarily

When Something Seems Wrong

The CLAUDE.md also includes a “Check Before Assuming” pattern that prevents Claude from jumping to conclusions:

Fixed Service Ports

Port conflicts are one of the most common problems in multi-service development. The CLAUDE.md locks them down:

Hooks — Stronger Than Rules

CLAUDE.md rules are suggestions. Hooks are stronger — they're guaranteed to run as shell/python scripts at specific lifecycle points. But hooks are not bulletproof: Claude may still work around their output. They're a significant upgrade over CLAUDE.md rules alone, but not an absolute guarantee that behavior will be followed.

# Files that should NEVER be read or edited by Claude
SENSITIVE_FILENAMES = {
    '.env', '.env.local', '.env.production',
    'secrets.json', 'id_rsa', 'id_ed25519',
    '.npmrc', 'credentials.json',
    'service-account.json',
}

# Exit code 2 = block operation and tell Claude why
if path.name in SENSITIVE_FILENAMES:
    print(f"BLOCKED: Access to '{file_path}' denied.", file=sys.stderr)
    sys.exit(2)

case "$EXTENSION" in
    ts|tsx)
        # TypeScript — run type check
        npx tsc --noEmit --pretty "$FILE_PATH" 2>&1 | head -20
        ;;
    js|jsx)
        # JavaScript — run eslint
        npx eslint "$FILE_PATH" 2>&1 | head -20
        ;;
    py)
        # Python — run ruff or flake8
        ruff check "$FILE_PATH" 2>&1 | head -20
        ;;
esac

# Check staged file contents for common secret patterns
if grep -qEi '(api[_-]?key|secret[_-]?key|password|token)\s*[:=]\s*["\x27][A-Za-z0-9+/=_-]{16,}' "$file"; then
    VIOLATIONS="${VIOLATIONS}\n  - POSSIBLE SECRET in $file"
fi
# Check for AWS keys
if grep -qE 'AKIA[0-9A-Z]{16}' "$file"; then
    VIOLATIONS="${VIOLATIONS}\n  - AWS ACCESS KEY in $file"
fi

# Run RuleCatch violation check
RESULT=$(npx @rulecatch/ai-pooler@latest check --quiet --format summary 2>/dev/null)

if [ -n "$RESULT" ] && [ "$RESULT" != "0 violations" ]; then
    echo "📋 RuleCatch: $RESULT" >&2
    echo "   Run 'pnpm ai:monitor' for details." >&2
fi

Hook Configuration

Hooks are wired up in .claude/settings.json. Each hook type fires at a different point in Claude's lifecycle:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [{ "type": "command", "command": "python3 .claude/hooks/block-secrets.py" }]
      },
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/check-rybbit.sh" },
          { "type": "command", "command": "bash .claude/hooks/check-branch.sh" },
          { "type": "command", "command": "bash .claude/hooks/check-ports.sh" },
          { "type": "command", "command": "bash .claude/hooks/check-e2e.sh" }
        ]
      }
    ],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{ "type": "command", "command": "bash .claude/hooks/lint-on-save.sh" }]
    }],
    "Stop": [{
      "hooks": [
        { "type": "command", "command": "bash .claude/hooks/verify-no-secrets.sh" },
        { "type": "command", "command": "bash .claude/hooks/check-rulecatch.sh" },
        { "type": "command", "command": "bash .claude/hooks/check-env-sync.sh" }
      ]
    }]
  }
}

Slash Commands — On-Demand Tools

Invoke these with /command in any Claude Code session. Each command is a markdown file in .claude/commands/ that gives Claude specific instructions and tool permissions.

# Open a separate terminal and run this while Claude works
npx @rulecatch/ai-pooler monitor --no-api-key

/worktree add-auth          # → task/add-auth branch
/worktree feat/new-dashboard # → uses prefix as-is

/refactor src/handlers/users.ts
/refactor src/server.ts --dry-run    # report only, no changes

/new-project my-app clean
/new-project my-app default
/new-project my-app fullstack next dokploy seo tailwind pnpm
/new-project my-api api fastify dokploy docker multiregion
/new-project my-site static-site
/new-project my-api go                    # Go API with Gin, StrictDB, Docker
/new-project my-api go chi postgres       # Go with Chi, PostgreSQL
/new-project my-cli go cli                # Go CLI with Cobra
/new-project my-app vue                    # Vue 3 SPA with Tailwind
/new-project my-app nuxt                   # Nuxt full-stack with StrictDB, Docker
/new-project my-app sveltekit              # SvelteKit full-stack
/new-project my-api python-api             # FastAPI with PostgreSQL, Docker
/new-project my-app django                 # Django full-stack

/convert-project-to-starter-kit ~/projects/my-app
/convert-project-to-starter-kit ~/projects/my-app --force

/update-project              # Pick from registered projects
/update-project --force      # Skip confirmation prompts

/add-feature strictdb         # Add StrictDB + query system
/add-feature vitest playwright # Add both test frameworks
/add-feature --list           # Show all available features

Supported Technologies

This starter kit works with any language, framework, or database. Use /new-project my-app clean for zero opinions, or pick a profile that matches your stack.

Languages & Frameworks

Recommended Stacks

Skills — Triggered Expertise

Skills are context-aware templates that activate automatically when Claude detects relevant keywords in your conversation. Unlike slash commands (which you invoke explicitly with /command), skills load themselves when needed.

What Triggers Skills?

Claude monitors your conversation for specific keywords. When it detects a match, it loads the relevant skill template — giving Claude structured instructions for that specific task. You don't need to do anything special.

How to Activate Skills

You don't — just use natural language. Say things like:

• “Review this file for security issues” → Code Review skill activates
• “Audit the authentication module” → Code Review skill activates
• “Create a new payment service” → Create Service skill activates
• “Scaffold a notification service” → Create Service skill activates

Skills vs Commands

Both skills and commands can cover similar ground (e.g., code review). Skills are more natural; commands are more predictable. Use whichever fits your workflow.

┌─────────────────────────────────────────────────────┐
│                    YOUR SERVICE                      │
├─────────────────────────────────────────────────────┤
│  SERVER (server.ts)                                  │
│  → Express/Fastify entry point, defines routes       │
│  → NEVER contains business logic                     │
│                       │                              │
│                       ▼                              │
│  HANDLERS (handlers/)                                │
│  → Business logic lives here                         │
│  → One file per domain                               │
│                       │                              │
│                       ▼                              │
│  ADAPTERS (adapters/)                                │
│  → External service adapters                         │
│  → Third-party APIs, etc.                            │
└─────────────────────────────────────────────────────┘

Custom Agents — Specialist Subagents

Agents are specialists that Claude delegates to automatically. They run with restricted tool access so they can't accidentally modify your code when they shouldn't.

// GOOD — explicit, specific assertions
expect(result.status).toBe(200);
expect(result.body.user.email).toBe('test@example.com');

// BAD — passes even when broken
expect(result).toBeTruthy();  // too vague

StrictDB — Unified Database Driver

The starter kit uses StrictDB — a production-grade unified database driver (npm package) supporting MongoDB, PostgreSQL, MySQL, MSSQL, SQLite, and Elasticsearch. It enforces every best practice that prevents the most common database failures in AI-assisted development.

The Absolute Rule

ALL database access goes through StrictDB. No exceptions. Never create direct database clients. Never import raw database drivers in business logic.

// CORRECT — import from StrictDB
import { queryOne, insertOne, updateOne } from 'strictdb';

// WRONG — NEVER do this
import { MongoClient } from 'mongodb';     // FORBIDDEN — use StrictDB
import { Pool } from 'pg';                 // FORBIDDEN — use StrictDB

Reading Data — Aggregation Only

// Single document (automatic $limit: 1)
const user = await queryOne<User>('users', { email });

// Pipeline query
const recent = await queryMany<Order>('orders', [
  { $match: { userId, status: 'active' } },
  { $sort: { createdAt: -1 } },
  { $limit: 20 },
]);

// Join — $limit enforced BEFORE $lookup automatically
const userWithOrders = await queryWithLookup<UserWithOrders>('users', {
  match: { _id: userId },
  lookup: { from: 'orders', localField: '_id', foreignField: 'userId', as: 'orders' },
});

Writing Data — BulkWrite Only

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

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

// Complex batch (auto-retries E11000 concurrent races)
await bulkOps('sessions', [
  { updateOne: { filter: { sessionId }, update: { $inc: { events: 1 } }, upsert: true } },
]);

Connection Pool Presets

Built-in Sanitization and Guardrails

All query inputs are automatically sanitized. The sanitizer uses an allowlist of known-safe query operators — standard operators pass through while dangerous ones are stripped.

This means standard queries just work without any special options:

// All of these work by default — no special options needed:
const entries = await queryMany('logs', [
  { $match: { timestamp: { $gte: new Date(since) } } },
]);

const total = await count('waf_events', { event_at: { $gte: sinceDate } });

const latest = await queryOne('events', {
  level: { $in: ['error', 'fatal'] },
  timestamp: { $gte: cutoff },
});

// Dangerous operators are automatically stripped:
// { $where: 'this.isAdmin' }     → stripped (JS execution)
// { $function: { body: '...' } } → stripped (JS execution)

Disable sanitization entirely with sanitize: false in StrictDB.create() config or sanitize = false in claude-mastery-project.conf.

{ trusted: true } — Escape Hatch

If you need an operator not in the allowlist, queryOne(), queryMany(), and count() accept { trusted: true } to skip sanitization entirely. This should be rare — if you use it frequently, add the operator to the SAFE_OPERATORS configuration in StrictDB instead.

// Only needed for operators NOT in the allowlist:
const results = await queryMany('collection', pipeline, { trusted: true });
const total = await count('collection', match, { trusted: true });
const one = await queryOne('collection', match, { trusted: true });

Additional Features

• Singleton per URI — same STRICTDB_URI always returns the same client, prevents pool exhaustion
• Next.js hot-reload safe — persists connections via globalThis during development
• Transaction support — withTransaction() for multi-document atomic operations
• Change Stream access — rawCollection() for real-time event processing
• Graceful shutdown — gracefulShutdown() closes all pools on SIGTERM, SIGINT, uncaughtException, and unhandledRejection — no zombie connections on crash
• E11000 auto-retry — handles concurrent upsert race conditions automatically
• $limit before $lookup — queryWithLookup() enforces this for join performance
• Index management — registerIndex() + ensureIndexes() at startup

Test Query Master — scripts/db-query.ts

One of the biggest problems with AI-assisted database development: Claude scatters random query scripts all over your project. The Test Query Master solves this completely.

import { queryMany } from 'strictdb';

export default {
  name: 'find-expired-sessions',
  description: 'Find sessions that expired in the last 24 hours',
  async run(args: string[]): Promise<void> {
    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
    const sessions = await queryMany('sessions', [
      { $match: { expiresAt: { $lt: cutoff } } },
      { $sort: { expiresAt: -1 } },
      { $limit: 50 },
    ]);
    console.log(`Found ${sessions.length} expired sessions`);
  },
};

Then register in scripts/db-query.ts and run: npx tsx scripts/db-query.ts find-expired-sessions

Every query uses StrictDB — same connection pool, same patterns, same rules. When you're done exploring, just delete the file and its registry entry.

Content Builder — scripts/build-content.ts

A config-driven Markdown-to-HTML article builder. Write content in content/ as Markdown, register it in scripts/content.config.json, and build fully SEO-ready static HTML pages with one command.

{
  "articles": [
    {
      "id": "getting-started",
      "published": true,
      "mdSource": "content/getting-started.md",
      "htmlOutput": "public/articles/getting-started/index.html",
      "title": "Getting Started Guide",
      "description": "Everything you need to know.",
      "url": "https://example.com/articles/getting-started/",
      "datePublished": "2026-01-15",
      "category": "Guides",
      "keywords": ["setup", "installation"]
    }
  ]
}

Each generated page includes: Open Graph, Twitter Cards, Schema.org JSON-LD, syntax highlighting, optional sidebar TOC, and parent/child article relationships.

pnpm content:build              # Build all published articles
pnpm content:build:id my-post   # Build a single article
pnpm content:list               # List all articles and status
pnpm content:dry-run            # Preview what would build

All Scripts — package.json

Everything is tied together through package.json scripts. No random npx commands to remember.

Documentation Templates

Pre-structured docs that Claude actually follows. Each template uses the “STOP” pattern — explicit boundaries that prevent Claude from making unauthorized changes.

## If You Are About To...
- Add an endpoint to the wrong service → STOP. Check the table above.
- Create a direct database connection → STOP. Use StrictDB.
- Skip TypeScript for a quick fix → STOP. TypeScript is non-negotiable.
- Deploy without tests → STOP. Write tests first.

Testing Methodology

From the V5 testing methodology — a structured approach to testing that prevents the most common AI-assisted testing failures.

describe('[Feature]', () => {
  describe('[Scenario]', () => {
    it('should [expected behavior] when [condition]', async () => {
      // Arrange — set up test data
      // Act — perform the action
      // Assert — verify SPECIFIC outcomes
    });
  });
});

E2E Infrastructure — playwright.config.ts

The Playwright config is pre-wired with test ports, automatic server spawning, and port cleanup. You never have to manually start servers for E2E tests.

pnpm test              # ALL tests (unit + E2E)
pnpm test:unit         # Unit/integration only (Vitest)
pnpm test:e2e          # E2E only (kills ports → spawns servers → Playwright)
pnpm test:e2e:headed   # E2E with visible browser
pnpm test:e2e:ui       # E2E with Playwright UI mode
pnpm test:e2e:report   # Open last HTML report

/create-e2e Slash Command

Use /create-e2e <feature-name> to generate a properly structured E2E test. Claude will:

1. Read the source code for the feature being tested
2. Identify all URLs, elements, and data to verify
3. Ask what specific success criteria you expect (if not obvious)
4. Create the test at tests/e2e/[name].spec.ts with happy path, error cases, and edge cases
5. Verify the test meets the “done” checklist before finishing

Windows Users — VS Code in WSL Mode

If you're developing on Windows, this is the single biggest performance improvement you can make — and most people don't even know it exists.

VS Code can run its entire backend inside WSL 2 while the UI stays on Windows. Your terminal, extensions, git, Node.js, and Claude Code all run natively in Linux. Everything just works — but 5-10x faster.

Setup (One Time)

# 1. Install WSL 2 (PowerShell as admin)
wsl --install

# 2. Restart your computer

# 3. Install VS Code extension
#    Search for "WSL" by Microsoft (ms-vscode-remote.remote-wsl)

# 4. Connect VS Code to WSL
#    Click green "><" icon in bottom-left → "Connect to WSL"

# 5. Clone projects INSIDE WSL (not /mnt/c/)
mkdir -p ~/projects
cd ~/projects
git clone git@github.com:YourUser/your-project.git
code your-project    # opens in WSL mode automatically

The Critical Mistake

Your project MUST live on the WSL filesystem (~/projects/), NOT on /mnt/c/. Having WSL but keeping your project on the Windows filesystem gives you the worst of both worlds — every file operation still crosses the slow Windows/Linux boundary.

# Check your setup:
pwd

# GOOD — native Linux filesystem
/home/you/projects/my-app

# BAD — still hitting Windows filesystem through WSL
/mnt/c/Users/you/projects/my-app

Run /setup in Claude Code to auto-detect your environment and get specific instructions if something is misconfigured.

Global CLAUDE.md — Security Gatekeeper

The global CLAUDE.md lives at ~/.claude/CLAUDE.md and applies to every project you work on. It's your organization-wide security gatekeeper.

The starter kit includes a complete global config template in global-claude-md/ with:

Coding Standards

Patterns and practices enforced across the project through CLAUDE.md rules, hooks, and code review.

Imports

// CORRECT — explicit, typed
import { getUserById } from './handlers/users.js';
import type { User } from './types/index.js';

// WRONG — barrel imports that pull everything
import * as everything from './index.js';

Error Handling

// CORRECT — handle errors explicitly
try {
  const user = await getUserById(id);
  if (!user) throw new NotFoundError('User not found');
  return user;
} catch (err) {
  logger.error('Failed to get user', { id, error: err });
  throw err;
}

// WRONG — swallow errors silently
try {
  return await getUserById(id);
} catch {
  return null; // silent failure
}

Naming Safety

Renaming packages, modules, or key variables mid-project causes cascading failures. If you must rename:

1. Create a checklist of ALL files and references first
2. Use IDE semantic rename (not search-and-replace)
3. Full project search for old name after renaming
4. Check: .md, .txt, .env, comments, strings, paths
5. Start a FRESH Claude session after renaming

Plan Mode — Named Steps + Replace, Don't Append

Every plan step MUST have a unique, descriptive name so you can reference it unambiguously:

Step 1 (Project Setup): Initialize repo with TypeScript
Step 2 (Database Layer): Configure StrictDB
Step 3 (Auth System): Implement JWT authentication

When modifying a plan, Claude tends to append instead of replacing — creating contradictions. The rules:

• REPLACE the named step entirely: “Change Step 3 (Auth System) to use session cookies”
• NEVER just append: “Also, use session cookies” ← Step 3 still says JWT
• After any change, Claude must rewrite the full updated plan
• If the plan contradicts itself, tell Claude: “Rewrite the full plan — Step 3 and Step 7 contradict”
• If fundamentally changing direction: /clear → state requirements fresh

Monitor Your Rules

Full disclosure: RuleCatch.AI is built by TheDecipherist — the same developer behind this starter kit. It's purpose-built for catching the exact issues AI-assisted development introduces.

Try It Now — Free Monitor Mode

See what your AI is doing in real-time. No API key, no account, no setup — just open a separate terminal and run:

# Open a separate terminal and run this while Claude works
npx @rulecatch/ai-pooler monitor --no-api-key

Also available as pnpm ai:monitor. You'll instantly see every tool call, token count, cost per turn, and which files Claude is touching — all updating live. Zero token overhead. This is the free preview that lets you see what you've been missing.

Unlock the Full Experience

Why you'd want it: AI models break your CLAUDE.md rules more often than you'd expect — wrong language, skipped patterns, hardcoded values, ignored constraints. Code that looks right and passes linting, but violates your project's actual standards. RuleCatch.AI bridges the gap between detecting these violations and fixing them.

AI-Pooler (Free Monitor Mode)

Free monitor mode works instantly — no API key needed. See every tool call, token, cost, and file access in a live terminal view. With an API key: adds persistent violation tracking, session history, and cost analytics

Dashboard

Violations across 18 rule categories, session analytics (tokens, cost, lines/hour), trend reports, per-file attribution. Alerts via Slack, Discord, PagerDuty, and more

MCP Server

Gives Claude direct read access to violation data. Ask: "Show all security violations this week" or "Create a plan to fix today's violations" — Claude reviews, analyzes, and generates file-by-file fix plans without leaving your session

200+ Rules & Privacy-First

Security, TypeScript, React, Next.js, MongoDB, Docker — violations in under 100ms. AES-256-GCM client-side encryption. You hold the key. US and EU data isolation, fully GDPR compliant

The RuleCatch dashboard — violation trends, category breakdown, per-file attribution, and top triggered rules at a glance. Configure alerts via Slack, Discord, PagerDuty, and more.

Full Setup (with API Key)

# Install the AI-Pooler with your API key (hooks into Claude Code automatically)
npx @rulecatch/ai-pooler init --api-key=dc_your_key --region=us

# Add the MCP server to query violations from Claude
npx @rulecatch/mcp-server init

npm: @rulecatch/ai-pooler · @rulecatch/mcp-server

The AI-Pooler free monitor in action — tokens, cost, and tool usage updating in real time. Try it now: open a separate terminal and run npx @rulecatch/ai-pooler monitor --no-api-key

Explore RuleCatch.AI 7-day free trial - no credit card required

Recommended MCP Servers

MCP (Model Context Protocol) servers extend Claude's capabilities by giving it tools beyond reading and writing files. Each server below solves a specific problem in AI-assisted development. All are optional — install the ones that fit your workflow.

claude mcp add context7 -- npx -y @upstash/context7-mcp@latest

claude mcp add github -- npx -y @modelcontextprotocol/server-github

claude mcp add playwright -- npx -y @playwright/mcp@latest

claude mcp add classmcp -- npx -y classmcp@latest

claude mcp add strictdb-mcp -- npx -y strictdb-mcp@latest

npx @rulecatch/mcp-server init

See the Claude Code Mastery Guide for the complete MCP server directory.

Screenshots

The starter kit in action — every screenshot is from real command output.

/help Command Output

All 26 commands organized by category — Setup, Kit Management, Code Quality, Development, Infrastructure, Monitoring

/review Catching Violations

Severity-rated findings with file:line references, fix suggestions, and CLAUDE.md rule citations

Auto-Branching on Commit

Hook blocks commits to main and suggests feature branches — zero-friction branch safety

Hooks Firing (lint-on-save)

TypeScript error caught immediately after file write — PostToolUse hook in action

/diagram architecture Output

ASCII box-drawing diagram generated from actual source files — Client, API, Handler, Adapter layers

/setup Interactive Flow

Category-by-category .env configuration — GitHub, Database, Docker, Analytics, RuleCatch

AI Monitor — Free Mode

Live view of tool calls, tokens, cost, and files accessed — npx @rulecatch/ai-pooler monitor --no-api-key

E2E Test Assertions: Good vs Bad

Side-by-side comparison — a test that passes when broken vs one with real assertions

Credits

Based on the Claude Code Mastery Guide series by TheDecipherist:

• V1: Global CLAUDE.md, Security Gatekeeper, Project Scaffolding, Context7
• V2: Skills & Hooks, Enforcement over Suggestion, Quality Gates
• V3: LSP, CLAUDE.md, MCP, Skills & Hooks
• V4: 85% Context Reduction, Custom Agents & Session Teleportation
• V5: Renaming Problem, Plan Mode, Testing Methodology & Rules That Stick

Community contributors: u/BlueVajra, u/stratofax, u/antoniocs, u/GeckoLogic, u/headset38, u/tulensrma, u/jcheroske, u/ptinsley, u/Keksy, u/lev606