CLAUDE.md Architecture

A typical CLAUDE.md is a dump of rules: "use TypeScript", "run tests before committing", "prefer small PRs." This works for small projects, but it doesn't scale. Claude re-reads the whole file every session, rules contradict each other, and there's no way to route Claude to the right workflow for the task at hand.

The better approach: treat CLAUDE.md as a routing layer. It maps trigger words to skills, enforces mandatory gates before code gets written, and points to external documentation instead of duplicating it. The actual workflow logic lives in skills and plugins — CLAUDE.md just directs traffic.

CLAUDE.md operates at three levels. Global rules apply everywhere. Project rules override for specific repos. Skills contain the actual workflow logic.

The most powerful section of a global CLAUDE.md is the trigger matrix — a lookup table that maps natural language to skill invocations. When a user says something that matches a trigger, Claude invokes the skill instead of improvising.

## Skill Trigger Matrix

| Trigger Words | Skill |
|---|---|
| prime, boot, status, catch me up | /prime |
| chat, talk, explore, idea | /chat |
| spec, requirements, design, tasks | /spec |
| issue, bug, track this, new bug | /issue |
| debug, test failure, unexpected | /systematic-debugging |
| wrap, done for now, end of session | /wrap |
| portainer, docker, stack, proxy | /home-infrastructure |
| deploy verify, smoke test | /deploy-verify |
| release, version bump, patch | /release |
| pr resolve, review threads | /pr-resolve |
| remember, save, recall, forget | /remember |
| vault update, update docs | /vault-update |

This is a routing table, not a rule list. Claude sees the trigger words, matches them against the user's message, and invokes the skill via the Skill tool. The skill file contains the full workflow — CLAUDE.md doesn't need to describe the steps.

Why this works

• No duplication — workflow logic lives in one place (the skill), not scattered across CLAUDE.md
• Easy to extend — adding a new workflow means creating a skill file and adding one row to the matrix
• Discoverable — Claude can scan the table to find the right skill for any task
• Versioned — skills can be updated independently without touching CLAUDE.md

Gates are pre-conditions that must be satisfied before Claude writes any code. They prevent common mistakes: coding without an issue, committing to main, skipping documentation, forgetting version bumps.

## Mandatory Gates — Before Writing Any Code

| # | Gate | Detail |
|---|------|--------|
| 1 | Skill check | If a task matches a skill, invoke it first |
| 2 | Context7 | Query library docs before writing code |
| 3 | Issue required | Every code change needs a tracked issue |
| 4 | Worktree required | All changes in isolated branches |
| 5 | Spec for features | Non-trivial features need specs |
| 6 | Log implementation | HARD GATE — call before marking task done |
| 7 | Version bump | For version-locked projects |
| 8 | DocVault before PR | Update docs THEN push — HARD GATE |
| 9 | PR completion | Resolve all review threads before done |

Two gates are marked HARD GATE — Claude must never skip them, even if the user doesn't mention them. Gate 6 (log implementation before marking a task complete) and Gate 8 (update documentation before pushing a PR) are the most commonly violated without explicit enforcement.

Skills live in three layers. This separation lets you iterate on workflows quickly (layer 1), share them as plugins (layer 3), and add project-specific wrapper logic without touching the core (layer 1 shims).

The shim pattern

A skill shim is a thin SKILL.md that adds wrapper logic around a plugin command. For example, adding a git sync check before running /spec:

# Spec — Spec-Driven Development

## Pre-flight: Git Sync
Before starting, verify the working directory is clean:
- Run `git status --short`
- If there are uncommitted changes, ask: commit, stash, or discard?

## Pre-flight: Issue Check
Verify an issue exists for this work:
- Check if the user provided an issue ID
- If not, ask for one or offer to create via /issue

## Then: Invoke specflow:spec
Invoke `specflow:spec` via the Skill tool, passing the issue ID.

The shim is natural language — Claude reads and follows it. No compilation needed. If the plugin's core logic changes, the shim stays the same. If you need project-specific pre-checks, edit the shim without touching the plugin.

Project-level CLAUDE.md files should be short and specific. Point to documentation, don't duplicate it. List project-specific skills, not global ones.

# StakTrakr

Free, privacy-first precious metals portfolio tracker.

## Documentation
Read DocVault/Projects/StakTrakr/ for architecture, API design,
and deployment docs. Start at the Overview page.

## API Infrastructure
| Feed | Staleness | Provider |
|------|-----------|----------|
| Spot prices | 5 min | metals-api.com |
| Retail prices | 30 min | Custom pollers |
| Historical | 24 hr | Cache layer |

## Critical Patterns
- All DOM manipulation via innerHTML with DOMPurify sanitization
- Storage keys prefixed with `stak_` in localStorage
- Version locked in devops/version.lock

## Issue Tracking
Prefix: STAK | Tag: staktrakr
Path: DocVault/Projects/StakTrakr/Issues/

## Project Skills
- /api-infrastructure — feed health, staleness checks
- /release — version bump workflow (6 phases)
- /ui-mockup — Stitch visual mockups

What NOT to put in project CLAUDE.md

• Architecture explanations (put in DocVault, link to it)
• Deployment procedures (put in a skill or runbook)
• Global rules (they're in ~/.claude/CLAUDE.md)
• Full API documentation (put in-repo at docs/)
• Historical decisions (put in mem0 or DocVault)

Knowledge Lookup Order

Tell Claude where to find information, in priority order:

## Knowledge Lookup Order
1. DocVault first — read ~/DocVault/ for architecture questions
2. mem0 second — search for past decisions and session context
3. Code third — read source files for current implementation
Never answer from training knowledge alone.

Code Search Order

If you have multiple code search tools, rank them cheapest-first:

## Code Search — Cheapest First
1. code-graph-context — structural: callers, imports, dead code
2. claude-context — semantic: "find code related to X"
3. Grep / Glob — literal strings, exact identifiers
4. code-oracle agent — only when tiers 1-3 leave gaps

Repo Boundaries

If you manage multiple projects, define PR targets and version locking:

## Repo Boundaries
| Repo | PR Target | Version Lock |
|------|-----------|-------------|
| StakTrakr | dev | devops/version.lock |
| HexTrackr | dev | devops/version.lock |
| Forge | main | devops/version.lock |
| MyMelo | main | — |

- NEVER push directly to main — always worktree + PR
- NEVER merge dev to main unless user says "release"

MCP Servers

List your MCP servers so Claude knows what tools are available:

## MCP Servers
| Server | Use For |
|--------|---------|
| mem0 | Cross-session memory |
| claude-context | Semantic code search (Milvus) |
| context7 | Library documentation lookup |
| codacy | Code quality analysis |
| infisical | Secrets management |

1. Start with the global file

mkdir -p ~/.claude
# Create ~/.claude/CLAUDE.md with:
# - User profile (role, preferences)
# - Skill trigger matrix (start with 5-10 triggers)
# - Mandatory gates (start with: issue, worktree, docs-before-PR)
# - Knowledge lookup order
# - Red flags section

2. Create your first skills

mkdir -p ~/.claude/skills/issue
mkdir -p ~/.claude/skills/wrap
# Write SKILL.md files with the workflow logic
# CLAUDE.md routes to them — it doesn't contain them

3. Add project-level files

# In each project repo
# Keep it under 100 lines
# Point to docs, list project skills, define boundaries