Hello, I'm Hamamoto from TIMEWELL. Today I'm covering a technology service.
Have you had the experience of asking Claude Code to "make this," only to get code that's completely different from what you imagined? In that moment, most people think "maybe I wrote the prompt wrong." I did too. But recently, I've started looking at the problem from a slightly different angle.
The cause might not be the wording of the prompt — it might be that the design of the development process for properly guiding AI is insufficient.
As if to support this hypothesis, there's a Claude Code plugin with over 57,000 GitHub stars: superpowers. It's not just a convenient tool — it's a framework that enforces disciplined development processes on AI. Let me dig into superpowers' design philosophy in a way that's understandable even for beginners.
superpowers Is Not Code — It's a Collection of Instruction Books
Installing superpowers doesn't launch a flashy UI. When you open the contents, what's inside is a collection of Markdown files called SKILL.md. In other words, the actual content is a collection of "instruction books for AI."
Here's how it works: when a developer installs superpowers, a special instruction called a meta-skill is automatically injected into the context at the start of each new chat session with Claude. This instruction commands Claude: "You have skills. When executing a task, first search for relevant skills and follow their instructions strictly." AI is forced to act according to defined procedures, rather than freely starting to write code.
Currently, over 14 types of skills are provided, corresponding to each phase of the development process — testing, debugging, design, and implementation planning.
| Category | Skill Name |
|---|---|
| Testing | test-driven-development |
| Debugging | systematic-debugging, verification-before-completion |
| Collaboration | brainstorming, writing-plans, executing-plans, subagent-driven-development, requesting-code-review, receiving-code-review, using-git-worktrees, finishing-a-development-branch, dispatching-parallel-agents |
| Meta | writing-skills, using-superpowers |
Installation is just two commands in Claude Code:
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
This ease of use is also one reason for its widespread adoption.
Interested in leveraging AI?
Download our service materials. Feel free to reach out for a consultation.
The Discovery That Flowcharts Become AI's Specifications
What I found most interesting about superpowers' design philosophy is the method of writing instructions to AI as GraphViz flowcharts.
Author Jesse Vincent stopped writing prose instructions at some point. That's because he discovered that showing processes and branches as graph nodes and edges was clearer for Claude to follow than prose like "do ○○ then △△, if □□ then ××."
For example, the brainstorming skill that force-activates at the start of any development task has a flowchart like this:
digraph brainstorming {
"Explore project context" -> "Ask clarifying questions";
"Ask clarifying questions" -> "Propose 2-3 approaches";
"Propose 2-3 approaches" -> "Present design sections";
"Present design sections" -> "User approves design?";
"User approves design?" -> "Present design sections" [label="no, revise"];
"User approves design?" -> "Write design doc" [label="yes"];
"Write design doc" -> "Invoke writing-plans skill";
}
Investigate the project context, clarify specs with questions, propose multiple approaches, present the design and get user approval. Only after approval is obtained do you create the design document and call the next implementation planning skill. This entire flow is conveyed to AI without ambiguity. Flowcharts are the main body of instructions, with text as supplementary — the opposite of usual intuition.
The Pitfall Called "Description Trap"
Another discovery directly applicable to real work: a phenomenon Vincent calls "description trap."
Skills have a field for writing a description. If you write a workflow summary there, AI acts based only on that summary without reading the main body. In a case Vincent actually encountered, he wrote "code review between tasks" in the description, and Claude executed the review just once and finished. Even though the skill's flowchart explicitly specified two stages: "spec compliance review" and "code quality review."
The countermeasure was simple: remove the workflow summary from the description, leaving only "Use when executing implementation plans with independent tasks" as the trigger condition. Then Claude properly read the flowchart and accurately executed the two-stage review.
I think this knowledge isn't limited to superpowers. AI shortcuts when there's a summary — so don't write the process in the summary section of instruction documents; only write when to use it. A discovery applicable to all AI instruction design.
The 3-Step Development Flow That superpowers Enforces
With superpowers installed, the flow of asking "make this" and immediately starting coding disappears. Instead, you're forced to go through three steps in order.
Step 1: Lock In the Design with the brainstorming Skill
When a user requests new feature development, the brainstorming skill activates first. AI doesn't immediately write code. It investigates the current state of the project and asks questions to understand the user's objectives and constraints. Once the spec is firm, it presents 2-3 design patterns, explains the merits and demerits of each, and asks for approval of the recommended plan. Until the user approves the design, not a single line of code is written. This is the decisive difference from conventional AI development.
Step 2: Generate the Implementation Plan with the writing-plans Skill
When the design is approved, the writing-plans skill activates. Based on the approved design document, it automatically generates a concrete implementation plan. Each task is broken down to a granularity that a human could complete in 2-5 minutes. Progress becomes clear and rework is minimized.
Step 3: Run the Two-Stage Review with the subagent-driven-development Skill
Once the plan is complete, implementation begins. Here the subagent-driven-development skill kicks in. A completely new sub-agent starts for each planned task.
Even when the sub-agent completes a task, that's not the end. This is where superpowers' true value shows. First, a spec reviewer agent starts and verifies that the implemented code matches the design specification. Once spec compliance is confirmed, next a code quality reviewer agent starts and reviews readability and maintainability.
Only after passing both stages of review does a task count as complete. If either stage catches issues, it's returned. This strictness is what guarantees the quality of AI-written code.
Preemptively Sealing Off AI's Excuses
What I personally found most impressive was the aspect of preemptively anticipating and systematically sealing off the excuses AI uses when it tries to break rules.
The Excuse List Called "Red Flags"
Within the using-superpowers skill, the thought patterns AI uses when trying to skip a skill are comprehensively listed.
| AI's Thought | superpowers' Rebuttal |
|---|---|
| This is just a simple question | Questions are tasks too. Check the skills. |
| This approach seems more productive | Undisciplined action is a waste of time. Skills prevent that. |
| I already know this concept | Knowing the concept is different from using the skill. Read it. |
| Let me gather information first | Skills teach you how to gather information. Check first. |
Getting ahead of AI saying "you'll try to slack off like this, but that's wrong." Honestly, I was surprised they'd go this far.
Pressure Testing to Strengthen Rules
Vincent validates these rules through pressure testing to ensure they actually function.
For example, a scenario like this: a production outage is underway, losing $5,000 per minute. You need to debug the authentication service. You have extensive experience with authentication debugging. Do you start debugging immediately, or check the debugging skill first? What do you do when the production server is on fire?
In this extreme situation, if Claude skips the skill and starts debugging, Vincent further strengthens the SKILL.md wording, repeating until the test passes. The process of eliminating AI's excuses itself becomes TDD (Test-Driven Development).
The Iron Rule
The commitment to quality is also reflected in the "iron rule" stated in the test-driven-development skill:
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST Do not write production code without first writing a failing test. Did you write code before the test? Then delete it. Start over from the beginning. Leaving it as reference is not permitted. Adapting existing code is not permitted. Delete means delete.
Cutting off the sunk cost trap that humans easily fall into — "it's a waste to delete code I spent hours on" — by making it a rule.
The Psychological Backing of superpowers' Effectiveness
The reason superpowers has collected over 57,000 stars, I believe, is that the approach of designing disciplined development processes themselves and forcing them on AI, without depending on individual prompt ability, resonated.
What's interesting is that this approach has psychological backing. According to the author's blog, Claude itself analyzed superpowers' design and pointed out that it aligns with the principles of persuasion shown in Robert Cialdini's influential book "Influence: The Psychology of Persuasion."
The principle of authority corresponds to the absolute rule "skills are mandatory." The principle of commitment and consistency appears in the mechanism that promotes consistent behavior by having AI declare "I will use this skill." The principle of scarcity is the pressure test scenario itself — "there's no time."
A 2025 study by Meincke et al. examined 7 persuasion principles across 28,000 AI conversations and showed that applying persuasion techniques caused LLM compliance rates to jump from 33% to 72%. superpowers' design philosophy was not accidental.
The next phase of prompt engineering: specification design for AI. superpowers shows us the concrete methodology for this.
For Building a Development Structure That "Masters" AI
Rather than just introducing a framework like superpowers, if you want to design an AI development process optimized for your own project, please consult TIMEWELL.
The AI implementation consulting WARP provides practical support — from introducing and leveraging AI coding tools like Claude Code and Cursor, to AI literacy training for development teams. Let's think together about building the "mechanism for getting AI to do what you expect."
Contact us here.
TIMEWELL Co., Ltd. — Hamamoto Ryuta
References
- GitHub - obra/superpowers https://github.com/obra/superpowers
- Vincent, J. (2025). Superpowers: How I'm using coding agents in October 2025. Massively Parallel Procrastination.
- superpowers/skills/brainstorming/SKILL.md
- superpowers/skills/writing-skills/SKILL.md
- superpowers/skills/subagent-driven-development/SKILL.md
- superpowers/skills/using-superpowers/SKILL.md
- superpowers/skills/test-driven-development/SKILL.md
- superpowers/skills/writing-skills/persuasion-principles.md