The architecture, as a map.

Your local development environment must mirror what production will look like. Build the workshop first — everything else depends on it.

Three rules: same container shape as production; a live preview answering its own URL; one command brings the whole stack up.

# ./start.sh output
✓ Docker running
✓ Stack up
Web: http://localhost:8080

I want a Docker-based local dev environment that mirrors production:
  Web framework: [DJANGO / RAILS / NEXT.JS / etc.]
  Database: MARIADB (default — or postgres / sqlite)
  Live preview port: 8080

Write me docker-compose.yml + start.sh.
Mount my source as a volume for live reload.
Make start.sh executable. Run it. Verify with curl.

services:
  web:
    image: [your-base-image]
    volumes:
      - .:/app
    ports:
      - "8080:8080"
    depends_on: [db]
  db:
    image: mariadb:11
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_DATABASE: ${DB_NAME}
    volumes: [dbdata:/var/lib/mysql]
volumes:
  dbdata:

#!/usr/bin/env bash
set -euo pipefail
docker compose up -d
echo "Web: http://localhost:8080"

Your production-shape stack is now running on your laptop. Same containers your servers will run.

CLAUDE.md is the first message the AI sees on every session. Not documentation for humans. Optimize it for the AI's eyes.

Three things go in: hard rules, the tool selection protocol, and named frameworks. Facts that change live in the knowledge graph, not here.

Write me a CLAUDE.md operating manual.

Project: [NAME — one-line description]
Layers: [LIST — e.g. "DB, API, admin, mobile, public"]
Database: MARIADB (default — or postgres / sqlite)
Stack: [LANGUAGE + FRAMEWORK]

Sections needed: Pre-Change Protocol, Tool Selection
Protocol, Four Guards, Sub-agent tiers, Commit rules.
Target: under 500 lines. Load-bearing only.

The AI just walked into your repo already knowing what you care about.

Give the AI better senses through MCP servers. Default tools (full-file read, grep, raw shell) are wrong on a real codebase.

Five MCP servers do most of the work:

• Code intelligence — Serena. Symbol-level retrieval via LSP. Cuts read-token spend ~10×.
• Live data — a database MCP matching your stack. AI queries the real schema instead of guessing.
• Browser automation — Playwright MCP. AI clicks through your live preview like a user.
• Doc retrieval — fetches sections of long docs, not the whole file.
• Knowledge graph — Stop 04.

Install these MCP servers in my Claude Code:
  1. Serena (code intel) - github.com/oraios/serena
  2. jCodeMunch (repo-scale code intel, blast radius, dep graphs)
  3. jDocMunch (section-level doc retrieval)
  4. MemPalace (knowledge graph + memory drawers)
  5. MariaDB live-DB MCP (default — or postgres / sqlite)
  6. Playwright MCP for browser automation

For each: find the install command, run it, verify with a
small test query.

Then add a Tool Selection Protocol to CLAUDE.md. Five
questions, in order: code → doc → cross-cutting wiring →
large output → conceptual. Forbid Read on indexed code.

Your AI now has eyes on the real schema. Hallucinated columns — gone.

The AI without memory walks in cold every session. The AI with memory walks in already knowing what you fixed last Tuesday.

Three entity types to start: Decision (why we chose this), KnownBug (we fixed this before), Rule (this is what we learned). A hook queries the knowledge graph on every new session and dumps relevant entities into the AI's context.

Build me a knowledge graph for this project.

Three entity types: Decision, KnownBug, Rule.

Need:
  1. A Python MCP server backed by SQLite. Tools:
     kg_query, kg_add, kg_list.
  2. A SessionStart hook (~12 lines of bash). Queries the
     KG by current branch + recent diff. Dumps matches as
     a system-reminder.
  3. A post-commit hook that re-indexes the KG.

