从 HTML 原型到结构化 AI Spec 的需求编译工具。补齐 Claude Code 生态中"原型 → 需求"这一环。
Claude Code 生态中有很多优秀的 Skill：superpowers:brainstorming 帮你构思方案，superpowers:writing-plans 帮你写实施计划，frontend-design 帮你实现 UI。但它们都有一个共同的前提——你得先告诉 AI 要做什么。
当一个产品经理丢给你一个 AI 生成的 HTML 原型时，这些 Skill 都帮不上忙。因为：
| 你手里有 | 你需要的 | 谁能做这个转换？ |
|---|---|---|
login.html（一个登录表单） |
一份包含 API 端点、校验规则、错误处理、状态矩阵的需求说明 | ❌ 没有现成的 Skill |
AI Spec Kit 就是填补这个空缺的。 它从 HTML 的 DOM 结构反推业务意图，把"这个页面长什么样"编译成"这个页面要做什么"。
AI Spec Kit 是流水线的入口——处理原型到需求的转换，然后把结构化的 Spec 交给下游 Skill：
HTML 原型
│
▼
/specify-html ← AI Spec Kit（本项目的角色）
│
▼
AI Spec（结构化需求文档）
│
├─→ /clarify-spec ← AI Spec Kit（消除待确认项）
│
▼
superpowers:brainstorming ← 基于 Spec 构思技术方案
│
▼
superpowers:writing-plans ← 生成实施计划
│
▼
frontend-design / 手动开发 ← 实现
│
▼
code-review / verify ← 对照 Spec 验证
没有 AI Spec Kit 时： 开发者盯着 HTML 原型，凭经验推断需求，边写边猜，容易遗漏边界情况和异常状态。
有 AI Spec Kit 时： HTML 进去，结构化的 Spec 出来。所有不确定性标记为 [待确认]，逐项澄清后再动手。下游的 brainstorming、writing-plans 等 Skill 拿到的是明确的输入，而不是模糊的"看原型做一个类似的功能"。
| 没有 AI Spec Kit | 有 AI Spec Kit |
|---|---|
| 看着 HTML 凭感觉估需求，想到哪做到哪 | 系统化提取：组件 → 业务意图 → 缺口 → Spec |
| 开发到一半发现忘了考虑 Loading 状态 | Step 3 缺口分析强制覆盖状态矩阵 |
| API 端点靠猜，和后端联调时才发现对不上 | 所有不确定的 API 标记 [待确认]，开发前先澄清 |
| 不同页面由不同人开发，风格不一致 | 同一套模板输出，格式统一 |
| 需求文档（PRD）有 70% 是 AI 不关心的内容 | AI Spec 只包含 AI 开发真正需要的信息 |
两种方式二选一。个人使用推荐系统级，团队共享推荐项目级。
安装到用户目录，之后在任何项目中都能直接调用 /specify-html 和 /clarify-spec。
git clone https://github.com/your-repo/ai-spec-kit.git
cd ai-spec-kit
# Windows PowerShell:
cp -r .claude/skills/specify-html $env:USERPROFILE\.claude\skills\
cp -r .claude/skills/clarify-spec $env:USERPROFILE\.claude\skills\
# macOS / Linux:
cp -r .claude/skills/specify-html ~/.claude/skills/
cp -r .claude/skills/clarify-spec ~/.claude/skills/验证安装： 在任意项目中打开 Claude Code，输入 /specify-html，如果 Skill 被识别即安装成功。
~/.claude/skills/
├── specify-html/ # ← 新安装
└── clarify-spec/ # ← 新安装
安装到项目的 .claude/skills/ 下，团队成员 clone 项目后自动生效。
# 在你的目标项目中
mkdir -p .claude/skills
cp -r /path/to/ai-spec-kit/.claude/skills/specify-html .claude/skills/
cp -r /path/to/ai-spec-kit/.claude/skills/clarify-spec .claude/skills/
# 提交到 Git
git add .claude/skills/
git commit -m "chore: add specify-html and clarify-spec skills"cd /path/to/ai-spec-kit && git pull
# 系统级：
cp -r .claude/skills/specify-html ~/.claude/skills/
cp -r .claude/skills/clarify-spec ~/.claude/skills/
# 或项目级：
cp -r .claude/skills/specify-html /path/to/your-project/.claude/skills/
cp -r .claude/skills/clarify-spec /path/to/your-project/.claude/skills/| 步骤 | 做什么 | 产出 |
|---|---|---|
| Step 0 | 读取项目上下文（.ai/、CLAUDE.md） |
了解技术栈和编码规范 |
| Step 1 | 解析 HTML，提取所有可交互元素 | 组件清单 |
| Step 2 | 推断业务语义（表单→CRUD，表格→列表） | 页面目的 + 用户操作 |
| Step 3 | 缺口分析：列出 HTML 无法推断的内容，交互式提问（≤3个/轮） | 待确认项清单 |
| Step 4 | 生成结构化 AI Spec | specs/001-功能名/spec.md |
逐轮消除 Spec 中的 [待确认] 标记。每次最多 3 个问题，按优先级排序（API > 校验 > 状态 > 其他）。
# 1. 准备一个 HTML 原型
# 2. 在 Claude Code 中运行
/specify-html prototype/login.html
# 3. AI 分析 HTML 后提问（每次最多 3 个）
# 4. 回答后，Spec 生成在 specs/001-login/spec.md
# 5. 运行澄清命令消除剩余 [待确认] 项
/clarify-spec specs/001-login/spec.md
# 6. Spec 就绪 → 交给 brainstorming → writing-plans → 开发 🚀
生成的 Spec 包含 6 个核心章节，技术无关——只描述 WHAT，不描述 HOW：
specs/001-功能名/
└── spec.md
├── 1. 页面目的 (Goal)
├── 2. UI 组件清单 (UI Components)
├── 3. 用户流程 (User Flow) # 正常流程 + 异常流程
├── 4. 数据与接口 (API & Data)
├── 5. 状态矩阵 (States) # Idle / Loading / Success / Error / Empty
└── 6. 校验规则 (Validation)
设计哲学和命令结构借鉴了 GitHub 的 spec-kit。核心区别在于输入源：
| spec-kit | AI Spec Kit | |
|---|---|---|
| 输入 | 自然语言描述 | HTML 原型 |
| 典型场景 | 开发者写 feature 描述 | PM 用 AI 生成 HTML → 开发者接手 |
| 在流水线中的位置 | 从 natural language 开始 | 从 HTML 开始，spec-kit 的上游 |
两者可以串联：
HTML 原型 → /specify-html → AI Spec → /speckit.plan → /speckit.tasks → /speckit.implement
↑ AI Spec Kit ↑ spec-kit（需单独安装）
your-project/
├── prototype/ # PM 生成的 HTML 原型
├── specs/ # AI Spec Kit 生成的 Spec
│ ├── 001-login/spec.md
│ └── 002-dashboard/spec.md
├── .ai/ # （可选）项目规范
│ ├── project.md
│ ├── coding_rules.md
│ └── ui_rules.md
├── .claude/skills/ # Skill（项目级安装）
│ ├── specify-html/
│ └── clarify-spec/
└── src/
- 技术无关 — Spec 只描述"用户要做什么"，不描述"用什么框架做"
- 项目自适应 — 优先读取项目已有的规范文件，不强行覆盖
- 交互式，不瞎猜 — 无法推断的信息标记
[待确认]，不编造 - 每次最多 3 个问题 — 不淹没开发者，分批确认
欢迎提交 Issue 和 PR！详见 CONTRIBUTING.md。
MIT