SpecLite：AI编程时代的结构化工作流框架设计与实践

1. 项目概述：SpecLite，一个为AI编程时代设计的结构化工作流框架

如果你和我一样，在过去一年里深度使用过Cursor、Claude Code这类AI编程工具，那你一定经历过这种场景：脑子里有个新功能的想法，于是打开AI助手，开始一段漫长的对话。你描述需求，AI生成代码，你指出问题，AI修改，几个回合下来，聊天记录已经长得看不清来龙去脉。最后代码是写出来了，但为什么选择这个方案？中间考虑了哪些备选？测试覆盖了哪些边界情况？这些关键决策就像水消失在水中，全埋在了聊天历史里。下次遇到类似需求，或者需要同事接手时，又得从头再来一遍。这就是典型的“高动量、低记忆”AI工作流——速度快，但毫无积累。

SpecLite就是为了解决这个问题而生的。它不是一个简单的提示词合集，而是一个基于产物的AI工作流框架。它的核心思想很直接：把AI辅助编程过程中那些本该被记录下来的关键决策——需求分析、技术调研、实施方案、验证逻辑——变成结构化的、可审查的、可复用的文本产物，保存在你的项目目录里。简单说，它试图在AI编程的“狂野西部”和传统软件工程的“繁文缛节”之间，找到一条实用的中间道路。

这个框架特别适合三类人：一是像我这样的独立开发者，希望AI辅助编程能更可控、更有条理；二是小团队，需要一套标准化的AI协作流程来保证代码质量；三是任何重度使用Cursor、Claude Code、Codex或Kiro，并受困于上下文丢失和决策追溯难题的工程师。它不强制你改变工具链，而是为你现有的AI编辑器（目前支持上述四个）增加一层轻量但坚固的“决策骨架”。

2. 核心设计理念：为什么是“产物优先”和“规范驱动”？

要理解SpecLite的价值，得先看看主流AI编程工作流到底缺了什么。我们通常的流程是线性的、对话式的：提问 -> 生成 -> 反馈 -> 再生成。这个过程有两个致命弱点。

第一，决策上下文是瞬态的。所有关于“为什么这么做”的推理都存在于AI模型的临时上下文中，一旦对话滚动或重启，这些上下文就消失了。你只得到了最终的代码这个“果”，却丢失了产生这个“果”的“因”。这导致代码库的知识无法沉淀，变成了所谓的“部落知识”——只有当时在场（在对话中）的人才知道。

第二，验证是模糊且非结构化的。我们通常会让AI“写点测试”，但测试覆盖哪些场景、边界条件是什么、通过标准如何，这些往往又是一段新的、可能丢失的对话。没有结构化的验证记录，你就无法系统地回答“我们怎么知道这代码是对的？”这个问题。

SpecLite的“产物优先”正是针对这两个弱点。它把软件开发生命周期中那些关键的、非代码的产出物——需求文档、调研报告、实施计划、验证总结——强制具象化为项目目录下的Markdown文件。每一次AI驱动的开发任务，都会生成一个独立的runs/<run_id>/目录，里面按阶段存放着这些产物。这样，决策过程从AI的“黑箱记忆”变成了团队可检视、可差异比较、可版本控制的“白纸黑字”。

而“规范驱动”则是它的执行引擎。SpecLite在项目根目录的.speclite/文件夹里，允许你定义项目专属的文档、规则和工作流。比如，你可以在.speclite/rules/下放一个api-design.md，规定“所有REST API响应必须包裹在{data: ..., error: null}的结构中”。当AI在执行implementation阶段时，它会优先参考这些本地规则，而不是完全依赖其内部知识或泛泛的最佳实践。这让AI的代码生成不再是“天马行空”，而是被项目自身的约定所“锚定”。

这种设计带来了一个根本性的转变：从“AI根据对话历史猜测项目该怎么建”，变成了“项目主动告诉AI它应该怎么被构建”。项目通过.speclite/层拥有了“表达自身规则”的能力。

3. 框架的四层架构与解析顺序

