AI编程 on 丸子有记, 记录生活、分享技术，专注于运维架构、运维开发(devops)。

Openspec进行存量项目开发

wzdushu@gmail.com (wanzi) — Mon, 30 Mar 2026 22:10:42 +0800

最近在使用opencode配合openspec对已有项目，进行二次开发，遇到一些坑记录一下：

一、初始化项目:

首先，在项目根目录运行CLI 命令来创建 OpenSpec 所需的基础目录结构。

# openspec init 
Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0
Detected tool directories: OpenCode (pre-selected for first-time setup)
✔ Select tools to set up (24 available) OpenCode
▌ OpenSpec structure created
✔ Setup complete for OpenCode

OpenSpec Setup Complete

Created: OpenCode
4 skills and 4 commands in .opencode/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Learn more: https://github.com/Fission-AI/OpenSpec
Feedback:   https://github.com/Fission-AI/OpenSpec/issues

Restart your IDE for slash commands to take effect.

另外，为了更深入理解openspec，建议把所有openspec的扩展功能都开启了，后续opencode或者claude code里直接使用，修改完需要重启opencode或者claude code：

# openspec config profile

Current profile settings
  Delivery: both
  Workflows: 11 selected (custom)
  Delivery = where workflows are installed (skills, commands, or both)
  Workflows = which actions are available (propose, explore, apply, etc.)

✔ What do you want to configure? Delivery and workflows
✔ Delivery mode (how workflows are installed): Both (skills + commands) [current]
? Select workflows to make available:
❯[x] Propose change
 [x] Explore ideas
 [x] New change
 [x] Continue change
 [x] Apply tasks
 [x] Fast-forward
 [x] Sync specs
 [x] Archive change
 [x] Bulk archive
 [x] Verify change
 [x] Onboard

Create proposal, design, and tasks from a request
Space to toggle, Enter to confirm

二、使用 explore 分析现有代码

这是最关键的一步，你需要使用 /opsx:explore 命令来引导 AI 分析你的代码库，并生成初始规范。

操作方法：在 AI 对话框中输入：

/opsx:explore 分析当前项目的架构和核心业务逻辑，并生成相应的规范文档

作用： AI 会扫描你的代码文件，理解现有的技术栈、目录结构和功能模块，然后尝试为你生成一份初始的 proposal.md 或 specs 文档，作为后续开发的基线。

三、补全配置

我们都知道openspec的核心思想是“先立规矩，再动手”，通过规范驱动开发（Spec-Driven Development, SDD）来解决 AI 在大型项目中容易出现的“上下文丢失”和“代码混乱”问题。

因此，为了让 AI 更精准地理解你的项目，你可以手动编辑openspec“宪法”文件 openspec/config.yaml

内容：添加你的技术栈（如 React, Python, Go）、编码约定、领域知识等。这能帮助 AI 在后续生成代码时更符合你的项目风格。

我这里直接在opencode里让agent直接输出了：

添加本项目的技术栈、编码约定、领域知识等到openspec/config.yaml 文件，方便后续openspec更精准地理解项目

四、开始增量开发

完成上述步骤后，就可以按照标准的 OpenSpec 流程进行开发了：

1.创建变更：使用 /opsx:ff <功能名>（快速模式）或 /opsx:new <功能名>（完整模式）开始一个新功能的开发。

2.定义增量规范：在生成的 specs/ 文件中描述本次变更（新增/修改/删除）。

3.执行与归档：使用 /opsx:apply 生成代码，验证无误后使用 /opsx:archive 归档。归档时，增量规范会自动合并到主规范中。再次为之前提供的不准确信息表示歉意，希望这次的流程能帮助你顺利接入 OpenSpec。

举例: 这里给自己的技术工具箱，新增一个文本翻译工具：

/opsx:new 增加一个文本翻译工具，背后调用大模型，默认使用minimax API接口参考这里https://platform.minimaxi.com/docs/guides/text-generation，也支持调用glm的模型，API接口参考https://docs.bigmodel.cn/cn/guide/develop/claude/introduction；翻译功能类似https://fanyi.baidu.com/mtpe-individual/transText#/

最终项目目录结构如下:

openspec
├── changes
│   └── archive
│       └── 2026-03-30-add-text-translator
├── config.yaml
└── specs
    └── text-translator
        └── spec.md

五、功能跑不通怎么办？

如果你是在 AI 生成代码后进行验证，发现代码跑不通或不符合预期，验证失败 (/opsx:verify)

不要直接修改代码：在 OpenSpec 的工作流中，代码是规范的产物。如果代码错了，通常是因为“规范”写得不够清楚，或者 AI 理解错了。
正确的修复步骤：

1. 修改规范 (spec.md)：

打开 openspec/changes/新功能1/specs/…/spec.md，把你的修正意见写进去。

例如：在场景描述中增加“必须处理网络超时的情况”。

2. 重新应用 (/opsx:apply)：

告诉 AI：“我已经更新了规范，请重新运行 /opsx:apply”。AI 会根据新的规范重新生成代码，覆盖之前的错误代码。

3. 再次验证：

