/spec - 我要验牌，牌没有问题

A single, repeatable Claude Code command in which the AI plays an expert requirements-elicitation analyst — it takes your vague idea and turns it into one authoritative, feasible specification.

Think of it like /init, but for the living spec. You run /spec; it clarifies the vague into the clear through investigation (reads what you point at, mines your project's data, searches its knowledge and the web, reasons it through — investigation is research), reflects your idea back organized, offers better views, and reports what's closed-loop (ready to build) vs what you haven't thought through yet. It then standardizes the result — key content, boundaries, and anti-patterns — into SPEC.md. Run it again any time — it resumes from where it left off.

What SPEC.md is (and isn't): a decision & feasibility contract — the load-bearing decisions, gates, boundaries, and anti-patterns. It is not a PRD / feature list / complete build blueprint; feature-level detail is regenerated by /build at construction time, never enshrined.

It is Gate 1 of an AI-assisted development process. Gate 1.5 is /build — the construction layer that reads SPEC.md and writes the code from it, keeping the design/tasks plan ephemeral (regenerated each run, never enshrined) so it can't drift, and closing only when each requirement's acceptance holds and the load-bearing gates are green. The third command, /yolo, is /build's autonomous-to-green mode plus a self-terminating loop: it schedules itself (Claude Code's /loop → cron, when available), keeps building to green, code-reviews each round, and deletes its own loop when nothing buildable remains — stopping early and handing back to you the moment it hits a genuine fork, a spec conflict, or two ticks with no progress. It changes /build's pace, never its rules. (Gate 2 — extracting a reusable skill from the finished project — is Claude Code's built-in skill-builder, out of scope here.)

This repo dogfoods itself: its own SPEC.md + .spec/ (from a real /spec run) specify the /spec → /build pipeline.

The deal: you weigh in only on the calls that are genuinely yours. The AI does the heavy lifting — investigating, reasoning, probing, deciding everything that's decidable, drafting, persisting. /spec is collaboration, not paperwork: no forms, no burden.

Install

Run one line inside your project to install /spec + /build + /yolo into its .claude/. It only touches .claude/skills/{spec,build,yolo}/, .claude/commands/{spec,build,yolo}.md, and .claude/spec-install.manifest — never your CLAUDE.md, SPEC.md, or .spec/ (those are generated by /spec itself, and are yours).

Windows — invokes powershell.exe explicitly, so it works pasted into any shell (cmd.exe, PowerShell, a Run dialog, a .bat file) without you having to know which one you're in:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/suifei/spec/main/scripts/install.ps1 | iex"

Linux / macOS / WSL / Git Bash:

curl -fsSL https://raw.githubusercontent.com/suifei/spec/main/scripts/install.sh | bash