Then seed 5 KnownBug entries (I'll list).

The first time the AI walks in and says "you fixed this on Tuesday, here's why" — the AI just became a colleague.

One operator. One Architect that plans. Specialists that execute. The Architect never writes code. The operator signs every decision.

Create three Claude Code sub-agent definitions:
  1. architect.md - largest-tier. Plans only. Never writes code.
     Produces a plan: Mission / Layers / Order / Acceptance /
     Verification / Commit msg. Waits for operator sign-off.
  2. executor.md - medium-tier. Implements plan literally.
     Full git autonomy.
  3. researcher.md - medium-tier. Read-only. SELECT-only DB.

And one slash command:
  4. /plan <description> - dispatches Architect → operator
     sign-off → Executor with approved plan.

You just stopped the AI from making the most expensive mistake in software: starting work it didn't yet understand.

Non-AI. Bash and Python. Regex + state files. An AI can argue any position eloquently. A regex cannot be persuaded. That asymmetry is what makes the whole stack shippable.

The four guards: Pre-Change Protocol (warns on edits to load-bearing files without prior KG query), Schema-Verify (refuses destructive DB ops on un-inspected tables), Parity Check (pre-commit gate; refuses if layers disagree), KG Refresh (post-commit; rebuilds the system map).

Install four non-AI guards for my project. Bash + Python only.

  1. .claude/hooks/pre-change-protocol.sh — PreToolUse hook
     on Edit/Write. Warns when load-bearing files are about
     to be edited without a prior KG query this session.

  2. .claude/hooks/schema-verify.sh — PreToolUse on the
     live-DB MCP. Parses SQL for destructive verbs
     (INSERT/UPDATE/DELETE/ALTER/DROP/TRUNCATE/RENAME).
     Refuses if target table wasn't inspected this session.

  3. .githooks/pre-commit — parity check on every staged
     file. Refuses if any two layers disagree.

  4. .githooks/post-commit — background-runs the KG miner.

Wire them. Activate: git config core.hooksPath .githooks
Default mode: WARN.

The AI just hit a wall it cannot argue past. That asymmetry is yours now.

Most platforms have 3–7 layers. Each has a different audience and writer. If any two stop agreeing about a field, somebody gets called by the wrong number on a wedding day.

Customize parity-check.sh.template for the [ENTITY] entity.

For each of my five layers, find which fields exist:
  - Database: query my schema
  - API: parse my serializer / API definition
  - Admin: parse my admin form
  - Mobile: parse my Codable / model
  - Public: parse my public template

Generate fields_in_*() functions. Smoke-test by staging a
one-line edit. If two layers disagree, the gate refuses.

Your model now physically cannot ship a half-finished feature.

Most apps die the day the user is offline. Build for the venue with bad WiFi, not the happy path. Skippable if you have no mobile app.

Every record carries a small metadata bundle (identifier, version counter, hash, soft-delete flag, per-field timestamps). The phone holds a local mirror. Offline edits queue. They drain on reconnect. The server-side merge is authoritative for money and state. (Academic name: CRDT-adjacent.)

Build offline-first sync for my mobile app.
Stack: [LANGUAGE], DB: MariaDB (default)

Help me:
  1. Choose a sync engine (Replicache, PowerSync, custom).
  2. Define per-record metadata: identifier, version, hash,
     soft-delete, per-field timestamps.
  3. Set merge precedence: server wins for money + state;
     phone wins for free-text.
  4. Wire the mobile local mirror.
  5. Write a sync-contract.md.

Your user just survived a WiFi outage without knowing there was one.

Every external system has a bad day. Plan for that day. Every integration fails closed.

For each external system you depend on (payments, email, calendar, storage, webhooks), wrap the call so that if the system errors, your code returns "we'll retry later" — not "success." Also: rate-limit primitives on public POST endpoints, and an SSRF guard on every server-side URL fetch.

For every external integration (payments, email, calendar,
storage, webhooks):

  1. Wrap with fail-closed logic. If external errors,
     return "we'll retry later" — not "success."
  2. Rate-limit every public POST endpoint.
  3. SSRF guard: refuse fetches to internal IPs and cloud
     metadata.
  4. Document in integration-map.md.

For each, show me a phantom-success failure mode my current
code might have, and the fix.

Your platform now tells the truth under stress.

Same container topology in production as on the desk. "Works on my machine" stops being a possible failure when the machines are identical.

Production runs on a VPS with the same docker-compose.yml as local. A reverse-proxy called Caddy auto-issues TLS for your domain. The deploy script takes a database backup before touching anything; if the post-deploy health check fails, the previous version is restored automatically.

Set up production deployment.
VPS: [HOST/IP], user [SSH_USER], domain [DOMAIN].

Generate:
  1. bin/vps/deploy.sh - backup → pull → up → health-check
     → rollback-on-fail. Takes a DB backup first.
  2. bin/vps/rollback.sh - restore latest backup, revert
     to HEAD~1, restart.
  3. etc/Caddyfile.template - Caddy reverse-proxy with
     auto-TLS for my domain.
  4. etc/.env.example - every env var production needs,
     with comments. Never commit real secrets.

Walk me through the first supervised deploy. Stop before
any destructive command and confirm.

Your stack is running on a server with the same containers as your laptop. Production exists.

Real customer data deserves real security maturity. Defense in depth. Multiple unrelated guards on every sensitive surface, so no single failure is catastrophic.

Two threats to defend against

Daily threat: the random internet scanner that finds your platform by accident and walks the public surface looking for anything default, exposed, or sleepy.
Tail-risk threat: the targeted attacker who actually wants the customer data in your database.

The architecture defeats the first comfortably and slows the second enough that anything they touch leaves a trail.

The nine guards of defense in depth

1. Money + state machines recomputed from canonical sources on the server. Never trusted from the screen.
2. Public POST endpoints rate-limited with fail-closed primitives.
3. Server-side URL fetches guarded against internal IPs and cloud metadata (SSRF guard).
4. Passwords hashed with a modern memory-hard key-derivation function. Auto-upgraded on next login.
5. 2FA codes replay-resistant. Used codes cannot be reused.
6. User-supplied HTML (email templates, page-builder blocks) sanitized at save time, not at render. Saved content is already safe.
7. Uploaded files content-type checked against actual bytes, not extension.
8. CSP headers enforced on every response. Violations reported.
9. TLS auto-issued by Caddy and renewed transparently. Nothing speaks plaintext to the outside world.

Red-team my codebase against the nine-guard checklist:

  1. Money + state recomputed server-side
  2. Public POST endpoints rate-limited
  3. SSRF guard on server-side URL fetches
  4. Modern password hashing + auto-upgrade
  5. 2FA replay protection
  6. HTML sanitized at save
  7. Uploaded files content-type checked by bytes
  8. CSP enforced + reported
  9. TLS auto-issued

For each: find one specific place I might be exposed.
Tell me the fix without naming the exact attack shape
(I don't want a writeup that becomes a checklist for
attackers). Write findings into a SECURITY.md.

A feature is not finished when it works. It is finished when it fails safely.