AI协同开发新范式：基于规范驱动的Agentic Workflows实践

1. 项目概述告别碎片化用“活的”规范驱动AI协同开发如果你和我一样每天都在跟Claude Code、Cursor这类AI编程工具打交道那你肯定也经历过这种痛苦想实现一个复杂功能得先花十几分钟给AI解释一遍项目背景、技术栈、之前的架构决策然后切换到实现细节再切回来检查代码风格最后还得考虑安全和性能。整个过程就像在十几个浏览器标签页和一堆零散的笔记之间反复横跳上下文切换的成本高得吓人。我最近深度体验了一个叫Agentic Workflows - SpecGen的开源项目它彻底改变了我的工作流。简单来说它不是一个新工具而是一套基于Claude Code的“优雅的上下文工程解决方案”。核心思想是让AI智能体Agent之间能“对话”和“记忆”。通过创建一系列专门化的智能体比如架构师、工程师、安全审查员并让它们围绕一份“活的”项目规范文档协同工作把复杂的开发任务变成一场顺畅的对话。你不再需要反复解释智能体会记住项目的所有上下文并在此基础上接力构建。这解决了我们日常开发中的一个核心痛点知识的持久化和传承。传统的AI对话是“健忘”的每次新对话都是一次重启。而SpecGen通过Model Context ProtocolMCP将项目分析、架构决策、实现细节全部沉淀为结构化的Markdown规范文件。这些文件成为项目唯一的“真相源”所有后续的智能体工作都基于此展开实现了真正的累积式学习和开发。2. 核心设计理念为什么“规范驱动”是AI辅助开发的未来在深入实操之前我们必须先理解SpecGen背后的设计哲学。这不仅仅是几个脚本的堆砌而是一套完整的、关于如何与AI协作进行软件开发的方法论。2.1 从“一次性问答”到“持续协作”传统的AI编码模式是“问答式”的。你提出一个问题“如何实现用户登录”AI给出一段代码。这个循环是封闭的、一次性的。下一次你想实现“记住登录状态”又得从头解释一遍什么是session、项目用了什么框架。SpecGen倡导的是“协作式”开发。它将开发过程解构为三个明确的阶段每个阶段由专门的智能体负责并通过规范文件传递上下文架构分析阶段/architect智能体登场。它的任务不是直接写代码而是深入分析你的需求研究你的代码库现有模式并生成一份详细的《功能规范》。这份规范会包含API设计、数据库Schema变更、前后端交互逻辑、潜在的技术选型建议等。工程实现阶段/engineer智能体接手。它直接阅读上一步生成的规范文件理解所有架构决策然后生成符合项目现有风格和约定的、可直接运行的代码。因为它“知道”整个设计背景所以生成的代码一致性极高。审查优化阶段/reviewer智能体及其背后的质量、性能、安全等子智能体对生成的代码进行多维度审查发现问题并提出修改建议这些建议同样会被记录回规范中形成知识闭环。这个流程模仿了优秀研发团队的协作模式让AI扮演了不同角色从而大幅提升了输出的质量和可维护性。2.2 “活的规范”作为单一事实来源这是SpecGen最精妙的设计。规范Specification不是一份写完就丢的文档而是一个随着项目演进而动态更新的知识库。自动生成与关联每次使用/architect命令都会生成一个类似SPEC-20250105-user-profiles.md的文件。这个文件有唯一的ID包含了时间戳和功能描述。结构化存储规范文件不是杂乱无章的。它通常包含“需求概述”、“架构设计”、“API端点”、“数据库变更”、“前端组件”、“测试策略”、“待决策项”等章节。这种结构是智能体之间沟通的“协议”。上下文持久化当engineer智能体去实现时它通过MCP协议读取这份规范完全继承了architect的全部思考。审查员的意见也会作为“修订记录”追加到文件中。这意味着三个月后任何开发者人或AI看到这份规范都能完全理解这个功能当时的完整决策链路。实操心得我最初低估了规范文件的力量。直到有一次我需要重构一个两个月前由AI协助开发的功能。我直接找到对应的SPEC文件里面清晰地记录了为什么选择A方案而非B方案考虑了哪些边界情况。这比翻看零散的Git提交记录和原始的Claude聊天历史要高效十倍。这本质上是在为你的项目构建一个可查询、可追溯的“开发记忆”。3. 核心组件深度解析与实战配置SpecGen项目主要由两大核心部分组成Claude Code工作流配置和SpecGen MCP服务器。理解它们各自的作用和交互方式是灵活使用和定制的基础。3.1 Claude Code工作流配置 (/core-workflows)这部分是一系列预定义的配置告诉Claude Code如何扮演不同的角色以及如何使用工具即MCP服务器。Agents智能体目录这里定义了8个各司其职的专家智能体。你可以把它们想象成一个开发团队中的不同成员。backend-explorer专门分析后端代码结构、路由、控制器和业务逻辑模式。frontend-explorer专注于前端组件、状态管理、UI库和样式体系。database-explorer负责解读数据库模型、关系、迁移脚本和查询模式。integration-explorer分析第三方API集成、Webhook和服务间通信。researcher负责调研最佳实践、新技术选型和解决特定技术难题。quality/performance/security三个审查员分别从代码质量、性能指标和安全漏洞角度进行专项审查。Commands命令目录这是暴露给用户的高级命令背后是智能体的复杂编排。/architect这是入口。当你输入/architect “添加一个带图片上传的用户资料编辑功能”时Claude Code会调用researcher、backend-explorer、frontend-explorer等多个智能体对现有项目进行扫描分析最终协作生成一份规范文件。/engineer实现命令。你只需提供规范文件的ID如SPEC-20250105-user-profilesengineer智能体会协调各探索者智能体依据规范写出完整代码。/reviewer审查命令。你可以针对某个规范或代码文件要求进行安全(--security)、性能(--performance)或全面审查。Hooks Settings用于系统集成和本地个性化配置比如可以配置规范文件的存储路径、默认的审查等级等。3.2 SpecGen MCP服务器 (/specgen-mcp)MCPModel Context Protocol是Anthropic推出的一个协议允许像Claude这样的AI模型安全地使用外部工具和数据源。SpecGen MCP就是一个实现了该协议的独立服务器程序。它的核心职责是“规范文件管理器”文件系统操作在指定目录通常是项目根目录下的docs/specs/创建、读取、更新、删除Markdown规范文件。提供搜索接口允许Claude Code智能体查询已有的规范比如“查找所有关于用户认证的规范”。运行Dashboard提供一个本地Web界面通常运行在http://localhost:3000让你能可视化地浏览、搜索、管理所有规范查看它们的状态待办、进行中、已完成。工作流程比喻Claude Code智能体是“大脑”它们负责思考和分析。SpecGen MCP是“手”和“记忆库”大脑发出指令“保存这份分析”手就去操作文件系统大脑需要信息“读取上次的架构决策”手就从记忆库里取出来。Dashboard就是这个记忆库的“可视化控制台”。3.3 一键安装与手动配置详解项目推荐的最简单安装方式极具创意直接对Claude Code说一句自然语言指令。这本身就在展示智能体协作的威力。方式一让Claude Code帮你安装推荐在Claude Code对话框中直接输入“Install specgen-mcp for me from https://github.com/pwnk77/agentic-workflows”Claude Code会理解这个指令并可能启动一个具备系统操作权限的智能体为你执行类似以下的自动化流程克隆仓库。进入specgen-mcp目录运行npm install。运行npm run build编译。将编译后的MCP服务器路径添加到Claude Code的MCP配置中。将core-workflows/claude-code/下的智能体和命令配置复制到你的Claude Code本地配置目录。方式二经典手动安装理解原理如果你更喜欢掌控感或者遇到问题需要排查手动安装能让你更清楚发生了什么。# 1. 克隆项目 git clone https://github.com/pwnk77/agentic-workflows.git cd agentic-workflows # 2. 编译并全局安装SpecGen MCP服务器 cd specgen-mcp npm install npm run build # 你可以选择全局安装方便在任何项目使用 npm install -g . # 注意最后的点表示安装当前目录 # 3. 配置Claude Code的MCP # 你需要找到Claude Code的配置目录通常在 ~/.config/Claude/claude_desktop_config.json # 在 mcpServers 部分添加如下配置 { specgen: { command: npx, args: [-y, specgen-mcplatest], env: { SPECGEN_PROJECT_ROOT: /ABSOLUTE/PATH/TO/YOUR/PROJECT # 关键设置为你的项目绝对路径 } } } # 4. 复制工作流配置 # 将 core-workflows/claude-code/ 下的 agents, commands, hooks 等文件夹 # 复制到你Claude Code的本地配置目录通常与上述mcp配置目录同级或在其子目录下。 # 具体路径请参考Claude Code的官方文档。注意事项手动配置中最关键的环节是设置SPECGEN_PROJECT_ROOT环境变量。这个路径决定了规范文件存储和读取的位置。务必使用绝对路径并且确保该目录是你的代码项目根目录。如果设置错误智能体将无法正确访问或创建规范文件。4. 完整实战从零构建一个任务管理API让我们通过一个完整的例子看看SpecGen如何在实际项目中发挥作用。假设我们有一个简单的Express.js后端项目现在需要增加一个“任务管理”功能模块。4.1 第一阶段架构分析与规范生成我们打开Claude Code定位到项目根目录然后输入命令/architect “为我们的Express.js后端项目添加一个完整的任务管理功能。需要包含1. 任务模型标题、描述、状态、创建时间、所属用户。2. 全套CRUD API端点。3. 基于JWT的用户认证确保用户只能操作自己的任务。4. 考虑分页和过滤查询按状态。请分析现有项目结构提出与现有模式一致的实现方案。”智能体协作过程researcher智能体被激活快速调研Node.js/Express中RESTful API和JWT认证的最佳实践。backend-explorer智能体开始扫描你的项目。它会查看现有的app.js或index.js、routes/文件夹、models/文件夹如果使用ORM、现有的中间件如认证中间件。database-explorer智能体检查现有的数据库连接配置和模型定义方式比如是用Mongoose、Sequelize还是原生SQL。这些探索者将发现的信息汇总给architect主智能体。architect智能体调用SpecGen MCP服务器的create_specification工具生成一份名为SPEC-20250321-task-management.md的规范文件。生成的规范文件核心内容预览# 规范任务管理功能 (SPEC-20250321-task-management) **状态**: In Progress **关联项目**: /Users/you/your-express-project **创建于**: 2025-03-21 10:30:00 ## 1. 需求概述 基于用户请求为现有Express.js后端添加任务管理模块... ## 2. 现有项目分析 - **框架**: Express.js 4.18 - **数据库**: 已使用Mongoose连接至MongoDB Atlas。 - **认证**: 项目中已存在 authMiddleware.js使用jsonwebtoken验证Bearer Token。 - **项目结构**: 采用MVC变体现有 models/User.js, routes/authRoutes.js。 ## 3. 建议架构 - **数据模型**: 在 models/ 下创建 Task.js。字段title (String, required), description (String), status (Enum: [todo, in-progress, done]), createdAt (Date), userId (ObjectId, ref: User)。 - **路由**: 在 routes/ 下创建 taskRoutes.js。挂载到 /api/tasks。 - **控制器逻辑**: 建议在 controllers/ 下创建 taskController.js包含 getAllTasks, createTask, updateTask, deleteTask。 - **认证集成**: 所有 /api/tasks/* 路由需应用现有的 authMiddleware。在控制器中从解码的JWT获取 req.user.id用于数据隔离。 ## 4. API端点设计 - GET /api/tasks - 获取当前用户的任务列表支持查询参数 ?statustodopage1limit10。 - POST /api/tasks - 创建新任务。请求体: { title, description, status }。 - PUT /api/tasks/:id - 更新任务。用户只能更新自己的任务。 - DELETE /api/tasks/:id - 删除任务。 ## 5. 数据库变更 需在MongoDB中创建 tasks 集合。索引建议在 userId 和 status 上创建复合索引以优化查询。 ## 6. 待决策项 - 错误处理是否创建统一的错误响应格式 - 输入验证是否使用Joi或Express-validator这份规范已经不是一个简单的需求描述了而是一个融合了项目现状分析和具体技术方案的可执行设计文档。4.2 第二阶段基于规范的代码实现有了规范实现就变得异常简单。我们继续在Claude Code中输入/engineer SPEC-20250321-task-managementengineer智能体会做以下事情通过MCP服务器读取SPEC-20250321-task-management.md文件理解全部设计。再次调用backend-explorer等智能体确认项目细节比如现有的错误处理中间件放在哪里模型文件的具体格式。开始生成代码。它会严格遵循规范中的建议创建models/Task.js字段和索引与规范一致。创建controllers/taskController.js实现四个核心函数并在每个函数中嵌入userId过滤逻辑。创建routes/taskRoutes.js定义路由并将它们与控制器绑定同时应用authMiddleware。修改主app.js或index.js引入新的任务路由。生成的代码会直接插入到你的项目文件中或者以清晰的代码块形式呈现供你审查和插入。关键优势因为engineer智能体“看到”了architect智能体对现有authMiddleware的分析所以它生成的代码能完美地集成这个中间件调用方式与现有项目完全一致。这避免了手动实现时可能出现的“风格不一致”或“集成错误”。4.3 第三阶段多维度代码审查功能实现后我们进行审查。可以执行全面审查也可以定向审查。/reviewer SPEC-20250321-task-management --security --performance这个命令会激活security和performance审查员智能体security审查员会检查JWT令牌是否在控制器中被正确解析和使用是否存在NoSQL注入风险因为用了Mongoose风险较低但会检查查询构建方式用户ID过滤是否彻底防止用户通过修改URL参数访问他人任务performance审查员会检查数据库查询是否使用了索引规范中建议的索引是否被实现分页逻辑是否高效使用skip()和limit()可能在大数据集有问题它会建议更优方案API响应是否包含不必要的数据审查结果会以评论或建议的形式输出并且可以通过MCP服务器追加到原规范文件的“修订记录”或“审查意见”章节。这样这份规范文件就不仅记录了“我们做了什么”还记录了“我们为什么这么做”以及“哪些地方可以做得更好”。5. 高级技巧与避坑指南经过一段时间的密集使用我积累了一些让SpecGen工作流更顺畅的经验和必须避免的坑。5.1 如何编写高效的/architect指令智能体的输出质量很大程度上取决于你的输入指令。模糊的指令得到模糊的规范。差指令/architect “加个评论功能”问题过于模糊。是文章评论、商品评论需要回复吗需要审核吗前端如何展示优秀指令/architect “在现有的博客文章模型基础上为每篇文章添加一个评论系统。功能包括1. 游客可查看评论。2. 登录用户基于现有JWT可发表评论。3. 评论支持Markdown基础语法加粗、链接。4. 后端需要API端点前端需要嵌入一个评论组件。请分析现有项目的前后端技术栈React Express并设计与之匹配的实现方案。”优点明确了功能范围、用户角色、技术细节并引导智能体去分析现有技术栈。核心技巧在指令中主动要求智能体“分析现有项目结构”analyze the existing project structure或“遵循现有模式”follow the existing patterns。这能强制激活backend-explorer等智能体确保生成的规范是贴合项目实际的而不是一个通用的模板。5.2 规范文件的组织与管理随着项目进行docs/specs/目录下可能会有几十个SPEC文件。良好的组织至关重要。利用DashboardSpecGen MCP自带的Web Dashboard是你最好的朋友。通过http://localhost:3000访问你可以按状态Todo, In Progress, Done、创建时间、关键词来过滤和搜索规范。养成定期查看Dashboard的习惯。命名约定虽然SpecGen会自动生成SPEC-日期-描述.md的名字但你可以在规范内部通过元数据YAML Frontmatter添加自定义标签比如category: auth,epic: user-management方便后期筛选。规范的生命周期一个规范的状态应该及时更新。实现完成后可以将状态从In Progress改为Completed。如果功能被废弃可以改为Archived。这有助于保持知识库的清洁。5.3 集成其他MCP服务器以增强能力SpecGen MCP管理规范而Claude Code可以同时连接多个MCP服务器形成更强大的工具链。静态分析MCP这是官方示例中推荐的。它可以为Claude Code提供项目的TypeScript类型信息、函数符号定义等。当backend-explorer智能体在分析一个TypeScript项目时结合静态分析MCP它能更精确地理解接口和类型从而给出更准确的架构建议。数据库MCP如果你在开发数据库密集型应用可以配置PostgreSQL或SQLite的MCP服务器。这样database-explorer智能体不仅能看代码中的模型定义还能直接查询数据库的Schema、索引甚至样例数据做出的建议会更具操作性。文件系统MCPClaude Code内置了文件访问能力但更复杂的操作如遍历目录树统计信息可以通过专用MCP增强。配置示例在你的Claude Code MCP配置中可以同时配置多个服务器{ mcpServers: { specgen: { ... }, staticAnalysis: { command: npx, args: [-y, modelcontextprotocol/server-static-analysis, /ABSOLUTE/PATH/TO/YOUR/TS-PROJECT] } } }5.4 常见问题与排查智能体找不到我的项目文件/规范文件原因99%是因为SPECGEN_PROJECT_ROOT环境变量设置错误。Claude Code的MCP配置中指定的路径必须是绝对路径且指向你的项目根目录。排查在Dashboard中查看如果看不到任何规范或者智能体说“找不到项目”首先检查这个路径。在Mac/Linux上可以在终端输入pwd获取当前目录的绝对路径。/architect命令运行后没有生成规范文件原因可能是MCP服务器没有正确启动或者Claude Code没有连接到它。排查首先确保SpecGen MCP服务器已安装并可在命令行中运行specgen-mcp或npx specgen-mcp。然后检查Claude Code的设置 - 开发者 - MCP服务器确认specgen服务器状态是“已连接”。查看Claude Code的日志也可能发现连接错误。生成的代码风格与现有项目不符原因backend-explorer等智能体没有足够的时间或上下文来深度理解你的代码风格。解决在运行/architect前可以先手动引导一下。例如先打开一个现有的、风格典型的文件如一个模型文件或控制器然后对Claude Code说“请分析这个文件的代码风格和模式。” 然后再运行/architect指令。此外在指令中明确强调“请严格模仿[某个文件]的代码风格和结构”也非常有效。Dashboard无法打开或空白原因MCP服务器启动时可能默认端口被占用或者前端资源构建失败。排查查看MCP服务器的启动日志。尝试指定另一个端口可以通过环境变量SPECGEN_DASHBOARD_PORT3001来设置。如果是手动安装确保在specgen-mcp目录下成功运行了npm run build。6. 项目适配与扩展思路SpecGen的设计并非只适用于Express.js或JavaScript项目。它的核心理念是通用的。你可以通过调整智能体的“知识”和“指令”将其适配到任何技术栈。适配Python Django/Flask项目你需要调整backend-explorer智能体的系统提示词System Prompt让它专注于分析settings.py、urls.py、views.py和Django的模型文件。规范模板也可以调整为包含Django特有的部分如models.py字段定义、serializers.py、urlpatterns等。适配React/Vue前端项目可以为前端项目创建一套专门的智能体如component-explorer分析组件库、store-explorer分析状态管理。/architect指令生成的前端规范会侧重于组件Props设计、状态结构、API Hook定义等。创建自定义智能体这是最强大的扩展方式。假设你的项目有独特的部署流程比如使用Kubernetes你可以创建一个deployment-explorer智能体。它的系统提示词包含分析Dockerfile、k8s.yaml的能力。然后在/architect的工作流中引入它这样生成的规范就会包含“部署建议”章节。扩展实践克隆core-workflows/claude-code/agents/目录下的一个现有智能体比如backend-explorer复制一份并重命名。然后仔细修改它的系统提示词定义它的专长领域、它能访问的工具MCP以及它的输出格式。最后在architect命令的配置中将这个新的智能体加入到其协作流程中。这个过程需要一些对Claude Code智能体配置的理解和调试但一旦成功你将拥有一个深度定制化的、理解你公司特有技术栈的AI开发伙伴。从我个人的实际体验来看SpecGen带来的最大改变不是“写代码更快了”而是“思考的负担更轻了”。我不再需要把整个项目的上下文都装在脑子里或者费力地通过文字传递给AI。项目知识被固化在规范文件里AI智能体成为了拥有长期记忆的协作者。它特别适合中型以上、需要长期维护的项目以及在团队中需要保持架构一致性的场景。当然初期需要一些学习成本和配置调试但一旦跑通它就会像一个无声的、不知疲倦的架构守护者和开发加速器持续为你的项目创造价值。