ZhuanSpec

ZhuanSpec 通过规范驱动开发让人类和 AI 编程助手保持一致，在编写任何代码之前就达成共识。无需 API 密钥。

为什么选择 ZhuanSpec ？

当需求只存在于聊天历史中时，AI 编程助手虽然强大但不可预测。ZhuanSpec 添加了一个轻量级的规范工作流，在实现之前锁定意图，为您提供确定性的、可审查的输出。

关键成果：

• 在工作开始前就规范达成一致。
• 结构化的变更文件夹（提案、任务和规范更新）保持范围明确且可审计。
• 共享可见性，了解哪些内容被提议、活跃或已归档。
• 与您已使用的 AI 工具配合：在支持的地方使用自定义斜杠命令，其他地方使用上下文规则。

ZhuanSpec 对比（概览）

• 轻量级：简单的工作流，无需 API 密钥，最小化设置。
• 优先支持现有项目：在 0→1 之外也能很好地工作。ZhuanSpec 将真实来源与提案分离：zhuanspec/specs/（当前真实状态）和 zhuanspec/changes/（提议的更新）。这使得跨功能的差异明确且易于管理。
• 变更跟踪：提案、任务和规范增量共存；归档将已批准的更新合并回规范中。
• 与 spec-kit 和 Kiro 对比：这些工具在全新功能（0→1）方面表现出色。ZhuanSpec 在修改现有行为（1→n）时同样出色，特别是当更新涉及多个规范时。

完整对比请参见 ZhuanSpec 对比。

工作原理

┌────────────────────┐
│ 起草变更提案        │
└────────┬───────────┘
         │ 与您的 AI 分享意图
         ▼
┌────────────────────┐
│ 审查与对齐          │
│ (编辑规范/任务)     │◀──── 反馈循环 ──────┐
└────────┬───────────┘                          │
         │ 已批准的计划                         │
         ▼                                      │
┌────────────────────┐                          │
│ 实现任务            │──────────────────────────┘
│ (AI 编写代码)       │
└────────┬───────────┘
         │ 交付变更
         ▼
┌────────────────────┐
│ 归档并更新          │
│ 规范（真实来源）    │
└────────────────────┘

1. 起草一个变更提案，捕获您想要的规范更新。
2. 与您的 AI 助手审查提案，直到所有人达成一致。
3. 实现引用已达成一致的规范的任务。
4. 归档变更，将已批准的更新合并回真实来源的规范中。

快速开始

支持的 AI 工具

这些工具具有内置的 ZhuanSpec 命令。在提示时选择 ZhuanSpec 集成。

| 工具 | 命令 | |------|------| | Amazon Q Developer | @zhuanspec-proposal, @zhuanspec-apply, @zhuanspec-archive (.amazonq/prompts/) | | Antigravity | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.agent/workflows/) | | Auggie (Augment CLI) | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.augment/commands/) | | Claude Code | /zhuanspec:proposal, /zhuanspec:apply, /zhuanspec:archive | | Cline | .clinerules/workflows/ 目录中的工作流 (.clinerules/workflows/zhuanspec-*.md) | | CodeBuddy Code (CLI) | /zhuanspec:proposal, /zhuanspec:apply, /zhuanspec:archive (.codebuddy/commands/) — 查看 文档 | | Codex | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (全局: ~/.codex/prompts, 自动安装) | | CoStrict | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.cospec/zhuanspec/commands/) — 查看 文档| | Crush | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.crush/commands/zhuanspec/) | | Cursor | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive | | Factory Droid | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.factory/commands/) | | Gemini CLI | /zhuanspec:proposal, /zhuanspec:apply, /zhuanspec:archive (.gemini/commands/zhuanspec/) | | GitHub Copilot | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.github/prompts/) | | iFlow (iflow-cli) | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.iflow/commands/) | | Kilo Code | /zhuanspec-proposal.md, /zhuanspec-apply.md, /zhuanspec-archive.md (.kilocode/workflows/) | | OpenCode | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive | | Qoder (CLI) | /zhuanspec:proposal, /zhuanspec:apply, /zhuanspec:archive (.qoder/commands/zhuanspec/) — 查看 文档 | | Qwen Code | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.qwen/commands/) | | RooCode | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.roo/commands/) | | Windsurf | /zhuanspec-proposal, /zhuanspec-apply, /zhuanspec-archive (.windsurf/workflows/) |