再次运行 /opsx:verify 确认问题已解决。

六、修改代码后如何确保与spec.md同步？

在 OpenSpec 的工作流中，代码是规范的产物。如果你手动修改了代码，但 spec.md 没有同步，就会导致“文档与代码脱节”，下次 AI 再根据 spec.md 生成代码时，你的手动修改就会被覆盖或产生冲突。

为了确保两者同步，请根据你修改代码的时机和原因，选择以下三种策略之一：

1. 最佳策略：先改文档，再生成代码 (Spec-First)

这是 OpenSpec 最推荐的方式。如果你发现代码有问题（比如逻辑不对、参数错误），不要直接去改代码文件。

操作步骤： 1.1 打开 openspec/changes/…/spec.md。 1.2 修改对应的需求描述或场景（Scenario）。 1.3 运行 /opsx:apply。 1.4 结果：AI 会根据新的文档重新生成代码，自动覆盖旧的实现。这是保持同步最彻底的方法。

2. 补救策略：代码已改，反向同步文档 (Reverse Sync)

如果你习惯先快速修改代码（比如修个 Bug 或微调样式），改完后必须立刻把变更“回填”到文档中。

操作步骤：
1. 保存代码：确保你的代码修改已保存。
2. 运行验证：在 AI 对话框中输入 /opsx:verify。
  - AI 会对比你的新代码和旧 spec.md。
  - 它会发现不一致（例如：“代码中 Redis 过期时间是 600 秒，但文档写的是 300 秒”）。
3. 接受建议：让 AI 根据代码更新 spec.md。
4. 结果：文档被更新以匹配你的代码，两者重新达成一致。

3. 归档时的强制同步 (/opsx:archive)

当你完成功能开发准备归档时，OpenSpec 会强制检查同步状态。

机制：
- 当你运行 /opsx:archive 时，OpenSpec 会将当前变更目录下的 spec.md 合并到项目的全局规范库（openspec/specs/）中。
- 注意：如果你手动改了代码但没更新 spec.md，归档后，你的代码逻辑将永远无法在文档中体现。下次有人（或 AI）查看归档文档时，看到的将是过时的逻辑。

七、归档后发现spec.md文档落后于代码

要避免这种情况，你需要建立一套“防御性”的工作习惯。

1. 养成“Verify -> Archive”的肌肉记忆

这是最直接、最有效的日常习惯。永远不要把 /opsx:archive 当作开发结束后的唯一动作。

错误习惯：改代码 -> 测试通过 -> /opsx:archive
正确习惯：改代码 -> /opsx:verify -> (若有差异则同步) -> 测试通过 -> /opsx:archive

具体操作：在你手动修改代码后，归档前，必须运行 /opsx:verify（或者在 AI 对话框中让 AI 检查）。

告诉 AI：“我手动修改了 xxx.ts，请对比 spec.md，如果有不一致，请帮我更新 spec.md。”
只有当 AI 确认“代码与规范一致”后，再执行归档。

2. 利用 Git 钩子（Pre-commit Hook）强制检查

如果你担心自己偶尔会忘记，可以利用 Git 的机制进行强制拦截。这是团队协作中推荐的做法。

你可以在项目的 .git/hooks/pre-commit 文件中加入检查逻辑。虽然 OpenSpec 没有直接提供这个钩子，但你可以写一个简单的脚本：

脚本逻辑思路：

检测是否有代码文件（如 .ts, .java, .py）被修改。
检测对应的 openspec/changes/ 下的文档是否也被修改。
如果代码变了但文档没变 -> 拦截提交，并提示：“检测到代码变更但 Spec 文档未更新，请先运行 verify 或更新文档！”

#!/bin/sh
# .git/hooks/pre-commit

# 检查暂存区是否有代码变更
CODE_CHANGES=$(git diff --cached --name-only | grep -E "\.(ts|js|java|py)$" | wc -l)
# 检查暂存区是否有 Spec 变更
SPEC_CHANGES=$(git diff --cached --name-only | grep "openspec/" | wc -l)

if [ "$CODE_CHANGES" -gt 0 ] && [ "$SPEC_CHANGES" -eq 0 ]; then
  echo "⚠️  警告：检测到代码变更，但未发现 OpenSpec 文档变更！"
  echo "⚠️  请确保你的代码逻辑已同步到 spec.md，或运行 /opsx:verify。"
  echo "如果想强制提交，请使用 --no-verify (不推荐)"
  exit 1
fi

exit 0

另外，对于现代项目，建议使用专门的工具来管理钩子，这样可以将配置写入代码库，全员共享。

Python 项目 / 通用：使用 pre-commit 框架。
- 配置 .pre-commit-config.yaml，定义检查规则（如 flake8, black, detect-secrets）。
- 运行 pre-commit install 即可自动配置钩子。
前端/Node 项目：使用 Husky。
- 它可以轻松在 package.json 中定义钩子逻辑，无需手动处理 shell 脚本权限。
Golang和Rust 项目:
- 使用lefthook：https://github.com/evilmartians/lefthook ，通用工具，go开发并行执行，速度飞快

lefthook.yml通用配置模版:

