Seb's Claude Code Setup

directory map

Where things live

Claude Code reads configuration from a few well-known places. This setup uses all of them:

~/CLAUDE.md                     # global instructions, loaded every session
~/.claude/
├── settings.json               # permissions, hooks, plugins, model
├── rules/
│   ├── projects.md             # taxonomy of every service I run (the fleet)
│   └── reflections.md          # pointers to post-mortem write-ups
├── skills/                     # ~35 skills, custom + third-party
├── hooks/  scripts/            # hook scripts (PowerShell + bash)
├── plugins/                    # marketplace plugins (superpowers, frontend-design)
├── wiki/                       # per-service spec sheets ("LLM wiki")
└── projects/<cwd>/memory/      # persistent memory, one fact per file

The theme of the whole setup: put knowledge in files the model reads, and enforcement in hooks the harness runs. Instructions drift; hooks don't.

~/CLAUDE.md

The rules file, lightly redacted

This is the global CLAUDE.md, minus sections that only describe my private server environment. It's grown over months of corrections — nearly every rule exists because Claude once did the opposite.

Think before coding

• Before implementing non-trivial changes, state assumptions and interpretation of the request explicitly.
• If multiple approaches exist, present them briefly — don't pick silently.
• If something is ambiguous, ask rather than guess.

Surgical changes

• Every changed line must trace directly to the current request.
• Don't "improve" adjacent code, comments, or formatting opportunistically.
• Match existing style even if you'd write it differently.
• If you notice unrelated issues, mention them — don't fix them silently.

Goal-driven execution

• For non-trivial tasks, state brief success criteria before starting implementation.
• "Fix the bug" → "Write a test that reproduces it, then make it pass."
• For multi-step work, state the plan with verification checkpoints.

Debugging discipline

• If more than 5 diagnostic commands run without progress, stop and summarize findings so far — what's been ruled out, the current best hypothesis, what data is missing.
• Don't chase a third hypothesis without reporting the first two's outcomes.

Fail visibly

• Never coerce a dependency failure into a "no result" outcome — surface it as an error.
• Never update staleness timestamps (last_checked, last_synced) on failed operations.
• If an external call errors, the user must know — don't swallow it into a default that looks like normal operation.

Test quality

• Tests must verify the actual fix or feature — not just "does it run without errors."
• A test that can't fail is worse than no test. If you can't articulate what regression the test catches, rewrite it.
• Tests with DB side effects must mock the persistence helper — never let a test write to a production store.

Discipline (the greatest-hits section)

• Close the loop: never say "fixed" or "done" without verifying the way the user would experience it — including delegated work.
• Model the system: before changing a config, script, or shared resource, identify what else depends on it. For infra changes, ask "what breaks if this is wrong?" and add safeguards.
• Chesterton's Fence: before modifying code you didn't write, understand why it exists.
• Learn from corrections: when the user corrects your approach, save a feedback memory before moving on.
• Confirm destructive ops: pause before rm -rf, DROP, reset --hard, force-push — even in auto-accept mode.
• Enumerate failure modes first: before coding against an external system (broker, API, network), list the ways it can fail and handle each.
• Backport fixes: after fixing a bug in one service, grep siblings for the same pattern; promote recurring fixes to a shared library.

Communication preferences

• When I say "execute it" or "run it", take immediate action — don't explain that something is already running.
• When I give a specific name for something, use it exactly on the first attempt.
• Don't frame work in calendar timelines ("this week", "N-week plan") — group by scope and dependency.
• When a response requires a manual sudo/restart step, restate the exact command at the very end.

Don't

• Don't summarize what you just did at the end of every response — I can read the diff.
• Don't add disclaimers to investment/stock discussion.
• Don't ask for confirmation on names or commands I've already specified.

~/.claude/skills + ~/.claude/plugins

Skills & plugins

Skills are markdown playbooks Claude loads on demand (or via /slash-command). Mine split into three groups.

Plugins, from the official marketplace

Install via /plugin → browse the claude-plugins-official marketplace.

Third-party skill packs (dropped into ~/.claude/skills/)

Custom skills (the real unlock)

About 15 more are hand-written operational runbooks for my own fleet of services: /deploy (transfer + checksum + restart + log-check sequence), /health (read-only diagnosis of a live service), /remote-edit, /new-service (first-deploy checklist across every registration surface), /sunset (decommissioning sequence), /wiki-refresh, /grill-me (interviews me relentlessly about a plan before I build it), and an idea-queue pair (/idea, /queue).

