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一个非常聪明的设计是它的解析顺序。当框架需要寻找一个工作流定义、一份文档或一条规则时它会按照以下优先级进行项目本地首先查找当前项目下的.speclite/目录。用户级如果项目本地没有则查找用户主目录下的~/.speclite/。内置最后才回退到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_DIRAI会扫描项目结构识别出已有的package.json、路由文件、数据库模型等。生成的research.md会指出“项目使用Express.js和Mongoose”“目前没有/api/auth路由”“需要创建User模型”。同时它会在index/子目录下创建代码文件的索引便于后续引用。基于清晰的需求和现状分析plan阶段会制定实施方案。./tools/run-phase.sh plan $RUN_DIR打开plan.md你会看到一个分步计划创建UserMongoose Schema包含邮箱、哈希密码、创建时间。创建/api/auth/register和/api/auth/login路由处理器。实现使用argon2的密码哈希与验证工具函数。实现使用jsonwebtoken库的JWT签发与验证中间件。将认证中间件应用到需要保护的路由。编写集成测试。这个计划就是我们的开发蓝图避免了想到哪写到哪的混乱。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 testAI会运行测试命令并将输出记录在案。它还会根据项目规则例如.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 常见问题速查表问题现象可能原因解决方案运行./tools/run-phase.sh时报“命令未找到”或权限错误。1. 未给脚本添加执行权限。2. 在错误目录下执行。1. 在SpecLite根目录执行chmod x tools/*.sh。2. 确保在SpecLite项目目录下执行命令或使用绝对路径。AI在implementation阶段生成的代码不符合项目规范。1. 项目本地.speclite/rules/规则未正确定义或缺失。2. AI模型未正确读取规则文件。1. 检查并完善.speclite/rules/下的规则文件确保描述清晰具体。2. 在阶段命令后添加--verbose标志查看AI是否加载了正确的规则。validation阶段测试失败但AI没有给出修复建议。validation阶段默认只运行命令和记录输出分析能力取决于AI。手动进入debug工作流/speclite-debug将测试失败日志提供给它让其分析原因并提供修复方案。运行产物runs/目录变得非常庞大。每次运行都会生成新目录长期积累会占用空间。定期清理旧的、不重要的运行记录。可以将有价值的runs/目录下的产物摘要整理到项目Wiki或.speclite/docs/中然后删除原始目录。在团队中不同成员生成的运行产物格式不一致。可能使用了不同版本的SpecLite或本地/全局配置不同。团队统一SpecLite版本并将核心的.speclite/配置如project.md、关键rules纳入版本控制。6.2 提升效率的实战心得从“前门工作流”开始而非直接调用“骨干阶段”对于大多数日常任务直接使用brainstorm、enhance、debug这些高级命令。它们内部会智能地调用和组合多个骨干阶段你不需要手动管理每个阶段。只有当你有非常明确、线性的任务时比如就是写一份技术调研才直接调用discovery。精心维护.speclite/rules/这是框架的“灵魂”规则文件的质量直接决定AI输出代码的质量。不要写“代码要整洁”这种模糊规则要写“函数长度不超过50行”、“使用async/await而非回调”、“错误信息必须本地化并记录到error.log”。越具体AI执行得越好。可以分门别类地创建文件如naming-rules.md、api-rules.md、security-rules.md。善用research阶段生成的项目索引在大型或陌生项目中research阶段生成的index/目录是你快速熟悉代码的利器。它相当于AI为你创建的一份实时代码地图比静态的文档更准确。将运行记录用于代码审查和知识分享在团队协作中不要只提交代码。将本次任务对应的runs/run_id/目录的压缩包或关键产物如requirements.md和plan.md作为PR的一部分附上。这能让审查者快速理解改动背景和设计思路极大提升审查效率。不必强求完整流程SpecLite是模块化的。如果你只是修复一个拼写错误直接用编辑器功能就好没必要走debug工作流。它的价值体现在需要决策、设计和验证的复杂任务上。对于简单任务过度使用反而会降低效率。SpecLite不是一个银弹它不会自动写出完美的代码。它是一个思维框架和协作协议强迫或者说鼓励我们在AI辅助编程时进行结构化思考并将思考过程沉淀下来。它带来的最大改变是让AI编程从一次性的、不可追溯的对话变成了可积累、可审查、可复用的工程实践。对于追求长期项目健康和团队协作效率的开发者来说这份“慢下来”的投入绝对是值得的。