Global Instructions
In one line: Global instructions encode cross-project rules and working style once, so every project inherits them instead of re-deriving them.
What: Global instructions live in ~/.claude/CLAUDE.md and ~/.claude/settings.json. They configure behavior that should be consistent across every project the developer works on.
Why: Without them, every project's CLAUDE.md re-specifies the same cross-cutting rules — ports, migration tooling, UI patterns, testing philosophy — and they drift, causing port collisions during parallel development. Global instructions set the baseline once.
They also encode working style ("always use subagent-driven development," "design before code," "no native dialogs") — judgment calls made once, then followed without reminding.
What belongs here:
| Category | Example | Rationale |
|---|---|---|
| Port assignments | Frontend :3001, Backend :8002, PostgreSQL :5432 | Prevents collisions between projects running simultaneously |
| Cross-project rules | "Always use Alembic for DB migrations" | Consistency across all projects using the same database tooling |
| Shared quality standards | "Design before code: brainstorm, spec, plan, execute" | Methodology rules that apply regardless of tech stack |
| Behavioral preferences | "Use subagent-driven development," "No native dialogs" | Working style encoded as structure, not discipline |
| Permission configuration | defaultMode: dontAsk with explicit allowlist | Trust calibration — tools the developer has validated as safe to run without confirmation |
| Plugin enablement | Superpowers, Pyright LSP, Frontend Design | Plugin availability across all projects |
What does NOT belong here:
- Technology-specific rules (asyncpg cast syntax, Temporal testing patterns) — these belong in project CLAUDE.md because they only apply to projects using those technologies.
- Architecture descriptions (data flow diagrams, service module inventories) — these are project-specific context.
- File path references (unless they point to cross-project resources like shared architecture documents).
Evidence: A shared port-assignment table in the global CLAUDE.md mechanically prevents collisions between projects running in parallel; reproducible by running two projects whose ports overlap and watching the bind failure that the table exists to avoid. templates/global-claude.md ships the parameterized version.
How: See templates/global-claude.md for a parameterized template. The setup guide (Step 4) walks through merging the template with existing global instructions, preserving any project-specific content the developer already has.