Claude Code setup

This is the actual Claude Code configuration I run day to day at EltexSoft: a stack-agnostic engineering "spine," platform-specific rule packs that load per file via path globs, a roster of 42 subagents across four stacks, a commit-guard hook plus an auto-formatter, and a repo scaffolder. It's the same setup I describe in 42: The AI Builder's Stack. Take what's useful.

Most people publish a single CLAUDE.md and call it a setup. The thing that actually makes Claude Code reliable is structure: a global file that never changes, rules that load only when Claude reads a file matching their path globs, agents scoped to one job each, and hooks that stop bad commits before they happen. That's what's here.

What's inside

Path	What it is
CLAUDE.md	The universal spine — a lean (~220-line) always-loaded core: workflow, git rules, coding guidelines, secrets, anti-patterns. Stack-agnostic. Longer reference material lives in docs/ and loads on demand.
rules/{web,android,ios,compute}.md	Platform rule packs. Each carries a paths: frontmatter glob; Claude Code loads a pack when it reads a file matching that glob (*.kt → android, *.swift → ios, *.ts/*.py → web, *.cpp/*.cu → compute). Path-triggered, so packs whose files you never touch stay out of context.
agents/ (15 + explorer)	The default subagent roster: the four-hat chain (architect → senior-swe → code-reviewer → qa), plus specialists (security, performance, db-migration, debugger, devops, docs, design), release-engineer + tech-writer, and a delivery layer (TPM, scrum-master). Plus a read-only explorer search utility (cheap model) that the roster and main model delegate reads to — a tool, not counted in the 42-agent roster.
agents-android/ (7), agents-ios/ (7), agents-compute/ (13)	Per-stack overrides. Drop them into a repo's .claude/agents/ and they override the generic ones of the same name with platform-brained versions.
hooks/guard-commit.sh	A Claude Code Bash hook (PreToolUse) that blocks the agent from force-pushing, skipping git hooks with --no-verify, committing as a non-human, writing AI attribution into a commit message, or staging obvious secrets. Every segment of a chained command is checked on its own. Quoted text, heredoc bodies, substitutions, and arithmetic are stripped as data first, so a commit message or a file body that merely mentions a blocked flag never trips it; a shape the check cannot classify (a shell wrapper of any form, a substitution inside ${...}, an unquoted pattern in a commit or push, git config passed through the environment) is refused rather than guessed. It guards Claude's git commands — not a human typing git directly in their own terminal.
hooks/format.sh	Auto-formats edited files by extension across every stack. Missing formatter is a silent no-op, never an error.
hooks/bootstrap-claude-md.sh	A Claude Code SessionStart hook that, when you open a git repo with no root CLAUDE.md, nudges Claude to offer to create one from the standard template (created only on your yes; §19 filled from what's detectable, the rest completed over time). Silent in the global config dir, in non-git directories, and once the file exists. It only inspects and nudges — it never writes a file itself.
tests/hooks/	Behavioral tests for all three hooks: a JSON payload on stdin, an exit code out, one case per rule and per past regression. Plain bash 3.2 + jq. CI (.github/workflows/gate.yml) runs them with the rest of the quality gate on every PR.
skills/new-repo/	A scaffolder skill: spins up a new repo with the right CLAUDE.md, .gitignore, quality gate, and release workflow. Scaffolds web + Android; iOS and compute ship as rule + agent packs (no scaffolder for them yet).
docs/	On-demand reference the spine points to (full roster tables, the Phase-3 review checklist, the error-recovery table, PR template, scaling notes). Installed to ~/.claude/docs/; loaded only when a stub references it.
templates/	Blank project CLAUDE.md templates (generic + compute) to copy into a new repo and fill in.
examples/CLAUDE.example-web.md	A filled-in example so you can see what "done" looks like before you write your own.
STRUCTURE.md	The full layout, install steps, and how the two-settings-file swap works. Read this first.

The idea in one paragraph

Two tiers. The global tier (~/.claude/CLAUDE.md + rules/ + agents/ + hooks/) is everything that's true regardless of what you're building. The project tier is a short CLAUDE.md at the repo root that holds only what's specific to that project (§19: stack, quality gate, release pointers, compliance scope). The spine gets prompt-cached and never changes; the project file is the only thing you edit per repo. Rules specialize by path-trigger (a pack loads when Claude reads a file its paths: glob matches); agents specialize by name-override (a repo's .claude/agents/<name>.md shadows the global agent of the same name). Neither scans the repo up front. You configure once, then mostly leave it alone.

Install

Mac/Linux, with Claude Code already installed. Full steps and the per-repo install are in STRUCTURE.md. First install the hook prerequisite jq (guard-commit.sh fails closed without it): brew install jq (macOS) / sudo apt-get install jq (Debian/Ubuntu); the guard also needs git 2.28 or newer. Then:

git clone https://github.com/roadhero/claude-code-setup.git && cd claude-code-setup
mkdir -p ~/.claude/rules ~/.claude/agents ~/.claude/hooks ~/.claude/skills
cp CLAUDE.md      ~/.claude/CLAUDE.md
cp settings.json  ~/.claude/settings.json      # merge your own model / plugin blocks in
cp rules/*.md     ~/.claude/rules/
cp agents/*.md    ~/.claude/agents/
cp -R agents-android agents-ios agents-compute ~/.claude/   # per-stack packs (scaffolder + per-repo overrides read these)
cp hooks/*.sh     ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh
cp -R skills/new-repo ~/.claude/skills/
mkdir -p ~/.claude/docs && cp -R docs/* ~/.claude/docs/

Then per repo, copy a template in as the project CLAUDE.md and fill in §19. See examples/ for a worked one.

A few honest caveats

This is opinionated and built for how my team works. The git rules assume PR-based flow with protected branches. The hooks assume the formatters are installed (they no-op cleanly if not). The compute stack is C++/CUDA/Python systems work and is overkill if you only ship web apps. Strip what you don't need. The point isn't to adopt my exact setup. It's to see a real, working one and build yours.

More

• The chapter on Claude Code goes deep on the why behind all of this – full version on Sub-Etha Press
• The book: 42: The AI Builder's Stack launching on Amazon August 15th, 2026
• Other sample chapters are at eltexsoft.com

MIT licensed. Use it, fork it, change it. No attribution required.