@chenxiangming/mgspec

v1.0.4

Published

5 days ago

AI-native system for spec-driven development

0High
0Medium
0Low

chenxiangming

mgspec specs cli ai development

MgSpec

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

为什么使用 MgSpec？

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

主要成果：

人类和 AI 利益相关者在工作开始前就规范达成一致
结构化的变更文件夹（提案、任务和规范更新）使范围明确且可审计
共享对提议、活动或归档内容的可见性
与你已经使用的 AI 工具配合使用：在支持的地方使用自定义 slash 命令,其他地方使用上下文规则

MgSpec 对比概览

轻量级：简单的工作流,无需 API 密钥,最少的设置
棕地优先：在 0→1 之外表现出色。MgSpec 将真实来源与提案分离：mgspec/specs/（当前真实）和 mgspec/changes/（提议的更新）。这使得跨功能的差异明确且可管理
变更跟踪：提案、任务和规范增量一起存在；归档将批准的更新合并回规范
与 spec-kit 和 Kiro 对比：这些工具在全新功能（0→1）方面表现出色。MgSpec 在修改现有行为（1→n）时也很出色,特别是当更新跨越多个规范时

查看完整对比,请参见 MgSpec 对比。

工作原理

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

1. 起草一个变更提案,捕获你想要的规范更新
2. 与你的 AI 助手审查提案,直到每个人都同意
3. 实施引用已同意规范的任务
4. 归档变更以将批准的更新合并回真实来源规范

开始使用

支持的 AI 工具

这些工具内置了 MgSpec 命令。在提示时选择 MgSpec 集成。

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

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

这些工具会自动从 mgspec/AGENTS.md 读取工作流指令。如果它们需要提醒,请要求它们遵循 MgSpec 工作流。了解更多关于 AGENTS.md 约定。

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

安装与初始化

前置条件

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

步骤 1：全局安装 CLI

npm install -g @chenxiangming/mgspec@latest

验证安装：

mgspec --version

步骤 2：在你的项目中初始化 MgSpec

导航到你的项目目录：

cd my-project

运行初始化：

mgspec init

初始化期间发生的事情：

系统会提示你选择任何原生支持的 AI 工具（Claude Code、CodeBuddy、Cursor、OpenCode、Qoder 等）；其他助手总是依赖共享的 AGENTS.md 存根
MgSpec 自动为你选择的工具配置 slash 命令,并始终在项目根目录编写托管的 AGENTS.md 交接文件
在你的项目中创建新的 mgspec/ 目录结构

设置后：

主要 AI 工具无需额外配置即可触发 /mgspec 工作流
运行 mgspec list 以验证设置并查看任何活动变更
如果你的编码助手没有立即显示新的 slash 命令,请重启它。Slash 命令在启动时加载,因此全新启动可确保它们出现

可选：填充项目上下文

在 mgspec init 完成后,你将收到一个建议提示以帮助填充你的项目上下文：

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

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

创建你的第一个变更

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

1. 起草提案

首先要求你的 AI 创建一个变更提案：

你：创建一个 MgSpec 变更提案,用于添加按角色和团队的个人资料搜索过滤器
    （具有 slash 命令的工具的快捷方式：/mgspec:proposal Add profile search filters）

AI：我将为个人资料过滤器创建一个 MgSpec 变更提案。
    *搭建 mgspec/changes/add-profile-filters/,包含 proposal.md、tasks.md、规范增量*

2. 验证与审查

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

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

3. 完善规范

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

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

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

4. 实施变更

一旦规范看起来不错,开始实施：

你：规范看起来不错。让我们实施这个变更。
    （具有 slash 命令的工具的快捷方式：/mgspec:apply add-profile-filters）

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

5. 归档已完成的变更

实施完成后,归档变更：

AI：所有任务已完成。实施已准备好。

你：请归档变更
    （具有 slash 命令的工具的快捷方式：/mgspec:archive add-profile-filters）

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

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

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

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

命令参考

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

示例：AI 如何创建 MgSpec 文件

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

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

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

# 认证规范

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

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

#### 场景：有效凭证
- 当用户提交有效凭证时
- 那么返回 JWT

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

# 认证增量

## ADDED Requirements
### 需求：双因素身份验证
系统必须在登录期间要求第二因素。

#### 场景：需要 OTP
- 当用户提交有效凭证时
- 那么需要 OTP 挑战

AI 生成的任务（在 `mgspec/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 助手会根据你的需求和现有代码库生成它们。

理解 MgSpec 文件

增量格式

增量是显示规范如何变化的"补丁"：

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

格式要求：

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

MgSpec 对比

vs. spec-kit

MgSpec 的双文件夹模型（mgspec/specs/ 用于当前真实,mgspec/changes/ 用于提议的更新）将状态和差异分开。当你修改现有功能或涉及多个规范时,这很好地扩展。spec-kit 在绿地/0→1 方面很强,但为跨规范更新和演进功能提供的结构较少。

vs. Kiro.dev

MgSpec 将功能的每个变更分组在一个文件夹中（mgspec/changes/feature-name/）,使得一起跟踪相关的规范、任务和设计变得容易。Kiro 在多个规范文件夹中传播更新,这可能使功能跟踪更困难。

vs. 无规范

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

团队采用

初始化 MgSpec – 在你的仓库中运行 mgspec init
从新功能开始 – 要求你的 AI 将即将到来的工作捕获为变更提案
渐进式增长 – 每个变更归档到记录系统的活动规范中
保持灵活性 – 不同的团队成员可以使用 Claude Code、CodeBuddy、Cursor 或任何 AGENTS.md 兼容工具,同时共享相同的规范

每当有人切换工具时运行 mgspec update,这样你的代理就可以获取最新的指令和 slash 命令绑定。

更新 MgSpec

升级包

npm install -g @chenxiangming/mgspec@latest

刷新代理指令
- 在每个项目内运行 mgspec update 以重新生成 AI 指导并确保最新的 slash 命令处于活动状态

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