roadhero/claude-code-setup

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 (~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. |
| `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. |

View full repository on GitHub →