Kilo Code 会自动发现团队工作流。将生成的文件保存在 .kilocode/workflows/ 下，并通过命令面板使用 /zhuanspec-proposal.md、/zhuanspec-apply.md 或 /zhuanspec-archive.md 触发它们。

这些工具会自动从 zhuanspec/AGENTS.md 读取工作流说明。如果它们需要提醒，请要求它们遵循 ZhuanSpec 工作流。了解更多关于 AGENTS.md 约定。

| 工具 | |-------| | Amp • Jules • 其他 |

安装与初始化

前置要求

• Node.js >= 20.19.0 - 使用 node --version 检查您的版本

步骤 1：全局安装 CLI

npm install -g @fission-ai/zhuanspec@latest

或从预构建包安装（如 distributions/fission-ai-zhuanspec-1.0.0.tgz）：参见 安装 ZhuanSpec。

验证安装：

zhuanspec --version

步骤 2：在您的项目中初始化 ZhuanSpec

导航到您的项目目录：

cd my-project

运行初始化：

zhuanspec init

初始化过程中会发生什么：

• 您将被提示选择任何原生支持的 AI 工具（Claude Code、CodeBuddy、Cursor、OpenCode、Qoder 等）；其他助手始终依赖共享的 AGENTS.md 存根
• ZhuanSpec 自动为您选择的工具配置斜杠命令，并始终在项目根目录写入一个受管理的 AGENTS.md 交接文件
• 在您的项目中创建一个新的 zhuanspec/ 目录结构

设置后：

• 主要 AI 工具可以在无需额外配置的情况下触发 /zhuanspec 工作流
• 运行 zhuanspec list 以验证设置并查看任何活动的变更
• 如果您的编程助手没有立即显示新的斜杠命令，请重启它。斜杠命令在启动时加载，因此重新启动可确保它们出现

可选：填充项目上下文

zhuanspec init 完成后，您将收到一个建议提示，帮助填充您的项目上下文：

填充您的项目上下文：
"请阅读 zhuanspec/project.md 并帮助我填写有关我的项目、技术栈和约定的详细信息"

使用 zhuanspec/project.md 定义项目级别的约定、标准、架构模式以及应在所有变更中遵循的其他指南。

创建您的第一个变更

这是一个真实示例，展示了完整的 ZhuanSpec 工作流。这适用于任何 AI 工具。具有原生斜杠命令的工具会自动识别快捷方式。

1. 起草提案

首先要求您的 AI 创建变更提案：

您：为添加按角色和团队筛选的配置文件搜索过滤器创建 ZhuanSpec 变更提案
     （带斜杠命令工具的快捷方式：/zhuanspec:proposal Add profile search filters）

AI：  我将为配置文件过滤器创建 ZhuanSpec 变更提案。
      *搭建 zhuanspec/changes/add-profile-filters/ 包含 proposal.md、tasks.md、规范增量。*

2. 验证与审查

检查变更是否正确创建并审查提案：

$ zhuanspec list                             # 确认变更文件夹存在
$ zhuanspec validate add-profile-filters     # 验证规范格式
$ zhuanspec show add-profile-filters         # 审查提案、任务和规范增量

3. 完善规范

迭代规范直到它们符合您的需求：

您：您能为角色和团队过滤器添加验收标准吗？

AI：  我将更新规范增量，添加角色和团队过滤器的场景。
      *编辑 zhuanspec/changes/add-profile-filters/specs/profile/spec.md 和 tasks.md。*

4. 实现变更

一旦规范看起来不错，开始实现：

您：规范看起来不错。让我们实现这个变更。
     （带斜杠命令工具的快捷方式：/zhuanspec:apply add-profile-filters）

AI：  我将完成 add-profile-filters 变更中的任务。
      *实现来自 zhuanspec/changes/add-profile-filters/tasks.md 的任务*
      *标记任务完成：任务 1.1 ✓、任务 1.2 ✓、任务 2.1 ✓...*

