Read on yashgadodia.com

I was setting up Claude Code on our manufacturing platform at work. Hono backend, React frontend, Drizzle ORM, Supabase, Graphile Worker for jobs. Not a trivial stack. Claude didn't know any of it. It kept suggesting Express patterns, tried to use Prisma, hallucinated a migration tool we don't use. I spent 40 minutes correcting it before any real work happened.

Next day, different repo, same problem. And I realised I'd already solved this for my personal site. The CLAUDE.md, the memory files, the skills system. It works brilliantly on one repo. But the setup is manual and non-transferable. Every new project means starting from scratch.

So I built claude-init. It's a Claude Code skill that analyses your codebase and generates a complete .claude/ configuration. Supports 13+ languages and 20+ frameworks out of the box.

What happens when you run it

You type /claude-init. Four agents spin up in parallel (one for stack detection, one for architecture patterns, one for testing and CI, one for conventions). They finish in about 30 seconds. Then it generates everything.

The output is a .claude/ directory with seven agent personas, up to eight skills, path-scoped rules, deterministic safety hooks, and a CLAUDE.md under 80 lines. Everything is conditional. No Docker? No devops agent. No API routes? No API rules. You only get what's relevant.

.claude/
├── CLAUDE.md           # Tailored project guide
├── agents/             # 7 personas (architect → writer)
├── rules/              # Path-scoped conventions
├── skills/             # Structured workflows
└── settings.json       # Safety hooks