# Lefthook 配置文件
# 支持多语言混合项目 (Polyglot/Monorepo)

# 全局设置
min_version: 1.4.0

# pre-commit 钩子：在 git commit 时触发
pre-commit:
  parallel: true # 核心优化：并行执行所有检查，极大提升速度
  commands:
    
    # ==========================================
    # 1. 前端 (JavaScript / TypeScript)
    # ==========================================
    frontend-lint:
      glob: "*.{js,ts,jsx,tsx,vue}"
      run: npx eslint {staged_files} --fix
      # 注意：如果项目没有 package.json，Lefthook 会自动跳过或报错，视配置而定

    frontend-format:
      glob: "*.{js,ts,jsx,tsx,vue,css,scss,json}"
      run: npx prettier --write {staged_files}

    # ==========================================
    # 2. Go (Golang)
    # ==========================================
    go-fmt:
      glob: "*.go"
      # gofmt -w 会直接修改文件，确保暂存区更新
      run: gofmt -w {staged_files}
    
    go-lint:
      glob: "*.go"
      # 假设你安装了 golangci-lint，这是 Go 社区标准 lint 工具
      run: golangci-lint run {staged_files}

    # ==========================================
    # 3. Rust
    # ==========================================
    rust-fmt:
      glob: "*.rs"
      run: cargo fmt -- {staged_files}

    rust-check:
      glob: "*.rs"
      # 使用 clippy 进行深度检查
      run: cargo clippy -- -D warnings

    # ==========================================
    # 4. Python
    # ==========================================
    python-lint:
      glob: "*.py"
      # 这里以 flake8 为例，也可以换成 black --check 或 pylint
      run: flake8 {staged_files}

    python-format:
      glob: "*.py"
      # 如果使用 black 格式化
      run: black {staged_files}

    # ==========================================
    # 5. Java / Kotlin
    # ==========================================
    # Java 通常依赖构建工具 (Maven/Gradle) 或特定的 linter (如 checkstyle)
    # 这里演示调用 Gradle 的检查任务，它会自动处理所有 Java 文件
    java-check:
      glob: "*.java"
      # 注意：Gradle 任务通常比较慢，且不支持只检查部分文件，
      # 建议只在 pre-push 中运行全量检查，或者使用 spotless 等支持增量检查的插件
      run: ./gradlew checkstyleMain checkstyleTest --quiet

    # ==========================================

3. 事后补救

创建一个新的变更：命名为 sync-logic-with-code 或 fix-docs-consistency。
让 AI 逆向工程：在这个新变更中，告诉 AI：“当前的 xxx 功能代码逻辑已经变更，但 spec.md 还是旧的。请以当前代码为准，重写/更新 spec.md。”
归档这个“文档修复”：运行 /opsx:apply（此时 AI 会生成更新后的文档）和 /opsx:archive。

结果：你的主规范库（openspec/specs/）会被这次新的归档更新，重新与代码保持一致。虽然历史归档里留下了“文档落后”的痕迹，但最新的主规范是准确的。

写在最后，在用OpenSpec开发项目过程中，一定要谨记OpenSpec核心原则：

文档（Spec）是源头，代码是结果。遇到问题，先修文档，再让 AI 重写代码。

选择SDD工具：OpenSpec 还是 Spec-Kit

wzdushu@gmail.com (wanzi) — Fri, 27 Feb 2026 10:30:00 +0800

在前文《什么是SDD》中我们了解了规范驱动开发的重要性，本文将深入对比两款主流SDD工具——OpenSpec和Spec-Kit，帮助开发者根据自身需求做出选择。

OpenSpec与Spec-Kit概览

OpenSpec简介

OpenSpec 是由Fission AI开发的规格驱动开发(SDD)框架，专门为AI编程助手打造。

项目地址：https://github.com/Fission-AI/OpenSpec

核心特点：

轻量级规格层，让人类和AI在写代码前对齐
每个变更有独立文件夹，包含提案、规格、设计和任务
支持20+种AI助手通过斜杠命令集成
灵活迭代，无刚性阶段门控
完整的变更生命周期管理

Spec-Kit简介

Spec-Kit 是由GitHub开发的规格驱动开发开源工具包。

项目地址：https://github.com/github/spec-kit

核心特点：

将规格文档变为可执行规范，直接生成可工作代码
支持多种AI代理：Claude Code、Copilot、Gemini CLI、Codex、Cursor、Windsurf等
完整的工作流程：Constitution → Specify → Plan → Tasks → Implement
丰富的扩展生态：Jira集成、Azure DevOps集成、代码审查等
支持Greenfield和Brownfield项目

安装与配置

OpenSpec安装

前置要求：Node.js 20.19.0或更高版本

# npm安装
npm install -g @fission-ai/openspec@latest

# 也支持pnpm、yarn、bun和nix
pnpm add -g @fission-ai/openspec

初始化项目

# 在项目目录初始化
openspec init

# 选择工作流配置
openspec config profile

# 刷新AI指导
openspec update

禁用遥测（可选）

1
2
3

export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1

Spec-Kit安装