SpecLite的威力来自于它清晰的分层设计。它不是一堆散落的脚本，而是一个由四层构成的完整框架，每一层都有明确的职责。

3.1 核心四层：工作流、文档、规则与运行记录

第一层：工作流。这是用户交互的入口，定义了“事情怎么做”。它分为“前门工作流”和“骨干阶段”。前门工作流如brainstorm、debug，是你日常直接调用的高级命令，用户体验友好。骨干阶段如discovery、implementation，是构成SDLC的具体、原子化的步骤，产生具体的产物。你可以把前门工作流看作是对骨干阶段的一种智能编排和封装。

第二层：文档。存放在.speclite/docs/下，这是项目的“长期记忆”。它可以包括架构决策记录、核心模块说明、第三方服务集成指南等。当AI执行research阶段时，它会首先查阅这些文档来理解代码库的上下文，避免重复劳动或做出与既有架构冲突的决定。

第三层：规则。存放在.speclite/rules/下，这是项目的“宪法”。它规定了代码应该遵循的编码规范、安全要求、性能指标、API设计模式等。例如，一个naming-convention.md可以规定使用驼峰命名法，而error-handling.md可以规定所有异步操作必须进行try-catch包装并记录日志。这些规则在implementation和validation阶段会被强制执行或作为检查依据。

第四层：运行记录。这是每次执行产生的“短期记忆”，存放在runs/<run_id>/下。它完整记录了本次任务从发起到结束的所有产物，形成了一个可审计的轨迹。这对于复盘、协作和知识传递至关重要。

3.2 关键机制：解析顺序与本地覆盖

SpecLite一个非常聪明的设计是它的解析顺序。当框架需要寻找一个工作流定义、一份文档或一条规则时，它会按照以下优先级进行：

1. 项目本地：首先查找当前项目下的.speclite/目录。
2. 用户级：如果项目本地没有，则查找用户主目录下的~/.speclite/。
3. 内置：最后才回退到SpecLite框架自带的默认内容。

这个顺序是SpecLite灵活性的基石。它意味着：

• 高度可定制：你可以为特定项目创建完全定制的工作流或规则，而不会影响其他项目。
• 配置显式化：所有定制都体现在文件系统中，一目了然，没有隐藏的魔法。
• 便于团队共享：将定制好的.speclite/目录提交到版本库，团队所有成员就自动继承了一致的工作流和规范。

举个例子，你的公司可能有一套内部的安全编码规范。你可以在~/.speclite/rules/security.md中定义这些通用规则。然后，在为某个特定前端项目工作时，你发现它还需要特殊的XSS防护规则，你可以在该项目的.speclite/rules/security.md中增加或覆盖相关条目。当AI为这个前端项目生成代码时，它会合并应用这两套规则，且项目本地的规则优先级更高。

实操心得：在团队中推广SpecLite时，我建议第一步就是建立一个共享的~/.speclite/配置库，包含团队共识的基础规则和常用工作流模板。然后鼓励各项目根据自身特点在本地.speclite/中进行细化。这既能保证一致性，又不失灵活性。

4. 完整工作流实战：从零构建一个用户认证模块

理论说得再多，不如动手试一次。假设我们正在开发一个Node.js后端服务，现在需要增加一个用户邮箱登录和JWT令牌颁发的认证模块。我们将使用SpecLite的完整流程来驱动这个任务。

4.1 环境准备与项目初始化

首先，确保你已经克隆了SpecLite仓库，并运行了安装脚本。然后，在你的Node.js项目根目录下，初始化SpecLite框架层。

# 在你的项目目录下执行 cp -R /path/to/speclite/templates/project/.speclite ./

这会在你的项目下创建基础的.speclite目录结构。接着，我们为这次“添加认证模块”的任务创建一个独立的运行目录。

# 在SpecLite工具目录下执行 RUN_DIR=$(./tools/new-run.sh "Add user authentication with email and JWT") echo "本次运行目录：$RUN_DIR"

这个$RUN_DIR（例如runs/20240517_142022_add_auth/）将是本次任务所有产物的家。

4.2 阶段一：探索与需求澄清

