/spec · 我要验牌

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

它做什么：/spec 把你含糊的想法问成一份能落地的规格，/build 照着规格写码，/yolo 让这件事自动跑到绿。

凭什么信：每个承重结论背后都挂着一个能真的变红的探针——变不红的检查不算数，所以"绿"是跑出来的，不是 AI 说的。

你省下什么：需求不再散在聊天记录里，AI 能查的自己查、能定的自己定并写进决策日志，只在真正的分叉上问你一次。

介绍视频 · 1 分 48 秒

https://github.com/user-attachments/assets/589849df-9629-42b7-b2f5-66a5c5d59012

六段，每段讲一个点：

https://github.com/user-attachments/assets/f78f1e35-e081-403e-9124-9f5e88c7483f

① 问题 · 17s 需求散在聊天里，一路绿灯却说不清凭什么

https://github.com/user-attachments/assets/6fc0b821-8fa4-4bbe-9c63-b4a6c5e2393f

② 安装 · 13s 一行装好，只碰 .claude/

https://github.com/user-attachments/assets/805ba9ab-0c4d-4b3f-af45-b3fafbd91920

③ 三道门 · 20s /spec → /build → /yolo

https://github.com/user-attachments/assets/a5176a5b-684b-48ee-b2cb-3bd3ca69c6ef

④ 人机协同 · 18s AI 扛重活，只有真分叉才问你

https://github.com/user-attachments/assets/9adcc4ef-9794-4817-8c15-380954c52ce4

⑤ 核心能力 · 20s 探针必须能变红，这个绿才算数

https://github.com/user-attachments/assets/f21e70bb-4d31-4b26-bb4c-831b8fed3e96

⑥ 效果 · 19s 自己管自己，22 条探针全绿

片子用 HyperFrames 制作（HTML → 确定性渲染 MP4）， 源码与构建说明在 [video/](video/)，配音用 NowVoice（云泽·纪录片解说）生成。 上面是 GitHub 的内嵌播放器：README 会过滤 ／ 标签，只有形如 github.com/user-attachments/assets/ 的链接会被转成播放器，且每条须独占一个段落。 想下载原文件，整片与六个分段也都在 v2026-09-10 release 里。

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](.claude/skills/build/SKILL.md)** — 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](.claude/skills/yolo/SKILL.md)**, 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

不用开终端，不用挑系统。在你的项目里打开 AI 开发工具（Claude Code / Cursor / Codex…）， 把下面这行发给它，让它自己装：

安装skill https://github.com/suifei/spec/releases/latest/download/spec-skills.zip

它会把 zip 取下来、解进项目的 .claude/，然后你就能用 /spec、/build、/yolo 了。 这个地址固定指向最新发布，不随版本变化。

装进去的东西只有 .claude/skills/{spec,build,yolo}/、.claude/commands/{spec,build,yolo}.md 和 .claude/spec-install.manifest —— 你的 CLAUDE.md、SPEC.md、.spec/ 一个都不碰 （那些是 /spec 自己生成的，属于你）。最新版本见 Releases 页。

或者自己跑安装脚本 （想要脚本化 / CI / 离线固定版本时）

Run one line inside your project to install /spec + /build + /yolo into its .claude/.

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- .zip on the Releases page (plus spec-skills.zip, a byte-identical copy under a stable name that releases/latest/download/ resolves to). Verify the .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 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/](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, calibrate