前置要求：Python环境（推荐使用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 <PROJECT_NAME>

# 升级
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

初始化项目

# 创建新项目
specify init <PROJECT_NAME>

# 在现有项目中初始化
specify init . --ai claude

# 指定AI代理初始化
specify init --here --ai claude

# 检查环境
specify check

核心功能对比

基础功能

功能	OpenSpec	Spec-Kit
实现语言	Node.js	Python
CLI工具	openspec	specify
AI代理支持	20+种	10+种
变更结构	提案+规格+设计+任务	Constitution+Specify+Plan+Tasks
状态管理	完整生命周期	阶段式流程
扩展生态	基础	丰富（Jira、Azure DevOps等）
并行执行	基础支持	工作包模式

OpenSpec斜杠命令

命令	功能
`/opsx:propose "想法"`	创建新提案
`/opsx:new`	创建新变更
`/opsx:continue`	继续变更
`/opsx:apply`	执行任务
`/opsx:ff`	快进完成
`/opsx:verify`	验证变更
`/opsx:sync`	同步状态
`/opsx:archive`	归档已完成变更
`/opsx:bulk-archive`	批量归档
`/opsx:onboard`	新成员入门

Spec-Kit斜杠命令

命令	功能
`/speckit.constitution`	建立项目治理原则
`/speckit.specify`	定义功能需求
`/speckit.plan`	技术规划
`/speckit.tasks`	分解任务
`/speckit.implement`	执行实现
`/speckit.clarify`	澄清模糊需求
`/speckit.analyze`	一致性分析
`/speckit.checklist`	质量检查

工作流程对比

OpenSpec工作流

OpenSpec以变更为核心，每个变更有独立的文件夹结构：

变更文件夹结构：
├── proposal.md      # 提案描述
├── spec.md          # 规格说明
├── design.md        # 技术设计
├── tasks.md         # 任务清单
└── artifacts/       # 产出物

开发循环

1. 提出想法
   /opsx:propose "添加用户认证功能"

2. 创建变更
   /opsx:new
   # 创建变更文件夹

3. 编写规格
   编辑 spec.md

4. 技术设计
   编辑 design.md

5. 执行任务
   /opsx:apply

6. 验证完成
   /opsx:verify

7. 归档
   /opsx:archive

Spec-Kit工作流

Spec-Kit采用阶段式流程，强调规范文档的可执行性：

工作流程：
Constitution → Specify → Plan → Tasks → Implement

开发循环

1. 初始化项目
   specify init . --ai claude

2. 建立原则
   /speckit.constitution
   # 定义项目治理规范

3. 定义规格
   /speckit.specify
   # 描述要构建的功能

4. 制定计划
   /speckit.plan
   # 提供技术栈和架构

5. 分解任务
   /speckit.tasks
   # 生成可执行任务列表

6. 执行实现
   /speckit.implement
   # 按计划实现功能

AI代理支持对比

OpenSpec支持

Claude Code ✅
GitHub Copilot ✅
Gemini CLI ✅
以及20+种其他AI助手

Spec-Kit支持

AI代理	支持	备注
Claude Code	✅
GitHub Copilot	✅
Gemini CLI	✅
Codex CLI	✅	需 `--ai-skills` 参数
Cursor	✅
Windsurf	✅
Qoder CLI	✅
Kilo Code	✅
Generic	✅	需指定 `--ai-commands-dir`

Spec-Kit扩展生态

Spec-Kit拥有丰富的扩展和预设：

扩展（Extensions）

扩展	功能
AI-Driven Engineering (AIDE)	7步结构化工作流
Jira Integration	与Jira同步任务
Azure DevOps Integration	与Azure DevOps同步
Review Extension	代码审查
Verify Extension	规格验证
Spec Sync	检测规格与实现偏差

预设（Presets）

预设	功能
AIDE In-Place Migration	技术迁移预设
Pirate Speak	海盗风格输出

适用场景对比

选择OpenSpec的场景

需要完整变更追踪的项目
重视提案→规格→设计→任务流程的团队
多AI工具混合使用的环境
喜欢灵活迭代而非严格阶段的项目
需要频繁变更审查的团队

选择Spec-Kit的场景

企业环境，需要Jira/Azure DevOps集成
需要代码审查和质量门控
重视规格文档可执行性的团队
需要技术迁移支持的场景
使用Claude Code、Copilot等主流AI代理

总结对比

┌─────────────────────────────────────────────────────────┐
│                      SDD工具对比                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   OpenSpec                │         Spec-Kit             │
│   ─────────               │         ─────────             │
│   • Node.js实现          │         • Python实现          │
│   • 变更驱动             │         • 规格可执行          │
│   • 20+ AI助手支持       │         • 10+ AI助手支持      │
│   • 灵活迭代             │         • 阶段式流程           │
│   • 完整变更生命周期     │         • 丰富扩展生态         │
│                          │         • 企业集成支持         │
│                                                         │
│   适合:                    │         适合:                  │
│   • 变更追踪重要          │         • 企业环境              │
│   • 灵活迭代流程          │         • 质量门控              │
│   • 多AI工具混用          │         • 规格验证              │
│                                                         │
└─────────────────────────────────────────────────────────┘

