Most Claude Code projects run on a CLAUDE.md and not much else. Claude works fine that way. You write project context, list your commands, add some guardrails.
Claude Code’s configuration surface goes well beyond that single file. Agents with restricted tool access. Hooks tied to your framework’s linter. Community skills for security, testing, database work. Plugins. Team-shared memory. Each in its own format.
Most of it goes unused because the knowledge needed to set it up is spread across official docs, blog posts and community repos.
Why most setups stay half-configured
Claude Code ships new features fast. Official marketplace plugins. Agent teams. Worktree isolation. HTTP hooks. New skill repos from Trail of Bits, Supabase, Vercel. Each one means new configuration in a different format: plugin entries in settings.json, skill files with SKILL.md format, hook scripts wired to the right events.
The knowledge needed to configure these well comes from multiple sources. Boris Cherny’s workflow patterns explain how to structure agents and commands for different development styles. Thariq’s prompt caching research changes how you should order your CLAUDE.md (stable content at the top stays cached across turns; changing content at the bottom gets reprocessed, which adds up over long sessions). Geoffrey Huntley’s Ralph Wiggum loop (now an official Anthropic plugin) introduced autonomous sessions with safety rails. Skill repos like obra/superpowers, Trail of Bits, Supabase and Vercel each have their own structure and installation approach.
The community has built ways to navigate this. Projects like SuperClaude provide comprehensive pre-built configs. awesome-claude-code curates tools and skills. Aggregator sites collect options from multiple repos. These help with discovery.
The gap is resolution. You can browse all of these, but you still need to figure out which options matter for your stack, how they should reference each other, what order your CLAUDE.md content should be in, and which community defaults are actually worth using. That research is the bottleneck. Writing the files once you know what to put in them is mechanical.
What a fully configured project looks like
Take a FastAPI project.
With the right setup, Claude runs ruff and mypy before every commit via hook scripts triggered by Claude Code’s hook system (not git hooks). A Rails project gets RuboCop instead. A Go project gets gofmt and go vet. Safety hooks block pushes to main and .env commits. The hooks are framework-specific.
Agents are scoped to their role. An architect can read and search code but can’t edit files. A test-writer is restricted to the test directory. Without scoping, every agent has full tool access and will occasionally edit files outside whatever you actually asked for.
Community skills from repos like obra/superpowers, Trail of Bits, Supabase and Vercel add domain knowledge Claude doesn’t have by default: TDD enforcement, security review, database optimization. A FastAPI project with PostgreSQL needs a different skill set than a Next.js frontend.
Plugins like Pyright LSP and the GitHub plugin (which replaced the old GitHub MCP) are matched to your language. Slash commands like /plan, /review and /fix-issue turn common workflows into single invocations. Agent docs load framework-specific conventions automatically via @import.
Team memory is separate from Claude’s built-in auto-memory. Claude already saves personal notes between sessions (in ~/.claude/projects/). That’s per-developer and unstructured. Team memory is git-tracked files in the repo: decisions, patterns, gotchas, session log. A new developer cloning the project gets the full history of architectural decisions. Growth rules prevent these files from ballooning into the context window.
Two independent axes
The insight behind cc-rig (the tool I built to solve this) is that project configuration has two orthogonal dimensions.
Framework determines the technical content. A FastAPI project needs different hooks, different agent docs, different skills and different MCP servers than a Rails project or a Go project. The lint command is different. The test conventions are different. The deployment patterns are different. These are properties of the framework, not the team’s process.
Workflow determines the process. How many agents do you want? How strict should the review process be? Do you want autonomous loops with budget enforcement? Do you want verification gates that block commits until tests pass? These are properties of how the team likes to work, independent of what framework they use.
A Django project can run a speedrun workflow (minimal process, 5 agents, 9 commands) or a verify-heavy workflow (12 agents, 19 commands, full safety hooks). The framework-specific content stays the same. The process layer changes.
cc-rig composes these two dimensions. Pick your framework from 16 options (FastAPI, Next.js, Django, Rails, Gin, Echo, Rust CLI, Rust/Axum, Spring Boot, ASP.NET, Laravel, Express, Phoenix, Go stdlib, generic, Flask). Pick your workflow from 5 options (speedrun, standard, spec-driven, gtd-lite, verify-heavy). The smart defaults engine resolves agents, commands, hooks, plugins, skills, MCPs and permissions from those two choices.
Expert mode and runtime harness
The defaults are a starting point. Expert mode lets you pick agents, commands, plugins and hooks individually. Maybe you want the architect and test-writer agents but not the code-reviewer. Maybe you want /plan and /test but not /refactor. The generated config is whatever you choose, not a fixed template.
The harness system adds optional runtime discipline. Four boolean features you can pick individually:
- Task tracking generates a todo system with slash commands for managing work.
- Budget awareness adds a stop hook that parses JSONL session logs and shows actual session cost at exit, with model-aware pricing (Opus at ~$15/M input tokens vs. Haiku at ~$0.80/M, for example).
- Verification gates add commit-blocking hooks that require test passage before code lands.
- Autonomy loop generates a loop script with iteration limits, checkpoint auto-commits when Claude doesn’t commit, stuck detection and budget enforcement that stops the loop before cost exceeds a threshold.
These compose independently. You can have budget tracking without autonomy. Verification gates without task tracking. Or pick the Ralph Loop plugin as an alternative autonomy approach (cc-rig handles the mutual exclusion).
For existing projects and teams
Most developers aren’t starting from scratch. They have a codebase, maybe a CLAUDE.md already, and want to fill the gaps.
cc-rig init --migrate reads your project files (pyproject.toml, package.json, go.mod, Cargo.toml, mix.exs, composer.json, *.csproj) and detects your framework. It proposes a configuration and won’t touch existing files.
For teams, the generated config is a JSON file (.cc-rig.json) that can be committed. A teammate clones the repo, runs cc-rig init --config .cc-rig.json, and gets the identical setup: same agents, same hooks, same permissions. No more configuration drift across team members.
When Claude Code ships something new, cc-rig config update re-runs the wizard with your existing choices pre-filled. It shows a diff of what changed and regenerates on confirmation. Your manual edits to generated files are preserved (cc-rig tracks what it generated via a manifest and won’t overwrite files you’ve modified).
The philosophy
cc-rig is a one-shot generator. It writes native Claude Code files and exits. No runtime component, no daemon, no hooks into Claude Code’s process. The output is the same files you’d write by hand if you had the time and the research.
This is a deliberate choice. Claude Code already has a well-designed configuration system. It reads files at startup and applies them. cc-rig respects that design by producing the right files, not by inserting itself between you and Claude Code.
Lightweight dependencies (rich, textual, prompt_toolkit for the TUI). The generated output has zero runtime dependencies — just plain files that Claude Code reads natively.
The generated files are plain text. Read them, edit them, delete the ones you don’t want. cc-rig won’t complain. It’s a generator, not a guardian.
pip install cc-rig
cc-rig init