The Windows installer needs nothing beyond PowerShell 5.1+ itself (falls back to pure Invoke-WebRequest + Expand-Archive if git isn't on PATH); the Linux/macOS one uses git if present, else curl + tar. Re-running either upgrades in place. Then open Claude Code in that directory and run /spec.

Prefer a pinned, offline copy? Every tagged release ships a spec-skills-<tag>.zip on the Releases page. Verify its .sha256, extract to a temporary directory, then invoke the same transactional installer with that directory as the source; do not unzip over a project:

tmp=$(mktemp -d)
unzip spec-skills-*.zip -d "$tmp"
SPEC_INSTALL_SOURCE="$tmp" bash "$tmp/scripts/install.sh" /path/to/project

How it works

/spec ─▶ rehydrate (.spec/STATE.md)         # know exactly where it left off
      ─▶ INVESTIGATE (= research): cache → your material → project data → knowledge → web (+ optional /deep-research for a contested, load-bearing question) → skills/MCP → reason → probe
      ─▶ resolve what you can; register the reasoning (Decision Log)
      ─▶ report findings + closure status (ready vs not-yet-thought-through)
      ─▶ ask only the genuine forks (or a better option found) — low-burden, calibrated
      ─▶ back load-bearing gates with evidence (probes must be able to go red)
      ─▶ persist everything + update CLAUDE.md ─▶ closure seals a phase

Principles

• Speaks the language you pick — asked once (highest-priority rule). On first persist it asks one question — which language for reports and SPEC.md (default: the language you're writing in; English/中文/日本語/… or other) — then pins it in SPEC.md and never asks again, regardless of what language you type in later. On a mismatch with existing content it translates proactively (chunked if large). Code/paths/URLs/timestamps stay verbatim. (This repo pins English.)
• Investigation is research (探真 = 研究). Finding the truth = finding the knowledge — by any means (knowledge, web, project data, skills/MCP, reasoning). A runnable probe is one instrument, not the definition.
• Decide what's decidable; ask rarely. It resolves what it can and registers the reasoning, asking you only about a genuine fork evidence can't settle, or a better option it found. It never makes you adjudicate commonsense.
• Honest, including "no". It refuses the research-proven-infeasible with the real reason and names problems in your decisions — it won't spec a known-wrong wish to be agreeable. Standing in for market/requirements/feasibility/ architecture/design-review at once, it pulls top-tier authoritative sources when a role needs knowledge it lacks.
• Gates are load-bearing only. A gate is a truth a real decision hinges on. Commonsense facts (a free port, a writable dir, a tool on PATH) are never gates and never a coding focus — we don't build around whether a port is free.
• Evidence, never fabrication. A load-bearing gate is backed by a probe that can go red, or a cited source (marked WEAK) when it can't be scripted.
• The filesystem is memory. State lives on disk, not in the context window — so it runs reliably in a small window and resumes across resets/compaction. Reconnaissance persists (.spec/knowledge/) so it isn't re-explored.
• The spec line. The spec governs the contract surface (behavior, contracts, load-bearing gates, NFRs, declared constraints, boundaries, anti-patterns) — never implementation detail. Code stays free below the line.
• Phases emerge from closure, they aren't pre-planned; sealed phases are read-only (corrections open a new, superseding phase).
• Honest limit. SPEC.md is a lower bound on verified truth, not a correctness proof.

Usage

/spec                                  # create, or resume where it left off
/spec add multi-tenant support         # fold in an idea, then converge
/spec read ./legacy-service and spec the rewrite   # point it at material to scout
/build                                 # construct the next phase from SPEC.md (propose-then-apply)
/yolo                                  # let /build loop autonomously to green; self-reviews, self-terminates

SPEC.md and .spec/ are generated on first run. The ideal day-to-day shape: /spec <your idea> to converge on the contract, then /yolo to let construction run to green while the gates keep it honest.

Examples

examples/self-evolving-agent/ — produced by an actual /spec skill invocation (the skill drove the run): real research of the authoritative literature, a real probe, and the forks decided by the human in the loop. It establishes the subject first (a "self-evolving agent" is an objective-gated propose→evaluate→select→archive loop, not "an LLM that edits itself"), verifies the one behavioral invariant with a probe (an objective gate rejects regressions), and — when the human picked the riskier auto-promote option — honestly hardened it (mandatory held-out eval + rollback + kill-switch) instead of rubber-stamping. ./verify.sh → 26 assertions, ALL PASS.

examples/web-claude-code/ (below) was hand-authored to model the skill's output — its probes and research are real, but it was not produced by invoking the skill. Kept as a worked illustration of the format.

A complete /spec run is captured under examples/web-claude-code/ as a worked illustration, on a deliberately knowledge-heavy brief: "develop a Web version of Claude Code." It also captures a real mistake-and-correction that shows the discipline working: a first draft jumped to "build an agent backend" — designing the how before establishing what Claude Code is (define the noun before the verb). The corrected spec establishes the subject first from official docs (Claude Code is an agentic CLI with a takeover-able I/O surface), and so finds the real core problem: "to web" = take over the existing CLI's I/O (PTY or stream-json) and relay it to the browser over WebSocket — not rebuild the agent. Two gates are settled by cited research (the subject; the credential boundary), the one behavioral truth (a CLI's stdio can be taken over and relayed) by a runnable probe with a negative control, and the old framing is honestly superseded. Run ./verify.sh there for the probe + 24 assertions (ALL PASS, exit 0). Its README carries an objective value assessment.

Files

.claude/
├── skills/
│   ├── spec/
│   │   ├── SKILL.md                    # the /spec procedure (investigate → ask → decide → probe → persist → resume)
│   │   └── references/
│   │       ├── questioning.md          # how to ask (Socratic, info-gap, low-burden, calibrated)
│   │       ├── probes.md               # how to probe (evidence + mandatory negative control)
│   │       ├── SPEC.template.md        # structure of SPEC.md
│   │       ├── STATE.template.md       # the .spec/STATE.md progress ledger
│   │       └── knowledge.template.md   # a .spec/knowledge/ reconnaissance entry
│   ├── build/SKILL.md                  # the /build procedure (Gate 1.5: spec → code)
│   └── yolo/SKILL.md                   # the /yolo procedure (autonomous construct-to-green loop)
├── commands/spec.md                   # /spec slash-command wrapper
├── commands/build.md                  # /build slash-command wrapper
├── commands/yolo.md                   # /yolo slash-command wrapper
scripts/install.ps1                    # one-line installer (Windows, run via powershell.exe)
scripts/install.sh                     # one-line installer (Linux/macOS/WSL/Git Bash)
CLAUDE.md                              # declares SPEC.md the supreme, read-first reference
docs/DESIGN-NOTES.md                   # full design rationale: discussion rounds + decision log
docs/PAPER.md                          # academic paper (English): design, method, empirical study, with figures/tables
docs/PAPER-short.md                    # short-paper (English): conference-style condensation of PAPER.md
docs/PAPER.zh-CN.md                    # academic paper (Chinese): full translation of PAPER.md, with figures/tables
docs/USER-GUIDE.zh-CN.md               # usage manual (Chinese): when to use it, scenarios, strategy, philosophy
docs/RESEARCH-REPORT.zh-CN.md          # research report (Chinese): background, pain points, decision context

# this repo dogfoods itself — produced by a real /spec run:
SPEC.md                                # the spec (the /spec → /build pipeline)
.spec/STATE.md                         # progress ledger (resumability; incl. the /build-owned ## build section)
.spec/investigation.log                # append-only trail: consulted source → conclusion (internal)
.spec/knowledge/<topic>.md             # persisted reconnaissance (pinned deps/facts)
.spec/probes/<gate>.sh                 # executable probes
.spec/evidence/<gate>-<ts>.log         # captured probe output

Design rationale

docs/DESIGN-NOTES.md records the whole design conversation — from "port OpenSpec" to this expert-analyst, resumable, single-command Gate 1 — plus a consolidated decision log. docs/RESEARCH-REPORT.zh-CN.md is a structured Chinese-language synthesis of that conversation (background, pain points, decision context) for readers who want the thinking without the round-by-round log. docs/USER-GUIDE.zh-CN.md is a Chinese-language usage manual — when to reach for /spec vs /build, worked scenarios (real and illustrative, clearly labeled), strategy, anti-patterns, and the engineering philosophy behind the design.

For an academic treatment — the drift and hollow-green problems, the Intent/Acceptance/Method + falsifiable-probe + intent-review model, the consistency lens, and the empirical study (dogfooding, non-programming evaluation, adversarial review, representation blind-study) — see docs/PAPER.md (with figures/tables), or docs/PAPER-short.md for a conference-style condensation. A full Chinese translation is in docs/PAPER.zh-CN.md(中文全文).