最终建议

选择OpenSpec如果：

需要完整的提案→规格→设计→任务流程
重视变更的历史追踪和审查
喜欢灵活迭代的工作方式
使用多种AI编程工具

选择Spec-Kit如果：

需要与企业工具（Jira、Azure DevOps）集成
重视代码审查和质量验证
需要规格与实现一致性检查
使用Claude Code、Copilot等主流AI代理

可以结合使用：两个工具可以互补——使用OpenSpec进行快速变更探索，使用Spec-Kit进行企业级规范管理。

什么是SDD？为什么AI编程工具里需要用到它

wzdushu@gmail.com (wanzi) — Wed, 25 Feb 2026 10:30:00 +0800

在AI编程工具日益普及的今天，一个重要的概念正在改变我们与AI协作编写代码的方式——SDD（Specification-Driven Development，规范驱动开发）。本文将深入解析SDD的核心理念，以及为什么主流AI编程工具都选择支持SDD模式。

什么是SDD

SDD的定义

Specification-Driven Development（规范驱动开发） 是一种软件开发方法论，它强调在编写代码之前先编写清晰、精确的规范说明，然后严格按照规范来实现代码。

核心原则：

规范先行：代码实现之前必须先编写Spec
精确描述：用形式化或半形式化的语言描述需求
双向追踪：规范与代码保持一致，可相互验证
迭代完善：从简单规范开始，逐步细化完善

SDD vs 传统开发模式

维度	传统开发	SDD
起点	需求文档或口头描述	精确编写的Spec文件
灵活性	需求边改边写	规范确认后再实现
验证方式	手动测试为主	规范可作为测试用例
AI协作	AI自由发挥空间大	AI按规范执行
变更处理	需求变更成本高	规范变更驱动代码修改

为什么AI编程需要SDD

AI编程的挑战

1. 上下文理解偏差

AI模型虽然强大，但并非能完全理解人类的模糊描述。传统开发中的需求往往是：

"实现一个用户登录功能，要有基本的验证"

这种模糊描述会导致AI生成代码与预期不符。

2. 生成代码质量不稳定

没有规范约束时，AI可能：

遗漏边界情况处理
忽略安全考量
API设计风格不统一
实现与项目已有代码风格不一致

3. 迭代维护困难

AI生成的代码在没有规范的情况下：

难以判断是否满足需求
修改时不知道影响范围
新人接手难以理解设计意图

SDD如何解决这些问题

规范提供精确意图

# 传统需求描述
"实现一个用户登录功能"

# SDD规范描述
## 功能需求
1. 支持用户名/邮箱 + 密码登录
2. 登录成功后生成JWT token，有效期24小时
3. 密码错误3次后锁定账户15分钟
4. 登录接口需要防暴力破解（限流：同一IP 5分钟内最多10次）

## 接口规范
- POST /api/v1/auth/login
- Request: { "username": string, "password": string }
- Response: { "token": string, "expiresIn": 86400 }

## 错误处理
- 400: 参数校验失败
- 401: 用户名或密码错误
- 423: 账户已被锁定

## 安全要求
- 密码存储使用bcrypt
- 返回的token不包含敏感信息

规范即测试用例

SDD规范可以直接或通过工具转换为：

API的Mock测试
单元测试用例
集成测试场景
验收标准

SDD在AI编程中的价值

1. 减少幻觉（Hallucination）

AI在有明确规范约束时，更容易生成符合预期的代码，而不是"创造"一些不存在的功能。

2. 提高代码一致性

规范定义了统一的：

API设计风格
代码组织结构
命名规范
错误处理模式

3. 便于审查和协作

规范的清晰性使得：

代码审查有据可依
team member可以并行工作
新成员快速理解项目

4. 支持渐进式开发

SDD支持从简单规范开始，逐步扩展：

# v1.0 最小可用版本
## AuthService
- login(username, password): Promise<User>

# v1.1 增加token支持
## AuthService
- login(username, password): Promise<LoginResult>
- logout(token): Promise<void>
- refreshToken(token): Promise<LoginResult>

# v1.2 增加第三方登录
## AuthService
- login(username, password): Promise<LoginResult>
- loginWithOAuth(provider, code): Promise<LoginResult>
- logout(token): Promise<void>
- refreshToken(token): Promise<LoginResult>

SDD的核心组件

1. Spec文件结构

project/
├── SPEC.md              # 主规范文件
├── api/
│   └── openapi.yaml     # API规范
├── models/
│   └── schema.md        # 数据模型规范
└── specs/
    ├── auth.md          # 认证模块规范
    ├── user.md          # 用户模块规范
    └── ...

2. 规范编写原则

FIRRN原则：

Factual（事实性）：描述系统实际行为，不是愿望清单
Independent（独立性）：每个规范模块独立描述一个功能
Readable（可读性）：规范要易于理解和维护
Realistic（可行性）：规范要可实现、可测试
Necessary（必要性）：每个需求都是必要的

3. 规范与代码的对应

## UserService.getUserById

### 描述
根据用户ID获取用户信息

