1. 这个项目为什么值得单独拿出来聊第一次在热榜上刷到msitarzewski/agency-agents这个仓库的时候我的第一反应是又是一个把一堆提示词打包成 Markdown 的合集。点进去翻了大概二十分钟我改主意了。它真正有意思的地方不在于提示词写得多花哨而在于它用一套非常朴素的目录结构把一个 AI 智能体团队这件事给工程化了。说白了它把原本散落在各个聊天窗口里的角色设定变成了可以版本管理、可以复用、可以组合的文本资产。这个仓库的核心形态其实很简单一堆 Markdown 文件每个文件描述一个agency agent也就是某个职能角色的智能体定义。有负责前端体验的、有负责后端架构的、有负责增长运营的、有负责内容策划的角色划分非常接近一家真实的小型数字代理公司。每个文件里通常包含角色定位、职责边界、工作方式、输出规范、协作接口这几块内容。你拿到这些文件之后可以喂给任意支持系统提示词的大模型让它扮演这个角色来干活。它解决的问题很具体。以前我们想让 AI 帮忙做一件事往往要临时写一大段提示词写完这次下次还得重写团队里几个人各写各的风格完全不统一。这个仓库提供了一套现成的、结构化的角色模板你直接拿来改改就能用省掉了从零设计提示词的时间。更重要的是它把多角色协作这件事变得可视化了——你可以清楚地看到每个角色负责什么、不负责什么、跟谁对接。适合谁来参考我觉得有三类人。第一类是独立开发者或者小团队想用 AI 补齐自己团队缺失的职能比如你只会写代码但不会做增长那就可以直接调用对应的角色。第二类是做智能体开发的人想找一个现成的角色定义范式来参考避免自己从零设计目录结构。第三类是产品经理或者运营想理解AI 智能体团队到底是怎么组织的这个仓库是一个很好的入门样本。哪怕你完全不懂代码只要能读懂 Markdown就能用起来。我下面会从设计思路、文件结构、实操落地、常见坑这几个角度把这个仓库拆开讲清楚。不是复述它的 README而是讲我实际用下来觉得有价值的部分以及那些文档里不会写、只有踩过才知道的细节。2. 整体设计思路为什么用 Markdown 来定义智能体2.1 用纯文本做角色定义到底图什么很多人第一次接触智能体开发会下意识觉得应该用某种框架或者平台来做比如拖拽式的编排工具、带可视化流程图的平台。但agency-agents走的是完全相反的路线纯 Markdown 文件没有任何运行时依赖没有配置文件没有代码。这个选择乍看很土实际上非常聪明。Markdown 的第一个优势是零门槛可读可改。一个不懂编程的运营打开文件就能看懂这个角色是干嘛的改几个字就能调整它的行为。如果换成 JSON 或者 YAML 配置虽然机器友好但人读起来就累了改的时候还容易因为缩进、引号出错。Markdown 用自然语言写角色定义本质上就是用人类语言描述需求这恰恰是大模型最擅长理解的形式。第二个优势是天然适配版本管理。每个角色一个文件改动就是一次 commit谁在什么时候把增长负责人的职责从三条改成五条git log 里清清楚楚。团队协作的时候角色定义的演进历史是可追溯的。这一点在提示词工程里特别重要因为提示词是会不断迭代的没有版本管理你根本不知道哪一版效果最好。第三个优势是可组合、可移植。因为角色定义就是文本你可以把它塞进任何支持系统提示词的地方本地跑的开源模型、云端 API、各种智能体平台。不绑定任何一家厂商今天用这个平台明天换那个平台角色文件原封不动搬过去就行。这种资产不锁定的特性在工具迭代飞快的当下价值极高。提示不要小看纯文本这个选择。我见过太多团队把提示词硬编码在代码里结果想改一句话要重新发版运营完全插不上手。把角色定义抽成独立文件是提示词工程走向规范化的第一步。2.2 角色划分背后的代理公司隐喻这个仓库最有辨识度的地方是它用代理公司agency这个隐喻来组织角色。你把它想象成一家接项目的数字工作室有对接客户的、有做策略的、有做执行的、有做质检的。每个 agent 就是公司里的一个岗位。这种划分方式的好处是职责边界清晰。单个大模型如果什么都让它干很容易出现什么都懂一点、什么都不精的情况输出质量不稳定。而把它拆成多个专职角色每个角色只关注自己那一亩三分地输出的专业度和一致性都会明显提升。这跟真实团队分工的逻辑是一样的一个人身兼数职往往哪样都做不好。另一个好处是协作关系可描述。在真实公司里设计师做完稿子要交给前端前端做完要交给测试。这个仓库里的角色定义很多都写了上游输入是什么、下游交付给谁这就为多智能体协作打下了基础。你可以让一个角色输出结构化结果再喂给下一个角色形成一条流水线。我实际用下来这种划分对内容生产类任务效果最明显。比如做一篇产品推广文案可以让策略角色先出定位内容角色再写初稿最后质检角色挑毛病。三个角色各司其职比让一个模型一次性写完质量高出一截。2.3 和主流智能体框架的定位差异现在市面上智能体框架很多有做编排的、有做工具调用的、有做记忆管理的。agency-agents跟它们不是竞争关系而是互补关系。它解决的是角色定义这一层也就是这个智能体是谁、该干什么而框架解决的是怎么调度、怎么调用工具、怎么存记忆。打个比方框架是舞台和灯光agency-agents是演员的剧本和人物小传。你可以把这个仓库里的角色定义直接搬进任意一个智能体平台当系统提示词用。它不挑平台也不要求你学新的 DSL领域特定语言。这种定位差异决定了它的使用方式它不是拿来运行的而是拿来参考和复用的。你不需要安装任何东西clone 下来挑几个角色改吧改吧贴到你的工具里就完事了。对于不想被某个平台绑死的人来说这种轻量定位反而更实用。3. 文件结构与核心内容拆解3.1 一个角色文件里通常有什么虽然每个角色的具体内容不同但结构上有很强的共性。我拆了十几个文件之后总结出一个典型角色文件包含的几块内容你可以对照着看自己手上的文件是不是这个套路。第一块是角色身份与定位。通常开头一两句话说明你是谁、你擅长什么。比如你是一位有十年经验的前端工程师专注于用户体验和性能优化。这句话看着简单但它给模型定了一个基调后面所有的输出都会围绕这个身份展开。第二块是核心职责。用列表形式列出这个角色负责的具体事项一般五到十条。这块是角色定义的骨架写得好不好直接决定输出质量。好的职责描述是具体、可执行的比如为每个页面提供至少三种布局方案并说明取舍而不是空泛的负责页面设计。第三块是工作方式与原则。这块讲的是怎么干包括思考框架、优先级判断、输出风格。比如先理解需求再动手优先考虑可维护性输出必须包含理由。这块往往是区分普通提示词和高质量角色定义的关键。第四块是输出规范。规定输出的格式、长度、结构。比如用 Markdown 输出每个方案配一个表格对比结论放最前面。有了这块多个角色的输出才能拼到一起不打架。第五块是协作接口。说明这个角色的上游和下游是谁需要什么输入、产出什么交付物。这块在多角色协作时特别重要相当于定义了接口协议。注意不是每个文件都完整包含这五块有些角色写得简略有些写得很细。用的时候不要照单全收要按自己的需求裁剪。我一般会把协作接口这块补全因为原始文件里这块经常缺失导致多角色串起来的时候对不上。3.2 目录组织与命名习惯仓库的目录结构整体是扁平的角色文件按职能分组放在不同目录下命名基本是职能-细分的形式一眼能看出这个角色是干嘛的。这种命名习惯值得借鉴用文件名承载信息而不是靠记忆。你打开一个几十个角色的仓库如果文件名都是agent1.md、agent2.md那基本没法用而如果文件名是frontend-performance.md、growth-content.md你扫一眼就知道该用哪个。我建议你在自己的项目里也沿用这个习惯。角色文件命名遵循领域-职责两段式比如marketing-seo、engineering-review、design-system。这样即使角色数量涨到上百个你依然能快速定位。另外很多角色文件之间会有引用关系比如一个项目负责人角色会提到需要协调设计和工程角色。这种软引用不需要严格的依赖管理但你在使用时要注意如果只调用下游角色而没调用上游输出可能会缺上下文。3.3 提示词写法上的几个亮点翻完这些文件我发现几个在提示词写法上很值得学的技巧这里单独拎出来讲。第一个是用你会/你不会来划边界。好的角色定义不仅说清楚该做什么还说清楚不该做什么。比如你不会替用户做最终决策只提供选项和理由。这种负向约束能有效防止模型越界输出一些它不该管的内容。第二个是把判断标准写进角色里。比如质检类角色会写如果发现三个以上问题必须逐条列出并给出修改建议。这种量化的标准比认真检查这种模糊描述有用得多因为它给了模型一个可执行的判断依据。第三个是要求输出理由。很多角色都强调每个建议都要说明为什么。这一条看似增加输出长度实际上大幅提升了可用性因为你能判断这个建议是不是靠谱而不是盲信。第四个是用示例锚定风格。部分角色文件里会带一两个输入输出示例告诉模型遇到这种情况应该这样回。示例是最有效的提示词技巧之一比任何形容词都管用。4. 实操落地从 clone 到跑通一条流水线4.1 环境准备与获取方式这个仓库的使用门槛极低你不需要装任何运行时。最基本的操作就是把它下载到本地。如果你熟悉命令行直接 clone 即可如果不熟悉网页上点下载压缩包也行。git clone https://github.com/msitarzewski/agency-agents.git cd agency-agents ls下载完之后用任意文本编辑器打开就行。我推荐用支持 Markdown 预览的编辑器这样你能边看渲染效果边改。如果你习惯用笔记软件也可以把整个目录导入进去当成一个角色库来管理。提示如果你只是想快速试用不必把整个仓库都读完。先挑三五个跟你当前任务最相关的角色读透它们比囫囵吞枣看五十个有用得多。4.2 挑选角色的判断标准面对几十个角色怎么挑我的经验是按当前任务缺什么来选而不是按哪个角色听起来厉害来选。具体判断可以问自己三个问题。第一这个任务我目前最缺的是哪个环节的能力是缺创意、缺执行、还是缺质检第二这个角色的职责描述跟我实际要做的事匹配度有多高如果只有一半匹配那可能得改。第三这个角色的输出规范跟我下游要用的格式对不对得上如果对不上要么改角色要么加一个转换环节。我一般会先选一个主角色负责核心产出再选一到两个辅助角色负责补充和检查。角色不是越多越好三个以上就容易出现职责重叠、互相打架的情况。4.3 把角色定义接入你的工具接入方式取决于你用什么工具。如果你用的是支持系统提示词的对话工具直接把角色文件内容复制进去当系统提示词就行。如果你用的是智能体平台通常在角色设定或人设字段里粘贴。如果你自己写代码调用 API那就把文件内容读出来作为 system message 传进去。# 一个最简的接入示例把角色文件作为系统提示词 with open(agents/frontend-performance.md, r, encodingutf-8) as f: role_prompt f.read() messages [ {role: system, content: role_prompt}, {role: user, content: 帮我优化这个页面的首屏加载速度} ] # 然后把 messages 传给任意支持该格式的模型接口这里有个细节要注意角色文件里如果包含大量 Markdown 格式符号某些工具可能会把它们当成格式指令而不是内容。如果发现模型输出异常可以试着把文件里的标题符号去掉只保留纯文本内容。4.4 串起一条多角色流水线单角色用顺了之后可以试试多角色协作。基本思路是上一个角色的输出作为下一个角色的输入。比如做一篇内容流程可以是策略角色出大纲 → 内容角色写初稿 → 质检角色挑问题 → 内容角色按意见修改。实操的时候我建议把每个角色的输出都存成独立文件而不是全堆在一个对话里。这样做的好处是每一步的产出都可追溯哪一步出了问题一目了然。而且你可以随时替换其中某个角色不影响其他环节。# 一个简单的流水线目录结构 pipeline/ step1-strategy.md # 策略角色输出 step2-draft.md # 内容角色初稿 step3-review.md # 质检角色意见 step4-final.md # 最终稿串流水线的时候最容易踩的坑是上下文丢失。第二个角色如果不知道第一个角色为什么这么决策可能会推翻前面的结论。解决办法是在交接的时候把上游的关键决策和理由一起传下去而不只是传结果。5. 常见问题与排查技巧实录5.1 角色不听话、输出跑偏怎么办这是最常见的问题。模型没有严格按照角色定义来输出要么风格不对要么职责越界。排查思路按顺序来先看角色定义本身是不是太模糊再看是不是跟用户指令冲突最后看是不是模型能力不够。如果角色定义里全是你应该专业你要认真这种形容词模型很难把握。改成具体的、可验证的描述比如输出必须包含三个方案每个方案列出优缺点。如果用户指令跟角色定义冲突比如角色说只做设计用户却让它写代码那模型大概率会听用户的。这时候要么改用户指令要么在角色定义里加强约束。还有一个容易被忽略的点角色定义太长模型可能只记住开头和结尾。如果发现中间的关键约束被忽略可以把它挪到开头或结尾或者用更醒目的方式重复一遍。5.2 多角色输出风格不统一多个角色串起来用的时候经常出现风格割裂策略角色写得像咨询报告内容角色写得像朋友圈文案拼在一起很违和。这个问题的根源是每个角色的输出规范不一致。解决办法是定义一个全局风格约定让所有角色都遵守。比如统一用词习惯、统一段落长度、统一标题格式。你可以单独写一个style-guide.md在每个角色定义里引用它。这样既保持了角色的个性又保证了整体的协调。5.3 角色文件改乱了怎么回滚因为角色定义是纯文本改坏了很容易恢复。如果你用了 git直接git checkout就行。如果没用 git建议在改之前先复制一份备份。我自己的习惯是每次大改之前先 commit 一次改完对比效果不行就回滚。提示角色定义的迭代一定要有记录。我见过有人改了几十版最后发现还是第一版最好但第一版已经被覆盖找不回来了。养成改前备份、改后记录的习惯能省掉很多返工。5.4 常见问题速查表问题现象可能原因排查方向解决建议输出风格跑偏角色定义太模糊检查是否有具体可验证的描述把形容词换成量化标准职责越界负向约束缺失检查有没有你不会做什么补充边界说明关键约束被忽略定义过长检查约束在文中的位置挪到开头或结尾并重复多角色风格割裂输出规范不统一对比各角色的输出要求增加全局风格约定上下文丢失交接信息不全检查上游决策是否传递交接时带上理由输出格式错乱格式符号被误读检查 Markdown 符号必要时转纯文本6. 我实际用下来的一些体会这个仓库最打动我的地方是它把提示词这件事从个人技巧变成了团队资产。以前提示词是每个人脑子里的经验人一走就带走了现在它变成了仓库里的文件可以 review、可以迭代、可以传承。这个转变的价值比单个角色写得好不好重要得多。另外一个体会是角色定义不是越细越好。我一开始恨不得把每个角色写到上千字结果发现模型反而抓不住重点。后来精简到几百字只保留最关键的职责、边界和输出规范效果反而更好。角色定义的核心是约束不是描述把该管的管住剩下的交给模型发挥。最后分享一个小技巧如果你不确定某个角色定义好不好用别急着改先原封不动用三次。三次都出问题再动手改。因为单次输出有随机性一次不好不代表定义有问题。用三次能帮你区分定义的问题和运气的问题避免瞎改。这个仓库后续还可以这样扩展把你自己团队的角色定义也按这个格式沉淀下来慢慢形成一套属于你自己的角色库。用久了你会发现真正好用的角色就那么几个把它们打磨透比收集一堆用不上的角色有价值得多。