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 (~215-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)	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).
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, committing as a non-human, writing AI attribution into a commit message, or staging obvious secrets. 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.
.githooks/pre-commit	Git pre-commit hook for this repo that lints staged Markdown files with markdownlint-cli2.
.github/workflows/markdownlint.yml	CI job that runs markdownlint-cli2 on every PR and push to main.
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). 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.

For this repository, enable the Markdown git hook once per clone:

git config core.hooksPath .githooks

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.