(The full tree has about 25 files. I'll spare you.)

After running claude-init on that same manufacturing repo, Claude got the Drizzle migrations right first try. Knew to use Hono's router, not Express. Knew about Graphile Worker. The 40-minute correction loop just disappeared.

Model tiering

Not every task needs the most expensive model. This sounds obvious, but most people run everything on the same one.

The architect runs on Opus. Structural decisions: API contracts, data models, system boundaries. A bad architecture decision costs you weeks, so you want the strongest model here. The developer and reviewer run on Sonnet (great at implementation, good at pattern-following). The researcher runs on Haiku because exploration should be fast and cheap.

Seven agents. Three models. Each matched to the kind of thinking it needs to do.

I wrote about this in The Death of SaaS. Not one expensive AI doing everything. Specialised agents at appropriate price points. The interesting side effect is that an architect agent that can't write code is forced to think structurally rather than jumping to implementation. The constraint makes the output better.

RALPH

The developer agent has a self-correction cycle it runs before reporting back. It's based on RALPH, the autonomous agent loop pattern:

• Read: re-read every file you changed
• Act: verify the change does what was asked (not more, not less)
• Log: note what you changed and why
• Pause: is there anything you assumed but didn't verify?
• Hallucination-check: did you reference any API or function you haven't confirmed exists?

That last one is the important one. The most common failure mode in AI coding isn't bad logic. It's hallucinated APIs. Claude will confidently call prisma.user.softDelete() when no such method exists. RALPH forces it to stop and check. Doesn't eliminate the problem entirely (nothing does), but it catches the obvious ones before they reach you.

Five steps might be too many. Some of them probably overlap. But in practice, the developer agent with RALPH catches phantom function calls that would otherwise reach you. On the manufacturing repo, it flagged a drizzle.migrate() call that doesn't exist before I ever saw it.

The devil's advocate

This is my favourite part of the project. /devils-advocate runs on Opus in a forked context and does nothing but find problems with your design. Four phases: extract every claim (explicit assumptions, implicit assumptions, unstated dependencies), attack each claim by searching the codebase for contradictions, stress-test under failure conditions, deliver a verdict.

The instruction that makes it work: "Spend 60%+ of your effort looking for reasons this FAILS."

Most AI tools are optimised to agree with you. This one is specifically designed to disagree. The stress test questions are good: "What happens under 10x the expected load?", "What if this external service is down for 30 minutes?", "What happens if this operation runs twice?", "What happens 6 months from now when the team has forgotten the context?"

That last question. I keep coming back to that one.

Test bootstrapping

If claude-init detects no test suite, it doesn't just warn you. It picks the right framework for your stack (Vitest for Vite projects, pytest for Python, RSpec for Rails), installs it, writes baseline tests covering your existing code.

This is the thing I keep coming back to. Without tests, AI-assisted coding is a leap of faith every time. Claude can write code all day, but if there's no way to verify it works, you're just accumulating risk. Not shipping. Accumulating. Tests are the trust layer. Without them, the entire "AI-native" setup collapses.

The bootstrapping still gets confused by monorepos with mixed languages, and I'm not sure yet whether the fix is better detection or just letting the user override.

Design decisions

Rules must earn their place. Every rule passes one test: "Would removing this cause Claude to make a mistake on THIS project?" "Validate user input" doesn't make the cut (Claude already knows that). But "this project's API always returns { data, error, meta } and errors use the AppError class from src/lib/errors.ts" does. Rules are also path-scoped, so API rules only load when you're in src/api/**. Generic advice is noise. Project-specific context is signal.

Safety hooks are deterministic. Not LLM-based. Just grep:

grep -qEi 'git\s+push\s+(-f|--force)|npm\s+publish|docker\s+push|terraform\s+destroy'

I tried LLM-based hook evaluation early on. Slow and unreliable. Shell commands are boring and correct. There's a second hook that blocks writes to credential files (.env*, .pem, .key, anything in ~/.ssh/). Belt and braces.

Progressive disclosure. Skill descriptions are about 100 tokens. Full instructions only load when you invoke the skill. Same for rules (path-scoped) and agents (separate files). Eight skills and seven agents sounds heavy, but the context cost at any given moment is minimal. The whole design is about keeping the window clean so Claude can focus on the actual task.

The lifecycle

claude-init isn't a one-shot tool:

• /claude-init: initial setup, analyses everything, generates config
• /onboard: new dev joins? Mental model in under 100 lines, with ASCII architecture diagrams
• /update: codebase evolved? Re-analyse and refresh without overwriting your customisations
• /doctor: validate everything works (commands run, paths exist, hooks fire)

Getting started

# Global install
curl -fsSL https://raw.githubusercontent.com/yash-gadodia/claude-init/main/scripts/install.sh | bash

# Then in any repo:
cd /path/to/your-project
claude
# Type: /claude-init

After that, /claude-init is available in any repo you open with Claude Code. It also generates a GitHub Actions template for automatic PR review with Claude (if you want it).

What I'm still figuring out

Stack detection covers the common cases but it's not perfect. Unusual project structures trip it up. The test bootstrapping, as I mentioned, struggles with mixed-language monorepos. And the generated CLAUDE.md is good but not great. It captures the factual stuff (commands, paths, architecture) but misses the tribal knowledge that makes the best CLAUDE.md files actually useful. Things like "don't touch that file" or "this endpoint is load-bearing for the mobile app" or "we tried Redis here and it made things worse." That kind of context still needs a human.

The other big one is solo vs team. The default output assumes a team workflow: architect, developer, reviewer, QA, each with a role. If you're a solo dev talking directly to Claude, most of that is ceremony. I ran it on a personal project with 288 tests and a solid CLAUDE.md already in place. The best outputs were the architecture doc and a safety rules file. The five agents and four skills mostly gathered dust. The tool needs a lighter mode for single-contributor repos. Detect it from git log, skip the pipeline agents, keep the stuff that actually helps.

What I'm more curious about is whether the config can evolve automatically as the codebase changes, not just when you run /update. Right now it's a snapshot. The codebase is alive. There's a gap there, and I don't have a clean answer yet.

The goal is simple: you should never have to explain your codebase to an AI twice.

github.com/yash-gadodia/claude-init — open source, MIT licensed.

This post was generated by Claude Code (Opus 4.6). The prompts, structure, and editorial direction are mine. The drafting and formatting are the model's. I reviewed and approved everything.