~/.claude/projects/<cwd>/memory/

Memory system

Claude Code gives the model a persistent per-project memory directory. The convention: one fact per file, with frontmatter typing it as user (who I am), feedback (corrections — "you did X wrong, do Y, here's why"), project (ongoing work state), or reference (pointers). A MEMORY.md index — one line per memory — is what actually loads into context each session; bodies are read on demand.

---
name: feedback-verify-order-fills
description: Never assume an order filled — verify via position check
metadata:
  type: feedback
---
Never assume an order filled just because "open orders is empty".
**Why:** an order can vanish from the open list by being cancelled.
**How to apply:** confirm via a position or balance query after placing.

Currently ~100 memories: ~50 project state files, ~50 feedback files, a handful of reference pointers, plus two long-form "engineering reflection" post-mortems distilled from finished projects.

Recent work: making memory self-maintaining

Hand-maintained memory rots, so three hooks now automate the janitorial work:

• Index rebuild (PostToolUse on Write/Edit) — whenever a memory file is written, a script regenerates the MEMORY.md index from the files' frontmatter. The index can no longer drift from the directory.
• Weekly lint (SessionStart, stamped to run at most every 7 days) — checks memories for staleness, broken cross-links, and duplication, and injects a digest into session context so Claude sees "these 3 memories look stale" at startup.
• Recall ledger (SessionEnd) — streams the session transcript and records which memory files were actually read this session. Memories that never get recalled are candidates for pruning; a memory system is only as good as its hit rate.

Two conventions from CLAUDE.md complete the loop: when I correct Claude's approach, it must save a feedback memory in the same session; and when new facts refute an old memory, the old file gets a SUPERSEDED tombstone edited in immediately — "a correction buried below a wrong headline doesn't exist."

~/.claude/settings.json → "hooks"

Hooks

Hooks are shell commands the harness runs at lifecycle events — the model can't skip them, which is exactly the point. Guardrails you'd otherwise write as instructions become mechanical:

settings.json / MCP / ~/.claude/wiki

Settings, MCP, and the wiki

settings.json highlights

{
  "permissions": { "allow": ["Read","Edit","Write","WebFetch","WebSearch","Bash(*)"],
                   "defaultMode": "auto" },   // trusted machine; hooks are the guardrails
  "effortLevel": "high",
  "enabledPlugins": { "superpowers": true, "frontend-design": true },
  "hooks": { /* …section above… */ }
}

Permissions are wide-open because the risky paths (package installs, shared-lib edits, email) are individually gated by hooks — allowlist coarse, guard fine.

MCP servers & connectors

• claude-in-chrome + chrome-devtools — drive a real browser: click, fill forms, read console/network, screenshot.
• ssh-remote — native command execution on the remote server that hosts the service fleet.
• Gmail / Calendar / Drive — claude.ai connectors for mail search, drafting, scheduling.
• A local Gmail MCP server (Node.js) predating the connectors — worth knowing you can write your own in an afternoon.

The service wiki

The biggest custom piece: I run ~20 small always-on services (bots, screeners, monitors) on one server, and Claude operates all of them. ~/.claude/wiki/ holds one spec sheet per service — machine-readable frontmatter (unit name, ports, dependencies, data stores) plus a prose "decisions & gotchas" section. CLAUDE.md requires reading a service's page before non-trivial work on it, and a /wiki-refresh skill re-derives the frontmatter from live server state after big changes. A weekly lint job flags drift (new services without pages, stale entries, broken paths).

Alongside it, ~/.claude/rules/projects.md is a one-page taxonomy of every service — so "check on all the trading stuff" resolves to a concrete checklist instead of a guess.

closing notes

If you're starting from zero

• Start CLAUDE.md tiny. Add a rule only when Claude does something you'd correct a junior for — and phrase it as the correction. A rules file written speculatively is noise.
• Install the superpowers plugin first. Process skills (brainstorm → plan → TDD → verify) change output quality more than any prompt tweak.
• Promote repeated explanations to skills. Second time you type the same procedure, it's a skill.
• Put enforcement in hooks, knowledge in files. Instructions are suggestions; hooks are law.
• Let memory accumulate from corrections, not from ceremony — the feedback-memory habit compounds fastest, but budget for pruning (hence the lint + recall ledger).