1. 项目概述从“一次性计划”到“持久化规格”如果你用过 Claude Code、Cursor 或者任何带“计划模式”的 AI 编程工具大概率经历过这种挫败感你让 AI 帮你规划一个复杂功能它煞有介事地列出一份详尽的计划你点头称是然后开始执行。但当你中途需要切换上下文去处理一个紧急 bug或者干脆关掉终端去吃个饭再回来时你会发现那个完美的计划已经随着对话上下文的消失而烟消云散了。你不得不重新开始或者更糟在模糊的记忆中摸索试图找回当时的思路。这就是当前 AI 编程工具“计划模式”的致命缺陷——它是瞬时性的而非持久化的。它像一个写在沙滩上的蓝图潮水新的对话一来就什么都没了。你无法暂停、无法恢复、无法在多个计划间切换更无法追踪哪些任务已完成、哪些是下一步。所有在规划阶段进行的深度研究、技术选型讨论和架构决策都锁死在了那一次性的对话里。Spec Mint Core正是为了解决这个问题而生。它不是一个简单的计划工具而是一个持久化、可恢复、可协作的规格驱动开发框架。它的核心思想很简单将 AI 生成的“一次性计划”转化为项目根目录下.specs/文件夹里的一系列 Markdown 文件。这些文件就是你的“规格说明书”它们像代码一样可以被版本控制Git管理可以被任何文本编辑器阅读更重要的是可以被任何支持读取文件的 AI 编程工具Claude Code, Cursor, Windsurf, Cline 等理解和继续执行。简单来说Spec Mint Core 让你和 AI 的协作从“一次性的头脑风暴”升级为“可版本化、可追溯的工程项目管理”。它特别适合需要中大型功能开发、长期维护项目或者习惯在多个功能分支间跳跃式工作的开发者。无论你是独立开发者还是团队协作它都能将 AI 的规划能力从临时的“备忘录”变成项目资产的一部分。2. 核心工作流深度解析从“锻造”到“实现”Spec Mint Core 的核心价值体现在其精心设计的工作流中这远不止是“生成一个待办清单”。它模拟了一个资深工程师接手新需求时的完整思考与执行过程并将其结构化和持久化。整个流程可以概括为两大阶段“锻造”和“实现”。2.1 “锻造”阶段深度研究与迭代访谈当你运行/specmint-core:forge “添加用户认证系统”时一场由 AI 主导的深度需求分析与设计会议就开始了。这个过程不是一蹴而就的而是包含了多个严谨的步骤。第一步深度研究这绝非简单的文件列表扫描。Spec Mint Core 的研究员代理如果使用完整插件会进行“地毯式”搜索。它会读取 10-20 个甚至更多的实际源代码文件而不仅仅是文件名。它会追踪导入依赖链检查测试文件以理解现有的测试模式分析配置文件如package.json,docker-compose.yml来确认技术栈版本。此外它还会进行外部研究搜索网络最佳实践、查阅相关库的官方文档如果项目使用了 Context7 这类文档工具并进行库的横向对比。注意这个研究过程的所有发现都会被忠实地记录在.specs/spec-id/research-01.md文件中。这意味着即使你之后对 AI 的某个设计决策有疑问你也可以回溯到最初的研究笔记查看它当时是基于哪些信息做出的判断这极大地增加了决策的透明度和可审计性。第二步至第四步迭代访谈基于深度研究的发现AI 不会问你“你想要什么样的认证”。它会问出高度具体、上下文相关的问题例如“我看到在src/middleware/目录下现有的限流中间件使用了 Redis 集群。你希望新的认证中间件也复用同一套 Redis 配置还是为认证端点单独配置一个更严格的限流策略” 或者 “项目当前的User模型是用 Prisma 定义的。OAuth 令牌是应该作为User模型的一个字段还是创建一个独立的AuthToken模型”每一轮问答都会被保存到独立的interview-0x.md文件中。访谈会进行多轮通常是 2-5 轮直到规格中的每一个任务都足够具体没有模糊的“需要弄清楚 X”这样的表述。这个过程确保了最终产出的规格是经过双方你和 AI确认的、共识性的蓝图而不是 AI 的单方面臆测。第五步撰写规格说明书将所有研究和访谈结果合成一份完整的SPEC.md。这份文档远不止任务列表它通常包含架构图用 ASCII 艺术或 Mermaid 图表描绘系统组件和数据流。库选型对比表列出 2-3 个候选方案并附上选择最终方案的理由。分阶段任务将工作拆解为 3-6 个逻辑阶段如基础架构、OAuth 集成、测试与加固每个阶段包含具体、可检查的任务每个任务都有唯一编码如[AUTH-01]。测试策略明确说明要进行哪些类型的测试单元、集成、端到端使用什么框架测试文件大概放在哪里。决策日志一个表格记录所有重要的技术决策及其理由。恢复上下文一个区块准备在第一次暂停时记录详细状态。偏差记录一个表格用于在实现过程中记录与原始规格的偏离及其原因。在将规格呈现给你之前AI 会对其进行一次连贯性和逻辑性审查确保没有自相矛盾或遗漏的依赖。2.2 “实现”阶段按图索骥与状态追踪有了SPEC.md接下来的/implement命令就变得像执行一份清晰的施工图纸。AI 会按照规格一个任务一个任务地执行。关键在于状态管理。AI 不仅会执行任务还会同步更新规格文件开始一个任务时会在该任务后标记← current。完成任务后将复选框- [ ]改为- [x]。当一个阶段的所有任务都完成时将阶段标记从[in-progress]更新为[completed]。在.specs/registry.md索引文件中更新整体进度。严格按照规格中定义的测试策略编写测试。在实现过程中如果做出了新的、规格中未记录的决策会将其添加到“决策日志”。如果实现方式与规格描述有出入会在“偏差记录”表中说明原因。最强大的功能暂停与恢复。当你想中断时运行/pause。AI 会将当前状态——包括修改了哪些文件具体到路径和函数名、完成了什么、下一步具体要做什么——详细写入SPEC.md的“恢复上下文”区块并将规格状态设为paused。几天后你只需运行/resumeAI 读取上下文后就能从上次中断的精确位置继续仿佛从未离开。3. 规格文件系统与多工具协作生态Spec Mint Core 的持久化能力完全建立在它简单而强大的文件系统设计之上。它没有使用复杂的数据库或专有格式而是选择了最通用、最可移植的方案纯文本 Markdown 文件。3.1 目录结构与文件解析在你的项目根目录下会生成一个.specs/文件夹其结构清晰且富有逻辑.specs/ ├── registry.md # 核心索引所有规格的元数据和状态快照 └── user-auth-system/ # 一个规格对应一个文件夹 ├── SPEC.md # 规格主体蓝图、任务、决策 ├── research-01.md # 深度研究笔记 ├── interview-01.md # 第一轮访谈记录 ├── research-02.md # 后续研究笔记 └── interview-02.md # 后续访谈记录SPEC.md是权威来源。所有关于该规格的信息都以它为准。其开头的 YAML Frontmatter 定义了规格的基本属性--- id: user-auth-system # 必须URL友好的标识符 title: User Auth System # 必须人类可读的标题 status: active # 必须active|paused|completed|archived created: 2026-02-10 # 必须创建日期 updated: 2026-02-11 # 必须最后更新日期 priority: high # 可选优先级 tags: [auth, security, backend] # 可选标签数组 ---.specs/registry.md是反向索引。它是一个“非规范化”的索引文件包含了所有规格的摘要信息ID, 标题, 状态, 进度百分比最后更新时间主要用于快速查找和列表展示通过/list命令。它的存在避免了为了查看所有规格状态而需要遍历所有SPEC.md文件的操作。实操心得虽然.specs/在specmint-core自身的仓库中被.gitignore了用于自我测试但在你的实际项目中我强烈建议将其纳入版本控制。这些规格文件记录了项目重要的设计决策过程和实现路线图其历史价值不亚于代码本身。团队新成员可以通过阅读这些规格快速理解某个功能的来龙去脉。3.2 多工具无缝协作机制Spec Mint Core 的设计哲学是“开放格式工具无关”。SPEC.md是纯 Markdown这意味着任何能读取文本文件的 AI 编程工具都能参与进来。项目官方支持 Claude Code通过插件、Codex、Cursor、Windsurf、Cline 和 Gemini CLI。协作的核心是共享的约定任务编码[AUTH-03]这个任务在任何工具看来都是同一个任务。当前任务标记← current这个标记是所有工具的“接力棒”。恢复上下文所有工具都理解如何读取和更新这个区块。状态标记[pending],[in-progress],[completed],[blocked]的含义是统一的。如何为不同工具配置 对于 Claude Code安装完整插件能获得最佳体验/forge,/implement等命令。对于其他工具或者想在 Claude Code 中仅使用核心的规格读写能力可以使用npx快速安装通用的SKILL.md文件# 为 Cursor 安装规格技能 npx skills add ngvoicu/specmint-core -g -a cursor安装后当你对 Cursor 说“为我规划一个用户认证系统”它就会自动创建SPEC.md说“我上次做到哪了”它就会读取“恢复上下文”并继续。不同工具间切换时只要操作的是同一个.specs/目录工作流就是连续的。重要警告虽然支持多工具但绝对不要同时用两个工具处理同一个活跃的规格。这会导致状态文件冲突和更新丢失。正确的做法是在工具 A 中/pause一个规格后再到工具 B 中/resume它。并行处理不同的规格则是安全的。4. 安装与配置全指南选择你的最佳路径根据你的主要开发工具和所需功能深度Spec Mint Core 提供了两条安装路径。选择哪一条决定了你的工作流是“全自动豪华版”还是“轻量兼容通用版”。4.1 路径一Claude Code 完整插件推荐这是功能最全面的方式为你提供了 8 个强大的斜杠命令和一个由 Claude Opus 驱动的深度研究代理。安装步骤在 Claude Code 界面中直接输入/plugin marketplace add ngvoicu/specmint-core /plugin install specmint-core这会在 Claude Code 的插件市场中添加并安装 Spec Mint Core。或者如果你喜欢手动操作可以通过命令行克隆到插件目录git clone https://github.com/ngvoicu/specmint-core.git ~/.claude/plugins/specmint-core安装后你获得的能力包括/specmint-core:forge: 启动完整的“锻造”工作流研究、访谈、写规格。/specmint-core:implement: 执行规格中的任务并更新进度。/specmint-core:resume/pause/switch: 恢复、暂停、切换规格。/specmint-core:list/status: 列出所有规格或查看详情。/specmint-core:openapi: 一个额外福利可以从代码库扫描并生成 OpenAPI 规范。研究员代理: 在forge过程中进行深度代码分析和外部研究。自动触发器: 当你说“继续”、“我之前在做什么”、“为 X 创建规格”时插件会自动介入。4.2 路径二通过 npx 快速安装适用于任何工具这条路径的核心是安装一个SKILL.md文件到你的 AI 工具的“技能”或“指令”目录。它教会你的工具如何理解、创建、更新和恢复 Spec Mint Core 的规格格式。通用安装命令# 为 Claude Code 安装仅技能无斜杠命令 npx skills add ngvoicu/specmint-core -g -a claude-code # 为 OpenAI Codex 安装 npx skills add ngvoicu/specmint-core -g -a codex # 为 Cursor 安装 npx skills add ngvoicu/specmint-core -g -a cursor # 为 Windsurf 安装 npx skills add ngvoicu/specmint-core -g -a windsurf # 为 Cline 安装 npx skills add ngvoicu/specmint-core -g -a cline # 为 Gemini CLI 安装 npx skills add ngvoicu/specmint-core -g -a gemini这条路径能做什么安装后你的工具就“学会”了 Spec Mint Core 的规格生命周期管理。你可以通过自然语言或工具特定的方式来操作创建规格对工具说“创建一个关于用户认证的规格”。恢复工作说“恢复认证规格”或“我上次做到哪了”。暂停与切换说“暂停并保存上下文”、“切换到 API 重构规格”。查看列表说“列出我所有的规格”。这条路径不能做什么你将无法使用/forge的深度研究和访谈工作流也没有/implement的自动进度跟踪命令。你获得的是规格的“读写”能力而不是“智能生成”能力。你需要更多地引导 AI 去填充规格的内容。4.3 路径对比与选型建议为了帮你清晰决策下面是两种路径的功能对比功能特性完整插件 (路径一)npx 技能安装 (路径二)/forge(深度研究访谈)✅ 有❌ 无/implement(自动进度跟踪)✅ 有❌ 无/resume,/pause,/switch命令✅ 有❌ 无研究员子代理 (Opus 深度分析)✅ 有❌ 无自动触发器 (Claude Code)✅ 有✅ 有支持 Codex, Cursor 等其他工具❌ 仅 Claude Code✅ 所有跨工具共享.specs/目录✅ 是✅ 是我的建议是如果你是Claude Code 的重度用户并且希望获得从规划到实现的全自动、深度辅助毫不犹豫选择路径一完整插件。/forge带来的深度研究能力是革命性的能极大提升复杂任务的启动质量。如果你主要使用 Cursor、Windsurf 等其他工具或者你在团队中需要与使用不同工具的成员共享规格选择路径二。它提供了跨工具协作的基础。如果你使用Claude Code 但不想装太多插件或者只想先体验核心的规格持久化概念也可以从路径二开始。你仍然可以通过对话让 Claude 遵循规格格式来工作只是少了那些便捷的命令。5. 高级用法与集成策略掌握了基础工作流后我们可以探索一些能进一步提升效率的高级用法和集成方案。5.1 与 Kluris 集成注入“部落知识”Spec Mint Core 在“锻造”阶段会深度阅读你的代码。但一个项目的决策往往还存在于代码之外那些没有写进注释的架构讨论、过去线上事故的教训、第三方服务的特殊怪癖、以及每个“奇怪”实现背后的“为什么”。这些就是“部落知识”通常只存在于老队员的脑子里或零散的会议记录中。Kluris 就是一个用来捕获、组织和查询这些部落知识的工具。你可以把它想象成项目的“第二大脑”或“知识图谱”。将 Spec Mint Core 与 Kluris 结合能让 AI 在规划时不仅看到代码还能“咨询”这个集体大脑。集成工作流安装并启动 Klurispipx install kluris kluris wake-up。将项目相关的设计文档、事故复盘、技术讨论等资料“喂”给 Kluris形成一个知识库Brain。当你在 Spec Mint Core 中运行/forge时在深度研究阶段AI 不仅可以分析代码还可以通过 Kluris 查询“关于这个项目的认证和会话处理我们有哪些历史决策或已知问题”这样生成的规格就不再仅仅基于代码现状和通用最佳实践而是深度植根于你项目特有的上下文和历史约束中。它能避免重复讨论半年前就已定下的方案让新加入的成员无论是人还是 AI能快速继承完整的项目背景。5.2 处理复杂依赖与多规格管理当项目变得复杂你可能同时有多个规格在并行它们之间可能存在依赖关系。策略一使用tags和registry.md进行关联在规格的 Frontmatter 中善用tags字段。例如一个user-auth-system规格和一个api-rate-limiting规格都可以打上backend,security标签。你可以通过/specmint-core:list过滤查看同一领域的规格。在registry.md中快速浏览它们的状态有助于你规划依赖顺序。策略二在规格中明确记录跨规格依赖在SPEC.md的“概述”或“决策日志”部分可以明确写道“本规格用户认证依赖于api-gateway规格中定义的中间件管道。应在该规格完成后启动。” 这样当你/resume时就能立刻意识到前置条件。策略三使用/switch进行上下文切换这是 Spec Mint Core 的杀手锏之一。假设你正在实现“认证系统”规格 A突然需要紧急修复一个与“支付模块”规格 B相关的 bug。在规格 A 的上下文中运行/specmint-core:pause。当前状态被完美保存。运行/specmint-core:switch payment-fix。这会自动暂停 A如果还没暂停加载并激活规格 B。处理完支付模块的 bug。运行/specmint-core:switch user-auth-system即可无缝切换回认证任务从上次中断的精确位置继续。这种能力彻底改变了多任务开发的心智负担让你可以像操作系统切换进程一样在多个开发上下文间轻松跳转。5.3 规格的演进与维护规格不是一成不变的圣旨。在实现过程中你可能会发现更好的方案或者遇到不可预知的技术障碍。Spec Mint Core 通过“偏差记录”表来优雅地处理这种变化。如何记录偏差当实现与原始规格不一致时应在SPEC.md的“Deviations”部分添加一条记录。例如任务规格计划实际实现原因AUTH-05使用 passport.js 库直接调用 googleapis 库项目只需 Google 单一提供商避免 passport 的会话管理开销简化依赖。这既是对历史的忠实记录也为未来的维护者包括未来的你提供了宝贵的上下文。当几个月后有人问“为什么我们没用 passport”时答案就在规格里。规格的“归档”状态当一个规格对应的功能完全实现并上线后不要删除它。将SPEC.md的status改为archived。这样它既不会出现在活跃列表中干扰视线又作为一个完整的设计与实现档案永久保存可供审计、复盘或作为类似新功能的参考模板。6. 常见问题与故障排查实录在实际使用中你可能会遇到一些典型问题。以下是我在深度使用 Spec Mint Core 过程中积累的排查经验和解决方案。6.1 命令未找到或插件不工作问题现象在 Claude Code 中输入/specmint-core:forge没有任何反应或者提示命令不存在。排查步骤确认安装路径首先检查插件是否正确安装。在 Claude Code 中尝试输入/plugin list查看specmint-core是否在列表中。检查插件目录如果不在列表中可能是手动安装路径错误。Claude Code 插件默认目录是~/.claude/plugins/。确保specmint-core文件夹直接位于该目录下而不是嵌套在子目录里。重启 Claude Code有时安装新插件后需要完全重启 Claude Code 桌面应用不仅仅是刷新页面才能加载新的命令。权限问题确保你有对插件目录的读写权限。网络问题如果通过/plugin marketplace add安装确保网络连接正常能访问 GitHub。6.2 规格文件状态不同步或损坏问题现象/list命令显示的状态与SPEC.md文件内的状态不一致或者 AI 在恢复时找不到上下文。根本原因.specs/registry.md索引文件和各个SPEC.md源文件之间的状态不一致。这通常发生在非正常中断如工具崩溃或手动修改了文件但未通过规范命令更新时。解决方案手动重建索引这是最彻底的修复方法。你可以运行一个简单的脚本或者手动检查每个SPEC.md的 Frontmatter 中的status字段然后相应地更新registry.md文件。registry.md的格式是纯文本易于编辑。利用/status命令对某个规格运行/specmint-core:status spec-idAI 会读取SPEC.md并计算当前进度有时它能自动检测并提示不一致。预防措施永远通过 Spec Mint Core 的命令/implement,/pause来更新进度避免直接手动修改- [ ]复选框或status:字段。如果必须手动修改请确保同时更新SPEC.md的 Frontmatter 和registry.md。6.3 “锻造”过程卡住或访谈问题不相关问题现象/forge命令执行时间异常长或者 AI 在访谈阶段问的问题非常笼统没有基于代码库的深入分析。排查步骤检查研究员代理权限完整插件的/forge依赖研究员代理进行深度分析。确保 Claude Code 有权限读取你项目中的所有相关文件。检查是否有.gitignore或文件权限导致关键文件无法被读取。查看研究笔记到.specs/id/research-01.md中查看 AI 到底分析了哪些内容。如果文件列表很少或内容空泛说明深度研究环节可能失败了。项目规模过大如果项目非常庞大数十万行代码初始扫描可能会超时。可以尝试在更具体的子目录下启动规格或者先通过对话给 AI 一些背景信息缩小其研究范围。访谈引导如果 AI 问的问题太泛可以在回答时主动提供更具体的上下文。例如AI 问“认证系统有什么要求”你可以回答“请参考src/middleware/里现有的中间件模式以及prisma/schema.prisma中的用户模型定义。我们希望保持一致性。”6.4 与其他 AI 工具协作时的冲突问题现象在 Cursor 中处理一个规格然后在 Claude Code 中打开同一项目尝试/resume发现状态混乱。黄金法则一次只用一个工具处理一个活跃规格。这是避免冲突的最重要原则。安全协作流程在工具 A如 Cursor中处理规格 X。结束时明确让 AI “保存进度并暂停”或使用/pause命令。确认SPEC.md中status已变为paused并且“恢复上下文”已更新。关闭工具 A。打开工具 B如 Claude Code使用/switch X或让其“恢复规格 X”。工具 B 会读取到paused状态和上下文并正确接管。冲突发生后的处理如果发现两个工具都修改了同一个规格文件优先以SPEC.md文件本身的内容为准。检查文件的修改时间手动合并更改重点是确保“当前任务标记”← current、“复选框状态”和“恢复上下文”这三者逻辑一致。6.5 性能与速度考量潜在瓶颈首次/forge较慢深度研究阶段需要读取大量文件和可能进行网络搜索耗时较长可能几分钟。这是为了换取更高质量的规格请耐心等待。大规格文件响应慢当SPEC.md文件变得非常大包含大量任务、决策日志和偏差记录时AI 每次读取和分析它可能会稍慢。registry.md膨胀当项目中有几十上百个历史规格时registry.md文件会变大。不过纯文本的读取开销在现代硬件上几乎可忽略。优化建议对于非常庞大的项目考虑按模块或子系统创建独立的规格而不是一个巨无霸规格。定期将已完成的规格status改为completed或archived。活跃列表只保留当前正在进行的少数几个规格便于管理。确保你的 AI 工具有足够长的上下文窗口来处理大型规格文件。7. 设计哲学与同类工具对比理解 Spec Mint Core 背后的设计哲学能帮助你更好地运用它并明白它为何与众不同。7.1 为什么不是“更好的计划模式”许多 AI 编码工具都有“计划模式”让 AI 在写代码前先思考。Spec Mint Core 的作者认为现有的计划模式是一个“好主意但糟糕的实现”。其核心缺陷在于瞬时性和隔离性。瞬时性计划存在于对话上下文中会话结束计划消失。隔离性计划与代码库是分离的。它不基于对代码的深度理解也不将计划本身作为可版本化的项目资产。Spec Mint Core 从根本上重新构思了这个过程。它不试图“改进”计划模式而是用一套完整的“规格驱动开发”框架来取代它。这个框架包含持久化一切皆文件可版本化可共享。可恢复性状态被明确保存支持跨会话、跨日期的无缝继续。研究驱动规划基于对代码库和外部知识的深度分析而非空想。协作性规格是人类和 AI甚至不同 AI 工具之间的共识性接口。7.2 与传统项目管理工具如 Jira, Linear的关系你可能会问这不像是一个简化版的 Jira 吗确实有相似之处任务、状态、分配但定位截然不同。抽象层级Jira 等工具管理的是“功能”、“用户故事”、“Bug”等产品层或项目管理层的事务。Spec Mint Core 管理的是“如何实现”的技术规格和具体任务它更贴近代码。核心用户Jira 面向产品经理、项目经理和整个团队。Spec Mint Core 主要面向实际写代码的开发者或 AI。生成方式Jira 条目通常由人工创建。Spec Mint Core 的规格是 AI 通过研究、访谈与你协作生成的并且能直接驱动实现。状态同步在 Spec Mint Core 中任务完成状态是通过 AI 实际执行代码来更新的这与手动点击“完成”有本质区别。它们可以共存。一个高层的 Jira 工单如“实现第三方登录”可以链接到一个 Spec Mint Core 规格user-auth-system。规格负责拆解技术细节和跟踪实现进度而 Jira 负责跟踪业务价值和发布状态。7.3 在 Mint 插件家族中的定位Spec Mint Core 是一个更大家族的一部分。了解其兄弟姐妹有助于你选择适合的工具Spec Mint Core本工具核心是持久化规格管理。重点在于“锻造”蓝图和“按图索骥”地实现支持暂停、恢复、切换。Spec Mint TDD一个强调测试驱动开发的分支。它在核心工作流中强制加入了“红-绿-重构”的 TDD 循环确保每个任务都从编写失败的测试开始。适合那些希望将 AI 编程与严格 TDD 实践结合的团队。选择哪个取决于你的工作流偏好。如果你更看重灵活性和状态管理选 Core如果你希望 AI 严格遵循 TDD 纪律选 TDD。我个人在实际使用中的体会是Spec Mint Core 最大的价值在于它将 AI 的“思考过程”外化和资产化了。过去AI 的规划锁在对话里价值随会话结束而清零。现在这些研究、讨论和决策被保存下来成为了项目文档的一部分。这不仅对当前任务有帮助当半年后需要修改或重构这个功能时这份规格就是最好的“为什么当时这么设计”的说明书。它降低了对原始开发者或当初下指令的你记忆的依赖让项目的知识得以沉淀和传承。对于长期维护的项目和团队协作来说这是一项基础设施级别的改进。