1. 项目概述一个为开发者准备的AI智能体“菜谱”库如果你和我一样每天都在和代码打交道同时也在尝试用各种AI助手比如Cursor、Claude Code、GitHub Copilot来提升效率那你肯定遇到过这样的场景想让AI帮你做一次彻底的代码审查或者自动生成单元测试但每次都要费劲地组织语言描述你的需求、上下文和期望的输出格式。结果往往是AI要么理解偏差要么给出的结果不尽人意来回沟通几次时间也浪费了。Sagargupta16/agent-recipes 这个项目就是为了解决这个痛点而生的。你可以把它理解为一个“AI智能体工作流菜谱库”。它不是一个需要你安装和配置的复杂软件而是一个由社区驱动的、开箱即用的提示词Prompt集合。项目里精心设计了针对各种真实开发任务的标准化工作流比如代码审查、测试生成、依赖迁移、文档编写等等。每一个“菜谱”都是一个独立的Markdown文件里面包含了经过验证的、结构清晰的提示词。你只需要复制粘贴到你的AI编码助手里它就能像一个经验丰富的搭档一样按照预设的、最优的路径帮你完成任务。这个项目的核心价值在于“标准化”和“可复用性”。它把那些我们通过无数次试错才摸索出来的、与AI高效协作的最佳实践固化成了一个个可以直接“抄作业”的模板。无论你是前端、后端还是全栈开发者无论你在处理JavaScript、Python还是Go项目这里总有一些菜谱能直接派上用场让你把AI从“一个有时灵有时不灵的聊天伙伴”真正变成你开发流程中一个可靠、高效的自动化环节。2. 核心设计思路为什么“菜谱”模式是高效的AI协作范式2.1 从临时对话到结构化工作流我们平时使用AI编码助手大多处于一种“临时对话”模式。你遇到一个问题然后向AI描述它。这种模式的弊端很明显上下文不完整和指令模糊。比如你想让AI审查一个Pull Request如果你只是说“请帮我看看这段代码”AI缺乏审查的维度安全、性能、风格、缺乏项目的代码规范背景、也不知道你期望它以什么格式输出结果是列表还是段落是否需要给出修改建议的代码片段。agent-recipes 的“菜谱”模式正是对这种临时对话模式的升级。它将一个复杂的开发任务如代码审查分解为一系列结构化的、可预期的步骤并封装在一个完整的提示词中。这个提示词通常会包含以下几个关键部分角色定义明确告诉AI它现在要扮演什么角色例如“你是一名资深的安全工程师和代码审查专家”。任务目标清晰、无歧义地描述需要完成的具体任务。输入上下文告诉AI它将获得哪些信息例如“我将给你提供Git Diff内容、相关文件的代码以及PR描述”。处理步骤与规则一步步指导AI如何分析给出具体的审查维度如检查SQL注入、硬编码密钥、错误处理等。输出格式要求严格规定AI回复的结构例如“请按以下格式输出1. 安全问题2. 性能问题3. 代码风格问题每个问题需标明文件、行号和具体建议”。通过这种结构化的方式我们极大地降低了AI的“自由发挥”空间将其引导到一个确定性的、高质量的输出轨道上。这就像给AI一份详细的工作说明书SOP而不是让它自由猜测你的意图。2.2 社区驱动与场景化积累的价值一个人的经验总是有限的但一个活跃开发者社区的经验则是巨大的宝藏。agent-recipes 采用开源和社区贡献的模式使得针对各种细分场景的最佳实践得以快速积累和迭代。例如项目初期可能只有作者自己常用的几个代码审查提示词。但随着社区贡献逐渐加入了针对特定框架如React Hooks迁移、特定风险如OWASP Top 10、特定运维场景如生成多阶段Dockerfile的专用“菜谱”。这种模式的好处是场景覆盖更全你遇到的某个小众但棘手的问题比如将大型CJS项目迁移到ESM可能已经有社区成员踩过坑并贡献了优化好的提示词。质量持续优化一个菜谱被使用的次数越多其提示词在社区反馈中就被打磨得越精准、越健壮。后来者可以直接享受到这个“经验红利”。降低使用门槛即使你对如何设计高效的AI提示词Prompt Engineering并不精通你也可以直接使用这些经过实战检验的“菜谱”立刻获得专业级的结果。这种模式本质上是在构建一个关于“如何与AI协作解决开发问题”的集体智慧库。它让AI能力的应用从一种个人技巧变成了一种可共享、可复用的团队资产。3. 核心“菜谱”类别深度解析与实战要点项目将菜谱分为了六大类基本覆盖了开发生命周期的核心环节。下面我们深入每一类看看它们具体解决了什么问题以及在使用时需要注意哪些细节。3.1 代码审查从人工巡检到自动化审计代码审查是保证代码质量的关键环节但也是耗时且容易疏漏的。AI菜谱将其系统化。PR全面审查这个菜谱不仅仅是找语法错误。它会引导AI从安全检查常见的漏洞模式如XSS、SQL注入、性能识别低效循环、重复计算、内存泄漏风险、代码风格与一致性是否符合项目约定的lint规则、可维护性函数是否过长、复杂度是否过高以及测试覆盖新增代码是否有对应测试等多个维度进行扫描。我个人的使用心得是在运行此菜谱前最好确保AI能获取到项目的ESLint或Prettier配置这样它给出的风格建议才更具参考性。架构评审这对于评估新模块或重构旧代码非常有用。菜谱会要求AI分析模块的职责划分是否清晰、依赖关系是否合理、是否存在循环依赖、扩展性如何。它不能替代资深架构师的经验但可以作为一个强大的辅助工具快速指出明显的设计缺陷或耦合度过高的地方。依赖审计这个菜谱自动化了本需手动检查的工作。它会检查package.json或pom.xml识别过时的、存在已知安全漏洞的依赖项并标记出那些在项目中已声明但实际未使用的“僵尸依赖”。注意事项AI给出的漏洞信息需要二次确认最好能链接到国家漏洞数据库或GitHub Advisory Database进行核实因为依赖的版本和漏洞影响范围可能很复杂。性能审查专注于识别性能瓶颈。例如在React组件中它可能会指出不必要的重新渲染、未做防抖/节流的频繁事件处理、大型内联函数或对象导致的不必要的引用变化等。实操心得不要期待AI审查能100%替代人工。它的优势在于“广度”和“不知疲倦”能快速扫描所有变更指出潜在问题。但最终对问题严重性的判断、对修改方案可行性的评估以及那些涉及复杂业务逻辑的深层缺陷仍然需要开发者的经验和智慧来做最终决策。最佳实践是用AI做第一轮快速筛查过滤出明显问题然后人工进行重点深度审查。3.2 测试生成填补覆盖空白提升测试效率编写测试尤其是全面的单元测试和E2E测试是很多开发者的痛点。这些菜谱旨在将测试用例的生成自动化。单元测试生成你指向一个函数或模块AI会根据其输入、输出和逻辑分支自动生成一组测试用例。这对于填补测试覆盖率空白、或者为遗留代码快速添加测试基线特别有效。关键点生成的测试用例可能覆盖了“快乐路径”但边界条件和异常情况如输入为null、空字符串、极大值等可能不足。你需要审查并补充这些用例。此外生成的测试代码风格需要调整以符合你项目的测试框架Jest, Mocha, pytest等和断言库的约定。E2E测试编写根据用户故事或功能描述生成端到端测试脚本例如使用Cypress或Playwright。这个菜谱的价值在于快速搭建测试骨架但生成的脚本通常需要你补充具体的页面元素选择器因为AI无法直接访问你的UI并调整等待和断言逻辑以适应你应用的实际响应时间。覆盖率缺口查找这个菜谱更像一个分析工具。它结合代码覆盖率报告和静态分析找出那些被测试遗漏的分支、边界条件和错误处理路径。它能帮你回答“我的测试还缺什么”这个问题让测试补充工作更有针对性。3.3 迁移与重构自动化繁琐的代码转换框架升级、语法迁移这类重复性高、规则明确的任务是AI最擅长的领域之一。JavaScript转TypeScript这不仅仅是添加any类型。一个好的菜谱会指导AI根据上下文推断出尽可能精确的类型接口、泛型、联合类型等并处理模块导入导出类型的转换。重要提示大规模迁移后务必运行TypeScript编译器进行严格检查tsc --noEmit因为AI可能会在某些复杂泛型或动态类型场景下推断错误。React Class组件转Hooks将旧的基于类的组件转换为使用函数组件和HooksuseState, useEffect等。菜谱需要正确处理生命周期方法的映射如componentDidMount-useEffectwith empty deps以及状态this.state和实例方法this.method的转换。转换后必须手动测试组件行为因为某些生命周期方法的细微差别如componentDidUpdate与useEffect的依赖数组可能导致不同的行为。CJS转ESM将require()和module.exports转换为import和export语句。这听起来简单但实际会遇到很多边缘情况比如动态require、循环依赖的处理、以及__dirname等Node.js全局变量的替换。一个成熟的菜谱会包含处理这些情况的规则。3.4 文档自动化让文档与代码同步“代码即文档”是理想但良好的外部文档同样不可或缺。这些菜谱帮助减轻文档负担。README生成器分析项目结构、入口文件、配置文件如package.json和主要的导出模块自动生成一个结构化的README包含项目描述、安装步骤、使用示例、API概览等。这能快速为一个新项目或缺乏文档的旧项目建立基础文档。API文档生成从代码中的JSDoc/TSDoc注释或路由定义中提取信息并生成OpenAPI/Swagger规范的YAML或JSON文件。这对于维护API接口文档的一致性非常有用能确保文档随代码更新而更新。变更日志编写解析Git提交历史将 Conventional Commits 格式的提交信息如feat:,fix:,break:分类整理生成结构化的CHANGELOG.md。这能极大简化发布新版本时的手动汇总工作。3.5 安全扫描将安全左移融入开发流程在开发阶段就引入安全检查成本远低于在生产环境发现问题。密钥扫描在代码库中搜索硬编码的密码、API密钥、令牌、私钥等敏感信息。正则表达式模式是核心。注意事项这个检查可能会有误报比如一个看起来像密钥的随机字符串常量也可能有漏报比如经过简单编码或拆分的密钥。它应该作为CI/CD流水线中的一个强制关卡但发现的问题仍需人工确认。OWASP Top 10审计根据最新的OWASP Top 10清单如注入、失效的身份认证、敏感信息泄露等对代码进行模式匹配和上下文分析寻找潜在漏洞。例如检查数据库查询是否使用参数化查询而非字符串拼接。输入校验增强自动分析API端点检查请求参数是否缺乏足够的验证和清理sanitization并建议添加相应的校验逻辑如使用Joi、Yup、validator.js等库。3.6 DevOps自动化标准化部署与运维配置为项目快速生成标准化的基础设施即代码配置。Dockerfile生成器根据项目类型Node.js, Python, Go等生成遵循最佳实践的多阶段构建Dockerfile包括使用轻量级基础镜像、合理分层以利用缓存、设置非root用户运行等。CI/CD流水线生成分析项目后生成对应平台GitHub Actions, GitLab CI的流水线配置文件包含典型的步骤安装依赖、运行lint、执行测试、构建镜像、安全扫描、部署等。这为项目快速建立了自动化质量门禁。监控配置为应用添加健康检查端点/health、基础指标暴露如使用Prometheus客户端和日志配置建议帮助快速搭建可观测性基础。4. 实战指南如何高效使用与定制你的“菜谱”拥有了这些强大的菜谱如何将它们无缝集成到你的工作流中并使其发挥最大效用下面是一些具体的操作步骤和技巧。4.1 主流AI助手集成方法1. 与Claude Code集成Claude Code通常通过命令行或API调用。项目README给出了最直接的方法使用cat命令读取菜谱文件内容并将其作为提示词输入。# 基本用法直接运行菜谱 claude -p $(cat recipes/code-review/pr-review.md) # 进阶用法将菜谱保存为自定义命令 # 首先在项目根目录创建或确保存在.claude/commands/目录 mkdir -p .claude/commands/ # 将菜谱复制过去并重命名 cp recipes/code-review/pr-review.md .claude/commands/pr-review.md # 之后在Claude Code中直接输入 /pr-review 即可触发该工作流这种自定义命令的方式非常高效相当于为你常用的审查流程创建了一个快捷指令。2. 与Cursor、Windsurf或IDE插件集成这些工具通常以聊天界面为主。操作流程非常直观打开你想要的菜谱Markdown文件例如recipes/testing/generate-unit-tests.md。复制整个“## Prompt”部分下的内容。将其粘贴到AI助手的聊天输入框中。紧接着在同一个对话中提供AI完成任务所需的上下文。例如对于单元测试生成你需要附上目标函数的代码对于PR审查你需要粘贴Git Diff的内容。发送消息AI就会按照菜谱的指令开始工作。3. 与GitHub Copilot Chat集成Copilot Chat通常集成在VS Code等IDE中。你可以将菜谱提示词保存为一个代码片段或文本片段在需要时快速插入到聊天中。更高级的用法是利用Copilot的“自定义指令”功能将某个高频使用的菜谱如代码风格审查设置为全局上下文的一部分这样在日常编码对话中AI也会潜移默化地遵循这些审查原则。4.2 核心操作流程与现场示例让我们以“使用PR审查菜谱”为例走一遍完整流程准备阶段在本地终端对你的功能分支运行git diff main...HEAD -- .来获取本次PR涉及的所有变更。或者直接从GitHub/GitLab的PR界面上复制“Files changed”的diff内容。执行阶段打开你的AI助手以Cursor为例新建一个对话。将pr-review.md文件中的整个Prompt部分复制粘贴进去。然后在下方附上你刚才准备好的diff内容以及PR的描述如果有的话。最后发送。AI处理与输出AI会按照Prompt中的角色设定和步骤要求开始分析代码。它会输出一个结构化的审查报告。以下是一个模拟的简化输出示例## 代码审查报告 ### 1. 安全问题 - **文件**: src/api/user.js - **行号**: 45 - **问题**: 发现潜在的SQL注入风险。直接使用模板字符串拼接用户输入req.body.email构建SQL查询。 - **建议**: 请使用参数化查询或预编译语句。例如如果使用pg库应改为 client.query(SELECT * FROM users WHERE email $1, [email])。 ### 2. 性能问题 - **文件**: src/components/ProductList.jsx - **行号**: 12-25 - **问题**: 在渲染函数内部定义了一个大型内联函数filterProducts这会导致每次渲染都创建一个新的函数引用可能引发子组件不必要的重渲染。 - **建议**: 使用useCallback钩子包裹此函数或将其移出组件。 ### 3. 代码风格与维护性 - **文件**: src/utils/helpers.js - **行号**: 78-95 - **问题**: calculateDiscount函数过长超过20行且圈复杂度较高包含多层嵌套if-else。 - **建议**: 考虑拆分为更小的、职责单一的函数如validateInput, getDiscountRate, applyDiscount。后续处理根据AI的报告逐项评估并处理。对于明确的安全漏洞和明显的性能问题应立即修复。对于代码风格和建议可以根据团队规范和个人判断决定是否采纳。4.3 菜谱的个性化定制与调优没有一套提示词能完美适应所有项目和团队。因此定制化是发挥其最大威力的关键。调整审查规则如果你团队禁用var强制使用或者有特定的命名约定你可以在菜谱的Prompt中修改或添加相应的检查规则。例如在PR审查菜谱的“代码风格”部分明确加入“检查是否使用了var声明变量如有建议改为let或const”。融入项目特定上下文在Prompt的开头可以添加一段关于你项目的固定背景信息。例如“本项目为基于Next.js 14的React应用使用TypeScript遵循ESLint配置company/eslint-config状态管理使用Zustand。” 这能帮助AI做出更符合项目上下文的判断。修改输出格式如果你希望审查报告以JIRA ticket的格式输出或者能直接生成一个包含// TODO注释的代码片段你可以修改Prompt中的“输出格式”部分让AI按你的需求来组织信息。创建组合菜谱你可以将多个菜谱组合起来形成一个更强大的工作流。例如创建一个“上线前检查”菜谱它依次执行1) 依赖审计2) 安全扫描3) 全面PR审查4) 生成单元测试覆盖率报告。这可以通过将多个Prompt按顺序组合在一个文件中来实现。重要提示每次修改菜谱后建议先用一个小型的、熟悉的代码片段进行测试观察AI的输出是否符合预期。这是一个迭代调优的过程。将最终稳定版的菜谱保存在你团队的知识库或共享目录中确保所有成员使用的是同一套高质量标准。5. 常见问题、局限性与进阶技巧即使是最好的工具也有其适用范围和局限性。了解这些能帮助你更理性地使用它并规避潜在的风险。5.1 典型问题与排查清单问题现象可能原因解决方案AI输出不符合预期或遗漏明显问题1. 提供的上下文信息不足。2. Prompt指令不够清晰或存在歧义。3. AI模型本身的局限性或“幻觉”。1. 检查是否提供了AI完成任务所需的所有代码和背景信息如配置文件、相关模块。2. 精炼Prompt语言使用更明确、无歧义的指令。参考菜谱的原始格式确保结构完整。3. 对于关键任务如安全审计AI结果必须由人工二次验证。可以尝试让AI“逐步思考”或换用不同的模型/助手。生成的代码如测试、迁移代码无法运行或存在语法错误1. AI不了解项目特定的运行时环境或依赖版本。2. 生成的代码基于过时的API或语法。3. 复杂逻辑转换出错。1. 在Prompt中明确指定技术栈、框架版本和关键依赖。2. 将生成的代码视为“初稿”必须放入IDE中运行测试和类型检查。3. 对于复杂的重构如CJS转ESM分批进行并辅以大量的测试。在CI/CD流水线中集成AI审查时结果不稳定1. AI服务的API响应时间或速率限制波动。2. 代码变更的上下文差异导致AI输出波动。3. 成本考虑。1. 为自动化任务设置合理的超时和重试机制。2. 考虑将AI审查作为“辅助性”而非“阻塞性”环节其报告仅供开发者参考不直接决定流水线成败。3. 评估API调用成本对于大型团队或频繁提交可能需要优化调用策略如仅对核心路径或大型PR触发。菜普对某些编程语言或框架支持不佳社区贡献的菜谱覆盖度不均某些小众技术栈缺乏优化过的Prompt。1. 以现有菜谱为模板根据目标语言/框架的官方最佳实践自行修改和创建。2. 向原项目仓库提交Issue或PR贡献你创建的菜谱。5.2 理解AI智能体的固有局限性我们必须清醒认识到当前阶段的AI编码助手即使配合最优秀的提示词也并非全能缺乏深层业务理解AI无法理解你代码背后的商业逻辑、产品意图和用户场景。它只能基于代码模式和常见实践进行分析。对于“这个功能设计是否符合产品目标”这类问题AI无能为力。创造力与架构设计的局限AI擅长基于现有模式的优化和重构但在从零开始设计一个新颖、优雅的系统架构方面仍无法替代经验丰富的工程师的创造性和大局观。“幻觉”与自信的错误AI可能会以非常肯定的语气给出一个完全错误或不存在的信息例如引用一个不存在的库函数。这是大语言模型的固有风险对AI的输出必须保持批判性思维进行核实。上下文长度的限制即使是支持超长上下文的模型在处理整个大型代码库时也可能无法将所有相关文件一次性纳入分析。这可能导致分析不全面。5.3 进阶技巧构建团队级的AI工作流资产要让agent-recipes这类工具的价值最大化不能仅停留在个人使用层面而应将其提升到团队协作的高度。建立团队菜谱库在团队内部Git仓库或共享文档中维护一个经过你们共同验证和调优的“私有菜谱库”。可以基于开源菜谱进行定制也可以从头创建针对你们特定技术栈如内部框架、特定微服务模式的专用菜谱。标准化与培训在团队内推广使用这些标准化菜谱并组织简短的分享会演示如何最有效地使用它们。确保大家理解菜谱的意图和局限避免盲目依赖。集成到开发流程将关键菜谱集成到团队的Git钩子pre-commit或CI/CD流水线中。例如每次提交前自动运行“密钥扫描”和“基础代码风格检查”每次PR创建时自动运行“PR全面审查”并将报告评论到PR中。这能将质量保障和最佳实践左移到开发的最早期。持续迭代与反馈鼓励团队成员在使用菜谱时如果发现其指令不清晰、输出不佳或有改进想法及时在内部的菜谱库中提出修改建议或直接提交更新。让这个资产随着团队经验一起成长。我个人在团队中推行这一套方法后最直观的感受是代码审查的一致性和效率得到了显著提升。新同事能快速通过AI菜谱的输出了解团队关注的质量维度老同事则从重复性的基础检查中解放出来更专注于逻辑和设计的深度讨论。它没有取代我们而是让我们变得更高效、更聚焦。