### 输入
- userId: string (必填，用户ID)

### 输出
- User对象或null

### 行为
1. 验证userId格式
2. 从数据库查询用户
3. 返回用户信息（密码字段排除）

### 错误
- InvalidUserIdError: userId格式无效

对应代码：

async getUserById(userId: string): Promise<User | null> {
  // 1. 验证userId格式
  if (!isValidUserId(userId)) {
    throw new InvalidUserIdError(userId);
  }

  // 2. 从数据库查询用户
  const user = await this.db.users.findOne({
    where: { id: userId },
    attributes: { exclude: ['password'] }
  });

  // 3. 返回用户信息
  return user;
}

SDD工作流程

完整开发流程

┌─────────────────────────────────────────────────────────┐
│  1. 需求分析                                             │
│     - 收集业务需求                                        │
│     - 识别关键用例                                        │
│     - 确定约束条件                                        │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  2. 编写Spec（规范）                                      │
│     - 编写SPEC.md                                        │
│     - 定义API接口                                         │
│     - 描述数据模型                                         │
│     - 明确边界条件和错误处理                                │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  3. 评审与确认                                            │
│     - 技术评审                                            │
│     - 业务确认                                            │
│     - 达成共识后锁定规范                                    │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  4. AI生成代码                                            │
│     - 基于Spec生成代码                                     │
│     - 生成单元测试                                         │
│     - 生成API文档                                          │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  5. 验证与迭代                                            │
│     - 代码是否符合Spec                                     │
│     - 测试覆盖是否完整                                      │
│     - 发现问题时更新Spec或修复代码                            │
└─────────────────────────────────────────────────────────┘

Spec评审检查清单

功能描述清晰，无歧义
输入输出明确定义
边界条件已覆盖
错误处理完整
API设计一致
数据模型合理
安全考虑周全
性能要求明确

SDD工具生态

主流SDD工具

工具	特点	适用场景
Spec-Kit	专为AI编程设计，CLI工具	Claude Code集成
OpenSpec	开放标准，社区驱动	跨工具通用
Stopify	简单Markdown格式	轻量级项目
Docusaurus	文档驱动	文档完善项目

Claude Code与SDD

Claude Code天然支持SDD工作流：

# 1. 创建项目并编写规范
mkdir my-project && cd my-project
claude "初始化一个Node.js REST API项目，创建SPEC.md规范文件"

# 2. 基于规范实现
claude "根据SPEC.md实现用户认证模块"

# 3. 验证实现是否符合规范
claude "检查当前实现是否完全符合SPEC.md中的定义"

# 4. 规范更新时同步修改
# 编辑SPEC.md添加新功能
claude "根据更新后的SPEC.md重构相关代码"

SDD最佳实践

规范编写技巧

1. 使用结构化格式

## 功能名称

### 描述
简短描述功能做什么

### 输入
- param1: type (描述)
- param2: type (描述)

### 输出
- type: 描述

### 行为
1. 步骤1
2. 步骤2

### 错误
- ErrorType: 描述

2. 使用具体例子

### 登录成功示例
输入: { "username": "user@example.com", "password": "correct_password" }
输出: { "token": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 86400 }

### 密码错误示例
输入: { "username": "user@example.com", "password": "wrong_password" }
输出: 401 { "error": "INVALID_CREDENTIALS", "message": "用户名或密码错误" }

3. 定义清晰的验收标准

## 验收标准
- [ ] 用户名格式验证正确
- [ ] 密码强度验证正确
- [ ] 登录成功返回有效token
- [ ] 错误次数统计正确
- [ ] 账户锁定功能正常
- [ ] Token过期处理正确

常见陷阱

1. 规范过于详细

# 不好的做法：规定代码实现细节
### 实现
使用for循环遍历数组，在第5行调用helper函数

# 好的做法：只描述行为
### 实现
按指定顺序处理数据项

2. 规范与实现脱节

每次代码更新都同步更新Spec
Spec变更必须经过评审
禁止"代码实现了但Spec没更新"

3. 过度抽象

规范要具体可执行，不是泛泛而谈的架构设计。

总结

SDD的核心价值

明确性：消除模糊需求，减少沟通成本
可验证性：规范可直接转化为测试用例
可维护性：代码和文档始终保持一致
AI友好：为AI提供清晰执行目标

SDD适用场景

场景	SDD适合度	原因
AI辅助编程	非常适合	AI需要明确指令
复杂业务系统	适合	减少需求理解偏差
快速原型	一般	规范可能成为负担
个人小项目	可选	过度设计可能浪费
多人协作项目	非常适合	统一理解和标准

学习建议

从小项目开始：选择一个简单项目练习SDD工作流
使用好用的工具：推荐从Spec-Kit或简单Markdown开始
保持规范更新：规范不是一次性的，需要持续维护
与AI协作：让AI帮你生成规范初稿，你来审核和完善

SDD不是银弹，但它为AI编程提供了一个可靠的框架。随着AI编程工具的不断进化，SDD将成为高效人机协作的重要基础。

Claude Code使用最佳实践

