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.

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

Project Structure

project/
├── CLAUDE.md                    # Project instructions (customize this!)
├── CLAUDE.local.md              # Personal overrides (gitignored)
├── .claude/
│   ├── settings.json            # Hooks configuration
│   ├── commands/
│   │   ├── 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-clean-as-default.md # /set-clean-as-default — clean as default profile
│   │   └── reset-to-defaults.md # /reset-to-defaults — reset to default profile
│   ├── 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
├── src/
│   ├── core/db/index.ts         # Centralized database wrapper
│   ├── handlers/                # Business logic
│   ├── adapters/                # External service wrappers
│   └── 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
├── .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.

# Run in a separate terminal
npx @rulecatch/ai-pooler@latest monitor -v

/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

Skills — Triggered Expertise

Skills are context-aware templates that activate automatically when Claude detects relevant triggers. Unlike commands (which you invoke), skills load themselves when needed.

┌─────────────────────────────────────────────────────┐
│                    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 wrappers                         │
│  → Database, 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

Database Wrapper — Production MongoDB

The starter kit includes a production-grade MongoDB wrapper at src/core/db/index.ts using the native driver (no Mongoose, no ODMs). It enforces every best practice that prevents the most common database failures in AI-assisted development.

The Absolute Rule

ALL database access goes through src/core/db/index.ts. No exceptions. Never create new MongoClient() anywhere else. Never import mongodb directly in business logic.

// CORRECT — import from the centralized wrapper
import { queryOne, insertOne, updateOne } from '@/core/db/index.js';

// WRONG — NEVER do this
import { MongoClient } from 'mongodb';  // FORBIDDEN outside src/core/db/

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

Additional Features

• Singleton per URI — same 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

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 '../../src/core/db/index.js';

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 the MongoDB wrapper — 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 the wrapper.
- 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): Create MongoDB wrapper
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

This starter kit gives you rules, hooks, and quality gates. But how do you know when they're actually being followed?

RuleCatch.AI monitors your AI-assisted development sessions in real-time, detecting rule violations as they happen. It uses the same Claude Code hooks system this starter kit teaches — running completely outside the AI context with zero token overhead.

200+ Pre-Built Rules

Security, TypeScript, React, Next.js, MongoDB, Docker, Python — violations detected in under 100ms

Session Analytics

Track token usage, cost per session, lines per hour, and correction rates across your team

MCP Integration

Ask Claude directly: "RuleCatch, what was violated today?" — query violations without leaving your session

Privacy-First & GDPR Compliant

AES-256-GCM client-side encryption. You hold the key — RuleCatch never sees your plaintext data. Fully GDPR compliant with servers in both the US and EU

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.

Quick Setup

# Install the AI-Pooler (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 CLI also gives you a live terminal view — tokens, cost, violations, and tool usage updating in real time as you work.

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

Recommended MCP Servers

# Live documentation (eliminates outdated API answers)
claude mcp add context7 -- npx -y @upstash/context7-mcp@latest

# GitHub integration (PRs, issues, CI/CD)
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# E2E testing
claude mcp add playwright -- npx -y @anthropic-ai/playwright-mcp

# AI development analytics & rule monitoring (RuleCatch.AI)
npx @rulecatch/mcp-server init

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

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