1. 项目概述构建你的AI智能体“众神殿”如果你和我一样每天都在和Cursor、Roo Code这类AI编程助手打交道那你肯定也经历过这样的时刻面对一个复杂的重构任务你希望AI能像一个经验丰富的架构师一样思考而在编写单元测试时你又希望它能切换成一个严谨的测试专家。默认的“通用助手”模式虽然强大但就像让一个全科医生去做心脏外科手术不是不能做而是不够专业、不够高效。这正是jwadow/agentic-prompts这个项目试图解决的问题。它不是一个简单的提示词合集而是一套完整的、工程化的“智能体角色”配置系统。你可以把它想象成一个为AI编程助手准备的“角色扮演工具箱”。作者Jwadow将自己日常开发中沉淀下来的最佳实践封装成了九个各司其职的专家角色比如负责顶层设计和任务拆解的Maestro指挥家专攻深度系统设计的Principal Engineer首席工程师以及那个专门唱反调、帮你砍掉冗余功能的Annihilator歼灭者。这套系统的核心价值在于“专业化分工”。通过为不同的开发场景匹配最合适的AI角色你获得的不是泛泛而谈的建议而是深度、聚焦的专家级输出。这直接提升了从需求分析、架构设计、编码实现到测试重构整个工作流的效率与质量。无论你是独立开发者还是团队的技术负责人这套工具都能帮助你将AI编程助手的潜力最大化让它从一个好用的工具升级为一个高度定制化的“开发团队”。2. 核心架构解析“提示即代码”的工程实践很多人在使用AI时习惯于在聊天框里临时编写长篇大论的提示词。这种方法虽然灵活但难以复用、难以维护更难以团队协作。agentic-prompts项目引入了一个非常聪明的理念Prompt-as-Code提示即代码。这不仅仅是把提示词存成文本文件而是像管理软件源代码一样用工程化的方法来管理提示词。2.1 角色构建器从源码到配置的自动化流水线项目的核心是一个名为roles_builder的目录。这才是整个系统的“发动机房”。它的工作流程清晰且自动化源码管理在/sources子目录下每个智能体角色如maestro,principal_engineer都是一个独立的文件夹。里面通常包含两个核心文件config.yaml: 定义角色的元数据如名称、描述、头像符号。这相当于角色的“身份证”。prompt.md: 包含角色的详细系统指令、行为规范、思考框架。这是角色的“大脑和灵魂”。 这种分离的设计非常巧妙让你可以独立修改角色的外在表现和内在逻辑。清单控制manifest.yaml文件扮演了“产品经理”的角色。它是一份清单明确列出了本次构建需要包含哪些角色。如果你想暂时禁用某个角色或者只想构建一个轻量版只需在这里注释或删除对应的条目即可。这提供了极大的灵活性。构建脚本build.py是一个Python脚本它相当于“编译器”。当你运行它时它会读取manifest.yaml找到对应的所有角色源码然后将config.yaml和prompt.md的内容按特定模板合并、组装最终生成一个统一的、AI助手可以直接读取的配置文件——custom_modes.yaml。提示永远不要手动编辑custom_modes.yaml文件。因为它是构建过程的输出产物任何手动修改都会在下一次执行构建脚本时被覆盖。正确的做法是去修改/sources目录下的源码文件。这遵循了软件开发的“单一事实来源”原则避免了配置漂移和版本混乱。2.2 配置结构适配主流开发工具生成的custom_modes.yaml文件具有特定的结构以适配像Roo Code这样的AI编程助手。一个典型的角色定义如下所示- name: Maestro description: An expert project orchestrator who decomposes complex tasks... prompt: | # Role: Maestro - The Project Orchestrator ## Core Directive You are an expert software project manager and system architect... (后续是详细的、多段落的指令)这种结构将名称、描述和完整的系统提示词打包在一起使得AI助手能够将其识别为一个可切换的独立“模式”或“角色”。这种“提示即代码”的架构带来了几个显著优势版本控制友好所有源码都是纯文本文件可以轻松地用Git进行管理、比较差异、回溯历史。协作与共享团队可以共同维护一套角色库确保大家使用的是同一套高质量的标准。可测试性与迭代你可以像调试代码一样迭代优化某个角色的提示词并通过构建脚本快速验证效果。3. 智能体“众神殿”深度剖析与实战应用项目预设的九个角色并非随意堆砌它们共同构成了一个覆盖软件开发全生命周期的虚拟团队我称之为“众神殿”。每个角色都有其独特的思维模式和职责边界理解这些是高效使用的关键。3.1 核心角色分工与协作逻辑 Maestro项目指挥家定位总规划师与项目经理。当你面对一个模糊、庞大的需求如“重构一个微服务”时首先应该召唤Maestro。工作流它的核心工作是拆解。它会将模糊目标分解为清晰、可执行的具体子任务并为每个子任务分配合适的执行角色如“请Principal Engineer设计架构”“请Lead Implementer编写API层”。实战技巧向Maestro描述任务时尽量提供背景信息如项目类型、技术栈、核心痛点。它的输出通常是一个包含任务列表、依赖关系和推荐执行顺序的Markdown文档这是你后续行动的蓝图。️ Principal Engineer首席架构师定位技术深水区的探索者。当Maestro拆解出“设计数据库 schema”或“规划服务间通信协议”这类任务时就该它上场了。工作流它专注于权衡与决策。它会分析多种技术方案的利弊例如用REST还是gRPC用SQL还是NoSQL考虑可扩展性、维护成本和性能最终给出带有详细理由的推荐方案并可能产出架构图描述或核心接口定义。注意事项Principal Engineer的思考往往非常详尽可能会产出很长的分析。对于快速原型阶段有时可能会显得“过度设计”。你需要根据项目阶段判断是否采纳其所有建议。 Lead Implementer主力开发定位高质量的代码产出机器。它是你日常编码最频繁切换到的角色。工作流它擅长将设计转化为具体、整洁、可运行的代码。你给它一个清晰的函数签名或模块描述它能高效地实现业务逻辑并遵循常见的编码规范如清晰的命名、适当的注释、错误处理。实操心得与Lead Implementer交互时指令要具体。与其说“写一个用户登录函数”不如说“请实现一个基于JWT的用户登录函数login(username: str, password: str) - Dict需要验证密码成功则返回包含access_token和refresh_token的字典失败则抛出AuthenticationException”。 Test Engineer质量守护者定位偏执的完美主义者。在Lead Implementer写完代码后立即让Test Engineer为同一段代码生成测试用例。工作流它专注于边界条件、异常流程和覆盖率。它会思考“如果输入是null怎么办”“如果网络超时怎么办”“这个函数在并发环境下安全吗”。它生成的测试代码通常包含正例、反例和Mock的使用。避坑指南不要指望一次生成完美的测试。将其产出作为基础你需要结合业务逻辑进行审查和补充。Test Engineer有时会过度Mock导致测试与实现耦合过紧需要手动调整。 Annihilator复杂性歼灭者定位团队里的“魔鬼代言人”。这是一个极具特色的角色用于项目中期或后期当你感觉代码库变得臃肿时。工作流它的任务就是质疑和删除。你可以将一段代码、一个模块甚至一个需求描述丢给它它会无情地指出哪些部分是多余的、过度抽象的、或者可以被更简单方案替代的。使用场景在代码评审前或者准备重构时让Annihilator先过一遍往往能发现你潜意识里已经感觉到但不愿面对的“代码债”。它的结论可能很尖锐但通常能直指要害。其余角色如Advocate用户体验、Gardener代码园艺、Mr. Robot安全审计、Observer可观测性则分别在UI/UX设计、代码重构、安全渗透、监控部署等专业领域提供深度支持。你可以根据当前的工作焦点像切换工具一样切换它们。3.2 命令与独立提示词场景化效率工具除了常驻角色项目还提供了“命令”和“独立提示词”用于处理一些特定的、高频的临时性任务。 GitHub Release 命令这个命令解决了每次发版都要苦思冥想更新日志的痛点。你只需要提供两个Git标签如v1.2.0和v1.3.0它就能自动分析期间的提交信息归类为feat、fix、BREAKING CHANGE等生成结构清晰、可直接用于GitHub Releases的Markdown文档。这比手动整理要可靠和高效得多。 Question ChatGPT 命令这个设计非常实用。有时你在与Claude深度讨论一个技术问题但想获得GPT-4的不同视角。直接复制粘贴上下文会丢失大量信息。这个命令能帮你将当前对话的完整上下文包括之前的代码和讨论重新组织成一个结构清晰、独立的问题方便你直接粘贴到ChatGPT的对话框中确保了背景信息的无损传递。️ Context Compression 独立提示词当与AI的对话轮次太多触发了上下文长度限制时这个提示词就是救命稻草。它能将冗长的对话历史压缩成一个保留了所有关键决策、代码状态和问题背景的摘要。你可以将这个摘要作为新对话的起点从而有效地延续之前的讨论而不是被迫重新开始。4. 从零开始部署与深度定制指南理解了理念和角色后让我们动手将其集成到你的工作流中。以下步骤以Roo Code为例其他工具如Cursor, Windsurf的路径可能不同但原理相通。4.1 环境准备与基础配置获取项目代码git clone https://github.com/jwadow/agentic-prompts.git cd agentic-prompts建议将该项目克隆到一个永久性目录如~/dev/tools/而不是临时目录方便长期维护。安装Python依赖构建脚本build.py通常只使用Python标准库但为确保无误建议使用Python 3.7版本。你可以通过以下命令检查python --version # 或 python3 --version4.2 构建与部署智能体角色首次构建在项目根目录下运行构建脚本。python roles_builder/build.py如果一切顺利你会在项目根目录看到新生成的custom_modes.yaml文件。用文本编辑器打开它你可以看到所有在manifest.yaml中定义的角色的完整配置。部署到Roo CodeWindows系统将生成的custom_modes.yaml文件复制到以下路径%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\你可以在文件资源管理器的地址栏直接输入%APPDATA%来快速进入该目录。macOS/Linux系统路径通常为~/.vscode/extensions/rooveterinaryinc.roo-cline-*/settings/或者通过Roo Code的设置界面查找“自定义模式”的配置路径。重启生效放置好配置文件后必须完全重启VS Code或你的IDE新的角色模式才会加载到Roo Code的菜单中。在IDE中使用重启后在你的Roo Code聊天界面应该能看到一个模式选择器通常在下拉菜单或按钮中。点击它就能看到“众神殿”的所有角色如“ Maestro”、“️ Principal Engineer”等选择即可切换。4.3 深度定制打造属于你自己的智能体直接使用预设角色很棒但根据你自己的技术栈和开发习惯进行定制才能发挥最大威力。场景一修改现有角色假设你觉得Lead Implementer生成的代码注释风格不符合你的团队规范例如你喜欢Google风格而非JSDoc风格。打开/roles_builder/sources/lead_implementer/prompt.md。找到关于代码注释或编码规范的段落。将其修改为你的团队标准例如## Coding Standards - Write clear, concise comments for all public functions and complex logic. - Follow Google-style docstrings for Python functions. - Use meaningful variable names that reveal intent.保存文件重新运行python roles_builder/build.py然后替换旧的custom_modes.yaml文件并重启IDE。场景二创建一个全新的角色假设你是一个数据工程师经常需要与AI讨论Apache Spark的优化。你可以创建一个Data Engineering Specialist角色。在/roles_builder/sources/目录下新建一个文件夹例如data_engineer。在该文件夹内创建config.yamlname: Data Engineer description: A specialist in big data processing, ETL pipeline design, and Spark optimization.创建prompt.md详细定义该角色的专长、思考框架和输出要求例如# Role: Data Engineering Specialist ## Core Expertise You are an expert in distributed data systems. Your primary domains are: - Apache Spark (PySpark/Scala) performance tuning and fault diagnosis. - Designing scalable and reliable ETL/ELT pipelines. - Data modeling for data warehouses and data lakes. - SQL optimization for large datasets. ...编辑/roles_builder/manifest.yaml在列表中添加- data_engineer。运行构建脚本部署然后你就可以在模式列表中使用这个全新的数据专家了。4.4 命令的安装与使用项目的/commands目录下存放着各种Slash命令模板如github_release.md。部署命令将这些.md文件复制到Roo Code的自定义命令目录。对于Windows上的Roo Code通常是%USERPROFILE%\.roo\commands\如果目录不存在可以手动创建。使用命令在Roo Code聊天框中输入/你应该能看到一个命令列表其中包含你刚复制的命令如/github_release。选择它命令模板会自动插入到输入框你只需填充必要的参数如版本号即可执行。5. 常见问题、排查技巧与进阶玩法在实际使用中你可能会遇到一些问题。以下是我在长期使用中总结的一些经验和解决方案。5.1 常见问题速查表问题现象可能原因解决方案角色模式未在IDE中显示1. 配置文件路径错误。2. 未重启IDE。3. YAML文件格式错误。1. 仔细核对Roo Code官方文档中的自定义模式配置路径。2. 彻底关闭并重新启动VS Code。3. 使用在线YAML校验器检查custom_modes.yaml格式。构建脚本执行报错Python相关1. Python版本过低。2. 缺少依赖库。3. 源码文件YAML/Markdown语法错误。1. 升级Python至3.7。2. 查看build.py开头是否有import非标准库若有则用pip install安装。3. 检查/sources下各角色的config.yaml和prompt.md文件确保无语法错误。角色行为不符合预期1. 提示词指令有歧义或冲突。2. AI模型如Claude-3, GPT-4的理解差异。1. 回看该角色的prompt.md确保指令清晰、无矛盾。尝试简化或重组指令。2. 这是提示工程的常态。需要基于模型的实际反馈迭代优化提示词。记录下AI“犯错”的场景针对性修改提示词。命令 (/) 不生效1. 命令文件未放在正确目录。2. 命令文件扩展名或格式不对。1. 确认命令文件位于%USERPROFILE%\.roo\commands\Windows或等效目录。2. 确保文件是.md格式且内容符合Roo Code命令模板规范。5.2 进阶技巧与心得角色组合拳最强大的用法不是单一角色作战而是角色链。例如需求分析链先用Maestro拆解一个大型需求得到任务列表。设计开发链将“设计API”任务交给Principal Engineer将其输出的API设计交给Lead Implementer去实现。质量保障链实现完成后立即让Test Engineer为生成的代码编写测试。最后可以请Gardener审查代码风格和结构。 这种流水线式的协作能系统化地保障产出质量。提示词迭代心法不要指望一次写出完美的角色提示词。我的方法是记录故障当AI角色输出不符合预期时不要简单重试。把整个对话你的指令、它的输出复制下来。分析根因思考是哪里导致了误解是指令不清晰是缺少约束条件还是角色职责定义有重叠小步修改回到prompt.md中针对性地增加一条规则、一个例子或修改一段描述。然后重新构建、部署、测试。 这个过程很像训练一个员工需要耐心和清晰的反馈。上下文管理策略AI的上下文窗口是宝贵资源。对于非常长的对话例如持续数天的复杂调试定期使用Context Compression提示词来总结之前的对话然后用总结开启一个新对话。这能有效避免因上下文过长导致的模型遗忘早期重要信息的问题。团队共享方案如果你想在团队内推广这套系统最佳实践是建立一个内部Git仓库来维护你们团队定制版的agentic-prompts。每个人都可以克隆这个仓库并通过简单的构建和文件复制来更新自己的本地配置。这确保了全团队使用统一、高质量的角色定义提升了协作效率。这套agentic-prompts系统本质上是一套“元工具”它赋予了你深度定制AI工作伙伴的能力。从简单的使用到深度的定制再到创造全新的专家角色这个过程本身也是对“如何更有效地与AI协作”这一命题的持续探索。我自己的体验是投入时间精心打磨几个核心角色的提示词所带来的长期效率提升是远超预期的。它让AI从一个需要你详细指挥的士兵变成了一个能理解你战术意图、并能自主执行专业任务的军官团。