IncSpec

面向 AI 编程助手的增量规范驱动开发工具

GitHub npm node version License: ISC

IncSpec

为什么选择 IncSpec?

IncSpec 对比一览

工作原理

完整模式 (7步)

┌────────────────────┐
│ 1. 分析 │ 分析现有代码流程
│ 代码流程 │ 生成基线快照
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 2. 收集 │ 捕获结构化需求
│ 需求 │ 5 列表格格式
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 3. 收集 │ 分析 UI 依赖
│ 依赖 │ API、Store、Types、Utils、Components、Hooks
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 4. 设计 │ 生成增量蓝图
│ 增量 │ 7 模块设计文档
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 5. 应用 │ 实现代码变更
│ 变更 │ 按照蓝图执行
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 6. 合并 │ 合并为新基线
│ 到基线 │ 验证功能正常
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 7. 归档 │ 归档本轮产出
│ 产出 │ 清空工作区
└────────┬───────────┘
 │
 └──────────────────────────────────────┐
 │
 ┌───────────────────────────┘
 │ 新基线成为
 │ 下一轮增量循环的
 ▼ 起点
 ┌───────────┐
 │ 迭代 │
 └───────────┘

快速模式 (5步)

┌────────────────────┐
│ 1. 分析 │ 分析现有代码流程
│ 代码流程 │ 生成基线快照
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 2. 收集 │ 捕获结构化需求
│ 需求 │ 5 列表格格式
└────────┬───────────┘
 │
 │ (跳过步骤 3 UI依赖采集)
 │ (跳过步骤 4 增量设计)
 │
 ▼
┌────────────────────┐
│ 5. 应用 │ 基于需求文档
│ 变更 │ 直接实现代码变更
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 6. 合并 │ 重新分析代码
│ 到基线 │ 生成新基线
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 7. 归档 │ 归档本轮产出
│ 产出 │ 清空工作区
└────────────────────┘

极简模式 (3步)

┌────────────────────┐
│ 1. 分析 │ 分析现有代码流程
│ 代码流程 │ 生成基线快照
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 5. 应用 │ 基于口头需求
│ 变更 │ 直接实现代码变更
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 7. 归档 │ 归档本轮产出
│ 产出 │ 清空工作区
└────────────────────┘

快速开始

支持的 AI 工具

安装与初始化

前置条件

步骤 1:安装 CLI

# 从 Npm 安装(推荐)
npm install -g @localsummer/incspec
# 从 GitHub 克隆并安装
git clone https://github.com/localSummer/IncSpec.git
cd IncSpec
npm link

incspec --version

步骤 2:在项目中初始化 IncSpec

cd my-project

incspec init

步骤 3:同步 IDE 集成(可选)

incspec sync # 交互式选择(默认不预选)
incspec sync --cursor # 仅 Cursor
incspec sync --claude # 仅 Claude Code
incspec sync --all # 全部

创建你的第一个增量

1. 分析现有代码

你:分析 Home 页面组件及其 API 流程
 (Cursor 快捷命令:/incspec/inc-analyze)
AI:我来分析 Home 组件的代码流程。
 *生成 incspec/baselines/home-baseline-v1.md,包含 API 调用序列、
 依赖关系和组件结构。*

$ incspec status # 检查当前工作流状态
$ incspec analyze src/views/Home --complete # 标记步骤 1 完成

$ incspec analyze src/views/Home --quick # 启动快速模式工作流

$ incspec analyze src/views/Home --minimal # 启动极简模式工作流

$ incspec analyze --baseline=home-baseline-v1.md # 直接使用现有基准报告

2. 收集结构化需求

你:我需要在 Home 页面添加搜索过滤功能
 (Cursor 快捷命令:/incspec/inc-collect-req)
AI:我来为搜索过滤创建结构化需求。
 *生成 incspec/requirements/structured-requirements.md,
 包含 5 列表格:ID | 类型 | 描述 | 验收标准 | 优先级*

3. 收集 UI 依赖

你:搜索过滤功能需要哪些依赖?
 (Cursor 快捷命令:/incspec/inc-collect-dep)
AI:我来分析所需的依赖。
 *生成 incspec/requirements/ui-dependencies.md,
 涵盖 API、Store、Types、Utils、Components 和 Hooks*

4. 设计增量

你:为搜索过滤功能设计增量
 (Cursor 快捷命令:/incspec/inc-design)
AI:我来创建增量设计文档。
 *生成 incspec/increments/search-filter-increment-v1.md,
 包含 7 个模块:概述、API 变更、Store 变更、类型定义、
 组件变更、新文件和迁移说明*

5. 应用变更

你:应用搜索过滤增量
 (Cursor 快捷命令:/incspec/inc-apply)
AI:我将按照增量设计实现变更。
 *根据蓝图修改源文件*

6. 合并到新基线

你:合并创建新基线
 (Cursor 快捷命令:/incspec/inc-merge)
AI:我将增量合并到新基线。
 *创建 incspec/baselines/home-baseline-v2.md,
 准备进入下一轮迭代循环*

7. 归档已完成的工作

你:归档本轮工作流产出
 (Cursor 快捷命令:/incspec/inc-archive)
AI:我来归档本轮工作流的所有产出文件。
 *运行 incspec archive --workflow*

$ incspec archive -y # 归档所有工作流产出,跳过确认

归档流程

为什么需要归档?

归档时机

归档命令详解

# 归档整个工作流(推荐)
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/ # 当前工作流产出默认已移动

归档工作流示意

┌────────────────────┐
│ 步骤 1-6 完成 │
│ 新基线已生成 │
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 验证功能 │ 确认代码变更符合预期
│ 测试通过 │
└────────┬───────────┘
 │
 ▼
┌────────────────────┐
│ 执行归档 │ incspec archive -y
│ │
└────────┬───────────┘
 │
 ▼
┌────────────────────────────────────────────┐
│ 归档完成 │
│ │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ archives/ │ │ baselines/ │ │
│ │ 2024-12/ │ │ requirements/ │ │
│ │ workflow/ │ │ increments/ │ │
│ │ ├─*.md │ │ (当前工作流产出 │ │
│ │ └─*.md │ │ 已移动) │ │
│ └─────────────┘ └─────────────────┘ │
└────────────────────────────────────────────┘

归档最佳实践

回退与重置

incspec reset # 全量重置,归档所有产出
incspec reset --to=3 # 回退到步骤 3,保留 1-3,重置 4-7
incspec reset -t 3 # 短选项形式

目录结构

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 对比

vs. OpenSpec

vs. 无规范

团队采用

更新 IncSpec

技术要求

License