在盲目开始写代码前，我们先进行discovery和requirements阶段。discovery阶段关注外部最佳实践和技术选型。

./tools/run-phase.sh discovery "$RUN_DIR" --topics "JWT authentication best practices, Node.js auth libraries (Passport.js, express-jwt), secure password hashing (bcrypt, argon2), session management alternatives"

执行后，查看$RUN_DIR/discovery/discovery.md，你会发现AI已经为你整理了一份调研报告，比较了Passport.js策略和手动express-jwt的优劣，列出了bcrypt和argon2的选用场景，甚至提到了防范时序攻击。这些信息不再是聊天记录里的只言片语，而是结构化的文档。

接下来，用requirements阶段来明确我们的具体需求。

./tools/run-phase.sh requirements "$RUN_DIR"

你需要与AI交互，回答它关于用户故事、功能范围、非功能需求（如安全性、性能）的问题。完成后，$RUN_DIR/requirements/requirements.md会清晰定义出：“作为用户，我可以用邮箱和密码登录，获取一个JWT令牌”，“令牌有效期2小时”，“密码必须用argon2id算法加盐哈希存储”等具体条款。

4.3 阶段二：研究与计划制定

现在，让AI分析我们现有的代码库，这就是research阶段。

./tools/run-phase.sh research "$RUN_DIR"

AI会扫描项目结构，识别出已有的package.json、路由文件、数据库模型等。生成的research.md会指出：“项目使用Express.js和Mongoose”，“目前没有/api/auth路由”，“需要创建User模型”。同时，它会在index/子目录下创建代码文件的索引，便于后续引用。

基于清晰的需求和现状分析，plan阶段会制定实施方案。

./tools/run-phase.sh plan "$RUN_DIR"

打开plan.md，你会看到一个分步计划：

1. 创建UserMongoose Schema（包含邮箱、哈希密码、创建时间）。
2. 创建/api/auth/register和/api/auth/login路由处理器。
3. 实现使用argon2的密码哈希与验证工具函数。
4. 实现使用jsonwebtoken库的JWT签发与验证中间件。
5. 将认证中间件应用到需要保护的路由。
6. 编写集成测试。

这个计划就是我们的开发蓝图，避免了想到哪写到哪的混乱。

4.4 阶段三：实施、验证与版本控制

重头戏implementation阶段开始。AI会根据之前的产物（需求、研究、计划）以及项目本地规则，开始生成代码。

./tools/run-phase.sh implementation "$RUN_DIR"

这个过程可能是交互式的。AI可能会问你：“我发现项目里没有.env文件管理密钥，你是希望我创建一个.env.example，还是直接使用config.js？” 你的回答也会被记录在implementation.md中。最终，所有新建或修改的代码片段都会附在这个文档里，并说明修改原因。

代码写完了，但还没结束。validation阶段确保代码质量。

./tools/run-phase.sh validation "$RUN_DIR" --test-cmd "npm test"

AI会运行测试命令，并将输出记录在案。它还会根据项目规则（例如，.speclite/rules/里可能定义了“所有路由必须有单元测试”）来检查实现是否合规。validation.md会总结测试通过情况、静态分析结果（如果配置了）以及任何发现的警告。

最后，version-control阶段帮你整理这次修改。

./tools/run-phase.sh version-control "$RUN_DIR" --status --commit "feat: add email/password authentication with JWT"

这个阶段会运行git status、git diff等命令，将结果保存，并可以辅助生成符合约定式提交的提交信息。所有差异都保存在version-control/目录下，方便代码审查。

至此，一个功能从构思到提交，全过程都被结构化的产物记录了下来。$RUN_DIR就是一个完整的、自包含的任务档案。

5. 编辑器集成与日常高效使用技巧

SpecLite的强大之处在于它无缝融入了你现有的AI编程环境。你不需要离开熟悉的编辑器去使用它。

5.1 配置与使用：以Cursor为例

在Cursor中，SpecLite通过.cursor/rules/下的规则文件来集成。你需要将SpecLite提供的integrations/cursor/下的文件复制到你的项目或全局配置中。