5. 归档已完成的变更

实现完成后，归档变更：

AI：  所有任务都已完成。实现已准备就绪。

您：请归档变更
     （带斜杠命令工具的快捷方式：/zhuanspec:archive add-profile-filters）

AI：  我将归档 add-profile-filters 变更。
     *运行：zhuanspec archive add-profile-filters --yes*
      ✓ 变更已成功归档。规范已更新。准备好下一个功能！

或者您自己在终端中运行命令：

$ zhuanspec archive add-profile-filters --yes  # 无需提示归档已完成的变更

注意： 具有原生斜杠命令的工具（Claude Code、CodeBuddy、Cursor、Codex、Qoder、RooCode）可以使用显示的快捷方式。所有其他工具使用自然语言请求来"创建 ZhuanSpec 提案"、"应用 ZhuanSpec 变更"或"归档变更"。

命令参考

zhuanspec init

在项目中初始化 ZhuanSpec。创建目录结构、模板文件，并配置 AI 工具集成。

zhuanspec init [path] [options]

参数：

| 参数 | 说明 | 默认值 | |------|------|--------| | [path] | 目标项目目录 | .（当前目录） |

选项：

| 选项 | 说明 | 示例 | |------|------|------| | --tools <tools> | 非交互式配置 AI 工具。接受 all、none 或逗号分隔的工具 ID 列表 | --tools claude,cursor | | --business-direction <direction> | 指定业务方向，使用对应的微服务架构文档作为 project.md | --business-direction oms |

使用示例：

# 交互式模式（默认）— 提示您选择 AI 工具
zhuanspec init

# 初始化指定目录
zhuanspec init ./my-project

# 非交互式模式 — 无需提示直接配置指定工具
zhuanspec init --tools claude,cursor

# 配置所有可用工具
zhuanspec init --tools all

# 指定业务方向初始化 — 使用架构文档作为 project.md
zhuanspec init --business-direction oms

# 组合选项
zhuanspec init --tools claude --business-direction oms

--business-direction 的作用：

指定后，ZhuanSpec 会查找名为 {direction}_project_architect.md（如 oms_project_architect.md）的微服务架构文档，并将其直接替换生成的 zhuanspec/project.md。这对于已有预构建的服务架构文档、希望 AI 助手从一开始就理解完整微服务拓扑的团队非常有用。

未指定此选项时，project.md 将从默认模板生成，包含占位章节供您填写。

初始化过程中会发生什么：

1. 创建 zhuanspec/ 目录结构（specs/、changes/、changes/archive/）
2. 生成模板文件（AGENTS.md、project.md）
3. 为您选择的工具配置 AI 工具集成和斜杠命令
4. 在项目根目录写入受管理的 AGENTS.md 存根

扩展模式： 如果 zhuanspec/ 已存在，init 将以扩展模式运行 — 保留现有文件，仅添加缺失的文件或刷新工具配置。

其他命令

zhuanspec list               # 查看活动变更文件夹
zhuanspec view               # 规范和变更的交互式仪表板
zhuanspec show <change>      # 显示变更详情（提案、任务、规范更新）
zhuanspec validate <change>  # 检查规范格式和结构
zhuanspec archive <change> [--yes|-y]   # 将已完成的变更移动到 archive/（使用 --yes 为非交互式）

示例：AI 如何创建 ZhuanSpec 文件

当您要求 AI 助手"添加双因素身份验证"时，它会创建：

zhuanspec/
├── specs/
│   └── auth/
│       └── spec.md           # 当前身份验证规范（如果存在）
└── changes/
    └── add-2fa/              # AI 创建整个结构
        ├── proposal.md       # 为什么以及什么变更
        ├── tasks.md          # 实现清单
        ├── design.md         # 技术决策（可选）
        └── specs/
            └── auth/
                └── spec.md   # 显示添加内容的增量

AI 生成的规范（在 zhuanspec/specs/auth/spec.md 中创建）：

# 身份验证规范

## 目的
身份验证和会话管理。

