1. 项目概述：从“一次性计划”到“持久化规格”的范式转变
如果你和我一样，长期使用各种AI编程工具（Claude Code、Cursor、Windsurf等），肯定对它们的“计划模式”（Plan Mode）又爱又恨。爱的是，它确实能帮你理清思路，让AI在动手前先想清楚；恨的是，这个计划就像沙滩上的字迹，对话窗口一关，或者新开一个会话，它就彻底消失了。你没法暂停一个做到一半的计划，没法在多个功能需求之间切换，更没法在一周后回来时，还能精准地接着上次的断点继续。这种“健忘症”式的体验，让AI编程在复杂、长期的项目中显得力不从心。
这就是Spec Mint Core要解决的核心痛点。它不是一个简单的计划工具，而是一个完整的“规格驱动开发”（Spec-Driven Development）工作流引擎。它的核心思想很简单，却非常强大：将AI生成的、短暂存在于对话上下文中的“计划”，转化为持久化、可恢复、可迭代的“规格说明书”（Specification）。这些规格以纯Markdown文件的形式，保存在你项目的.specs/目录下，与你的代码库一同受版本控制。它们不再是AI的“内部记忆”，而是项目资产的一部分。
想象一下，你正在开发一个用户认证系统。你启动/specmint-core:forge "add user authentication with OAuth"。接下来发生的事情，远不止是列一个任务清单：
深度研究：Spec Mint Core 会像一个经验丰富的技术负责人，先对你的代码库进行一次“地毯式”扫描。它不只是看看文件名，而是深入读取10-20个甚至更多相关文件，理解你现有的架构模式、依赖关系、测试风格。同时，它还会结合网络搜索、库文档（如Context7）和跨领域研究，为你寻找最佳实践和可行的技术方案。所有这些研究笔记，都被忠实地记录在
.specs/user-auth-system/research-01.md里。针对性访谈：基于研究发现，它会向你提出一系列具体而非泛泛的问题。比如：“我看到你在
src/middleware/里使用了Express中间件模式X，新的认证中间件是否应该遵循同样的模式？” 或者 “项目里已经用了Prisma，OAuth令牌是放在现有的User模型里，还是新建一个AuthToken模型？” 这些问答记录在interview-01.md中，确保了规格是基于你的真实意图和项目约束定制的。迭代与深化：研究-访谈的循环会进行多轮，直到每一个待办事项都足够具体、没有歧义，不再是“想办法搞定X”这种模糊描述。
生成规格说明书：最终，所有信息被整合成一份结构清晰的
SPEC.md。这份文档包含架构图、技术选型对比表、分阶段的任务列表（每个任务都有唯一编码）、测试策略、决策日志，以及最重要的——恢复上下文。在生成前，它还会进行一次逻辑连贯性审查。按规格实施：之后，你可以通过
/implement命令，让AI按照SPEC.md里的任务列表，一个接一个地编码。每完成一个任务，它就在清单上打勾，更新进度，并在“决策日志”中记录任何临时的技术决策。任何时候，你都可以/pause暂停，它会将当前状态（修改了哪些文件、函数名、下一步具体要做什么）详细写入“恢复上下文”。几天后，一个/resume命令，就能让你无缝衔接。
这种工作流带来的改变是根本性的。它让AI编程从“一次性的对话魔术”，变成了一个可管理、可追溯、可协作的工程过程。你不再是与一个“健忘”的AI合作，而是在与一个拥有“项目记忆”的智能伙伴共同推进工作。这对于需要长期维护、功能迭代或多人参与的项目来说，价值巨大。
2. 核心工作流深度解析：Forge、Implement与生命周期管理
Spec Mint Core 的核心价值体现在其精心设计的工作流中。理解这个工作流，是高效使用它的关键。我们将其拆解为三个主要阶段：锻造（Forge）、实施（Implement）和生命周期管理（Resume/Pause/Switch）。
2.1 Forge工作流：从想法到可执行规格的锻造过程
/forge命令是规格的诞生之地。它远不止是生成一个任务列表，而是一个包含深度研究、多轮访谈和综合设计的完整需求分析过程。这个过程确保了最终产出的规格是接地气的、可行的、且与你项目现状深度结合的。
2.1.1 深度研究阶段：超越表面扫描
当AI执行研究时，它不是在玩“猜猜看”。以“添加OAuth认证”为例，一个合格的研究过程会包含：
- 代码库考古：它会系统性地读取所有与认证、用户、会话、路由、中间件相关的文件。不仅仅是
src/auth/目录，还包括src/middleware/（看现有中间件模式）、prisma/schema.prisma（看数据模型）、package.json和锁文件（看现有依赖和版本）、相关的测试文件（看测试风格和覆盖率）。它会追踪导入关系，理解代码的组织逻辑。 - 外部知识整合：它会搜索“OAuth 2.0 best practices 2024”、“Express JWT middleware secure implementation”、“Prisma OAuth token storage”等主题，并参考
Context7这类库文档聚合服务，获取权威、最新的库文档。 - 技术选型对比：对于关键决策点，比如“用
passport.js还是直接调用googleapis库？”，它会生成一个对比表格，列出各自的优缺点、社区活跃度、与当前项目的契合度。 - 风险评估：初步识别潜在风险，例如“现有代码中会话处理是否与无状态的JWT冲突？”、“OAuth回调URL在开发/生产环境如何配置？”
实操心得：研究阶段的质量直接决定了后续规格的可靠性。我发现在项目根目录放一个简明的
ARCHITECTURE.md或TECH-STACK.md文件，能极大帮助AI快速理解你的技术选型和设计哲学，让研究更聚焦。
2.1.2 访谈阶段：从“要什么”到“具体怎么做”
这是Spec Mint Core最精妙的部分。AI不会问你“你想要什么样的认证？”，而是基于研究发现，提出高度具体、引导性的问题。例如：
- “代码库显示你在
src/middleware/rateLimit.ts中实现了基于IP的速率限制。认证端点（如/login,/callback）是否应该使用相同的限制器，还是需要一个更严格的、基于用户ID的限制策略？” - “我注意到
src/utils/logger.ts使用了Winston并集成了Sentry。认证流程中的错误（如无效令牌、OAuth提供商错误）是否应该以error级别记录并上报？” - “前端路由（
src/pages/login.tsx）目前处理登录状态的方式是检查本地存储的令牌。我们是否需要在成功OAuth登录后，增加一个重定向到原请求页面的逻辑？”
这种访谈确保了规格中的每一个任务（Task）都是原子化的、可执行的，避免了“实现登录功能”这种模糊的大项。每一轮访谈的记录都保存下来，形成了宝贵的决策溯源文档。
2.1.3 规格合成与审查
最终生成的SPEC.md是一个结构化的知识库。除了分阶段的任务列表，以下几个部分尤为关键：
- 架构图：用ASCII或Mermaid图描绘系统组件和数据流，让所有参与者对整体设计一目了然。
- 决策日志：一个表格，记录所有重要的技术决策及其理由（例如：“选择直接调用
googleapis而非passport-google-oauth20，因为项目只需Google一家提供商，避免引入不必要的会话中间件。”）。这相当于项目的“设计决策ADR（Architecture Decision Record）”。 - 恢复上下文：在规格生成时，这里可能是空的，或者包含一些初始说明。它的真正价值将在实施阶段体现。
2.2 Implement工作流：按图索骥的精准编码
有了高质量的SPEC.md，/implement命令就变成了一个高效的执行引擎。它的工作模式非常清晰：
- 定位：读取
SPEC.md，找到标记为[in-progress]的阶段，以及该阶段中标记为← current的任务。 - 执行：专注于完成这个当前任务。AI会参考任务描述、相关的决策日志以及“恢复上下文”中的具体指引进行编码。
- 更新：任务完成后，将复选框标记为
- [x]，并可选地将← current标记移动到下一个任务。如果当前阶段的所有任务都完成了，将阶段状态更新为[completed]，并激活下一个[pending]阶段。 - 记录：在实施过程中，如果出现了与原始规格不同的实现（这很常见），就在“偏差记录”表中添加一行，说明“规格计划怎么做”、“实际怎么做”以及“为什么改变”。
- 测试：按照规格中“测试策略”部分的要求，编写相应的单元测试、集成测试。
这个过程的魅力在于它的可中断性和可恢复性。你不需要一口气做完。完成一个小任务后，可以自然地/pause。AI会自动将当前的工作状态——包括正在编辑的文件路径、写到一半的函数名、下一步要调用的API——详细地写入“恢复上下文”。
2.3 生命周期管理：多任务并发的指挥官
现代开发很少是单线程的。Spec Mint Core 的生命周期管理命令让你能像项目管理工具一样操控多个规格。
/list：快速浏览所有规格，按状态（进行中、已暂停、已完成）分组，一目了然。/status <spec-id>：查看某个规格的详细进度报告，包括各阶段完成百分比、当前任务、阻塞项等。/switch <spec-id>：这是核心场景。假设你正在实施“用户认证系统”（user-auth-system），突然需要紧急修复一个“API缓存层”（api-cache）的bug。你只需运行/switch api-cache。Spec Mint Core 会自动：- 对当前活跃的
user-auth-system规格执行一次完整的/pause，保存所有上下文。 - 将
user-auth-system的状态在registry.md中设为paused。 - 加载
api-cache规格，将其状态设为active。 - 读取其“恢复上下文”，让AI直接从上次中断的地方开始工作。
- 对当前活跃的
/resume：当你回到主任务时，一个简单的/resume（或/switch user-auth-system）就能让你瞬间回到之前的编码上下文中，几乎感觉不到中断。
注意事项：虽然Spec Mint Core支持多规格并行，但严禁两个不同的AI工具（或会话）同时操作同一个规格文件。这会导致文件冲突和状态不一致。正确的做法是：一个规格在同一时间只由一个“会话”处理。不同规格之间可以安全地并行。
3. 两种集成模式详解：完整插件与轻量级Skill
Spec Mint Core 提供了两种集成到你的AI编程工具链的方式，适应不同的使用场景和工具偏好。理解它们的区别，能帮你做出最合适的选择。
3.1 路径一：Claude Code 完整插件（功能全开）
这是功能最强大、体验最完整的集成方式。通过Claude Code的插件市场安装后，你将获得一套完整的斜杠命令（/commands）和一个独立的研究员子代理。
安装与激活：
# 在Claude Code界面中，最方便的方式是使用插件市场 /plugin marketplace add ngvoicu/specmint-core /plugin install specmint-core # 或者，你也可以手动克隆到插件目录 git clone https://github.com/ngvoicu/specmint-core.git ~/.claude/plugins/specmint-core安装后，在Claude Code的聊天框中输入/specmint-core:就会自动补全所有子命令。
核心优势：
- 研究员子代理（Opus驱动）：这是
/forge命令强大研究能力的引擎。它不是一个简单的脚本，而是一个被专门调教、用于深度代码分析和综合研究的AI代理。它能理解复杂的代码结构，进行有逻辑的搜索和推理，确保研究阶段的质量。 - 完整的斜杠命令集：
/forge,/implement,/resume,/pause,/switch,/list,/status,/openapi。你几乎不需要手动输入任何关于规格管理的提示词，全部通过直观的命令完成。 - 深度集成体验：命令的输出格式美观，与Claude Code的UI无缝结合，交互体验流畅。
适用场景：如果你主要使用Claude Code进行开发，并且希望获得最强大、最自动化的工作流体验，这是不二之选。
3.2 路径二：通过npx安装的通用Skill（跨工具兼容）
这是Spec Mint Core设计中最巧妙的部分。即使你的主力AI编程工具不是Claude Code（比如你用Cursor、Windsurf、Codex或Gemini CLI），你依然可以享受持久化规格带来的核心好处。这是通过一个名为SKILL.md的文件实现的。
安装原理：SKILL.md是一个精心编写的“教学文档”，它教会AI工具如何理解.specs/目录结构、如何读取和更新SPEC.md文件、以及如何响应“创建规格”、“恢复”、“暂停”等自然语言指令。
运行npx skills add命令，本质上就是把这个SKILL.md文件安装到你对应工具的“技能”或“指令”目录中。例如，对于Cursor，它可能被添加到~/.cursor/instructions目录下。
安装命令示例：
# 为Claude Code安装（仅Skill，无斜杠命令） npx skills add ngvoicu/specmint-core -g -a claude-code # 为Cursor安装 npx skills add ngvoicu/specmint-core -g -a cursor # 为Windsurf安装 npx skills add ngvoicu/specmint-core -g -a windsurf # 为Codex安装 npx skills add ngvoicu/specmint-core -g -a codex # 为Cline安装 npx skills add ngvoicu/specmint-core -g -a cline # 为Gemini CLI安装 npx skills add ngvoicu/specmint-core -g -a gemini工作模式：安装后，你不再使用斜杠命令，而是使用自然语言与你的AI工具交互。工具在每次响应时，都会参考SKILL.md中的指令，从而“学会”了规格工作流。
- 创建规格：你对AI说：“请为‘添加Redis缓存层’创建一个详细的规格说明书。” AI会引导你进行简化的访谈（可能没有研究员代理那么深入），然后生成
SPEC.md。 - 恢复工作：你问：“我上次在做什么？” 或者直接说：“恢复缓存规格的工作。” AI会读取
.specs/registry.md，找到活跃或最新的规格，加载SPEC.md和“恢复上下文”，然后从断点继续。 - 暂停与切换：你说：“先暂停这个，我要去修一下认证的bug。” AI会更新当前规格的上下文并标记为暂停。然后你说：“切换到‘用户认证’规格。” AI就会加载对应的规格并恢复。
核心优势与限制：
- 优势：真正的跨工具兼容。你可以在公司用Cursor，在家用Windsurf，只要它们都配置了同一个
SKILL.md，就能无缝协作同一个项目的规格。规格文件是纯Markdown，是通用的真理来源。 - 限制：没有
/forge命令那种深度的、自动化的研究-访谈循环。研究深度依赖于你给AI的上下文和它自身的知识。没有独立的“研究员子代理”。功能上更依赖于AI工具本身对自然语言指令的理解和执行能力。
3.3 模式对比与选型建议
为了更直观地对比，我将两种模式的核心差异总结如下：
| 特性维度 | Claude Code 完整插件 | npx 安装的通用Skill |
|---|---|---|
深度研究 (/forge) | ✅ 有，由Opus研究员代理执行 | ❌ 无，依赖工具自身能力 |
| 完整斜杠命令 | ✅/forge,/implement,/resume等 | ❌ 无，使用自然语言指令 |
| 研究员子代理 | ✅ 有，专用于深度分析 | ❌ 无 |
| 自动触发（Claude Code） | ✅ 有（如检测到“规划”意图） | ✅ 有（通过Skill指令） |
| 跨工具协作 | ⚠️ 有限（需其他工具也装Skill） | ✅ 优秀（.specs/ 是通用格式） |
| 学习成本 | 低（记命令即可） | 中（需熟悉自然语言指令模式） |
| 功能上限 | 高（全功能工作流） | 中（核心的持久化与恢复） |
选型建议：
- 首选完整插件：如果你的工作流深度绑定Claude Code，且追求最高程度的自动化和研究深度，直接安装完整插件。
- 选择通用Skill：如果你使用多种AI编程工具，或者你的主力工具不是Claude Code（如Cursor重度用户），那么安装对应的Skill是最佳选择。它确保了工作流的一致性。
- 混合使用：实际上，你可以在Claude Code上安装完整插件以获得最佳创作（
/forge）体验，同时在Cursor等工具上安装Skill，以便在需要时用其他工具进行简单的修改或查阅。只要遵守“同一时间只用一个工具操作一个规格”的规则，它们可以和平共处。
4. SPEC.md 文件格式详解：你的项目记忆中枢
.specs/<spec-id>/SPEC.md文件是Spec Mint Core工作流的核心载体。它不仅仅是一个任务清单，更是一个结构化的项目知识库。理解其每个部分的构成和最佳实践，能让你更好地驾驭这个工具。
4.1 文件结构与元数据（Frontmatter）
文件以YAML格式的Frontmatter开头，这定义了规格的基本属性和状态。这些元数据是.specs/registry.md索引生成的依据。
--- id: user-auth-system # 必填。URL安全的标识符，用于命令引用（如 /switch user-auth-system） title: User Auth System # 必填。人类可读的标题 status: active # 必填。状态：active, paused, completed, archived created: 2026-02-10 # 必填。创建日期（ISO 8601） updated: 2026-02-11 # 必填。最后更新日期 priority: high # 可选。优先级：high, medium, low (默认 medium) tags: [auth, security, backend] # 可选。标签数组，用于分类过滤 ---实操要点：
id一旦确定，尽量不要修改，因为其他命令（如/switch）和内部索引都依赖它。status是工作流引擎的关键。active表示正在处理；paused表示已保存上下文等待恢复；completed表示所有任务完成；archived可用于历史参考或废弃的规格。updated字段应该在任何实质性修改后（如完成任务、更新决策日志）由AI自动更新。
4.2 主体内容：从概述到任务分解
Frontmatter之后是Markdown格式的主体内容。
概述（Overview）： 用一两段话简要说明这个规格的目标、范围和核心设计决策。这是给任何新加入项目的人（包括未来的你）的快速导读。
阶段（Phases）与任务（Tasks）： 这是规格的执行蓝图。阶段将项目分解为逻辑上连贯的里程碑，任务则是每个阶段内原子化的行动项。
## Phase 1: Foundation [completed] - [x] [AUTH-01] Set up auth middleware in src/middleware/auth.ts - [x] [AUTH-02] Create User model with Prisma schema - [x] [AUTH-03] Implement JWT generation and verification in src/auth/tokens.ts - [x] [AUTH-04] Add refresh token rotation ## Phase 2: OAuth Integration [in-progress] - [x] [AUTH-05] Google OAuth provider - [ ] [AUTH-06] GitHub OAuth provider ← current - [ ] [AUTH-07] Token exchange flow for both providers ## Phase 3: Testing & Hardening [pending] - [ ] [AUTH-08] Unit tests for auth middleware - [ ] [AUTH-09] Integration tests for OAuth flow - [ ] [AUTH-10] Rate limiting on auth endpoints格式规范：
- 阶段状态：用
[pending],[in-progress],[completed],[blocked]明确标识。 - 任务编码：
[PREFIX-NN]格式，如[AUTH-01]。前缀通常与规格ID或模块相关，数字全局唯一递增。这便于在代码审查、会议或问题追踪中精确引用。 - 复选框：
- [ ]表示未开始，- [x]表示已完成。这是AI和人类都能快速解析的进度可视化。 - 当前任务标记：
← current标记紧跟在任务描述后。这是/implement和/resume命令定位执行位置的依据。 - 不确定性标记：如果某个任务在规划时还存在模糊点，可以标记为
[AUTH-XX] [NEEDS CLARIFICATION] ...，提醒在实施前需要进一步明确。
4.3 核心知识章节：决策、上下文与偏差
规格的真正力量在于这些“非任务”部分，它们记录了项目的“为什么”和“发生了什么”。
架构图与技术选型： 在概述之后，可以插入ASCII或Mermaid格式的架构图、数据流图或ER图。紧接着，应该有一个库/技术选型对比表。这个表记录了评估过的选项、最终选择及其理由，是宝贵的决策记录。
测试策略： 明确说明将如何进行测试。例如：
- 单元测试：使用Jest，针对
src/auth/tokens.ts中的generateToken和verifyToken函数。 - 集成测试：使用Supertest，测试
/auth/google/callback端点的完整OAuth流。 - E2E测试：使用Cypress，模拟用户从点击登录按钮到跳转回首页的全流程。
- 安全测试：检查JWT是否设置了合适的过期时间、是否使用了强密钥。
恢复上下文（Resume Context）： 这是实现“可恢复性”的魔法所在。它通常是一个引用块（>），里面用自然语言详细描述了中断时的精确状态。
> Finished Google OAuth. GitHub OAuth callback handler is in progress at > `src/auth/oauth/github.ts`. The authorization URL redirect works but > the callback endpoint at `/auth/github/callback` needs to exchange the > code for tokens. Use the same pattern as Google in `src/auth/oauth/google.ts` > lines 45-82. The GitHub OAuth app credentials are in `.env` as > GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.编写要点：上下文应包含具体文件路径、函数名、行号、环境变量名、下一步要调用的API等。越具体，恢复就越精准。
决策日志（Decision Log）： 以表格形式记录所有重要的、非显而易见的决策。
| Date | Decision | Rationale |
|---|---|---|
| 2026-02-10 | JWT over sessions | Stateless, scales for microservices |
| 2026-02-10 | Refresh token rotation | Limits damage from stolen tokens |
| 2026-02-11 | Prisma over raw SQL | Already used in the project for other models |
这个日志是项目演进的“考古学”记录，能有效防止团队在未来因为遗忘而重新讨论已定案的设计。
偏差记录（Deviations）： 计划赶不上变化。在实施过程中，如果发现更好的方法或遇到无法按计划实施的障碍，就在这里记录。
| Task | Spec Said | Actually Did | Why |
|---|---|---|---|
| AUTH-05 | Use passport.js | Direct googleapis calls | Simpler for a single provider, avoids passport session overhead |
记录偏差不是失败，而是学习和知识积累。它解释了最终代码为什么与最初设计不同。
5. 高级技巧、常见问题与生态集成
掌握了基础工作流和文件格式后，我们来看看如何更高效地使用Spec Mint Core，解决可能遇到的问题，并探索它与其它工具集成的可能性。
5.1 高效使用技巧与最佳实践
从“小规格”开始：如果你是第一次使用，不要一开始就规划一个“重写整个单体应用为微服务”的巨型规格。从一个明确、边界清晰的小功能开始，比如“为
/api/users端点添加分页”。这能让你快速熟悉整个工作流，建立信心。善用访谈阶段：当AI在
/forge的访谈中提问时，请尽可能提供具体、有上下文的回答。例如，当它问“应该采用哪种错误处理模式？”时，不要只说“用那个通用的”，而是可以回答：“参考我们在src/utils/errorHandler.ts里定义的ApiError类和全局中间件，新的认证错误应该继承这个类，并确保能被同一个中间件捕获和格式化。” 这能引导AI生成更贴合你项目现状的规格。规格的版本控制：
.specs/目录应该被纳入Git版本控制（除非你像本项目一样在.gitignore中排除了它用于本地测试）。这带来了巨大好处：- 协作：团队成员可以查看、评审甚至直接修改规格文件。
- 追溯：你可以看到规格是如何随着项目演进的，决策是如何做出的。
- 回滚：如果某个实现方向被证明是错误的，你可以回退到之前某个版本的规格，并基于它重新开始。
将规格作为沟通工具：
SPEC.md不仅是给AI看的，也是给人看的。在团队站会或代码评审前，分享相关规格的链接。它比口头描述或零散的聊天记录更能清晰地传达功能范围、设计决策和当前进度。定期回顾与归档：对于已
completed的规格，不要急于删除。可以将其状态改为archived。它们构成了项目的“功能实现档案”，未来在修改、调试或 onboarding 新成员时极具参考价值。
5.2 常见问题与排查实录
在实际使用中，你可能会遇到一些典型情况。以下是我踩过坑后总结的应对方法。
问题1：AI在/implement时似乎“忘记”了规格的细节，写出了不符合设计的代码。
- 可能原因：AI的上下文窗口有限，如果
SPEC.md文件非常长（比如超过上万字），后面的任务细节可能无法被有效关注。 - 解决方案：
- 分阶段实施：使用
/implement phase 2这样的命令，只让AI关注当前阶段的任务，减少上下文负担。 - 强化“恢复上下文”：在
pause时，确保“恢复上下文”部分写得极其具体，明确指出下一步要修改的文件、函数、甚至代码行。 - 手动引导：如果发现AI跑偏，可以中断它，然后说：“请重新仔细阅读
SPEC.md中‘Phase 3’部分关于测试策略的描述，特别是对authMiddleware进行单元测试的要求。” 然后将正确的代码片段提供给它参考。
- 分阶段实施：使用
问题2：在多个AI工具（如Cursor和Claude Code）间切换时，规格状态似乎混乱了。
- 可能原因：违反了“同一时间只用一个工具操作一个规格”的规则。两个工具几乎同时读写
.specs/registry.md或同一个SPEC.md文件，导致状态覆盖或冲突。 - 解决方案：
- 严格遵守规则：这是最重要的。在切换工具前，确保在旧工具中已正确执行了
/pause或让AI完成了当前原子任务并更新了状态。 - 检查状态文件：如果怀疑状态混乱，直接打开
.specs/registry.md和出问题的SPEC.md文件，手动检查status、updated时间和← current标记是否正确。 - 手动同步：如果发现冲突，以最新、最接近真实进度的文件为准，手动修改另一个文件使其一致。
- 严格遵守规则：这是最重要的。在切换工具前，确保在旧工具中已正确执行了
问题3：/forge的研究阶段耗时很长，或者给出的方案不切实际。
- 可能原因：研究范围过于宽泛，或者AI缺乏足够的项目上下文。
- 解决方案：
- 提供更精确的指令：在
/forge命令中增加约束。例如：/specmint-core:forge "add server-side caching using Redis, reusing the connection pool pattern from src/db/redis.ts"。 - 利用 Kluris（如果已集成）：如前所述，Kluris 能为AI提供项目的“部落知识”，让研究更接地气。
- 人工干预研究：你可以手动创建或补充
.specs/<id>/research-01.md文件，放入你已知的技术方案、参考链接或决策约束，然后重新运行/forge，AI会以此为基础进行访谈和规格制定。
- 提供更精确的指令：在
问题4：生成的规格任务过于琐碎或过于宏大。
- 可能原因：AI对任务粒度的把握可能不总是完美。
- 解决方案：在访谈阶段进行校准。如果AI提出的任务像“在文件中引入依赖”这么细，你可以说：“这个任务可以合并到‘实现XXX函数’里。” 如果任务像“构建整个通知微服务”这么大，你可以说：“请将这个阶段拆分为‘设计消息队列模型’、‘实现生产者服务’、‘实现消费者服务’三个更具体的任务。” 访谈阶段正是用来做这种调整的。
5.3 生态集成：与Kluris配对使用
Spec Mint Core 解决了“代码上下文”的持久化问题，而 Kluris 旨在解决“部落知识”（Tribal Knowledge）的持久化问题——那些从未写入注释的架构决策、历史事故复盘、供应商怪癖、以及每个奇怪选择背后的“为什么”。
当两者结合时，/forge的研究阶段（Phase 1）就不仅仅是读代码和搜网页了。它可以查询你通过Kluris构建的“项目大脑”，获得更深层次的上下文。
工作流程示例：
- 你运行
/specmint-core:forge "add audit logging for financial transactions"。 - Phase 1a: AI像往常一样扫描代码库。
- Phase 1b: AI自动（或你手动触发）查询Kluris大脑：
/kluris-project-brain what's our existing logging standard and have we had any incidents related to audit trails? - 大脑返回信息：“我们所有服务都使用结构化JSON日志，通过Fluentd收集到Elasticsearch。去年曾因日志字段不一致导致审计失败，之后约定所有金额字段必须以‘cents’为单位存储为整数。”
- 基于这些信息，AI在访谈中会提出更精准的问题，并最终生成的规格会包含“遵循现有JSON日志结构”、“金额字段统一转换为分（cents）存储”等具体任务和决策记录。
这种结合让AI的规划能力建立在坚实的“项目记忆”之上，避免了重复发明轮子或重蹈覆辙。
安装Kluris：
# 使用pipx安装 pipx install kluris # 启动本地服务 kluris wake-up # 然后通过Web界面或API向你的“大脑”里添加知识Spec Mint Core 代表了一种AI辅助编程范式的进化：从临时的、对话驱动的互动，转向持久的、文档驱动的协作。它将AI从一个“聪明的临时工”，变成了一个拥有“项目记忆”和“工作流程”的持久化伙伴。通过将规划、决策和进度物化为可版本控制的文件，它不仅解决了AI的“健忘症”，更为团队协作、知识传承和复杂项目管理提供了坚实的基础。无论你是独立开发者还是团队一员，开始将你的AI编程会话转化为.specs/目录下那些结构清晰的Markdown文件，你会发现自己对项目的控制力和理解深度都达到了一个新的层次。这不仅仅是让AI更好地为你工作，更是让你和AI一起，更专业地构建软件。
