roadhero/claude-code-setup
36 stars · Last commit 2026-09-14
My actual Claude Code setup: a stack-agnostic engineering spine, auto-activating rule packs, 50 scoped subagents across web/Android/iOS/compute, safety hooks, and a repo scaffolder. From the book "42: The AI Builder's Stack."
README preview
# Claude Code setup
This is the actual Claude Code configuration I run day to day at [EltexSoft](https://eltexsoft.com): 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](https://subethapress.com)**. 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. |