wzdushu@gmail.com (wanzi) — Thu, 05 Feb 2026 10:30:00 +0800

Claude Code是Anthropic公司推出的官方AI编程工具，可以读取代码库、编辑文件、运行命令，并与开发工具集成。它在复杂推理和代码理解方面表现优异，是当前最强大的AI编程工具之一。

Claude Code详细介绍

什么是Claude Code

Claude Code是一个由AI驱动的代理编码助手，可以帮助开发者构建功能、修复错误和自动化开发任务。它理解整个代码库，可以跨多个文件和工具工作以完成任务。

核心优势：

强大的代码理解和推理能力
支持终端、VS Code、JetBrains等多种界面
MCP（Model Context Protocol）扩展支持
多代理协作功能
完整的Git工作流集成
支持Claude全系列模型

Claude Code安装

macOS / Linux（推荐）

`1`	`curl -fsSL https://claude.ai/install.sh \| bash`

Windows PowerShell

`1`	`irm https://claude.ai/install.ps1 \| iex`

Windows CMD

`1`	`curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`

Homebrew

`1`	`brew install --cask claude-code`

WinGet（Windows）

`1`	`winget install Anthropic.ClaudeCode`

VS Code扩展

在VS Code扩展商店搜索"Claude Code"并安装。

快速开始

# 进入项目目录
cd your-project

# 启动Claude Code
claude

# 直接指定任务
claude "帮我创建一个用户登录功能"

Claude Code基础使用

基本使用技巧

1. 任务分解策略

不要一次性让AI完成复杂任务：

# 低效 ❌
claude "帮我写一个完整的电商系统"

# 高效 ✅
claude "帮我设计用户数据表结构"
claude "基于这个结构写用户注册API"
claude "添加登录验证逻辑"

2. 提供完整上下文

# 缺少信息 ❌
claude "这个代码报错"

# 完整信息 ✅
claude "我在用Flask写一个Web服务，登录接口返回500错误。
错误信息：TypeError: Cannot read property 'name' of undefined
堆栈显示发生在app.py第45行。
帮我分析原因并修复。"

3. 使用工具调用

Claude Code可以执行多种操作：

# 读取文件
Read file: src/main.py

# 搜索代码
Grep pattern: "def login" path: src/

# 执行命令
Bash command: python -m pytest

# 写入文件
Write file: src/utils.py

# 批量操作
Glob pattern: "**/*.py"

Claude Code模型选择

Claude Code支持多种Claude模型，可根据任务复杂度选择：

模型	能力	速度	适用场景
Claude Opus 4.6	最高	较慢	复杂架构设计、深度重构
Claude Sonnet 4.6	高	中等	日常开发、代码生成
Claude Haiku 4.5	中等	快	快速补全、简单任务

1
2

# 切换模型
/model claude-sonnet-4-6

Claude Code进阶功能

MCP服务器集成

MCP（Model Context Protocol）可以连接Claude Code到外部工具和数据源：

# 在配置文件中设置MCP服务器
# ~/.claude/config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem"],
      "allowedDirectories": ["~/projects"]
    }
  }
}

CLAUDE.md文件

在项目根目录创建CLAUDE.md文件，Claude Code会在每个会话开始时读取：

# 项目说明

## 代码标准
- 使用TypeScript strict模式
- 遵循Airbnb ESLint配置

## 架构决策
- 使用依赖注入模式
- 所有API调用必须包含错误处理

## 首选库
- 状态管理：Zustand
- HTTP客户端：Ky

自定义命令（Skills）

创建可复用的命令模板：

# 创建 /review-pr 命令
# ~/.claude/commands/review-pr.md
# 审查Pull Request

请审查这个PR：
1. 检查代码质量和风格一致性
2. 查找潜在的安全问题
3. 评估测试覆盖是否充分
4. 验证文档是否更新

@pr-url

Hooks配置

在操作前后自动执行shell命令：

# ~/.claude/config.json
{
  "hooks": {
    "PostEdit": [
      {
        "match": "*.ts",
        "command": "npx eslint --fix {file}"
      }
    ]
  }
}

计划任务

# 按计划运行Claude
claude /schedule

# 自动化早晨PR审查
claude /loop 8h /pr review

# 自动化夜间CI失败分析
claude /schedule "0 22 * * *" "分析今天的CI失败"

多代理协作

# 启动多个代理并行工作
claude "启动一个团队来处理这个功能：
- 代理1：前端组件开发
- 代理2：后端API开发
- 代理3：测试编写
协调它们的工作并合并结果"

Git与工作流集成

Git工作流

# 提交更改
claude "commit my changes with a descriptive message"

# 创建分支
claude "创建一个feature分支来实现用户注册功能"

# 分析变更影响
claude "分析当前分支相比main有哪些变更"

代码审查流程

# 1. 让Claude阅读代码
claude "请阅读src目录下所有Python文件，了解项目结构"

# 2. 提出具体审查要求
claude "针对src/api/v1/users.py文件：
- 检查输入验证是否完整
- 查找潜在的安全漏洞
- 评估错误处理是否合理"

# 3. 要求修复建议
claude "针对发现的问题，请逐个提供修复方案"