## 要求
### 要求：用户身份验证
系统应在成功登录时颁发 JWT。

#### 场景：有效凭据
- 当用户提交有效凭据时
- 然后返回 JWT

AI 生成的变更增量（在 zhuanspec/changes/add-2fa/specs/auth/spec.md 中创建）：

# 身份验证的增量

## 新增要求
### 要求：双因素身份验证
系统必须在登录期间要求第二个因素。

#### 场景：需要 OTP
- 当用户提交有效凭据时
- 然后需要 OTP 挑战

AI 生成的任务（在 zhuanspec/changes/add-2fa/tasks.md 中创建）：

## 1. 数据库设置
- [ ] 1.1 向用户表添加 OTP 密钥列
- [ ] 1.2 创建 OTP 验证日志表

## 2. 后端实现
- [ ] 2.1 添加 OTP 生成端点
- [ ] 2.2 修改登录流程以要求 OTP
- [ ] 2.3 添加 OTP 验证端点

## 3. 前端更新
- [ ] 3.1 创建 OTP 输入组件
- [ ] 3.2 更新登录流程 UI

重要提示： 您不需要手动创建这些文件。您的 AI 助手会根据您的需求和现有代码库生成它们。

理解 ZhuanSpec 文件

增量格式

增量是显示规范如何更改的"补丁"：

• ## ADDED Requirements - 新功能
• ## MODIFIED Requirements - 更改的行为（包含完整的更新文本）
• ## REMOVED Requirements - 已弃用的功能

格式要求：

• 使用 ### Requirement: <name> 作为标题
• 每个要求至少需要一个 #### Scenario: 块
• 在要求文本中使用 SHALL/MUST

ZhuanSpec 对比

vs. spec-kit

ZhuanSpec 的双文件夹模型（zhuanspec/specs/ 用于当前真实状态，zhuanspec/changes/ 用于提议的更新）保持状态和差异分离。这在您修改现有功能或涉及多个规范时具有可扩展性。spec-kit 在全新项目/0→1 方面很强，但在跨规范更新和演进功能方面提供的结构较少。

vs. Kiro.dev

ZhuanSpec 将功能的每个变更分组到一个文件夹中（zhuanspec/changes/feature-name/），使跟踪相关规范、任务和设计变得容易。Kiro 将更新分散到多个规范文件夹中，这可能使功能跟踪变得更加困难。

vs. 无规范

没有规范时，AI 编程助手从模糊的提示生成代码，经常遗漏要求或添加不需要的功能。ZhuanSpec 通过在编写任何代码之前就期望的行为达成一致来带来可预测性。

团队采用

1. 初始化 ZhuanSpec – 在您的仓库中运行 zhuanspec init。
2. 从新功能开始 – 要求您的 AI 将即将进行的工作捕获为变更提案。
3. 逐步增长 – 每个变更都会归档到记录您系统的活动规范中。
4. 保持灵活 – 不同的团队成员可以使用 Claude Code、CodeBuddy、Cursor 或任何 AGENTS.md 兼容的工具，同时共享相同的规范。

每当有人切换工具时运行 zhuanspec update，以便您的代理获取最新的说明和斜杠命令绑定。

安装 ZhuanSpec

从 npm 安装（推荐）

npm install -g @fission-ai/zhuanspec@latest

从预构建包安装

若项目提供预构建的 .tgz 包，可从 distributions/ 目录安装：

npm install -g ./distributions/fission-ai-zhuanspec-1.0.0.tgz

本地安装

如果您需要从本地打包文件或 git 仓库安装，请查看 INSTALLATION.md 获取详细说明。

更新 ZhuanSpec

1. 升级包

   npm install -g @zhuan-ai/zhuanspec@latest

2. 刷新代理说明
   • 在每个项目内运行 zhuanspec update 以重新生成 AI 指导并确保最新的斜杠命令处于活动状态。

贡献

• 安装依赖：pnpm install
• 构建：pnpm run build
• 测试：pnpm test
• 本地开发 CLI：pnpm run dev 或 pnpm run dev:cli
• 约定提交（单行）：type(scope): subject

许可证

MIT