SuperClaude Framework - Developer Guide
The SuperClaude Framework is a Claude Code-specific workflow framework that turns plain Claude Code into a more opinionated development environment with slash commands, specialized agents, behavioral modes, PM-style coordination, and optional MCP integrations. This guide explains what SuperClaude is, where it is genuinely useful, where it adds too much overhead, and how to use it well in real projects.
1. What is SuperClaude?​
SuperClaude is not a new model and not a replacement for Claude Code. The right mental model is:
| Layer | Role |
|---|---|
| Claude Code | The base coding agent that reads files, edits code, runs commands, and works in your repo |
| SuperClaude Framework | A structured command-and-behavior layer on top of Claude Code |
| Optional MCP servers | Extra capabilities for research, docs lookup, browser work, memory, and reasoning |
The project describes itself as a meta-programming configuration framework that transforms Claude Code into a structured development platform through behavioral instruction injection and component orchestration.
The practical meaning​
Without SuperClaude, you mostly drive Claude Code by writing prompts directly.
With SuperClaude, you get:
- a larger shared command vocabulary such as
/sc:brainstorm,/sc:implement,/sc:test, and/sc:research - a background PM-style orchestration layer
- named specialist agents
- behavioral modes for different task types
- clearer separation between planning work and implementation work
That is the real product: more structure, more repeatability, and more workflow framing around Claude Code.
2. Why developers use it​
SuperClaude is attractive when normal free-form prompting starts to feel too inconsistent.
The main advantages​
| Advantage | Why it matters |
|---|---|
| 30 slash commands | Common development tasks become named workflows instead of ad-hoc prompts |
| 20 specialized agents | Different roles such as PM, security, frontend, backend, and research can be activated more explicitly |
| 7 behavioral modes | The framework can adapt its behavior to brainstorming, research, orchestration, token efficiency, and more |
| PM Agent patterns | Confidence checking, self-checking, and reflexion add more guardrails than a raw coding loop |
| Document-vs-execution split | Some commands are planning/reporting only, others actually make changes |
| Optional MCP acceleration | Research, docs lookup, browser automation, and reasoning can become faster and more grounded |
What makes it different from plain Claude Code​
Claude Code alone is excellent at:
- repo navigation
- implementation
- debugging
- command execution
- flexible open-ended prompting
SuperClaude adds:
- a standardized command language
- built-in workflow expectations
- stronger planning/execution boundaries
- more opinionated delegation patterns
- repeatable operating conventions across sessions
3. The most important thing to understand​
SuperClaude is not magic intelligence dust. It is a behavioral wrapper and workflow system around Claude Code.
That means the framework helps most when your problem is:
- too fuzzy for direct implementation
- large enough to benefit from decomposition
- cross-functional across architecture, security, backend, frontend, and testing
- repetitive enough that named workflows save effort
It helps less when your task is already obvious and tiny.
If you mostly need better workflow discipline, SuperClaude can help. If you mostly need one quick code edit, raw Claude Code is often faster.
4. The current state of the framework​
This matters because the repo explicitly distinguishes between today's stable version and future plans.
| State | Reality |
|---|---|
| Current stable line | v4.x, currently documented as v4.3.0 |
| Current delivery model | Python package plus installed Claude Code slash commands, agents, skills, and MCP setup helpers |
| Future direction | TypeScript plugin system planned for v5.0 |
| Important caveat | The plugin/marketplace flow described in some older references is not the current install path |
This is one of the most important adoption details: install and evaluate SuperClaude as a v4 slash-command framework, not as a finished v5 plugin marketplace product.
5. How SuperClaude is structured​
The repo documents four big pieces you will feel in daily use.
5.1 Slash commands​
This is the main user-facing layer. SuperClaude installs 30 commands into Claude Code, typically under ~/.claude/commands/sc/.
Representative commands:
/sc:brainstorm/sc:research/sc:design/sc:workflow/sc:implement/sc:task/sc:test/sc:analyze/sc:improve/sc:document
5.2 Agents​
The framework also installs 20 specialized agents under ~/.claude/agents/.
The role of these agents is not to replace commands, but to provide more stable domain behavior such as:
- project management
- architecture
- security
- frontend
- backend
- deep research
5.3 Behavioral modes​
The docs list 7 adaptive modes:
- Brainstorming
- Business Panel
- Deep Research
- Orchestration
- Token-Efficiency
- Task Management
- Introspection
These are useful because they change how the framework reasons about the work, not just what command name you typed.
5.4 PM Agent patterns​
This is the most distinctive architectural piece in the repo.
The framework centers several PM-style patterns:
| Pattern | Purpose |
|---|---|
| ConfidenceChecker | Evaluate confidence before implementation and avoid wrong-direction work |
| SelfCheckProtocol | Validate implementation after the fact with evidence |
| ReflexionPattern | Learn from failures and recurring mistakes |
The repo frames these as a way to reduce hallucinated completion and to improve token efficiency over time.
6. The command model you actually need​
If you only remember one thing, remember this distinction:
| Category | Meaning |
|---|---|
| Document-only commands | Produce plans, reports, specs, or analysis, then stop |
| Execution commands | Actually write code, run tests, build, or perform changes |
Document-only commands​
These include workflows such as:
/sc:brainstorm/sc:workflow/sc:spawn/sc:research/sc:estimate/sc:design/sc:analyze/sc:spec-panel/sc:business-panel
These are not supposed to silently drift into implementation. That boundary is one of SuperClaude's better ideas.
Execution commands​
These include:
/sc:implement/sc:improve/sc:cleanup/sc:task/sc:test/sc:build/sc:git
This split matters because it helps you avoid a common agent mistake: asking for a plan and getting half a feature implemented before the plan is even good.
7. The most important command relationships​
SuperClaude's own docs spend a lot of time clarifying where similar commands differ. That is a good sign, because this is where users otherwise waste a lot of tokens.
7.1 /sc:spawn vs /sc:task vs /sc:implement​
| Command | Best mental model |
|---|---|
/sc:spawn | Break the big thing down |
/sc:task | Coordinate execution across multiple domains |
/sc:implement | Directly write code for a specific thing |
Good rule:
- use
/sc:spawnwhen the task is still too big or tangled - use
/sc:taskwhen work spans several domains such as backend, frontend, security, and QA - use
/sc:implementwhen you already know exactly what should be built
7.2 /sc:task vs /sc:implement​
SuperClaude's own docs basically warn you not to over-coordinate simple tasks.
Use /sc:task when:
- the feature spans multiple domains
- you need architecture/security/test coordination
- the codebase is unfamiliar
- the task is critical, such as auth or payments
Use /sc:implement when:
- it is one component, one endpoint, or one contained feature
- the architecture is already decided
- you want speed more than coordination
7.3 /sc:design vs /sc:workflow​
This is another useful distinction:
/sc:designanswers: what should the system look like?/sc:workflowanswers: in what order should we build it?
That difference is subtle but important. Design is blueprint. Workflow is execution plan.
8. How to install it today​
The stable v4 path is straightforward.
pipx install superclaude
superclaude install
superclaude install --list
superclaude doctor
Optional MCP installation:
superclaude mcp --list
superclaude mcp
superclaude mcp --servers tavily --servers context7
The repo also documents direct installation from Git via ./install.sh, but the pipx path is the recommended starting point.
Do not evaluate SuperClaude based on the planned v5 plugin story. The current real product is the v4 slash-command and Python-package setup.
9. How to use SuperClaude well​
9.1 Learn the command families before trying to memorize everything​
You do not need all 30 commands in your head on day one. Learn the big families:
- discovery
- planning
- implementation
- quality
- improvement
- documentation
That gets you productive much faster than rote memorization.
9.2 Respect the planning/execution boundary​
One of SuperClaude's strengths is that it explicitly separates commands that plan from commands that execute.
If you ignore that and keep using document-only commands as if they were implementation commands, the framework will feel noisy and redundant.
9.3 Start with a small command set​
A very practical starter set is:
/sc:brainstorm/sc:design/sc:workflow/sc:implement/sc:test/sc:analyze
That already covers a large amount of real work without forcing the whole framework surface into your habits at once.
9.4 Add MCPs for real benefit, not for checkbox completeness​
The repo claims meaningful gains from MCP-backed workflows, especially for:
- Tavily for research
- Context7 for official documentation
- Sequential for reasoning efficiency
- Serena for persistence and project memory
- Playwright for browser-driven testing
This is one of the areas where SuperClaude can move from "prompt organization" to actual capability improvement.
9.5 Use /sc:task selectively​
This is probably the single most important habit for keeping SuperClaude from feeling bloated.
Do not use multi-agent coordination for:
- tiny UI changes
- simple CRUD endpoints
- a one-file bug fix
- a straightforward refactor
Use it where coordination changes the quality of the outcome.
9.6 Let raw Claude Code stay part of your workflow​
SuperClaude is best treated as an augmentation layer, not a religion.
You can still use plain Claude Code prompts whenever:
- you need a quick answer
- the task is too small to deserve a command
- you want free-form investigation
- the framework's structure would cost more than it saves
10. Recommended workflows​
10.1 New feature from vague idea​
This is a strong SuperClaude path:
/sc:brainstormto clarify the idea/sc:researchif outside information matters/sc:designfor architecture or API shape/sc:workflowto generate the implementation order/sc:implementfor concrete build steps/sc:testand/sc:analyzefor validation
This is a good fit because the framework adds clarity before code generation starts.
10.2 Bug fix​
Recommended flow:
/sc:troubleshootto identify root cause/sc:implementfor the actual fix/sc:testto verify
That is lean enough to stay practical.
10.3 Large cross-domain feature​
This is where /sc:task and /sc:spawn start making more sense:
/sc:brainstorm/sc:design/sc:workflow/sc:spawnfor decomposition/sc:taskfor coordinated execution/sc:test/sc:analyze --focus securityor another targeted audit
10.4 Existing codebase onboarding​
SuperClaude's docs also emphasize session context and repo understanding. In established codebases, it is especially useful to combine:
- Serena-based memory and symbol understanding
/sc:index-repo/sc:analyze/sc:explain
That helps Claude Code become repo-aware faster and more consistently.
11. Where SuperClaude is a good fit​
SuperClaude is a good fit when:
- you already use Claude Code heavily
- you want more structure than plain prompting gives you
- your work often spans planning, implementation, testing, and review
- you value explicit command boundaries
- you want optional MCP-backed enhancement without building your own framework from scratch
It is especially attractive for developers who like the idea of a shared operating system for AI-assisted development.
12. Where it is overkill​
SuperClaude is a poor fit when:
- you do not use Claude Code as your main environment
- you want a provider-agnostic framework like BMAD or a multi-agent orchestrator like Ruflo
- your tasks are mostly tiny edits and fast loops
- you dislike command-heavy workflows
- you are still learning basic Claude Code usage
It can also become counterproductive if you treat every task like an enterprise process.
Examples of overkill:
- using
/sc:taskfor a button label change - generating design and workflow artifacts for a one-line fix
- turning a simple implementation into a multi-role coordination ceremony
SuperClaude can create the feeling of rigor without always creating better outcomes. The framework helps most when its structure improves decision quality, not when it merely adds process.
13. How it compares to BMAD​
Because you asked for this in the same style as the BMAD guide, the cleanest distinction is:
| Framework | Best at |
|---|---|
| BMAD | Structured product/development planning across phases and artifacts |
| SuperClaude | Claude Code-centered command workflows and execution discipline |
BMAD is more about method and phased planning across tools. SuperClaude is more about operating Claude Code itself in a structured way.
That means they are not direct clones:
- BMAD is more tool-agnostic and planning-centric
- SuperClaude is more Claude-specific and command-centric
14. A realistic adoption strategy​
If you want the signal without drowning in surface area, use this order:
Phase 1 - Learn the basics​
- install SuperClaude
- learn the command families
- use only 5-6 core commands
- keep MCP optional at first
Phase 2 - Add real capability​
- install Tavily and Context7
- try Serena if you want more persistent project understanding
- use
/sc:research,/sc:design, and/sc:analyzeon real work
Phase 3 - Add coordination only where it pays​
- start using
/sc:spawnand/sc:taskfor larger features - lean on planning/execution boundaries
- decide where plain Claude Code is still faster
That gives you an actual workflow advantage instead of just a larger command list.
15. Bottom line​
SuperClaude is a strong fit for developers who already like Claude Code but want a more explicit, repeatable, and command-driven way of working. Its biggest strengths are the structured command model, the planning-vs-execution separation, and the option to enrich Claude Code with MCP-backed research, documentation lookup, and coordination.
It is not the right tool for everyone. If you want pure speed or model-agnostic freedom, it may feel heavy. But if you want to turn Claude Code into something closer to a structured development platform, SuperClaude is one of the more serious attempts to do exactly that.