调试技巧

# 提供错误信息
claude "运行 'python app.py' 时出现以下错误：
TypeError: Cannot read property 'name' of undefined
堆栈信息显示错误发生在第45行。
帮我定位问题并修复。"

# 提供复现步骤
claude "1. 运行 'npm run dev'
2. 访问 http://localhost:3000
3. 点击登录按钮
4. 输入正确凭据后点击提交
期望：登录成功并跳转
实际：页面卡住无响应
控制台显示：Pending POST /api/login"

国产大模型配置

Claude Code原生使用Claude模型，但也支持配置其他国产模型作为替代。

GLM4系列（智谱AI）

智谱GLM系列在中文理解和代码生成方面表现出色。

GLM4.7特点：

超长上下文支持
强大的中文理解能力
代码生成能力强
Tool Calling支持

配置方法：

# 通过MCP配置GLM
# ~/.claude/config.json
{
  "mcpServers": {
    "glm": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-zhipu-api-key",
        "OPENAI_BASE_URL": "https://open.bigmodel.cn/api/paas/v4"
      }
    }
  }
}

Kimi K2.5（月之暗面）

Kimi K2.5在长上下文和多模态方面有独特优势。

K2.5特点：

256K超长上下文
多模态理解
专业代码生成，编程能力可比肩Claude

定价：

输入：¥4.00/MTok
输出：¥21.00/MTok
缓存命中：¥0.70/MTok

配置方法：

# 通过MCP配置Kimi
# ~/.claude/config.json
{
  "mcpServers": {
    "kimi": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-kimi-api-key",
        "OPENAI_BASE_URL": "https://api.moonshot.cn/v1"
      }
    }
  }
}

MiniMax M2.5

MiniMax M2.5专为编程设计，主打快速响应。

M2.5特点：

高吞吐量、低延迟
专为生产环境优化
编程和Agent能力SOTA
性价比高

配置方法：

# 通过MCP配置MiniMax
# ~/.claude/config.json
{
  "mcpServers": {
    "minimax": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-minimax-api-key",
        "OPENAI_BASE_URL": "https://api.minimax.chat/v1"
      }
    }
  }
}

与其他AI编程工具对比

Cursor

Cursor是最受欢迎的AI原生IDE之一，被超过一半的Fortune 500企业使用。

与Claude Code对比：

Cursor是完整的AI编辑器，Claude Code是CLI工具
Cursor支持GPT-5、Claude、Gemini等多种模型
Claude Code的推理能力更强，适合复杂任务
Cursor的AI深度集成度更高

Cursor核心功能：

Composer 2：一句话完成多文件修改
Tab智能补全
BugBot自动代码审查
代码库全局理解

Trae

Trae是一款自适应AI IDE，主打本地优先和隐私保护。

与Claude Code对比：

Trae中文界面友好，免费额度充足
Claude Code功能更强大，适合复杂项目
Trae适合国内用户快速上手

Trae核心功能：

Builder模式：对话创建文件
中文界面
隐私保护（不二次训练数据）
MCP协议支持

OpenCode

OpenCode是一款轻量级终端AI编程工具，基于Go语言开发。

与Claude Code对比：

OpenCode更轻量，适合简单任务
Claude Code功能更全面
OpenCode支持更多模型提供商

OpenCode支持模型：

OpenAI: GPT-4.1、GPT-4.5、GPT-4o、O1、O3
Anthropic: Claude 4 Sonnet/Opus、Claude 3.5/3.7 Sonnet
Google: Gemini 2.5、2.5 Flash、2.0 Flash

对比总结

特性	Claude Code	Cursor	Trae	OpenCode
类型	CLI+插件	AI IDE	AI IDE	CLI工具
模型	Claude	多模型	多模型	多模型
推理能力	最强	强	中等	强
中文支持	一般	一般	优秀	一般
学习曲线	中等	低	低	中等
免费额度	有限	有限	充足	依赖API

选择建议：

复杂重构和深度任务 → Claude Code
日常开发和IDE体验 → Cursor
国内用户快速上手 → Trae
轻量级终端任务 → OpenCode

常见问题

Q: Claude Code需要付费吗？

A: Claude Code本身免费，但需要Claude API密钥。新用户有免费额度，订阅用户额度更充足。

Q: 国产模型能否替代Claude？

A: 对于日常编程任务，国产模型已经接近Claude水平。复杂推理任务Claude仍有优势。国产模型价格更便宜。

Q: AI写的代码可以直接用吗？

A: 不可以！AI代码必须经过自己理解、本地测试、代码审查、确认安全后才能使用。

Q: 如何选择Claude模型？

A: 简单任务用Haiku，日常开发用Sonnet，复杂任务用Opus。

总结

Claude Code是当前最强大的AI编程工具之一，特别适合：

复杂的代码理解和重构
多文件批量操作
深度调试和问题分析
需要强大推理能力的任务

通过配置MCP，Claude Code也可以使用国产模型（GLM4、Kimi K2.5、Minimax M2.5）作为替代。根据任务复杂度和预算选择合适的工具和模型。