我被AI坑了两个月才明白：先定规范再动手，效率翻倍 (English)

Generated: 2026-06-21 07:41:01

---

I Spent Two Months Getting Fooled by AI Before I Finally Got It: This Thing Isn't Meant to "Do the Work"!

It all started with a train wreck three months ago.

You know that feeling? You pick up a project, thinking it's just a small bug, and then as you start fixing it, the entire codebase collapses like a row of dominoes.

I was maintaining a Node project. The upstream parent kept updating every few days. And my fork? It was like a dumped ex—falling further and further behind.

I thought: AI is pretty awesome now, right? Let Claude Code handle it!

Guess what happened?

Every time I started a new session, it acted like an amnesiac, re-reading my entire project from scratch.

I asked it to modify the routing layer, and it went ahead and changed the type definitions too. But the modified type definitions didn't match the database models! Fixing one bug introduced two new ones; adding a feature created three breaking changes.

You think I was using AI? No, I was cleaning up after it!

After two weeks of torture, I couldn't take it anymore—if AI can read the whole repository, why does it still perform so poorly?

---

At this point, you might think I was about to give up on AI.

Just the opposite.

I stumbled upon a project on GitHub called Superpowers. The very first line of its Readme hit me right where it hurt—

"Don't start writing code right away. First, clarify the requirements."

Then I found OpenSpec, whose philosophy was even more direct: define the spec before you start coding.

I thought to myself: Isn't this just the old-school software engineering way?

Turns out we've all been spoiled by AI. We jump straight into making it work, forgetting that we humans also need to align on requirements first.

---

Phase One: Claude Code Finally Acts Like a Real Programmer

When Claude Code first came out, I was pumped. It wasn't just a chat window—it could read the codebase, modify files across the project, run tests, and output commit-ready results.

Way better than Copilot, which only does code completion.

I jumped in and modified a middleware. It effortlessly changed three files and even ran the linter automatically.

I was flying high.

But problems surfaced fast.

Every new session, it would forget everything and re-read my project. When I told it to change the routing layer, it casually modified the type definitions too—but the updated types didn't align with the database models.

I spent most of the day cleaning up the mess it made.

In short, Claude Code is fine when working on its own, but it can't handle "task boundaries" or "behavioral frameworks."

Tell it to "add a CSV export feature," and it might add a new route in the controllers while also changing the existing error-handling logic, then run the tests and report everything green.

You think it's reliable?

It's just that the test coverage didn't catch the landmines it stepped on.

By this point, I realized: no matter how smart the model, it needs constraints. You can't let it run wild.

---

Phase Two: OpenSpec—First Bury the Dead, Then Hand Out Candy

When I first tried OpenSpec, I thought it was too fussy—writing a feature requires a proposal, specs, design, and tasks. Isn't this just going back to the old document-driven approach?

But after using it, I had to admit: in AI collaboration, this step is indispensable.

Here's what it does: type in /opsx:propose "Add CSV export for Dashboard", and the AI generates a proposal.md (why), a specs/ directory (acceptance criteria), and a tasks.md (task list).

After I review and approve, we move into development.

That "approval" step locks down the requirements, so no matter how creative the AI gets later, it can't stray too far.

I fell into a trap once: early on, I used OpenSpec's apply command directly during development to auto-implement the spec, but the code it wrote didn't match the spec.

From then on, I only took the spec and tasks, and handed the implementation over to Superpowers. I disabled OpenSpec's apply feature in the configuration—openspec config profile and uncheck "Apply tasks."

So now it only outputs specifications without getting involved in implementation.

Honestly, OpenSpec solves just one problem: turning AI from "generate and pray" into "deliver against a checklist."

---

Phase Three: Superpowers—Manage AI Like an Intern

Superpowers won me over completely.

Its core is three steps: brainstorming → writing-plans → subagent-driven-development.

In plain English: first ask to clarify requirements, break them into 2-to-5-minute executable tasks, then run them in parallel.

I once used it for a database migration + user model update. I kicked it off in Superpowers mode.

First, it fired off a bunch of questions: "What's the encoding format? How to handle large files? Do we need transaction rollback?"

It asked more details than my PM.

After I confirmed each one, it automatically created a git worktree on an isolated branch, read OpenSpec's tasks.md, split the work into four subtasks, and launched two subagents in parallel—one for the password utility, one for the JWT tool.

Dependent tasks (migration → model) ran sequentially; independent tasks ran in parallel.

What gave me real peace of mind was its built-in TDD discipline. Before writing any code, tests must be written first, and they must fail before implementation is allowed.

I checked the branch coverage it generated—it required ≥80%, and it actually brought it up to 85% on its own.

Then I ran superpowers check, which validated TypeScript strict mode, banned any types, and checked error handling coverage.

Right then I thought: This is what engineering looks like.

It's not about replacing humans with AI, but encoding human engineering standards into rules that AI must follow.

Superpowers' true value is discipline. AI is too chaotic—it needs someone to hit the brakes.

---

Phase Four: The Trinity—This Is the AI Collaboration I Want

When you string these three tools together, the effect is 1+1+1 > 3.

My complete workflow now is:

1. Requirements Exploration

Use /opsx:explore to discuss requirements in detail. For example, with that statusline component, I first clarified what to display, what format, what the multi-color indicators meant. The AI outputs a proposal and specs—I review them to confirm no ambiguity remains.

2. Kick Off Development

I type: "Let's start developing the feature planned in OpenSpec. Please use the Superpowers skill to clarify requirements and develop." Superpowers automatically reads tasks.md, asks clarifying questions, waits for my confirmation, creates a git worktree, breaks down tasks, and enters development.

3. Development with Constraints

During development, Agent Skills act like supervisors: no single file exceeds 500 lines, no function exceeds 50 lines—if they do, it automatically refactors; branch coverage ≥80% or it rejects commits; automatically scans for dependency vulnerabilities and secret leaks.

I don't even need to watch it code. I can go grab a coffee and by the time I'm back, it might have already finished two subagents.

4. Verification and Archiving

Run /opsx:verify, and AI goes through the spec line by line to confirm the feature. Then run /opsx:archive, which automatically moves all the documentation and code for that feature into openspec/changes/archive/, creating a versioned record.

Later, if I need to know why a certain decision was made, I just flip through the archive instead of searching chat logs.

---

Performance Optimization and Money-Saving Tips

This combo burns through tokens fast. After some trial and error, I found a few ways to save:

• Use Fast-Forward mode for small features. If a repetitive task takes less than 30 minutes, let Superpowers skip brainstorming and detailed planning, and go straight to implementation. Saves about half the tokens.

• Use parallel tasks judiciously. Independent tasks in parallel are faster, but token consumption doubles. I once ran three subagents in parallel and burned 3.2M tokens in a single session. If the task isn't urgent, sequential execution is cheaper.

• Cache specs. Every new session re-reading the spec wastes a lot. In .claude/settings.json, configure automatic loading of OpenSpec's archive directory so Claude Code loads the local spec on startup, preserving context across sessions.

• Keep task granularity small. Keep each tasks.md to 5–10 tasks max. The finer the granularity, the less the AI drifts, less rework, and naturally fewer tokens consumed.

---

Who Shouldn't Use This? Let Me Be Honest

If you're just writing a one-off script, a