# 全局安装，对所有项目生效 cp -R /path/to/speclite/integrations/cursor/* ~/.cursor/ # 或项目本地安装，仅对当前项目生效 cp -R /path/to/speclite/integrations/cursor/.cursor ./

配置完成后，在Cursor的命令面板中，你就会看到一系列/speclite-开头的命令，比如/speclite-brainstorm、/speclite-debug。当你输入/speclite-brainstorm并描述“我想给购物车加一个优惠券功能”时，Cursor会调用SpecLite的brainstorm工作流，引导你进行结构化头脑风暴，并将结果输出到指定的运行目录，而不是散落在聊天窗口。

对于Claude Code、Codex和Kiro，集成方式类似，都是通过复制对应的配置文件到特定目录。这使得你可以在不同编辑器间切换，而你的SpecLite工作流和项目规则保持一致。

5.2 高级技巧：自定义工作流与技能

SpecLite的灵活性允许你创建完全自定义的工作流。比如，你的团队可能有一个标准的“代码审查”流程，包括检查单元测试、运行linter、生成复杂度报告。你可以创建一个自定义工作流。

./bin/speclite workflow new code-review

这会在.speclite/workflows/下创建一个code-review.md模板。你可以在这个模板里定义该工作流由哪些阶段组成（例如，直接调用research和validation），以及每个阶段的默认参数。之后，你就可以通过/speclite-code-review命令来一键执行这个定制流程。

技能是更细粒度的复用单元。在.speclite/skills/下，你可以定义一些可复用的操作指令，比如“如何安全地连接Redis”、“如何构造分页响应”。在后续的implementation阶段，AI可以直接引用这些技能，确保操作的一致性。

注意事项：编辑器集成文件（如.cursor/、.claude/）通常不应该提交到版本库，除非你的整个团队都使用同一款编辑器并决定共享配置。而.speclite/目录，如果包含了有价值的项目文档和规则，则应该被提交。这确保了项目知识得以传承。

6. 常见问题排查与实战经验分享

在实际使用SpecLite几个月后，我积累了一些踩坑经验和高效使用的心得。

6.1 常见问题速查表

6.2 提升效率的实战心得

1. 从“前门工作流”开始，而非直接调用“骨干阶段”：对于大多数日常任务，直接使用brainstorm、enhance、debug这些高级命令。它们内部会智能地调用和组合多个骨干阶段，你不需要手动管理每个阶段。只有当你有非常明确、线性的任务时（比如就是写一份技术调研），才直接调用discovery。

2. 精心维护.speclite/rules/，这是框架的“灵魂”：规则文件的质量直接决定AI输出代码的质量。不要写“代码要整洁”这种模糊规则，要写“函数长度不超过50行”、“使用async/await而非回调”、“错误信息必须本地化并记录到error.log”。越具体，AI执行得越好。可以分门别类地创建文件，如naming-rules.md、api-rules.md、security-rules.md。

3. 善用research阶段生成的项目索引：在大型或陌生项目中，research阶段生成的index/目录是你快速熟悉代码的利器。它相当于AI为你创建的一份实时代码地图，比静态的文档更准确。

4. 将运行记录用于代码审查和知识分享：在团队协作中，不要只提交代码。将本次任务对应的runs/<run_id>/目录的压缩包或关键产物（如requirements.md和plan.md）作为PR的一部分附上。这能让审查者快速理解改动背景和设计思路，极大提升审查效率。

5. 不必强求完整流程：SpecLite是模块化的。如果你只是修复一个拼写错误，直接用编辑器功能就好，没必要走debug工作流。它的价值体现在需要决策、设计和验证的复杂任务上。对于简单任务，过度使用反而会降低效率。

SpecLite不是一个银弹，它不会自动写出完美的代码。它是一个思维框架和协作协议，强迫（或者说鼓励）我们在AI辅助编程时进行结构化思考，并将思考过程沉淀下来。它带来的最大改变，是让AI编程从一次性的、不可追溯的对话，变成了可积累、可审查、可复用的工程实践。对于追求长期项目健康和团队协作效率的开发者来说，这份“慢下来”的投入，绝对是值得的。