Spec-Kit 详解：概念澄清与 Claude Code 整合实战
·
Spec-Kit 详解：概念澄清与 Claude Code 整合实战
第一部分：概念地图——一张图理清所有概念
你为什么会晕
过去 4 篇文章引入了大量概念，它们是不同层级、不同来源的东西，但都叫"配置"或"规范"。先按来源分类：
概念来源全景图:
┌─────────────────────────────────────────────────────────────┐
│ Claude Code 内置 │
│ /plan → Plan Mode（先设计再施工的模式） │
│ /compact → 压缩上下文 │
│ /clear → 清空对话 │
│ @ 引用 → 文件/目录/git 引用 │
│ TODO → 对话内的任务追踪 │
│ CLAUDE.md → 项目级指令文件（CC 启动时自动读） │
│ .claude/commands/*.md → 自定义 Slash Commands │
│ .claude/hooks.json → 事件触发的自动脚本 │
│ .claude/settings.json → 项目级设置 │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ oh-my-claudecode（社区增强框架） │
│ 本质: 预配置的 CLAUDE.md 模板 + Hooks + Slash Commands │
│ 不引入新概念——它只是帮你"预写好了"上面的配置文件 │
│ → templates/CLAUDE.md → 复制到项目根目录 │
│ → hooks/*.json → 复制到 .claude/hooks.json │
│ → commands/*.md → 复制到 .claude/commands/ │
│ → skills/ → 复制到 .claude/skills/ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Spec-Kit（GitHub 官方工具包） │
│ 本质: 一套"先写文档再写代码"的工作流 + 对应的 Slash Commands │
│ 核心命令（都是 .claude/commands/ 下的 markdown 文件）: │
│ /speckit.constitution → 定义项目宪法（不可妥协的规则） │
│ /speckit.specify → 写需求规格（What + Why） │
│ /speckit.plan → 写技术方案（How） │
│ /speckit.tasks → 拆解任务（Do what, in what order） │
│ /speckit.implement → 逐任务执行 │
│ /speckit.clarify → 澄清模糊需求 │
│ /speckit.analyze → 跨文档一致性检查 │
│ /speckit.checklist → 质量验证清单 │
└─────────────────────────────────────────────────────────────┘
关键认知：oh-my-claudecode 和 Spec-Kit 不是竞争关系。oh-my-claudecode 管的是"AI 写代码时的行为规范"（格式化、不执行危险命令），Spec-Kit 管的是"写代码之前的规划流程"（先设计再动手）。两者可以叠加使用。
按功能层次分类
换个角度——把概念按"做什么用"而不是"从哪来的"来分：
第一层: AI 行为约束（管 AI 怎么写代码）
├── CLAUDE.md → 项目规则（技术栈、命名、禁忌）
├── .claude/hooks.json → 自动触发脚本（格式化、拦截危险命令）
├── /compact, /clear → 上下文管理
└── Memory → 跨会话持久记忆
第二层: 工作流编排（管 AI 按什么流程做事）
├── Claude Code Plan Mode → 内置的"先分析再动手"
├── .claude/commands/*.md → 自定义 Slash Commands
├── TODO → 对话内进度追踪
└── Spec → 需求/架构/任务文档（人工或 AI 生成）
第三层: Spec-Driven Development 方法论（管整个项目怎么推进）
├── Constitution → 项目宪法（最高原则，不可妥协）
├── Spec → 需求规格（What——要做什么）
├── Plan → 技术方案（How——怎么做）
├── Tasks → 任务拆解（Steps——分几步做）
├── Clarify → 澄清模糊点
├── Analyze → 一致性检查
├── Checklist → 质量门禁
└── Implement → 逐任务实现
概念速查表
| 概念 | 是什么 | 存在哪里 | 谁提供 | 类比 |
|---|---|---|---|---|
| CLAUDE.md | 项目级 AI 指令 | 项目根目录 | 你手写 或 oh-my-claudecode 模板 | 员工手册 |
| Memory | 跨会话持久记忆 | ~/.claude/projects/.../memory/ |
Claude Code 内置 | 你的笔记本 |
| Skill | 可复用的能力模块 | .claude/skills/ |
Claude Code 内置 | 员工的专项技能 |
| Slash Command | 自定义快捷命令 | .claude/commands/*.md |
你手写/Spec-Kit/oh-my-claudecode | 快捷键宏 |
| Hooks | 事件驱动的自动脚本 | .claude/hooks.json |
你手写/oh-my-claudecode | CI 流水线 |
| Plan Mode | 先设计再施工的交互模式 | Claude Code 内置 | Anthropic | 架构评审会 |
| Constitution | 项目不可妥协的原则 | .specify/memory/constitution.md |
Spec-Kit | 宪法 |
| Spec | 需求规格文档 | specs/xxx/spec.md |
Spec-Kit 或你手写 | PRD |
| Plan (文档) | 技术方案文档 | specs/xxx/plan.md |
Spec-Kit 或你手写 | 架构设计文档 |
| Tasks | 依赖排序的任务清单 | specs/xxx/tasks.md |
Spec-Kit 或你手写 | Jira Sprint |
最重要的区分：Plan Mode（Claude Code 功能）≠ Plan 文档（Spec-Kit 产物）。前者是一个交互模式，后者是一份 markdown 文件。Spec-Kit 的 /speckit.plan 命令会生成一份 Plan 文档，而 Claude Code 的 /plan 是让 AI 进入"先分析再写代码"的模式。
第二部分：Spec-Kit 核心方法论
2.1 Spec-Kit 的哲学：把"想清楚"变成强制的步骤
Vibe Coding 的问题不是 AI 不够强——是你没有在写代码前想清楚要什么。
Vibe Coding:
你: "帮我做个用户积分系统"
AI: [写了 800 行代码]
你: "不对不对，积分要支持部分使用，还要有过期机制"
AI: [重写 500 行]
你: "还有积分获取规则也不对..."
→ 来回 5 轮，每一轮 AI 都可能忘记前面的约束
Spec-Driven Development:
你: /speckit.specify → 生成 spec.md（完整需求文档）
你: [审阅 spec.md] → "积分有效期改为 2 年，不是 1 年"
你: /speckit.plan → 基于 spec.md 生成 plan.md（技术方案）
你: [审阅 plan.md] → "数据表加一个 expires_at 字段"
你: /speckit.tasks → 生成 tasks.md
你: /speckit.implement → AI 逐 Task 执行，每个 Task 有明确输入和验收标准
→ Spec 文档是 AI 的"外置大脑"，不需要在上下文中记住所有约束
Spec-Kit 的核心主张：把"想清楚"从可选的变成强制的。每一步都产出文档，文档是下一步的输入，人是最终的决策者。
2.2 安装 Spec-Kit
# 方式一: 用 uv 持久安装（推荐）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 方式二: 一次性使用
uvx --from git+https://github.com/github/spec-kit.git specify init <项目名>
# 初始化项目（在已有项目中）
cd ~/projects/my-app
specify init . --ai claude
# 这会在 .claude/commands/ 下创建所有 /speckit.* 命令
# 并在 .specify/ 下创建模板和脚本
2.3 Spec-Kit 初始化后你的项目多了什么
my-app/
├── .specify/
│ ├── memory/
│ │ └── constitution.md # 空模板，等你填充
│ ├── templates/
│ │ ├── spec-template.md # Spec 文档模板
│ │ ├── plan-template.md # Plan 文档模板
│ │ ├── tasks-template.md # Tasks 文档模板
│ │ └── checklist-template.md # Checklist 模板
│ └── scripts/
│ └── ... # 自动化脚本
│
├── .claude/
│ └── commands/
│ ├── speckit.constitution.md
│ ├── speckit.specify.md
│ ├── speckit.plan.md
│ ├── speckit.tasks.md
│ ├── speckit.implement.md
│ ├── speckit.clarify.md
│ ├── speckit.analyze.md
│ └── speckit.checklist.md
│
└── specs/ # 你的功能 spec 存放处
└── 001-user-points/ # 每个功能一个目录
├── spec.md # What
├── plan.md # How
├── tasks.md # Do
├── research.md # （可选）技术调研
├── data-model.md # （可选）数据模型
└── contracts/ # （可选）API 合约
第三部分：Spec-Kit 七大核心命令详解
3.1 /speckit.constitution — 项目宪法
什么时候执行：项目刚开始，只执行一次。后续所有功能 Spec 都会对齐这份宪法。
做什么：定义项目的"不可妥协原则"——技术栈、测试标准、安全要求、性能基线、编码规范。
在 Claude Code 中输入：
/speckit.constitution
请为我的量化分析工具项目定义宪法。
项目背景:
- Python 3.12+ CLI 工具，面向个人用户
- 核心功能: 金融数据获取、策略回测、HTML 报告生成
- 数据源: AKShare（免费 API）
- 本地存储: SQLite
原则:
- 所有函数必须标注类型
- 数据模型用 Pydantic v2 + SQLAlchemy 2.0
- 测试覆盖率 > 80%
- "能用"第一，"完美"第二——不引入多余抽象
- 外部 API 调用必须有重试和超时
- 不要硬编码任何 Token 或密钥
产出：.specify/memory/constitution.md
这个文件的角色和 CLAUDE.md 很像，但有本质区别：
| 维度 | CLAUDE.md | Constitution |
|---|---|---|
| 范围 | 项目级指令 | 项目级原则 |
| 内容 | 技术栈 + 目录结构 + 规则 + 禁忌 | 原则 + 质量标准 + 决策框架 |
| 加载时机 | Claude Code 每次启动 | /speckit.* 命令执行时引用 |
| 强制力 | 低（AI 可能忽略后面的规则） | 中（analyze 命令会检查合规性） |
| 维护者 | 你手动更新 | /speckit.constitution 生成 |
实际操作建议：把 CLAUDE.md 的"规则"章节和 Constitution 保持一致。最简单的做法——Constitution 写好后，把关键原则也复制到 CLAUDE.md。
3.2 /speckit.specify — 需求规格
什么时候执行：每个新功能开始前。
做什么：把"我想要做什么"变成结构化的需求文档。包含用户故事、功能需求（FR）、非功能需求（NFR）、验收标准、边界条件、不做什么。
在 Claude Code 中输入：
/speckit.specify
功能: 用户积分系统
背景: 电商平台，用户下单获得积分，积分可抵扣金额。
约束:
- 100 积分 = 1 元
- 积分有效期 1 年
- 支持部分使用
- 不引入新数据库
产出：specs/001-user-points/spec.md
你审阅时的检查清单：
□ 功能范围对不对（有没有漏掉的？有没有不该做的？）
□ 验收标准够不够具体（能直接用来验证"做完了"吗？）
□ 边界条件覆盖了吗（余额为 0、过期积分、并发扣减）
□ "不做什么"写清楚了吗（防止 AI 自作主张加功能）
3.3 /speckit.clarify — 澄清模糊点
什么时候执行：review spec.md 时发现有模糊的地方，或者 AI 主动问你要不要澄清。
做什么：AI 会读 spec.md，找出模糊或不一致的地方，然后向你提问（最多 5 个/轮）。你回答后 AI 更新 spec.md。
典型流程：
🤖 AI: 发现 3 个需要澄清的点:
1. "积分部分使用"——如果用户有 500 积分，订单需要抵扣 6 元（600 积分），
是全部不抵扣还是抵扣 500 积分（5 元）？
2. 积分过期——是精确到秒还是精确到天？过期前 7 天是否通知用户？
3. 退款场景——订单退款后，已使用的积分是否退回？如果积分已过期怎么处理？
👤 你: 1. 不足的部分用现金补，有多少扣多少
2. 精确到天，过期前 3 天通知
3. 退款退回积分，但积分有效期不变（不续期）
为什么这一步关键：这些模糊点在写代码时一定会遇到。提前澄清意味着 AI 不会在实现时"猜"——猜错了你又要纠偏。
3.4 /speckit.plan — 技术方案
什么时候执行：spec.md 确认后。
做什么：基于 spec.md 生成技术实现方案。包括数据模型、API 设计、关键流程、技术决策及原因。
与 Claude Code /plan 的区别：
| 维度 | Claude Code /plan |
/speckit.plan |
|---|---|---|
| 输入 | 你自然语言描述的需求 | 已确认的 spec.md |
| 输出 | 对话中的计划（可能被压缩） | 持久化的 plan.md 文件 |
| 模板 | 无固定模板 | 按 plan-template.md 结构化输出 |
| 可追溯 | 仅当前对话 | 版本控制，可回溯 |
| 合规检查 | 无 | analyze 命令可检查与 spec/constitution 一致性 |
| 适用场景 | 中等任务（3-10 文件） | 大功能（10+ 文件、3+ 天） |
实操建议：
小功能（改 1-3 个文件）:
→ 直接用 Claude Code，不需要 Spec-Kit
→ 口头说清楚需求，AI 直接写代码
中等功能（改 3-10 个文件）:
→ 用 Claude Code /plan
→ AI 先分析方案，你确认后逐步实现
大功能（改 10+ 个文件）:
→ 上 Spec-Kit 全流程
→ constitution → specify → clarify → plan → tasks → implement
3.5 /speckit.tasks — 任务拆解
什么时候执行：plan.md 确认后。
做什么：把 plan.md 的实现路径拆成可独立完成、可独立验证的任务清单。按依赖关系排序。
产出：specs/001-user-points/tasks.md
# 用户积分系统 - 任务列表
## Phase 1: 数据层（基础，无依赖）
- [ ] T001: 创建积分账户表 points_accounts (user_id, balance, total_earned, total_spent)
- [ ] T002: 创建积分流水表 points_transactions (user_id, amount, type, ref_id, expires_at)
- [ ] T003: 数据库迁移脚本 + 回滚脚本
## Phase 2: 核心业务逻辑（依赖 Phase 1）
- [ ] T004: [P] 积分获取服务 award_points(user_id, order_amount) ← 依赖 T001, T002
- [ ] T005: [P] 积分消费服务 spend_points(user_id, amount) ← 依赖 T001, T002
- [ ] T006: 积分过期处理定时任务 expire_points() ← 依赖 T002
## Phase 3: API 层（依赖 Phase 2）
- [ ] T007: GET /api/points/balance ← 依赖 T001
- [ ] T008: GET /api/points/history ← 依赖 T002
- [ ] T009: POST /api/orders（集成积分抵扣）← 依赖 T005
[P] 标记表示可以并行执行（不互相依赖）。
一个好的 Task 的标准：
✅ 好的 Task:
T004: 实现 award_points(user_id, order_amount) 函数
- 输入校验: user_id 存在、order_amount > 0
- 积分计算: 1 元 = 10 积分（向上取整）
- 写入 points_transactions 表（type='earn', expires_at = now + 1 year）
- 更新 points_accounts 表（balance += earned, total_earned += earned）
- 返回: EarnedPoints { earned: int, balance: int }
❌ 差的 Task:
实现积分获取功能
→ AI 不知道"实现"包含什么，你不知道怎么验证
3.6 /speckit.analyze — 一致性检查
什么时候执行：tasks.md 生成后、implement 之前。
做什么：交叉检查 spec.md、plan.md、tasks.md、constitution.md 之间是否存在矛盾。
检查维度：
1. 需求覆盖: spec.md 里的每个 FR 在 tasks.md 中都有对应的 Task 吗？
2. 架构一致: plan.md 里的每个组件在 tasks.md 中都有对应的 Task 吗？
3. 宪法合规: plan.md 的选型符合 constitution 的技术约束吗？
4. 依赖正确: tasks.md 里的依赖关系有循环依赖吗？
5. 验收对齐: Task 的验收标准覆盖了 spec.md 里的验收标准吗？
这一步的价值：在写代码之前发现"spec 说要支持部分积分使用，但 plan 里只设计了全额使用"这类矛盾。提前 5 分钟发现，省下 2 小时的返工。
3.7 /speckit.implement — 执行实现
什么时候执行：所有文档确认后。
做什么：按 tasks.md 的顺序逐 Phase 执行。关键行为：
- 每开始一个 Task，先读相关 spec/plan 章节确保理解正确
- 写代码 → 写测试 → 跑测试 → 通过 → 标记
[x] - 一个 Task 完成后再开始下一个
- 遵循 constitution 中的规则
你怎么参与：
AI 每完成一个 Task:
1. 你审阅 diff（git diff --cached）
2. 发现问题 → 立即纠正（不要等"后面一起改"）
3. 确认通过 → AI 标记 [x] → 下一个 Task
第四部分：Claude Code 全家桶——三个框架怎么配合
4.1 三个框架的定位
Claude Code（底座）:
→ 核心 Agent 能力（读文件、写代码、执行命令）
→ 内置功能: /plan, /compact, @ 引用, TODO
oh-my-claudecode（行为增强层）:
→ 管 AI 写代码时的行为
→ Hooks: 自动格式化、拦截危险命令、自动跑测试
→ Slash Commands: /review, /test, /clean, /git-commit
→ CLAUDE.md 模板: 按项目类型预配置规则
→ 本质: 帮你提前写好了 .claude/ 下的配置文件
Spec-Kit（流程管理层）:
→ 管 AI 写代码前的规划流程
→ Slash Commands: /speckit.constitution → specify → plan → tasks → implement
→ 文档模板: spec-template, plan-template, tasks-template
→ 本质: 把"先想清楚再动手"变成强制流程
4.2 推荐组合方案
方案 A: 纯 Claude Code（极简）
CLAUDE.md (手写) + /plan + TODO
适合: 个人小项目，功能简单
方案 B: Claude Code + oh-my-claudecode（行为规范化）
CLAUDE.md (模板) + Hooks + Slash Commands
适合: 个人中等项目，注重代码质量
方案 C: Claude Code + oh-my-claudecode + Spec-Kit（全流程管控）
Constitution + CLAUDE.md + Hooks + Spec-Kit 命令
适合: 多人项目，复杂功能，需要文档可追溯
方案 D: Claude Code + Spec-Kit（流程规范化）
Constitution + Spec-Kit 命令 + 手写 CLAUDE.md
适合: 新项目从零开始，功能和团队都有一定规模
4.3 具体怎么叠加
以"用户积分系统"为例，展示三个框架如何在同一项目中配合：
项目目录（叠加后的完整状态）:
my-ecommerce/
├── CLAUDE.md ← oh-my-claudecode 模板 + Constitution 关键原则
├── .claude/
│ ├── hooks.json ← oh-my-claudecode（自动格式化 + 拦截危险命令）
│ ├── settings.json ← 项目设置（可选）
│ └── commands/
│ ├── review.md ← oh-my-claudecode
│ ├── test.md ← oh-my-claudecode
│ ├── clean.md ← oh-my-claudecode
│ ├── git-commit.md ← oh-my-claudecode
│ ├── speckit.constitution.md ← Spec-Kit
│ ├── speckit.specify.md ← Spec-Kit
│ ├── speckit.plan.md ← Spec-Kit
│ ├── speckit.tasks.md ← Spec-Kit
│ ├── speckit.implement.md ← Spec-Kit
│ ├── speckit.clarify.md ← Spec-Kit
│ ├── speckit.analyze.md ← Spec-Kit
│ └── speckit.checklist.md ← Spec-Kit
├── .specify/ ← Spec-Kit
│ ├── memory/
│ │ └── constitution.md
│ └── templates/
│ ├── spec-template.md
│ ├── plan-template.md
│ ├── tasks-template.md
│ └── checklist-template.md
└── specs/ ← Spec-Kit
└── 001-user-points/
├── spec.md
├── plan.md
└── tasks.md
它们怎么协作：
开发一个功能的完整时序:
1. /speckit.specify
→ 生成 specs/001-user-points/spec.md
→ 你审阅修改
2. /speckit.clarify
→ AI 提问题，你回答
→ spec.md 被更新
3. /speckit.plan
→ 基于 spec.md + constitution.md 生成 plan.md
→ 你审阅修改
4. /speckit.tasks
→ 基于 plan.md 生成 tasks.md
→ 你审阅修改
5. /speckit.analyze
→ 检查 spec/plan/tasks/constitution 一致性
→ 如有问题 → 回到对应步骤修复
6. /speckit.implement
→ 逐 Task 执行
→ 每写一个文件 → hooks.json 触发 ruff format ✅
→ 每完成一个 Task → hooks.json 触发 pytest ✅
→ 危险命令被拦截 → hooks.json PreToolUse ✅
功能开发中遇到代码质量问题:
/review → oh-my-claudecode 的审查命令
/clean → 自动格式化 + 清理 import
/test → 运行相关测试
功能完成后:
/git-commit → 自动生成规范的 commit message
第五部分：完整实战——用 Spec-Kit 从零做一个功能
以"用户积分系统"为例，展示 Spec-Kit 完整流程。
Step 1: 初始化 Spec-Kit
cd ~/projects/my-ecommerce
specify init . --ai claude
# 输出: Spec-Kit initialized. 8 commands added to .claude/commands/
Step 2: 写 Constitution（一次性）
/speckit.constitution
为这个电商后端项目定义宪法。原则：
1. Python 3.12 + FastAPI + SQLAlchemy 2.0 + PostgreSQL
2. 所有 API 有 Pydantic 校验，所有 DB 操作有类型标注
3. 测试覆盖率 > 80%，关键业务路径 > 90%
4. "简单"优先——能用标准库解决的不引入第三方库
5. 敏感信息（密码、Token）不得硬编码或出现在日志中
6. Git 提交前必须通过 ruff check + pytest
Step 3: 写 Spec
/speckit.specify
功能: 用户积分系统
用户场景:
1. 用户下单支付成功后自动获得积分（消费金额 × 10）
2. 用户下单时可用积分抵扣（100 积分 = 1 元）
3. 积分有效期 1 年，过期自动作废
4. 支持部分使用——有多少扣多少，不足的现金补
业务规则:
- 积分获取: 实付金额 × 10，向上取整
- 积分抵扣: 100 积分 = 1 元，最多抵扣订单金额的 50%
- 积分有效期: 获取后 365 天
- 退款: 退回已使用积分，但过期时间不变（不续期）
约束:
- 不新建数据库，用现有的 PostgreSQL
- 不改动现有订单模块的 API 接口格式
- 积分过期用定时任务（不要引入 Celery，用轻量方案）
Step 4: 审阅 Spec
打开 specs/001-user-points/spec.md，重点检查：
□ 积分抵扣上限 50%——合理吗？如果用户想全用积分支付呢？
→ 你决定: v1 先做 50% 上限，防止恶意使用，v2 再放开
□ "消费金额 × 10"——这个比例会不会变？要不要做成可配置的？
→ 你决定: 做成环境变量，方便运营调整
□ 定时任务用什么？不用 Celery 那用什么？
→ 你决定: 用 APScheduler，轻量够用
Step 5: 澄清模糊点
/speckit.clarify
🤖: 3 个需要澄清的问题:
Q1: 积分获取时机——是"支付成功"还是"订单完成（确认收货）"？
前者积分到账快但退款要扣回，后者积分安全但延迟。
Q2: 多笔积分有不同过期时间，消费时扣哪笔？
FIFO（先过期先扣）还是 LIFO（后过期先扣）？
Q3: 积分余额显示——只显示可用余额，还是要显示"即将过期"的积分？
👤: Q1: 支付成功即给积分（简单），退款时扣回
Q2: FIFO——先过期的先扣，对用户最友好
Q3: 显示可用余额 + "未来 30 天内将过期: XXX 积分"
Step 6: 生成技术方案
/speckit.plan
AI 生成的 specs/001-user-points/plan.md 核心内容：
## 数据模型
### points_accounts（积分账户表）
```sql
CREATE TABLE points_accounts (
id SERIAL PRIMARY KEY,
user_id INT UNIQUE NOT NULL REFERENCES users(id),
balance INT NOT NULL DEFAULT 0, -- 当前可用积分
total_earned INT NOT NULL DEFAULT 0, -- 历史累计获取
total_spent INT NOT NULL DEFAULT 0, -- 历史累计消费
updated_at TIMESTAMP DEFAULT NOW()
);
```
### points_transactions（积分流水表）
```sql
CREATE TABLE points_transactions (
id SERIAL PRIMARY KEY,
user_id INT NOT NULL REFERENCES users(id),
amount INT NOT NULL, -- 正数=获取，负数=消费
type VARCHAR(20) NOT NULL, -- earn/spend/expire/refund
ref_id VARCHAR(100), -- 关联订单号
expires_at DATE, -- 过期日期（仅 earn 类型）
created_at TIMESTAMP DEFAULT NOW()
);
```
### points_batches（积分批次表——用于 FIFO 扣减）
```sql
CREATE TABLE points_batches (
id SERIAL PRIMARY KEY,
user_id INT NOT NULL REFERENCES users(id),
amount INT NOT NULL, -- 批次初始积分
remaining INT NOT NULL, -- 批次剩余积分
expires_at DATE NOT NULL, -- 过期日期
ref_id VARCHAR(100), -- 关联订单号
created_at TIMESTAMP DEFAULT NOW()
);
```
## 关键设计决策
1. **FIFO 扣减用 batches 表而非 transactions 推导**
原因: 推导方式每次消费都要查询所有未过期流水，性能差。batches 表直接记录剩余量。
2. **积分过期用 APScheduler + cron**
原因: 轻量，不需要额外进程。每天凌晨 3 点跑一次，逐 batch 检查并过期。
3. **积分抵扣不放在订单创建事务中**
原因: 积分扣减和订单创建是两个独立的业务操作。先创建订单（状态=PENDING），
支付时再扣积分。如果支付失败，积分自动回滚。
Step 7: 拆解任务
/speckit.tasks
生成的 tasks.md：
## Phase 1: 数据层
- [ ] T001 [P] 创建 points_accounts 表 + 迁移脚本
- [ ] T002 [P] 创建 points_transactions 表 + 迁移脚本
- [ ] T003 [P] 创建 points_batches 表 + 迁移脚本
- [ ] T004 数据库 Session 依赖注入（复用现有 pattern）
## Phase 2: 核心服务（依赖 Phase 1）
- [ ] T005 award_points(user_id, order_amount) → AwardResult
- [ ] T006 spend_points(user_id, amount) → SpendResult（FIFO 扣减）
- [ ] T007 expire_points() → 定时任务（APScheduler）
- [ ] T008 refund_points(order_id) → 退款回退积分
## Phase 3: API（依赖 Phase 2）
- [ ] T009 GET /api/points/balance
- [ ] T010 GET /api/points/history?page=&size=
- [ ] T011 修改 POST /api/orders —— 集成积分抵扣字段
## Phase 4: 测试（依赖 Phase 3）
- [ ] T012 积分获取单测（正常、边界、异常）
- [ ] T013 积分消费单测（FIFO、部分使用、余额不足、过期批次跳过）
- [ ] T014 积分过期单测
- [ ] T015 退款回退单测
- [ ] T016 积分抵扣集成测试（下单→支付→积分扣减→退款→积分回退）
Step 8: 一致性检查
/speckit.analyze
输出示例：
✅ 需求覆盖: 7/7 FR 在 tasks.md 中有对应 Task
✅ 架构一致: plan.md 的 4 个组件对应 tasks.md 的 Phase 1-3
✅ 宪法合规: 使用 PostgreSQL（符合），Pydantic 校验（符合），无硬编码（符合）
⚠️ 发现: NFR-003 "积分过期处理延迟 < 1 小时" 在 plan.md 的 APScheduler 方案中没有明确说明延迟保障。建议补充。
Step 9: 逐步实现
/speckit.implement
AI 开始逐 Task 执行：
🔄 Phase 1: 数据层
T001: 创建 points_accounts 表 + 迁移脚本 ... ✅
T002: 创建 points_transactions 表 + 迁移脚本 ... ✅
T003: 创建 points_batches 表 + 迁移脚本 ... ✅
T004: 数据库 Session 依赖注入 ... ✅
🔄 Phase 2: 核心服务
T005: award_points(user_id, order_amount) ... ✅
→ [审阅] 👤: award_points 里加上事务，防止重复获取
→ [修改] 🤖: 已加 SELECT ... FOR UPDATE + 唯一约束
T006: spend_points(user_id, amount) ... ✅
→ [审阅] 👤: FIFO 逻辑确认——先过期先扣，批次不足跳过 ✅
第六部分：常见困惑解答
Q1: Spec-Kit 的 /speckit.plan 和 Claude Code 的 /plan 到底有什么区别？
/speckit.plan:
→ 读 spec.md → 按 plan-template.md 格式 → 写 plan.md 文件
→ 产物持久化，可版本控制，可被 analyze 命令检查
/plan (Claude Code Plan Mode):
→ 读你的自然语言描述 → 在对话中提出方案 → 等你确认
→ 产物在对话里，/compact 后可能丢失
当你需要"文档留下来给以后的自己（或同事）看" → 用 /speckit.plan
当你在快速探索，方案不需要持久化 → 用 /plan
Q2: Constitution 和 CLAUDE.md 有什么区别？写两遍不冗余吗？
定位不同：
- CLAUDE.md：告诉 AI “怎么在这个项目里写代码”（技术栈、命名、目录结构、禁忌）
- Constitution：告诉所有人（AI + 人）“这个项目的原则是什么”（质量标准、决策框架、不可妥协的底线）
实际做法：
CLAUDE.md 的"规则"章节 ≈ Constitution 的技术原则（保持同步）
但 CLAUDE.md 偏操作（目录结构、文件命名），Constitution 偏原则（简单优先、测试覆盖要求）
如果你不用 Spec-Kit，Constitution 的内容可以写在 CLAUDE.md 里。如果你用 Spec-Kit，建议分开——Constitution 是 analyze 命令的检查标准。
Q3: Skill 和 Slash Command 有什么区别？
Slash Command（.claude/commands/review.md）:
→ 你输入 /review → AI 按 review.md 的指令执行
→ 本质: 一段固定的 Prompt 模板
→ 适合: 单一任务，每次执行差不多
Skill（.claude/skills/xxx/SKILL.md）:
→ 更复杂的能力模块，可以包含多个步骤、条件分支
→ 本质: 一个"能力包"，AI 自动判断何时使用
→ 适合: 复杂的多步骤工作流
简单理解：Slash Command = 快捷方式，Skill = 专项技能。
oh-my-claudecode 和 Spec-Kit 提供的都是 Slash Commands（放在 .claude/commands/ 下），不是 Skills。但 v0.4.5+ 的 Spec-Kit 也开始支持 Skill 格式。
Q4: 我已经有 oh-my-claudecode 了，还需要 Spec-Kit 吗？
看你项目的复杂度：
个人小项目（< 5 个功能模块）:
oh-my-claudecode 够用了
→ CLAUDE.md + Hooks + /review + /test 覆盖日常需求
中等项目（5-15 个功能模块）:
可以只加 Spec-Kit 的 /speckit.specify + /speckit.tasks
→ 不一定要走全流程，但需求和任务文档化对你有好处
大项目（15+ 功能模块，或有其他人参与）:
建议全流程
→ constitution → specify → clarify → plan → tasks → analyze → implement
→ 文档可追溯，减少沟通成本
Q5: 国产模型（DeepSeek 等）用 Spec-Kit 有什么注意事项？
1. /speckit.specify 时给的上下文要充分
→ 国产模型对省略的细节倾向于"猜"而非"问"
→ 把你的约束写详细，不要期望 AI 追问
2. /speckit.clarify 要主动触发
→ Claude Opus 可能会主动提出模糊点
→ 国产模型更容易"假设一个答案继续往下"
→ 你 review spec.md 时主动找模糊点，然后手动追问
3. 长 Spec 文档会被遗忘
→ spec.md 超过 ~200 行后，国产模型可能忽略后半部分
→ 应对: 把 spec 拆成多个小文件（spec.md + business-rules.md）
4. /speckit.analyze 的一致性检查可能不全面
→ 国产模型在跨文档对比时可能漏掉细节
→ 应对: 你自己过一遍 checklist，不要完全依赖 AI
概念速查：一页纸搞定
┌──────────────────────────────────────────────────────────┐
│ 你做决策的流程图 │
├──────────────────────────────────────────────────────────┤
│ │
│ 接到一个功能需求 │
│ │ │
│ ├── 改 1-3 个文件？ │
│ │ └── 直接在 Claude Code 里说，不规划 │
│ │ │
│ ├── 改 3-10 个文件？ │
│ │ └── Claude Code /plan → 逐步实现 │
│ │ │
│ └── 改 10+ 个文件？或团队协作？ │
│ └── 上 Spec-Kit: │
│ /speckit.specify → clarify → plan │
│ → tasks → analyze → implement │
│ │
│ 日常代码质量保障: │
│ oh-my-claudecode Hooks（自动格式化 + 拦截） │
│ /review（代码审查） │
│ /test（运行测试） │
│ │
│ 概念记忆: │
│ CLAUDE.md = 项目手册（AI 每次启动读） │
│ Hooks = CI 流水线（事件触发自动化） │
│ Constitution = 宪法（最高原则） │
│ Spec = PRD（做什么） │
│ Plan = 架构文档（怎么做） │
│ Tasks = Sprint Backlog（分几步） │
│ Slash Cmd = 快捷方式（一键触发） │
│ Skill = 专项技能（AI 自动调用） │
│ │
└──────────────────────────────────────────────────────────┘
总结
这篇文章的核心交付：
-
理清概念地图：CLAUDE.md、Hooks、Slash Command、Skill、Constitution、Spec、Plan、Tasks——各自是什么、在哪个层次、谁提供的。
-
Spec-Kit 完整方法论：Constitution → Specify → Clarify → Plan → Tasks → Analyze → Implement 七步流程，每一步做什么、产出什么、你怎么审阅。
-
三个框架的分工协作：
- Claude Code = 底座（Agent 能力）
- oh-my-claudecode = 行为增强（代码质量自动化）
- Spec-Kit = 流程管理（需求→设计→任务→实现）
-
什么时候用什么：小功能直接写、中等功能用 /plan、大功能上 Spec-Kit 全流程。
-
国产模型适配要点：上下文要充分、clarify 要主动、长文档要拆分、一致性检查要自己过一遍。
延伸阅读
- AI Coding 最佳实践（第 11 篇） —— CLAUDE.md/Memory/Skills 设计
- GitHub Spec-Kit 官方仓库
更多推荐
4
0- 0
已为社区贡献15条内容
所有评论(0)