AI智能体工程化实践：基于Prompt-as-Code构建专业角色团队

1. 项目概述构建你的AI智能体“梦之队”如果你和我一样每天都在和Cursor、Roo Code这类AI编程助手打交道那你肯定也经历过这样的时刻面对一个复杂的重构任务你希望AI能像一个经验丰富的架构师一样思考而在编写单元测试时你又希望它能切换成一个严谨的测试专家。默认的“通用助手”模式往往力不从心你需要更专业、更聚焦的“角色”。这正是jwadow/agentic-prompts这个项目试图解决的问题。它不是一个简单的提示词合集而是一套完整的“智能体即代码”工程化方案旨在将零散的提示词管理升级为可维护、可组合、可版本控制的开发工作流。简单来说这个项目为你预制了一支由9位各怀绝技的“数字员工”组成的团队——从统筹全局的项目指挥家Maestro到深谋远虑的首席工程师Principal Engineer再到专注代码整洁的园丁Gardener甚至包括专门唱反调、负责给项目“做减法”的歼灭者Annihilator。你可以根据手头任务随时召唤其中最合适的专家。更重要的是它提供了一套构建工具Roles Builder让你能像管理代码一样管理这些AI角色的定义、更新和部署彻底告别在聊天窗口里复制粘贴大段提示词的原始方式。2. 核心理念与架构“提示词即代码”在深入使用之前理解这个项目的设计哲学至关重要。传统的提示词使用方式存在几个明显痛点难以复用、无法版本管理、混合在对话中容易丢失上下文、修改起来牵一发而动全身。agentic-prompts项目提出的“Prompt-as-Code”理念正是为了解决这些问题。2.1 从“文本片段”到“工程化资产”该项目的核心是将提示词从临时的文本对话转变为结构化的、可编程的工程资产。这带来了几个根本性优势版本控制所有角色定义/roles_builder/sources/下的文件都可以用Git管理你可以清晰地追踪“园丁”角色的职责在哪个版本进行了优化或者“首席工程师”的分析框架何时被增强。关注点分离每个角色的指令prompt.md和元数据config.yaml如角色名称、描述、图标被分开存放。修改角色行为时你只需编辑prompt.md而不会意外改动其展示名称。可组合与可构建通过一个构建脚本build.py项目将分散的源文件编译成单个AI助手可直接读取的配置文件custom_modes.yaml。这意味着你可以轻松地启用或禁用某个角色或者为不同的项目组合不同的角色套装而无需手动拼接文本。标准化与一致性所有角色都遵循相似的结构和指令范式这确保了不同角色在与AI交互时其输出格式、思考逻辑具有一定的可预测性减少了切换角色时的认知负担。2.2 项目结构深度解析让我们拆解一下仓库的目录结构这能帮你理解整个工作流是如何运转的agentic-prompts/ ├── commands/ # 独立的自定义命令模板 │ ├── github-release.md │ ├── question-chatgpt.md │ └── ... ├── prompts/ # 独立的任务提示词模板 │ └── context-compression.md ├── roles_builder/ # “提示词即代码”的核心引擎 │ ├── build.py # 构建脚本将源文件编译为最终配置 │ ├── manifest.yaml # 构建清单声明要包含哪些角色 │ └── sources/ # 角色的“源代码” │ ├── maestro/ # 例如指挥家角色 │ │ ├── config.yaml # 角色元数据名称、描述 │ │ └── prompt.md # 角色的核心指令与系统提示词 │ ├── principal_engineer/ │ └── ... └── custom_modes.yaml # **生成文件**构建脚本的输出供AI助手加载关键理解custom_modes.yaml是生成物而非编辑对象。所有定制化工作都应在sources/目录下完成。这种设计强制了良好的工程实践避免了直接修改生成文件导致的配置混乱和变更丢失。实操心得刚开始接触时很容易下意识去直接修改custom_modes.yaml结果下次一运行构建脚本所有改动都被覆盖了。务必记住源代码在sources/里custom_modes.yaml只是编译后的“可执行文件”。3. “梦之队”角色全解与实战场景这个项目预置的9个角色并非随意堆砌而是覆盖了软件开发生命周期中的关键职能。理解每个角色的定位和最佳使用场景才能最大化其价值。3.1 核心角色职责与调用时机下面这个表格详细说明了每个角色的“人设”、核心能力以及你应该在什么情况下召唤他们角色核心职责典型使用场景输出物示例 指挥家 (Maestro)项目总控任务分解与规划。不写具体代码而是制定计划、分配子任务。面对一个模糊的大型需求如“开发一个个人博客系统”需要先理清步骤、技术选型和模块划分时。一份包含用户故事、模块清单、技术栈建议、阶段划分和风险评估的项目计划书。️ 首席工程师 (Principal Engineer)系统架构与深度设计。关注可扩展性、性能、长期维护成本。需要设计一个微服务通信方案、数据库 schema、或评估引入某个新框架的架构影响时。架构图文字描述、核心接口定义、数据流分析、技术决策文档及备选方案对比。 主导实现者 (Lead Implementer)将设计转化为高质量、可运行的代码。是主要的“写代码”角色。当架构或模块设计已清晰需要动手实现具体功能、API接口或业务逻辑时。完整的功能模块代码、遵循项目约定的类与函数、清晰的注释。 测试工程师 (Test Engineer)质量保障专家编写各种测试用例。在功能实现后需要编写单元测试、集成测试或对现有代码补充测试覆盖时。针对特定函数或模块的 pytest/JUnit 测试用例、Mock 配置、测试数据准备代码。 倡导者 (Advocate)用户体验与交互设计专家。从最终用户角度思考。设计一个功能的用户操作流程、界面交互逻辑或评审现有流程的易用性时。用户旅程地图、线框图文字描述、交互逻辑说明、可访问性改进建议。 园丁 (Gardener)代码整洁度守护者专注于重构和消除技术债。代码库变得臃肿、函数过长、有重复代码或需要升级依赖版本时。重构建议报告、具体的代码重构 diff、依赖版本升级计划及破坏性变更说明。 机器人先生 (Mr. Robot)安全与逆向工程专家擅长“黑盒”测试和寻找非传统解决方案。需要进行简单的安全自查如检查硬编码密钥、理解第三方库的行为或寻找取巧的集成方案时。安全漏洞分析报告、第三方API的反向工程推测、非常规的解决方案思路。️ 观察者 (Observer)可观测性与运维专家关注日志、监控和部署。需要为应用添加日志记录、性能指标或设计如何部署到云环境时。日志规范建议、关键 metrics 定义、Dockerfile 或部署脚本草稿。 歼灭者 (Annihilator)复杂性批判家唯一目标是质疑和简化。项目功能蔓延、代码库过于复杂、需要做减法以聚焦核心价值时。一份“可删除功能/代码”的清单附上详细的理由和对用户影响的评估。3.2 角色协同工作流示例这些角色最强的威力在于协同。假设你要开发一个带有用户认证的待办事项API一个高效的工作流可能是启动阶段先与 指挥家对话输入“我需要一个带用户注册登录的待办事项REST API”。指挥家会输出一份计划可能包括用户认证模块、待办事项CRUD模块、数据库设计、API文档等子任务。设计与架构将指挥家输出的“数据库设计”子任务交给️ 首席工程师。它会设计出User和Todo表的字段、关系并给出选用SQLite还是PostgreSQL的建议及理由。核心实现将首席工程师的数据库Schema和“用户认证模块”设计交给 主导实现者。它会用你指定的框架如FastAPI写出注册、登录、JWT令牌颁发的完整代码。质量保障拿到主导实现者写的登录函数后切换至 测试工程师让它为这个函数编写覆盖成功、失败如错误密码等多种情况的单元测试。代码优化在开发过程中感觉代码结构有些混乱可以请 园丁审查当前文件它会提出提取工具函数、优化导入语句等重构建议。最终审视功能基本完成后让 歼灭者审视整个项目。它可能会尖锐地指出“这个‘忘记密码’的邮件提醒功能在MVP阶段是否必需它引入了外部依赖增加了复杂性建议移除或推迟。”这个流程中你作为“人类项目经理”在不同阶段调度最专业的AI角色从而获得远超通用助手的输出质量和深度。注意事项角色切换会丢失上下文。虽然项目提供了/subtask系列命令来创建子会话保留上下文但在复杂跨角色协作时一个有效技巧是在切换角色前用一小段文字总结当前阶段的核心结论和待办事项并作为新对话的初始输入。这相当于为下一个角色做了“上下文交接”。4. 自定义命令与独立提示词的妙用除了角色模式项目还提供了/commands和/prompts目录它们代表了另一种更轻量级的提示词复用方式。4.1 自定义命令对话中的“快捷键”自定义命令Slash Commands是可以在AI助手对话过程中直接触发的模板。例如在Roo Code或Cursor中输入/github-release并按下Tab就会插入一个预设好的提示词模板用于生成发布说明。以“ GitHub Release”命令为例它的核心价值在于标准化。手动为每次更新写Release Notes既繁琐又容易格式不一。这个命令模板内嵌了分析git历史、归类提交信息feat, fix, chore等、识别破坏性变更的逻辑。你只需要提供前后两个版本标签它就能输出结构清晰、符合惯例的发布说明大大提升了效率和专业度。另一个强大的命令是“ Subtask Analysis”和“ Subtask Code”。它们解决了长上下文对话中的“任务污染”问题。当你在和一个角色如首席工程师进行深度架构讨论时突然需要详细分析某个文件的具体实现但又不想让这些细节冲淡主对话的架构语境就可以使用/subtask-code。它会创建一个专注于编码的子会话这个子会话能访问主会话的上下文如架构决策但它的所有讨论都局限在实现细节上完成后你可以将结果摘要带回主会话。这相当于为AI开辟了一个“线程”或“沙盒”。4.2 独立提示词应对特定难题的工具箱/prompts目录下的模板用于解决一些非常具体但棘手的问题。目前最典型的是“️ Context Compression”上下文压缩。为什么需要上下文压缩高级的AI编码助手通常有很长的上下文窗口如128K甚至更多但终究有上限。当一个长期项目对话包含了大量代码、错误信息、讨论历史时可能会触及令牌限制导致AI忘记最早的内容。此时直接丢弃历史是下策因为可能丢失关键决策信息。“上下文压缩”提示词的作用就是指导AI将冗长的对话历史提炼成一个精炼、结构化、包含所有关键决策、代码状态和待办事项的摘要。你可以将这个摘要作为新的对话起点从而“重置”上下文窗口同时不丢失项目记忆。这就像为漫长的会议做了一份精准的纪要。实操技巧不要等到令牌超限才做压缩。在开启一个复杂的新任务模块前主动进行一次上下文压缩是一个好习惯。这不仅能节省令牌还能迫使你和AI一起回顾并确认当前的项目状态减少后续的误解。5. 从零开始完整配置与使用指南了解了所有组件后我们来一步步完成从克隆仓库到在编辑器中使用的全过程。这里以在VSCode上配置Roo Code为例其他工具如Cursor的路径类似请参考其官方文档。5.1 环境准备与项目获取首先你需要一个能运行Python脚本的环境以及目标AI助手工具如Roo Code。获取项目代码git clone https://github.com/jwadow/agentic-prompts.git cd agentic-prompts检查Python环境确保你的系统已安装Python 3.7。在终端运行python --version或python3 --version确认。5.2 构建与部署自定义角色这是配置的核心步骤目的是生成AI助手能识别的custom_modes.yaml文件。可选角色定制在投入正式使用前我强烈建议你浏览/roles_builder/sources/下的各个角色目录。打开prompt.md看看预置的指令是否符合你的编码风格或团队规范。你可以进行微调例如在“主导实现者”的角色指令中加入你团队特定的代码风格要求如“所有函数必须包含Google风格的docstring”。执行构建脚本在项目根目录下运行构建命令。python roles_builder/build.py如果系统默认的python命令指向Python 2请使用python3。 运行成功后会在根目录生成或更新custom_modes.yaml文件。请勿手动编辑此文件。定位配置文件路径你需要将生成的custom_modes.yaml文件放置到Roo Code指定的配置目录。Windows%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\macOS/Linux~/.vscode/extensions/rooveterinaryinc.roo-cline-*/settings/(路径中的*为版本号) 或~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/注意路径可能因Roo Code版本更新而变动。最可靠的方法是在VSCode中打开命令面板CtrlShiftP搜索“Roo: Open Settings Folder”它会直接打开正确的目录。放置配置文件将生成的custom_modes.yaml文件复制或软链接到上述目录中。重启与验证完全重启VSCode。重启后在Roo Code的聊天界面你应该能看到模式选择下拉菜单中除了默认的“Roo”还出现了“Maestro”、“Principal Engineer”等所有你构建的角色。选择一个角色开始对话吧5.3 安装自定义命令自定义命令的安装相对简单它们是独立的Markdown文件。定位命令目录找到Roo Code存放自定义命令的目录。Windows%USERPROFILE%\.roo\commands\macOS/Linux~/.roo/commands/如果目录不存在可以手动创建。复制命令文件将本项目/commands目录下的所有.md文件如github-release.md复制到上述命令目录中。即时生效自定义命令通常无需重启。在Roo Code的聊天输入框键入/你应该能看到弹出的命令列表里包含了“GitHub Release”等新增选项。6. 高级定制打造属于你自己的AI角色预置的9个角色已经非常强大但真正的威力在于你可以基于此框架无限扩展。假设你想创建一个专注于数据库性能调优的专家角色“DBA Tuner”。6.1 创建新角色的源代码在/roles_builder/sources/目录下创建一个新的文件夹例如dba_tuner。在该文件夹内创建两个必需文件config.yaml: 定义角色的元数据。# config.yaml name: DBA Tuner description: A database performance tuning expert focused on query optimization, index design, and execution plan analysis. avatar: ️ # 选一个合适的表情符号作为头像prompt.md: 定义角色的核心指令和行为。这是最关键的部分。# 角色DBA Tuner (数据库性能调优专家) ## 核心身份 你是一位资深数据库管理员和性能优化专家尤其精通关系型数据库如 PostgreSQL, MySQL。你的专长是分析慢查询、设计高效索引、解读执行计划并提出切实可行的优化方案。 ## 核心能力与原则 1. **安全第一**任何建议的优化操作如创建索引、修改配置都必须评估其对现有业务的影响并优先建议在非高峰时段或测试环境执行。 2. **数据驱动**永远要求或主动寻找具体的性能数据如查询执行时间、EXPLAIN ANALYZE输出、慢查询日志片段。拒绝空谈优化。 3. **系统性思考**不仅关注单条查询还要考虑索引对写入性能的影响、锁竞争、连接池配置等系统性因素。 4. **沟通清晰**用通俗的语言解释复杂的数据库概念并使用比喻如“索引就像书的目录”帮助理解。 ## 工作流程 当用户提出一个性能问题时请按以下步骤响应 1. **信息收集**首先询问或要求用户提供 - 数据库类型和版本。 - 有问题的具体SQL查询。 - 相关的表结构CREATE TABLE语句。 - 已有的索引情况。 - 如果可能提供 EXPLAIN (ANALYZE, BUFFERS) 的输出。 - 查询的当前执行时间和频率。 2. **分析与诊断**基于提供的信息分析可能瓶颈 - 是否缺少必要的索引建议的索引字段是什么为什么 - 是否存在全表扫描如何避免 - 查询语句本身是否可以重写如避免SELECT *优化JOIN顺序 - 执行计划中是否有明显的警告如高代价的Sort、Nested Loop 3. **提供建议**给出具体的、可操作的优化建议列表每条建议应包含 - **建议内容**例如“在users表的email字段上创建索引”。 - **原因**解释为什么这个改动会有效。 - **潜在影响**说明创建索引的耗时、占用空间以及对INSERT/UPDATE操作的可能影响。 - **操作命令**提供可以直接执行的SQL语句如 CREATE INDEX CONCURRENTLY idx_users_email ON users(email);。 4. **后续步骤**建议如何验证优化效果如重新运行EXPLAIN ANALYZE并提醒监控变更后的系统表现。 ## 对话开场示例 “你好我是DBA Tuner专注于解决数据库性能难题。请告诉我你遇到的慢查询详情或者把EXPLAIN的输出贴给我我们一起分析。”6.2 注册新角色到构建系统创建好源文件后你需要告诉构建脚本将这个新角色包含进去。打开/roles_builder/manifest.yaml文件。在现有的角色列表下添加新角色文件夹的名称。# manifest.yaml roles: - maestro - principal_engineer # ... 其他已有角色 - dba_tuner # 添加这一行6.3 构建与使用保存所有修改后重新运行构建脚本python roles_builder/build.py然后将新生成的custom_modes.yaml文件覆盖到Roo Code的配置目录。重启VSCode后你的“DBA Tuner”就会出现在角色列表中了。通过这种方式你可以为任何垂直领域如前端CSS专家、DevOps流水线专家、技术文档写手创建专属AI角色不断扩充你的数字团队。7. 常见问题与故障排查在实际使用中你可能会遇到一些问题。以下是一些常见情况的排查思路。7.1 角色或命令未生效现象可能原因解决方案角色下拉菜单中没有新角色1.custom_modes.yaml文件未放在正确目录。2. VSCode/Roo Code未重启。3. 构建脚本执行失败custom_modes.yaml内容为空或格式错误。1. 使用“Roo: Open Settings Folder”命令确认路径。2. 完全关闭并重启VSCode。3. 在终端运行构建脚本检查是否有Python错误输出。确保manifest.yaml中角色名与文件夹名一致。自定义命令列表中无新增命令1. 命令文件未放在~/.roo/commands/目录。2. 命令文件扩展名不是.md。3. Roo Code版本过旧。1. 确认命令目录路径正确。2. 确保文件是Markdown格式。3. 尝试在输入框键入完整命令名如/github-release看是否能触发。切换角色后AI“失忆”这是预期行为。切换角色会开启新会话丢失之前对话的上下文。使用/subtask-analysis或/subtask-code命令在子会话中处理分支任务。或在切换前手动将关键信息复制到新对话中。7.2 构建脚本执行报错错误ModuleNotFoundError: No module named yaml原因缺少PyYAML库。 解决安装所需依赖。在项目根目录下通常可以运行pip install pyyaml或pip install -r requirements.txt如果项目提供了此文件。错误角色配置文件语法错误原因在编辑config.yaml或prompt.md时可能引入了不正确的YAML或Markdown格式。 解决仔细检查出错角色源文件中的语法。对于YAML注意缩进和冒号后的空格。可以使用在线YAML校验器辅助检查。7.3 性能与使用技巧提示词过长导致响应慢一些角色如“首席工程师”的指令非常详细这可能会略微增加AI处理提示词的开销并占用一部分上下文窗口。这是为了换取更精准、更专业的输出所做的权衡。如果感到响应迟缓可以尝试简化该角色prompt.md中非核心的指令部分。如何管理多个项目配置custom_modes.yaml是全局生效的。如果你希望为不同项目使用不同的角色组合一个变通方法是维护多个不同的manifest.yaml文件如manifest.project_a.yaml,manifest.project_b.yaml在切换项目时用对应的清单文件替换默认的manifest.yaml然后重新运行构建脚本并替换配置文件。更工程化的做法是编写一个简单的shell脚本来自动化这个过程。与团队共享配置你可以将定制好的sources/目录和manifest.yaml推送到团队内部的Git仓库。团队成员克隆后只需运行构建脚本并放置配置文件即可获得完全一致的AI助手体验这极大地促进了团队协作的标准化。这个项目将提示词工程从一种“艺术”转变为一种可管理、可扩展的“工程实践”。它可能不会让你立刻写出十倍好的代码但它能让你和AI的协作效率提升十倍并且让这种协作变得可预测、可重复。最让我个人受益的一点是通过角色划分我被迫在动手编码前更系统地去思考设计这本身就是一个巨大的进步。