- 特意强调，使用claude code直接驱动浏览器，避免Playwright
- 确保docker测试能跑通，以及约定运行的镜像
Spec Kit
本质：斜杠命令 = 预制的 prompt 模板 + 一点点约定俗成的文件路径
1.安装
这是一个python包推荐使用UV
先去 https://github.com/github/spec-kit/releases 看 tag找最新稳定版
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.12.8
验证
specify --version
specify check # 检查 git / claude 是否都能找到
2.初始化
# 从零开始,创建一个新目录
specify init my-app claude
# 或者在已有项目里直接初始化
specify init . --ai claude
# 目录非空--force 跳过确认
specify init . --force --integration claude
初始化后会多出（隐藏文件夹）：
.specify/
├── memory/ # 存 constitution.md(项目宪法)
├── scripts/ # create-new-feature.sh / setup-plan.sh 等辅助脚本
└── templates/ # spec / plan / tasks 模板
.claude/
├── commands/ 或 skills/ # Claude Code 的 /speckit.* 命令会从这里注册
3.正常使用claude
在终端中已打开项目，并执行claude 或全托管claude --dangerously-skip-permissions 模式
输入 / 应该能看到 /speckit.*的选项
4.speckit的使用
-
/speckit-constitution：创建项目宪法原则
- 例如：聚焦于:代码质量(强制类型检查、lint 零警告)、测试标准(核心逻辑覆盖率 80%+,每个新 feature 必须带测试)、用户体验一致性、性能要求(API 响应 < 200ms)。同时说明这些原则如何指导技术决策。
- 产物:.specify/memory/constitution.md。之后每一步 Claude 都会参考这份文件
-
/speckit-specify ：写需求 spec（类似speckit内部项目）
- 只说"做什么 / 为什么",不说技术栈
- 例如：做一个命令行笔记工具,叫 nt。支持:新建笔记(带标题、标签、正文)、按标签筛选、全文搜索、归档。笔记以 Markdown 存储在本地。使用者是单用户,注重快速捕获想法,追求键盘流。不需要同步、不需要图形界面、不需要分享。
- 产物：specs/001-nt-cli/spec.md,里面是 user stories + 功能需求 + 验收标准
-
/speckit-clarify：消除歧义，必须运行在/speckit-plan之前(可选但建议)
- 它会逐条询问你问题
- 它会生成spec.md 的 Clarifications 小节
-
/speckit-plan：用户给出出技术方案
- 例如：用 Rust 实现,存储用 sqlite(通过 rusqlite),全文搜索用 tantivy,CLI 框架用 clap v4。笔记以 markdown 文件存放在 ~/.nt/notes/,sqlite 做索引。
- 产物：specs/001-nt-cli/ 下会多出 plan.md、data-model.md、research.md、contracts/、quickstart.md
- 一定要审查plan(很重要)
-
/speckit-tasks：拆分任务
- 产物:specs/001-nt-cli/tasks.md
-
/speckit-analyze：一致性分析(可选但推荐)
-
/speckit-implement：开始任务
Claude 遇到不确定会问你,一个 feature 可能要几十到上百轮对话。不是"按下去睡觉"的模式,那是下一节 Ralph 干的事
实际操作里我建议你前几个 feature 严格按步走:
第 1 个 feature 完整走 8 步,哪怕做的是"hello world"级别的东西 —— 目的是熟悉工具,不是产出
第 2 个 feature 走完之后,回头审视 constitution,看看是否需要加规则(比如"所有公共 API 必须写文档注释")
第 3 个 feature 开始才算"进入节奏",可以开始酌情省略 clarify 或 analyze
写完 5 个 feature 之后,你的测试套件、typecheck、lint 应该已经稳定、可信 —— 这是第二部分的前置条件
5.阶段继续
/speckit-implement 开始执行Phase 3
6.中途修改或添加
第 1 步：暂停 implement，讨论方案
暂停当前 task。我想调整 Phase 4 的前端技术栈：
Vite 从 5.0 升到最新稳定版（你先查一下现在是几）
加入 Pinia 做状态管理（之前 plan 里没提）
Vue 3 也确认一下用最新稳定版
先不要改文件。告诉我：这些调整会影响 plan.md 的哪些章节、tasks.md 的哪些 task、已完成的代码有没有需要回改的地方。
让 Claude 先做影响分析。这一步很重要，因为：
你会知道这个改动的真实代价（可能只是改 package.json，也可能需要重做 3 个 task）
Claude 会主动查最新版本号（vite、vue、pinia 的当前稳定版）
你能在动手前拦截错误决策
第 2 步：更新 plan.md
按刚才的讨论更新 specs/001-metadata-record-engine/plan.m：
所有前端组件都适用当前最新稳定版，而不是指定某个版本+（因为目前指定的某个大版本已经过时了），请检查设计前端版本的都修改过来
如果有新增依赖，更新相关的项目结构描述
改完显示 diff，先不要动 tasks.md 和代码。
看完 diff 满意再进下一步。
第 3 步：同步 tasks.md（如果需要）
plan.md 已更新。现在看 tasks.md 的 Phase 4 部分（T060-T072），哪些 task 需要调整描述或新增？例如是否需要：
新 task：初始化 Pinia store 结构
修改 T06X：在组件脚手架里集成 Pinia
列出变更建议，我确认后你再改 tasks.md。
第 4 步：才是恢复 implement
这时候 plan 和 tasks 都对齐了，重新跑：
/speckit.implement 继续 Phase 4，从 T060 开始。注意 plan.md 已更新（Vite 最新版 + Pinia），请按新方案执行。范围 T060-T072，完成后停下
7.中断后恢复
假设是/speckit.plan 中途断电，可以重跑或者（除非已写了很多了）：
specs/001-metadata-record-engine/plan.md 是上次 /speckit.plan 中断生成到一半的文件。请先读 spec.md 和 constitution.md，然后检查 plan.md 当前内容，判断哪些章节缺失或不完整，补齐到完整状态。
假设/speckit.implement 中途关闭，大多数情况它自己会对 tasks.md 里已完成的任务标打勾，如果没有则：
我们上次在 /speckit.implement 中途关闭了。请帮我做进度盘点：
读 specs/001-metadata-record-engine/tasks.md 了解任务列表
用 git log --oneline 看已经提交的 commits
用 git status 和 git diff 看未提交的改动
检查每个 task 涉及的文件是否已创建、内容是否完整
告诉我：哪些 task 已经完成、哪些做了一半、哪些还没开始
然后
基于刚才的盘点，把 tasks.md 里已完成的任务打勾
然后
/speckit.implement 从 T0XX 继续执行，跳过已打勾的任务。
跑通宵任务
/goal 检查当前Spec Kit任务实际进度，实际到哪了就从哪里继续，挨个完成后续所有切片计划，每个切片都执行标准的speckit-specify、speckit-plan、speckit-tasks、speckit-implement。整个过程无人值守，请不要出现任何选择问答，全部按你的建议来。除非必须人工测试的tasks，否则全由你完成，直到计划中的切片完全完成为止。