This is one long conversation — about 40+ exchanges — in which I went from a very vague idea to the initial design of an open-source toolchain called spec-sonar. Part 1 ends where I hand 13 review questions to Fable 5.
Part 2 covers the next 24 hours: the review results, 25 files shipped, and a plot twist I never saw coming — the tool catching conflicts between my own two open-source repos.
Read on: Part 2 — Fable's review and a real-world conflict · 繁體中文版 · this tool is listed in my open-source toolkit index.
1. The starting point: an intuition
The first thing I typed into Claude was this:
"I'm wondering whether I can use the standard body of software-engineering knowledge, Claude Code's round-based questioning, and a well-designed skill to help people new to AI-assisted development turn ideas into reality — confirm the safety boundaries, set design limits to prevent scope creep, settle the architecture, and finally produce a series of execution playbooks or goals…"
Several key intuitions were already in that sentence:
- The concept of dark zones and bright zones — use set difference to find the questions worth asking.
- Convergence, not generation — the goal is fewer rework cycles, not faster output.
- Complexity loaded on demand — I decide how deep to go, instead of getting everything at full depth.
2. First turning point: interrogate before designing
I forced myself to answer one question first: is this reinventing the wheel?
What the search turned up:
- Requirements-management tools for PMs/BAs exist, but they assume you already understand User Stories.
- Spec-driven tools for developers exist, but they assume a spec draft already exists.
- Claude Code's CLAUDE.md ecosystem exists, but nobody generates specs for non-technical users.
Conclusion: not a reinvented wheel — but the differentiation has to be explicit. The real difference:
Existing tools' route: make the AI smarter so it tolerates vague input
spec-sonar's route: make the user's input itself precise
The latter is sturdier, because it doesn't depend on a model's tolerance for ambiguity — and that tolerance is exactly where hallucination comes from.
3. Second turning point: reframing the value proposition
I first wrote the value proposition as "reduce design rework." That was wrong.
The problem: a non-technical user can't perceive that value — they don't know how many detours they would otherwise have taken, so they can't feel the detours they avoided.
The corrected value proposition: "reduce the anxiety of landing something vague."
That's trust, not efficiency. What the user actually feels is: "I told it what I wanted, it told me the problems I hadn't thought of, and what got built matches what I had in mind."
This reframe shaped every later decision:
- The tone of the Q&A — assistance, not interrogation.
- How infeasibility is handled — not rejection, but shrinking to a feasible version.
- Showing bright/dark-zone progress every round — the core trust-building mechanism.
4. Core system-design decisions
4.1 A behavioral contract, not roleplay
My first idea was to inject a "you are a senior architect" persona prompt.
The problem: an identity is not a set of behavior rules. Claude plays the architect but doesn't know what this architect must do, must not do, or when to stop.
So I switched to injecting a behavioral contract:
Inject a behavioral contract, not an identity:
"Your job is to converge a software product idea into an executable spec.
You are not a roleplaying architect.
You are a system with fixed rules of behavior."
This made the system's behavior predictable, testable, and iterable.
4.2 STATE: externalizing conversational memory
The problem: there is no persistent memory between rounds; by round 4 the model has forgotten what round 1 established.
My fix was to externalize the conversation memory into a portable JSON block:
<STATE>
{
"round": 2,
"bright": ["established items"],
"dark": ["unconfirmed items"],
"next_focus": "next round's topic"
}
</STATE>
Key principles:
- Wrap it in an XML tag — more stable than plain text; Claude parses its own XML output more reliably.
- The
next_focusfield forces each round onto a single topic, preventing scattershot questioning. -
STATE_FINAL.jsonis portable — you can leave mid-process and resume later with full state.
4.3 The baseline problem of the set-difference method
Doing gap analysis, I found a hole:
Set difference only works if I already hold a standard template of "what a complete system looks like" to diff against. No baseline, no difference.
The solution is a dark-zone-baseline.md: 10 standard dimensions that seed every new session's dark list — target users, core feature boundary, data model, auth & permissions, third-party integrations, deployment platform, performance & scale, maintenance & updates, budget & timeline, success criteria.
The most important detail: the Session-vs-Persistent fork.
I only discovered this after running the real test case (a math tower-defense game). The "do we need an account system?" decision had been back-derived from "does the data persist?", rather than asked proactively. The fork has enormous architectural impact, so I promoted it to a mandatory proactive question.
5. The real test: a math tower-defense game
Why this case: a non-technical user (with an engineer partner) wanted to land "Plants-vs-Zombies tower defense × middle-school math × in-class team battle." I used it to stress-test my tool.
What ran: the full 5-round convergence, from "I don't know what to build" all the way to a complete README.md + CLAUDE.md + STATE_FINAL.json.
Key observations:
The resource mechanic was the highest-value discussion. That user raised the real classroom pain point — "a team-captain system creates conflict between teammates." The final design: personal earn, personal spend, plus per-unit cooldowns — individual effort converts directly into individual agency, with no middleman to skim.
Wheel-reinvention detection confirmed the differentiation. Single-player math tower-defense games exist; "whole class online + team battle + teacher console + realtime multiplayer" does not.
The dark zones cleared after 6 rounds — but one was never proactively probed. The Session-vs-Persistent fork emerged by inference from the "no accounts" answer, not from the baseline. That bug directly drove the baseline fix.
The test case's role: the math game is not spec-sonar's target scenario. It's a deliberately hard stress test — WebSocket realtime sync, a game engine, multiple dependency types, ephemeral-session design. Only that level of complexity genuinely probes the system.
6. Third turning point: from a tool to a toolchain
The original design was a single requirements-convergence skill (idea-to-spec). It kept growing:
idea-to-spec (requirements convergence)
↓ problem found: CLAUDE.md outputs modules, but no dependencies
goal-decomposer (goal decomposition)
↓ problem found: only works from zero; can't diagnose existing projects
Audit Mode (existing-project diagnosis)
↓ problem found: large complex systems (ERP) have different needs
Complex System Mode
↓ problem found: Claude-Code-only is too narrow
Adapters layer (platform-agnostic universal format)
The most consequential evolution: from Claude-specific to platform-agnostic.
Core spec layer (universal): goal-graph.json + goals/*.md
Adapter layer (per platform):
adapters/CLAUDE.md ← Claude Code
adapters/.cursor/rules ← Cursor
adapters/copilot-instructions.md ← Copilot
adapters/system-prompt.md ← any AI agent
That decision turned spec-sonar from "a Claude Code tool" into "a general requirements-engineering tool for the whole AI-coding ecosystem."
7. The philosophy: one expensive deep design → cheap structured execution
The core philosophy of the whole toolchain, surfaced while I was working out how goal-decomposer integrates with goal-workflow-designer.
The background problem is concrete: not everyone can afford Fable-tier model costs.
My insight:
Fable (expensive) thinks deeply once
→ the thinking is frozen into a goal graph and individual goal files
→ any model (Haiku, Sonnet) executes by following the graph
→ Fable-tier reasoning is no longer required
The analogy is compilation:
- Fable = the compiler that does the complex reasoning
- goal-graph.json = the compiled executable
- any model = the CPU that runs it
The smartest (and most expensive) model appears only once, at design time, to settle all the hard decisions; everything after that runs literally on cheap models.
8. Naming: spec-sonar
I considered SpecForge, DarkMap, ConvergeKit, and ReqSonar. I picked spec-sonar because it passed three tests:
- Searchability: no same-name repo on GitHub.
- Explanation cost: "like sonar, it finds what's submerged in your spec" — one sentence.
- Works in both languages: "I sonar-scanned the requirements" reads naturally.
The logic behind the name: sonar's core mechanism is using waves you can't see to find things you can't see. spec-sonar's core mechanism is using questions you didn't ask to find requirements you didn't think of. Form matches content.
9. Compatibility principles (the last major decisions)
Compatibility with existing CLAUDE.md files. spec-sonar is a design-time tool; CLAUDE.md is a build-time artifact — naturally on different timelines. So spec-sonar installs non-destructively: it never overwrites your existing CLAUDE.md, it only appends one reference line.
Conflict detection across existing skills. I upgraded the goal from "avoid conflicts" to "conflict as a feature": spec-sonar's Conflict Analysis Mode reads all your installed skills and outputs a conflict map. That turns it from "yet another skill" into "a governance tool for your skill ecosystem."
Load on demand: three install tiers — Lite (1 skill) for small projects/MVPs/anything finishable in a week; Standard (2 skills) for most projects under 3 months; Pro (full suite) for enterprise/ERP/long-term maintenance.
10. The role of Fable 5
On 2026-06-09 Anthropic released Claude Fable 5 — the first public model of the Mythos family. Its edge: "the longer and more complex the task, the wider the lead," with a particular strength in one-shotting a complete design.
My prompt strategy wasn't "what do you think of this design?" — it was "under what conditions does this design break, and fix it."
I asked Fable to do five things:
- Review the CLAUDE.md format from an executor's perspective ("could I start work from this spec?").
- Find the dark-zone baseline's systematic omissions per product type.
- Design STATE's conflict handling (retracted bright items, contradictions, late additions).
- Design the complete goal-decomposer SKILL.md (dependency inference, model-tier assignment).
- Design the adapter format for every platform.
11. This design was designed with spec-sonar
The most meta observation worth recording: this very design started from "I have a vague idea" and went through scope judgment, bright/dark separation, set-difference questioning, infeasibility detection (none found), complexity calibration, and wheel-reinvention detection — and that whole flow is spec-sonar's own flow.
The tool's first user was the person designing the tool.
12. Final output list
By the end of the conversation:
idea-to-spec-v1.1.zip
├── SKILL.md the convergence engine
├── references/
│ ├── dark-zone-baseline.md 10 dimensions (with the Session-vs-Persistent fix)
│ └── output-templates.md three output format templates
├── examples/
│ ├── README.md math tower-defense case (human-readable)
│ ├── CLAUDE.md math tower-defense case (executable spec)
│ └── STATE_FINAL.json final convergence state
└── docs/
├── fable-review-prompt.md the full Fable 5 review prompt (13 questions, 5 jobs)
└── spec-sonar-README.md open-source README draft
Pending Fable 5's reply: goal-decomposer/SKILL.md, project-scanner.py, the adapters/ directory (4 platforms), audit-mode, Conflict Analysis Mode, the tiered INSTALL.md.
(Every item on that list ships in Part 2 — plus three spec holes, one schema self-audit, and a real-world conflict analysis spanning two open-source repos.)
13. Reusable thinking patterns (Part 1)
- Interrogate before designing. Every new idea first answers "is this a reinvented wheel?" — with search results, not gut feeling.
- Dark zones matter more than bright zones. Stated requirements are rarely the problem; unstated assumptions are the root of failure.
- Behavioral contracts beat roleplay. Tell the AI its rules of behavior for this session, not who it is.
- Externalized state solves context loss. Multi-round tools must carry state explicitly every round.
- Find design gaps with real cases. After the theory, run one real case and let the gaps surface (that's how the Session-vs-Persistent fork was found).
- Expensive thinking once → cheap structured execution. The cost-optimal AI strategy.
- Universal core + per-platform adapters. The more universal the core format, the longer the tool lives.
- Load on demand. Tiered installation lets users choose their complexity instead of paying full cost by default.
Coming in Part 2
Part 1 ends with 13 questions packed into a review prompt and handed to Fable 5. Part 2 records what happened next:
- Fable reviews the test case as an executor and finds three day-one landmines in a seemingly complete spec.
- The tool audits its own output and catches its own schema drift.
- The full goal-decomposer design: dependency inference, contract freezing, pre-adjudication, the cold-start test.
- 25 files shipped as a complete open-source package.
- Then the real plot twist: installed into a production workspace, the Conflict Analysis Mode finds 5 conflicts between my own two open-source repos — and one structural problem nobody had seen.
本文原載於我的部落格：spec-sonar: The Complete Design Record (Part 1) — From One Idea to an Open-Source Toolchain
Top comments (0)