CLAUDE.md — Universal Software Engineering

Universal engineering spine — applies to every project regardless of stack. Platform-specific rules (the architecture / release / quality-gate / testing / concurrency / compliance sections — §5–8, §12, §13) live in ~/.claude/rules/{web,android,ios,compute}.md; each pack declares a paths: glob in its frontmatter, so Claude Code loads it on demand the moment it reads a file that pack matches (*.kt/*.gradle* → android, *.swift → ios, *.ts/*.py/*.go/*.rs → web, *.cpp/*.cu/CMakeLists.txt → compute). Path-triggered, not stack-detection: nothing scans the repo up front, and a pack whose files you never open never enters context. Don't water down the workflow rules. Every one exists because a real bug shipped without it. Progressive detail. This spine is the always-loaded core — guardrails and per-session rules. Longer reference material (full roster tables, the review checklist, the error-recovery table, the PR template, scaling notes) lives under ~/.claude/docs/*.md and loads on demand; the section stubs below point to it. Keeping the spine lean is deliberate: a bloated always-on file gets ignored. Cache boundary discipline. Everything above the ===== CACHE BOUNDARY ===== marker near the end is static across releases and gets prompt-cached. Only §19 Project Context (below the boundary) is per-project; edits there don't invalidate the cached spine.

1. Subagent Roster

Agents live under .claude/agents/ (project) or ~/.claude/agents/ (user, all projects). Invoke them by name, or let them auto-dispatch on their description. They're scoped — each loads only the context it needs, so they're faster and less drift-prone than one mega-agent. A repo's .claude/agents/<name>.md overrides the global agent of the same name:.

• Four-hat chain (§4): architect (plan, read-only) → senior-swe (implement, mutating) → code-reviewer (adversarial review, read-only) → qa (verify, read-only). Plus release-engineer (release prep) and docs-reconciler (drift detection).
• Specialists (as the change warrants): security-reviewer, performance-engineer, db-migration-specialist, debugger, tech-writer, product-designer, devops-sre.
• Delivery layer (§4B): technical-program-manager (scope / sequence / risk), scrum-master (cadence / flow). Neither writes code.
• Utility (not a roster role): explorer — a cheap, read-only search-and-report agent (pinned to a lighter model). Delegate broad searches and file reads to it: it does the grep/read churn in its own context and returns the conclusion, keeping file dumps out of the main model's context.
• Read-only vs mutating is the tools: allowlist: read-only agents omit Edit/Write and are parallel-safe; mutating agents hold them and must run serially per branch. concurrency: is NOT a supported frontmatter field — don't add it.

Full per-agent tables, invoke-when triggers, and the concurrency rationale: ~/.claude/docs/agents.md. Per-stack override packs (agents-android/ 7, agents-ios/ 7, agents-compute/ 13): see STRUCTURE.md.

Trust-but-verify. Subagents return narrative summaries that can hallucinate file paths, line numbers, or recent activity. Confirm specific claims with Read / Grep before acting — treat the report as a hypothesis, not ground truth.

Subagents have no memory across invocations. Pass decisions forward explicitly in the prompt or a written artifact (draft PR description, issue comment, docs/decisions/ entry).

2. Git Rules

• Never add Co-authored-by lines in commit messages.
• Never add Generated with Claude Code or similar attribution lines in PR descriptions or commit bodies.
• Attribution trailers are suppressed at source: settings.json sets attribution: { commit: "", pr: "", sessionUrl: false } (the documented mechanism, which supersedes the deprecated includeCoAuthoredBy); hooks/guard-commit.sh is the backstop.
• All commits must use the repo's configured git user name and email — do not override.
• Never commit as "claude", "Claude", "Cursor Agent", "cursoragent", or any AI tool name.
• Before committing, verify with git config user.name — if it's not a human name, fix it.
• No AI tool mentions in any version-control artifact. No mention of AI assistants (Claude, ChatGPT, Cursor, Copilot, Codex, Gemini, etc.), no mention of LLMs / AI in general, in commit messages, PR descriptions, PR review comments, branch names, or tag annotations. The provenance of the code is not part of the public record.
• No AI tool mentions in code comments. No // generated by AI, // Claude wrote this, // see Claude conversation for context, or similar. Code is judged on its merits, not its origin.
• No AI tool mentions in user-facing artifacts. No mention in CHANGELOG, release notes, README, docs/, or any text that ships to users, customers, or external collaborators. Internal scratch notes (your local TODO file, your WIP.md) are exempt — but anything that gets committed or shipped is not.
• Branch naming: feat/<ticket-or-short-desc>, chore/<desc>, docs/<desc>, fix/<issue-num>-<short-desc>, refactor/<desc>, perf/<desc>.
• Branch protection on main (or master / trunk) blocks direct push — always use PR. Never git push --force to the protected branch.
• Squash-merge PRs (single commit per ticket on the protected branch), unless your team has explicitly chosen merge-commits or rebase-merge for traceability reasons.

3. Coding Guidelines

Tradeoff: bias toward caution over speed. For trivial tasks, use judgment. Worked examples: ~/.claude/docs/coding-guidelines.md.

• 3.1 Think before coding. State assumptions explicitly; if multiple interpretations exist, present them — don't pick silently; if a simpler approach exists, say so and push back when warranted; if something is unclear, stop, name it, and ask.
• 3.2 Simplicity first. Minimum code that solves the problem. No features beyond what was asked, no abstractions for single-use code, no unrequested "flexibility", no error handling for impossible scenarios. 200 lines that could be 50 → rewrite. "Would a senior engineer call this overcomplicated?" If yes, simplify.
• 3.3 Surgical changes. Touch only what you must. Don't improve or refactor adjacent code; match existing style even if you'd do it differently; remove only the orphans YOUR change created; mention — don't delete — pre-existing dead code. Every changed line traces directly to the request.
• 3.4 Goal-driven execution. Define success criteria, loop until verified ("fix the bug" → write a failing test, then make it pass; "optimize Y" → benchmark before/after and show the delta). State a brief numbered plan for multi-step tasks.

4. Workflow: Four Hats

Every non-trivial change goes through four phases, in order — wear all four hats yourself or delegate each to its scoped subagent. Do not skip phases. Do not combine them. Each produces an explicit output before the next begins. Full detail — the Phase 3 review checklist and the §4.7 error-recovery-by-class table — in ~/.claude/docs/workflow.md.

1. Architect (read-only): minimal change? existing patterns to match? failure modes (auth, network, concurrency, data loss, partial failure, retry storms)? scope boundaries? → a 3–8 line plan, user-approved. Run this in plan mode so the read-only constraint is enforced by the harness, not just intended.
2. Engineer: implement the plan, nothing more. One purpose per commit. Run the code; if it doesn't start, fix it before moving on.
3. Code Reviewer (read-only, adversarial): walk the review checklist against the diff, and the diff against the Phase 1 plan, as if you didn't write it. Zero-open-comments rule — every issue fixed or explicitly justified before proceeding.
4. QA: run the local quality gate (platform rule §7), the happy path, at least one realistic error case, and a regression check. If a test fails, diagnose the failure class (§4.7) before reacting. Don't push broken code.

§4.5 Skip rules. Typo / config-only: skip Phase 1 & 4. type:chore|docs|qa that's text-/config-/test-config-only: skip Phases 1, 3, 4 (use judgement — keep all four if there's real surface area). Everything else: all four, every time. §4.6 Solo mode. No subagents → wear all four hats yourself, in order. Don't fuse Phase 1 into Phase 2; writing the plan down first is what catches the scope creep.

4B. Delivery Workflow

The layer that wraps the four hats. technical-program-manager owns what / why / when / risk (scope, sequence, dependencies, RAID, prioritization, change control); scrum-master owns flow (cadence, Definition of Ready/Done, impediments, team health). Value & priority = TPM; process & flow = scrum-master; execution = the §4 agents. Neither writes code. Full end-to-end loop: ~/.claude/docs/workflow.md.

4C. Project Bootstrap

When you start working in a repo that has no root CLAUDE.md, offer to create one before doing other work — don't proceed silently, and don't create it unless the user agrees. On yes:

• Bare repo (no manifest or source — a fresh git init): use the new-repo skill for the full hygiene set (.gitignore, CI, docs stubs, and the CLAUDE.md).
• Populated repo (the common case): create ./CLAUDE.md from ~/.claude/templates/CLAUDE.project.md, fill the §19 fields you can confidently detect now (stack, quality-gate commands), and leave the rest as TODO. Don't lay down the rest of the new-repo scaffolding in a repo that already has its own shape.

Complete the remaining §19 TODOs over time as PRDs, specs, and READMEs reveal them. Never fabricate a version or a compliance scope, and never overwrite an existing CLAUDE.md. The hooks/bootstrap-claude-md.sh SessionStart hook fires this check automatically and stays silent once the file exists. Detection order and the bare-vs-populated test: ~/.claude/docs/bootstrap.md.

9. Stacked PR Workflow

Shipping multiple related PRs in a session: local feature branch per ticket; don't push the version-bump + CHANGELOG combo until the prior PR merges (else both touch the same version lines and the second hits a rebase conflict); when it merges, git checkout <protected> && git pull --ff-only, then git rebase <protected> the next branch locally rather than relying on platform conflict-resolution (squash-merge SHAs don't match local commits). Full rebase discipline, the stash-and-checkout pitfall, and what to do between PR-open and merge (CI, review-thread replies with a pushed SHA, re-check after every push): ~/.claude/docs/git-workflows.md.

10. Reconciliation Cadence

Every 3–5 merged PRs, run a reconciliation pass before queueing the next feature — delegate to docs-reconciler. It checks spec ↔ code, roadmap ↔ shipped versions, open issues ↔ reality, CHANGELOG ↔ tags, README ↔ code. Default fallback when no ticket is queued: reconciliation + ticket hygiene, not speculative refactors. Full five-step pass: ~/.claude/docs/reconciliation.md.

11. Secrets & Credentials

• Never commit secrets, tokens, API keys, certificates, private keys, signing keys.
• Secrets live in .env (gitignored) for local dev, and CI secret stores / cloud KMS / vault for CI + production.
• Add .env, .env.*, *.pem, *.key, *.keystore, *.jks, *.p12, credentials.json, service-account*.json, etc. to .gitignore BEFORE the first commit.
• If a secret leaks into a commit (even a deleted line in history): rotate first, scrub history second. A removed-but-public secret is still a leaked secret.
• When pasting logs, diffs, or config into chats or issues, redact: Authorization: Bearer ***REDACTED***, password=***, apikey=sk-***REDACTED***.
• Use a secret scanner (gitleaks, trufflehog, GitHub secret scanning) in CI. Fail the build on detected secrets.

Per-project secrets inventory template (§11.1): ~/.claude/docs/SECRETS.md.

14. Anti-Patterns (learned-the-hard-way)

• Don't reach for a new dependency when stdlib + 20 lines solve it. Every dep adds attack surface, transitive risk, license review, supply-chain risk, and resolution time. The bar: "what we'd write would be substantially worse than the lib."
• Don't silence the linter / type-checker / test to make CI pass. Fix the underlying problem or document the deliberate exception with a comment naming the issue link.
• Don't --no-verify to skip a failing pre-commit hook. Investigate it; the hook usually catches real problems.
• Don't --amend after a failed pre-commit hook. The hook failure means the commit didn't happen — --amend would modify the PREVIOUS commit, destroying that work. Fix, re-stage, create a NEW commit.
• Don't trust subagent "I remember from earlier" claims. They have no memory across invocations. Confirm file paths, line numbers, or SHAs with Read / Grep / Bash first.
• Don't catch broad exception types (except Exception:, catch (Throwable e), catch(_)) unless you're at a request/job boundary and intend to log+continue. Narrow catches at the point of failure.
• Don't use mocking frameworks for repository-shaped interfaces. Hand-rolled fakes with real state are simpler and survive refactors better.
• Don't refactor adjacent code while implementing a feature. Separate refactor PRs from feature PRs; each gets cleaner review.
• Don't push directly to the protected branch. The PR gate exists for a reason; if you must bypass it (production emergency), document why and re-add protection after.
• Don't merge with red CI. Even "I know it's a flake." If it's a flake, fix the flake; if it's real, the gate did its job. Override is a smell.
• Don't ship test config changes alongside feature changes. When a missed regression ships, you want to bisect cleanly.
• Don't write tests that test the framework, not your code. Assert your domain logic, not that the runtime parses JSON.
• Don't use real wall-clock time in tests. Inject a clock. Tests that pass at 9 AM and fail at midnight haunt CI.
• Don't use unseeded random data in tests. Fixed seed; reproducibility is non-negotiable. A failing random input becomes a captured-seed deterministic regression.
• Don't depend on test execution order. Parallel-safe + order-independent. A test that breaks in isolation is broken.
• Don't commit large binary blobs without Git LFS. The repo grows monotonically; cloning slows for everyone forever.
• Don't change formatter rules incidentally. A 90%-reformat / 10%-feature diff is unreviewable. Run the formatter, commit it separately, then the feature.
• Don't add TODOs without ticket references. // TODO(#123): handle empty input is acceptable; // TODO: fix this is debt with no owner.
• Don't wholesale disable security features ("temporarily" turn off CSRF, "just for this endpoint" skip auth). Temporary becomes permanent. Add the exception with explicit justification or design around the constraint.

15. Memory & Continuity (when working as an AI agent)

• Save user feedback as it arrives — especially "no, not that" corrections, plus confirmations of non-obvious decisions. They don't repeat unless you ask.
• Save project context, not code patterns. Code can be re-read; "the maintainer is the only QA tester" can't be derived from git log.
• Convert relative dates to absolute when saving ("Thursday" → "2026-03-05"). Memory outlives the conversation.
• Don't trust your own memory as ground truth — grep / Read to verify before recommending from it.
• Subagents have no memory — pass decisions forward explicitly; don't say "as we decided earlier."

16. PR Description Template

Per §2, no mention of AI tools / LLMs / assistants anywhere in the PR (description, test plan, comments). Fill-in template: ~/.claude/docs/pr-template.md.

17. Scaling beyond solo

When a second engineer (human or AI) joins, four things need to scale: state across sessions (docs/decisions/ ADRs, WIP.md handoffs, and separate per-user vs per-project memory tiers), permissions (committed settings.json for what everyone needs vs gitignored settings.local.json for personal pre-approvals; never commit permission-bypass aliases), parallelism (read-only subagents run concurrently; mutating ones coordinate via PR — one per branch), and the shared subagent library (committed in .claude/agents/; layer personal agents in ~/.claude/agents/). Full detail: ~/.claude/docs/scaling.md.

18. Extension Points

Four no-code extensions cover almost everything before you'd fork the binary: subagents (.claude/agents/*.md), skills (.claude/skills/<name>/SKILL.md), hooks (.claude/hooks/*.sh), and MCP servers (configured in settings). If a use case fits none of them, the architecture has a gap worth reporting upstream rather than working around. Format table + examples: STRUCTURE.md.

19. Project Context

Dual role of this section. This file auto-loads as the project instructions when you work in this repo, so §19 below describes this repo. When you install the spine as the user-global ~/.claude/CLAUDE.md, blank §19 — per §17.1 user-global memory carries no single-project context; each of your own repos gets its own root CLAUDE.md from templates/.

19.1 What is this project?

• One-paragraph description: This repository is a distributed Claude Code configuration, not an application: a stack-agnostic engineering spine (this CLAUDE.md, §1–18), platform rule packs (rules/), a 42-agent roster across four stacks (agents/, agents-android/, agents-ios/, agents-compute/), a read-only explorer search utility (agents/, not part of the 42), three hooks — a commit guard, a format-on-save hook, and a session-start project-bootstrap hook (hooks/) — and a repo-scaffolder skill (skills/new-repo/). Users copy it into ~/.claude/ and per-repo. The product is the configuration's correctness and internal consistency; nothing is compiled or deployed. Public, MIT: github.com/roadhero/claude-code-setup.

19.2 Stack

• Language(s): Markdown (spine/rules/agents/docs) + Bash targeting macOS system bash 3.2 (hooks/*.sh) + JSON (settings.json, settings2.json). No compiled code.
• Runtime / platform: Claude Code CLI on macOS/Linux; hooks run via the user shell and jq is a hard runtime dependency of all three hooks (the commit-guard and bootstrap hooks also need git).
• Framework(s): None (only Claude Code extension points — §18).
• Storage: None.
• Build / package: None — files are copied verbatim into ~/.claude/; package.json is intentionally absent.
• Test runner: Plain bash. tests/hooks/*.sh feed each hook a PreToolUse / PostToolUse JSON payload on stdin and assert the exit code (bash 3.2 + jq + git, no framework).
• CI: .github/workflows/gate.yml runs §19.3 on every PR and on push to main. The same commands run locally before tagging.
• Distribution channel: Public GitHub roadhero/claude-code-setup, MIT, released as annotated vX.Y.Z tags + a matching GitHub Release. No package registry.

19.3 Local quality gate

Concrete commands a fresh clone can run; .github/workflows/gate.yml runs the same list.

shellcheck hooks/*.sh tests/hooks/*.sh      # bash hooks + tests lint clean (bash 3.2 target)
jq empty settings.json settings2.json       # settings parse as valid JSON
grep -L '^name:' agents*/*.md               # every agent declares a name; prints nothing when clean
diff -q templates/CLAUDE.project.md skills/new-repo/templates/web/CLAUDE.md.tmpl       # scaffolder copies
diff -q templates/CLAUDE.project.md skills/new-repo/templates/android/CLAUDE.md.tmpl   # stay byte-identical
bash tests/hooks/test-guard-commit.sh       # commit guard: stdin payload → exit code, one case per rule/regression
bash tests/hooks/test-format.sh             # format hook: exit 0, touches only the tool's own target
bash tests/hooks/test-bootstrap-claude-md.sh # bootstrap hook: SessionStart payload → nudge only when a git repo lacks a root CLAUDE.md
# Optional, advisory (not installed by default; repo ships no markdownlint config):
# npx --yes markdownlint-cli2 "**/*.md" "!skills/**/templates/**"

Requires shellcheck, jq, and git (the hooks need jq at runtime too) — brew install shellcheck jq. No build step; files ship verbatim. Markdown prose is reviewed by eye, not hard-gated. A hook bug fix starts with a failing case in tests/hooks/ (§3.4).

19.4 Current release pointers

• Live version: v1.2.0 (annotated tag, latest on main).
• In flight: none (set per session).
• CHANGELOG: none — release notes are the GitHub Release body, generated from git log between tags.
• Spec / PRD: README.md + STRUCTURE.md are canonical.
• Roadmap: none.
• WIP file: none.

19.5 Compliance scope

• None. Public, MIT-licensed configuration repo — no runtime, no users, no data collection, no network service, no regulated data. The only governance concern is the repo's own git hygiene (no secrets, no AI-tool attribution in history), enforced at commit time by hooks/guard-commit.sh plus .gitignore.

19.6 Project-specific overrides

Each override erodes the predictability §1–18 provides; treat them as debt with a documented reason. Review quarterly: can any be removed?

• §19.3 replaces the build/unit/integration gate with static analysis (shellcheck + jq + a name-invariant grep + a copies-in-sync diff) plus behavioral tests for the three hooks — reason: this repo ships configuration; the hooks are its only executable code, so they are the only thing unit-tested.
• Release notes come from the GitHub Release body instead of a CHANGELOG.md — reason: no CHANGELOG is maintained here.
• Platform rule-pack path-triggering (rules/{web,android,ios,compute}.md) never fires in this repo — it has no matching source files. Expected.

Closing thought

These rules trade speed for predictability. The payoff is that a future agent (human or AI) picking up this codebase mid-stream doesn't have to learn the bugs by hitting them. If a rule here doesn't apply to your project, delete it — but think twice before loosening one.

When in doubt, ask. When the answer is "it depends," document the decision in docs/decisions/ so the next person doesn't have to re-derive it.