IncSpec 通过增量规范驱动开发让人类与 AI 编程助手保持一致 - 这是一个 7 步工作流，在修改代码前先捕获代码流程基线。无需 API 密钥。
AI 编程助手在处理复杂前端代码库时常常力不从心，因为 API 调用、状态管理和组件依赖深度交织。incspec 添加了一个结构化分析工作流，在提出变更前先捕获当前状态，让你获得可预测、可审查的输出。
| 痛点 | 传统规范驱动 | IncSpec 增量规范驱动 |
|---|---|---|
| AI 不理解现有代码上下文 | 用户手动描述 | 自动捕获代码基线 |
| 变更破坏现有功能 | 事后发现 | 变更前风险评估 |
| 依赖关系不清晰 | 人工追踪 | 6 维度依赖追踪 |
| 增量变更难以管理 | 全量重写 | 基于基线的增量设计 |
| 历史变更不可追溯 | 依赖 Git 记录 | 规范化归档与版本管理 |
核心价值：
- 基线优先：在修改代码前先理解现有代码流程。
- 结构化需求：5 列表格精确捕获需求。
- 依赖追踪：6 维度分析 UI 依赖（API、Store、Types 等）。
- 增量设计：7 模块蓝图指导实现。
- 无缝迭代：将完成的工作合并为新基线，开启下一轮循环。
- 历史可追溯：归档按年月和工作流名称组织，便于回顾历史决策。
- 兼容你已有的 AI 工具：Cursor、Claude Code 及任何 AGENTS.md 兼容助手。
- 前端专注：专为 API 数据流程分析和组件依赖设计。
- 7 步循环：分析 → 收集需求 → 收集依赖 → 设计 → 应用 → 合并 → 归档。
- 基线管理：每个循环产出新基线，作为下一轮迭代的起点。
- 与 OpenSpec 对比：OpenSpec 擅长 0→1 功能规范。incspec 擅长理解和修改现有前端代码库（1→n），特别是 API 流程和状态管理复杂的场景。
完整对比见 incspec 对比。
适用于复杂功能开发，需要完整的 UI 依赖分析和增量设计。
┌────────────────────┐
│ 1. 分析 │ 分析现有代码流程
│ 代码流程 │ 生成基线快照
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 2. 收集 │ 捕获结构化需求
│ 需求 │ 5 列表格格式
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 3. 收集 │ 分析 UI 依赖
│ 依赖 │ API、Store、Types、Utils、Components、Hooks
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 4. 设计 │ 生成增量蓝图
│ 增量 │ 7 模块设计文档
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 5. 应用 │ 实现代码变更
│ 变更 │ 按照蓝图执行
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 6. 合并 │ 合并为新基线
│ 到基线 │ 验证功能正常
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 7. 归档 │ 归档本轮产出
│ 产出 │ 清空工作区
└────────┬───────────┘
│
└──────────────────────────────────────┐
│
┌───────────────────────────┘
│ 新基线成为
│ 下一轮增量循环的
▼ 起点
┌───────────┐
│ 迭代 │
└───────────┘
适用于 Bug 修复、简单功能、不涉及复杂 UI 依赖的变更。
┌────────────────────┐
│ 1. 分析 │ 分析现有代码流程
│ 代码流程 │ 生成基线快照
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 2. 收集 │ 捕获结构化需求
│ 需求 │ 5 列表格格式
└────────┬───────────┘
│
│ (跳过步骤 3 UI依赖采集)
│ (跳过步骤 4 增量设计)
│
▼
┌────────────────────┐
│ 5. 应用 │ 基于需求文档
│ 变更 │ 直接实现代码变更
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 6. 合并 │ 重新分析代码
│ 到基线 │ 生成新基线
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 7. 归档 │ 归档本轮产出
│ 产出 │ 清空工作区
└────────────────────┘
适用于紧急修复、单文件小改动、不需要新基线的变更。
┌────────────────────┐
│ 1. 分析 │ 分析现有代码流程
│ 代码流程 │ 生成基线快照
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 5. 应用 │ 基于口头需求
│ 变更 │ 直接实现代码变更
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 7. 归档 │ 归档本轮产出
│ 产出 │ 清空工作区
└────────────────────┘
模式选择建议:
- 完整模式: 复杂 UI 功能、多组件交互、需要详细设计审查
- 快速模式: Bug 修复、简单功能、不涉及 UI 依赖变更
- 极简模式: 紧急修复、单文件小改动、无需生成新基线
模式升级:
支持从宽松模式升级到严格模式（minimal → quick → full），使用 incspec upgrade <mode> 补齐缺失步骤。
提示: 如果已有基准报告，可使用
incspec analyze --baseline=<file>直接跳过分析步骤，快速进入后续工作流。
原生斜杠命令（点击展开）
运行 incspec sync 后，这些工具可使用内置的 incspec 命令。
| 工具 | 命令 |
|---|---|
| Cursor | /incspec/inc-analyze、/incspec/inc-collect-req、/incspec/inc-collect-dep、/incspec/inc-design、/incspec/inc-apply、/incspec/inc-merge、/incspec/inc-archive |
| Claude Code | 同 Cursor，使用相同的 /incspec/inc-* 命令 |
AGENTS.md 兼容（点击展开）
这些工具会自动读取 incspec/AGENTS.md 中的工作流指令。如需提醒，可让它们遵循 incspec 工作流。
| 工具 |
|---|
| Claude Code、Cursor（Agent 模式）及其他 AGENTS.md 兼容助手 |
- Node.js >= 18.0.0 - 使用
node --version检查版本
# 从 Npm 安装（推荐）
npm install -g @localsummer/incspec
# 从 GitHub 克隆并安装
git clone https://github.com/localSummer/IncSpec.git
cd IncSpec
npm link验证安装：
incspec --version进入项目目录：
cd my-project运行初始化：
incspec init初始化过程中会：
- 创建
incspec/目录结构 - 生成包含工作流指令的
AGENTS.md - 在
incspec/project.md中设置项目配置 - 询问是否立即同步 IDE 命令（可选择目标 IDE 和同步范围）
如果在初始化时跳过了 IDE 同步，或需要重新同步，可以单独运行：
incspec sync # 交互式选择（默认不预选）
incspec sync --cursor # 仅 Cursor
incspec sync --claude # 仅 Claude Code
incspec sync --all # 全部设置完成后：
- 运行
incspec status验证设置 - Cursor 和 Claude Code 用户都可直接使用
/incspec/inc-*命令 - 命令生成到
.cursor/commands/incspec/或.claude/commands/incspec/目录
以下是展示完整 incspec 工作流的真实示例。
首先分析你要修改的代码：
你：分析 Home 页面组件及其 API 流程
（Cursor 快捷命令：/incspec/inc-analyze）
AI：我来分析 Home 组件的代码流程。
*生成 incspec/baselines/home-baseline-v1.md，包含 API 调用序列、
依赖关系和组件结构。*
验证并标记完成：
$ incspec status # 检查当前工作流状态
$ incspec analyze src/views/Home --complete # 标记步骤 1 完成启动快速模式 (5步流程):
适用于 Bug 修复或简单功能变更：
$ incspec analyze src/views/Home --quick # 启动快速模式工作流快速模式跳过步骤 3 (UI依赖采集) 和步骤 4 (增量设计)，直接从需求进入代码应用。
启动极简模式 (3步流程):
适用于紧急修复或单文件小改动：
$ incspec analyze src/views/Home --minimal # 启动极简模式工作流极简模式跳过步骤 2、3、4、6，仅保留分析 → 应用 → 归档；如需补齐步骤可使用 incspec upgrade <mode>。
使用现有基准报告 (跳过分析):
如果已有基准报告文件，可直接使用，跳过分析步骤：
$ incspec analyze --baseline=home-baseline-v1.md # 直接使用现有基准报告- 自动搜索
baselines/和archives/目录 - 若文件在归档目录，自动移动到
baselines/目录 - 模块名自动从文件名推断 (
xxx-baseline-vN.md->xxx) - 可通过
--module覆盖模块名
定义你想要的变更：
你：我需要在 Home 页面添加搜索过滤功能
（Cursor 快捷命令：/incspec/inc-collect-req）
AI：我来为搜索过滤创建结构化需求。
*生成 incspec/requirements/structured-requirements.md，
包含 5 列表格：ID | 类型 | 描述 | 验收标准 | 优先级*
分析新功能所需的依赖：
你：搜索过滤功能需要哪些依赖？
（Cursor 快捷命令：/incspec/inc-collect-dep）
AI：我来分析所需的依赖。
*生成 incspec/requirements/ui-dependencies.md，
涵盖 API、Store、Types、Utils、Components 和 Hooks*
生成实现蓝图：
你：为搜索过滤功能设计增量
（Cursor 快捷命令：/incspec/inc-design）
AI：我来创建增量设计文档。
*生成 incspec/increments/search-filter-increment-v1.md，
包含 7 个模块：概述、API 变更、Store 变更、类型定义、
组件变更、新文件和迁移说明*
按照蓝图实现：
你：应用搜索过滤增量
（Cursor 快捷命令：/incspec/inc-apply）
AI：我将按照增量设计实现变更。
*根据蓝图修改源文件*
完成循环：
你：合并创建新基线
（Cursor 快捷命令：/incspec/inc-merge）
AI：我将增量合并到新基线。
*创建 incspec/baselines/home-baseline-v2.md，
准备进入下一轮迭代循环*
完成步骤 1-6 后，使用归档命令保存本轮产出：
你：归档本轮工作流产出
（Cursor 快捷命令：/incspec/inc-archive）
AI：我来归档本轮工作流的所有产出文件。
*运行 incspec archive --workflow*
或直接在终端执行：
$ incspec archive -y # 归档所有工作流产出，跳过确认归档是 incspec 工作流的收尾步骤，将本轮迭代的产出文件移入历史存档，为下一轮迭代腾出空间。
- 保持工作区整洁：避免多轮迭代的文件混杂在一起。
- 历史可追溯：按年月和工作流名称组织，便于回顾历史决策。
- 迭代边界清晰：每轮归档后，当前工作流产出从
baselines/、requirements/、increments/移出，便于下一轮重新生成。
在以下情况下执行归档：
- 步骤 1-6 全部完成 - 代码已应用，新基线已生成
- 功能已验证通过 - 确认变更符合预期
- 准备开始下一轮迭代 - 需要清空当前工作区
# 归档整个工作流（推荐）
incspec archive # 交互式确认（默认归档当前工作流）
incspec archive --workflow # 显式指定归档当前工作流
incspec archive -y # 跳过确认，直接归档
# 归档指定文件
incspec archive baselines/home-baseline-v1.md
# 归档但保留原文件（复制而非移动）
incspec archive baselines/home-baseline-v1.md --keep
# 查看归档内容
incspec list -a # 列出所有文件，包含归档
incspec list archives # 仅列出归档文件归档命令按年月和工作流名称组织文件（文件直接放在工作流目录下）：
incspec/
├── archives/
│ └── 2024-12/ # 按年月组织
│ └── home-search-filter/ # 工作流名称
│ ├── home-baseline-v1.md
│ ├── structured-requirements.md
│ ├── ui-dependencies.md
│ ├── search-filter-increment-v1.md
│ └── home-baseline-v2.md
├── baselines/ # 当前工作流产出默认已移动
├── requirements/ # 当前工作流产出默认已移动
└── increments/ # 当前工作流产出默认已移动
说明：若单文件归档且没有当前工作流，文件会直接进入 archives/YYYY-MM/。
┌────────────────────┐
│ 步骤 1-6 完成 │
│ 新基线已生成 │
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 验证功能 │ 确认代码变更符合预期
│ 测试通过 │
└────────┬───────────┘
│
▼
┌────────────────────┐
│ 执行归档 │ incspec archive -y
│ │
└────────┬───────────┘
│
▼
┌────────────────────────────────────────────┐
│ 归档完成 │
│ │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ archives/ │ │ baselines/ │ │
│ │ 2024-12/ │ │ requirements/ │ │
│ │ workflow/ │ │ increments/ │ │
│ │ ├─*.md │ │ (当前工作流产出 │ │
│ │ └─*.md │ │ 已移动) │ │
│ └─────────────┘ └─────────────────┘ │
└────────────────────────────────────────────┘
- 及时归档 - 完成一轮迭代后立即归档，避免文件堆积。
- 优先归档整个工作流 - 直接执行
incspec archive或--workflow，确保产出完整。 - 明确移动/保留策略 - 默认移动到归档目录，需保留原文件时使用
--keep。 - 保持工作流命名清晰 - 归档目录按工作流名称分组，命名清晰更易追溯。
incspec reset # 全量重置，归档所有产出
incspec reset --to=3 # 回退到步骤 3，保留 1-3，重置 4-7
incspec reset -t 3 # 短选项形式回退行为: 保留目标步骤及之前状态，重置后续步骤为 pending，被重置步骤的产出自动归档。
限制: 目标步骤必须已完成（1-6），快速模式下不能回退到被跳过的步骤（3、4），极简模式下不能回退到被跳过的步骤（2、3、4、6）。
your-project/
├── AGENTS.md # AI 代理指令（包含 incspec 指令块）
├── src/ # IncSpec 源代码
│ ├── index.mjs # CLI 入口
│ ├── commands/ # 命令实现
│ ├── lib/ # 核心库
│ └── templates/ # Markdown 模板文件
├── incspec/
│ ├── project.md # 项目配置
│ ├── workflow.json # 当前工作流状态
│ ├── AGENTS.md # incspec 使用指南
│ ├── baselines/ # 基线快照
│ │ └── home-baseline-v1.md
│ ├── requirements/ # 需求文档
│ │ ├── structured-requirements.md
│ │ └── ui-dependencies.md
│ ├── increments/ # 增量设计
│ │ └── feature-increment-v1.md
│ └── archives/ # 历史归档
│ └── 2024-12/ # 按年月组织
│ └── {workflow}/ # 按工作流名称分组
└── .cursor/
└── commands/
└── incspec/ # Cursor 命令
初始化与状态（点击展开）
incspec init # 初始化项目
incspec init --force # 强制重新初始化
incspec update # 更新模板到最新版本（别名：up）
incspec update -y # 跳过确认提示
incspec status # 查看工作流状态（别名：st）
incspec help # 显示帮助（别名：h）
incspec help <command> # 显示特定命令帮助工作流命令（点击展开）
所有工作流命令支持 --complete 标记步骤完成。
# 步骤 1：分析代码流程
incspec analyze <source-path> [--module=name] [--quick|--minimal] # 别名：a
incspec a src/views/Home --module=home
incspec analyze src/views/Home --quick # 启动快速模式
incspec analyze src/views/Home --minimal # 启动极简模式
incspec analyze src/views/Home --complete -o baselines/home-baseline-v1.md
incspec analyze --baseline=home-baseline-v1.md # 使用现有基准(自动从归档恢复)
# 步骤 2：收集结构化需求
incspec collect-req # 别名：cr
incspec cr --complete
# 步骤 3：收集 UI 依赖（快速/极简模式跳过）
incspec collect-dep # 别名：cd
incspec cd --complete
# 步骤 4：生成增量设计（快速/极简模式跳过）
incspec design [--feature=name] # 别名：d
incspec d --feature=user-auth --complete -o increments/auth-increment-v1.md
# 步骤 5：应用代码变更
incspec apply [increment-path] # 别名：ap
incspec ap --source-dir=src/ --complete
# 快速/极简模式下自动使用 requirements/structured-requirements.md 作为输入
# 步骤 6：合并到基线
incspec merge [increment-path] # 别名：m
incspec m --complete -o baselines/home-baseline-v2.md
# 快速模式下重新分析代码生成新基线
# 极简模式默认跳过步骤 6（需升级模式后执行）管理命令（点击展开）
incspec list [type] # 列出规范文件（别名：ls）
incspec list baselines # 列出基线文件
incspec list -l # 详细模式
incspec list -a # 包含归档
incspec validate # 验证规范完整性（别名：v）
incspec validate --strict # 严格模式，有错误时返回非零退出码
incspec archive # 归档所有工作流产出（别名：ar）
incspec archive --workflow # 同上，显式指定
incspec archive <file> # 归档指定文件
incspec archive <file> --keep # 复制而非移动
incspec archive -y # 跳过确认提示
incspec reset # 重置当前工作流（别名：rs）
incspec reset --to=3 # 回退到步骤 3，保留步骤 1-3 的状态
incspec reset -t 3 # 同上，短选项形式
incspec upgrade <mode> # 升级工作流模式（别名：ug）
incspec upgrade quick # minimal → quick
incspec upgrade full # quick/minimal → full命令别名（点击展开）
| 命令 | 别名 | 说明 |
|---|---|---|
analyze |
a |
步骤 1 |
collect-req |
cr |
步骤 2 |
collect-dep |
cd |
步骤 3 |
design |
d |
步骤 4 |
apply |
ap |
步骤 5 |
merge |
m |
步骤 6 |
archive |
ar |
步骤 7 |
status |
st |
状态 |
list |
ls |
列表 |
validate |
v |
验证 |
sync |
s |
同步 |
update |
up |
更新 |
reset |
rs |
重置/回退 |
upgrade |
ug |
模式升级 |
help |
h |
帮助 |
| 特性 | incspec | OpenSpec |
|---|---|---|
| 工作流 | 7 步增量循环 | 3 阶段（proposal → apply → archive） |
| 侧重点 | 前端 API 流程分析 | 通用功能规范 |
| 编号系统 | S/D/N/C/R 多层编号 | 单一编号 |
| 代码生成 | 集成应用步骤 | 需手动编码 |
| 迭代管理 | 基线合并 + 归档，无缝循环 | 无明确迭代管理 |
何时使用 incspec： 修改具有复杂 API 流程、状态管理和组件依赖的现有前端代码库。
何时使用 OpenSpec： 从零开始定义新功能，特别是后端或全栈工作。
没有规范时，AI 编程助手根据模糊提示生成代码，常常破坏现有功能或遗漏依赖。incspec 先捕获当前状态，确保变更基于对代码库的准确理解。
- 初始化 incspec - 在仓库中运行
incspec init。 - 从复杂变更开始 - 在修改包含大量 API 调用或依赖的代码时使用 incspec。
- 增量构建基线 - 每个循环产出下一轮的基线。
- 跨工具共享 - 团队成员可使用 Cursor、Claude Code 或任何 AGENTS.md 兼容工具。
运行 incspec update 将模板和代理指令刷新到最新版本。
- 拉取最新变更
cd /path/to/IncSpec # 进入之前克隆的目录 git pull npm link
- 刷新项目模板
incspec update
- Node.js >= 18.0.0
- 无第三方依赖
ISC