先交代一个背景。我平时写代码有一半时间都耗在“来回切换上下文”上需求从文档里来编码前要脑补设计写完要自己补测试最后还要过一遍代码审查。后来我把这套流程整体搬进了终端里的AgentTeam初步跑通了从需求拆解到代码审查的完整链路。下面这篇实战记录就是我在OpenCode上搭AgentTeam的全过程适合已经用过AI编程助手、但觉得单个Agent输出不够稳定的人也适合想把团队开发规范固化到AI协作流程里的同学。我会从OpenCode到底是什么讲起一路讲到角色设计、配置写法、一次完整需求怎么从拆解走到交付再附上我踩过的坑和排查思路。全程不涉及复杂架构只要你有一个能跑Node的终端加上一个支持工具调用的模型服务就可以按步骤复现。1. 先搞清楚OpenCode和AgentTeam到底是什么关系1.1 OpenCode不是又一个聊天窗口OpenCode是一个在终端里运行的AI编码代理形态上很像命令行工具但它不是简单的“问答框”。它能拿到你的项目目录能读文件、改文件、执行命令、搜索代码并且根据你的自然语言指令决定调用哪些工具。你可以把它理解成一个“有手有脚”的实习生你给它一个任务它能自己去翻代码、跑测试、改文件然后把结果汇报给你。它的核心优势是“一切皆文件”。OpenCode的Agent、命令、规则、权限、自动化钩子都是用一个一个Markdown或JSON文件定义的。这一点很关键你能像管理代码一样管理你的AI协作流程而不是每次都在GUI界面里点点点。配置可以进Git仓库可以走代码评审可以版本回滚新同事clone下来就能复用。AgentTeam不是OpenCode官方造的词而是我在实践中给它起的模式名。说的是把一个原本“什么都干”的Agent拆成多个角色Agent比如产品Agent、开发Agent、测试Agent、审查Agent。用户只给一句需求团队里的Agent按角色链路依次或按需接管而不是一个Agent从头包到尾。1.2 为什么要组团队而不是用单Agent单Agent最大的问题不是能力而是上下文负担。一个Agent既要理解产品意图又要设计技术方案还要写代码、跑测试、自查风格所有信息都堆在同一个上下文窗口里。一旦对话变长或者任务变复杂它很容易“忘掉”最开始的约束输出变得随意。你可以想象让一个人同时做产品经理、开发、测试、运维而且这个人还特别自信做完了根本不自查。AgentTeam把职责切开了。每个Agent的上下文入口很小只需要关注自己负责的那一段。产品Agent只需要把模糊需求拆成可验收的PRD开发Agent只需要照着PRD实现测试Agent只需要照着验收标准去验证。上下文负担下降输出质量自然更稳定。两种模式的差异我可以直接拿实际体验说模式上下文负担质量稳定性可维护性适合阶段单Agent直出大依赖输入顺序容易中途漂移低规则全塞在对话里一次性脚本、临时需求AgentTeam流水线小高每个环节有明确输入输出高角色规则全部文件化产品功能、长期项目、多人协作所以我的建议很直接如果你只是让AI写个一次性处理脚本单Agent够用如果你是在正经项目里做功能迭代而且希望产出能被后来人接手那非常值得把AgentTeam这套模式建起来。1.3 这套方案适合谁、需要什么前置条件适合人群主要有三类。第一种是已经在用AI编程助手、但觉得输出不够稳的人尤其是同一个需求要反复“喂”给AI的情况。第二种是团队里想统一编码规范、但不想靠口头传达的人把规则写成AgentTeam的公共配置每次协作自动生效。第三种是想做自动化试点的人比如把“需求到PRD到实现”这条链路沉淀成团队资产。前置条件真的不高。你需要一个能跑Node的终端环境一个支持工具调用的模型服务以及基础的Markdown读写能力。不要求你会Kubernetes不要求你懂微服务也不需要额外起一套服务端。OpenCode自己就是个命令行客户端所有Agent逻辑都跑在你本地。2. 环境准备与基础配置5分钟跑通OpenCode2.1 安装和初始化一步都不能省我这里以npm全局安装为例因为跨平台最简单。你可以打开终端执行npm install -g opencode-ai opencode --version正常能看到版本号就说明装好了。如果你的包管理器是Homebrew也可以尝试用brew安装具体以你用的版本所对应的官方安装文档为准不用在一个安装方式上死磕。装好之后先初始化opencode init这个命令会在项目根目录生成一个.opencode/配置目录里面通常包含默认的opencode.json、示例AGENTS.md以及一些子目录。首次执行时我建议你直接回车用默认配置先把基础链路跑通再去做定制。一个实操小经验不要在项目根目录里直接初始化就完事应该先确认这个目录确实是你接下来要做的项目目录。因为OpenCode的Agent会基于当前目录感知项目结构如果在错误目录初始化后面Agent读取上下文时容易“找错家”。2.2 模型接入和密钥管理别把Key写进配置文件OpenCode本身不绑定某个固定模型它支持接入多种兼容主流协议的模型服务。你需要把模型服务的接口信息配置好。我习惯的做法是优先使用环境变量而不是把密钥写进配置文件export LLM_PROVIDERyour-provider export LLM_API_KEYsk-xxxx export LLM_MODELyour-model-name如果你用的是本地模型服务还需要额外配置服务的本地地址把provider指到对应的本地服务名上。配置完成后可以随便发一句“你好”测试一下通不通。第一次跑通的时候OpenCode会列出当前可以选用的模型和工具确认模型支持工具调用即可。我把密钥管理单独拿出来强调是因为很多人为了方便喜欢直接把API Key填到opencode.json里。一旦这个文件进了Git仓库等于把钥匙交给了所有能看仓库的人。环境变量虽然也没多复杂但至少不会因为一次误提交就泄露。2.3 认识配置目录一切皆文件一切可Git初始化之后你的配置目录大概长这样项目根目录 └── .opencode/ ├── opencode.json ├── AGENTS.md ├── agent/ │ ├── pm.md │ ├── architect.md │ ├── coder.md │ ├── tester.md │ └── reviewer.md ├── command/ │ ├── plan.md │ ├── implement.md │ ├── verify.md │ └── review.md ├── skill/ └── hook/opencode.json是主配置负责模型、权限、工具开关这类全局项。AGENTS.md是所有Agent共享的项目规则和上下文你可以把它理解成“团队的入职手册”。agent/目录下每个Markdown文件就是一个角色定义了角色的职责、可用工具、模型偏好。command/目录是斜杠命令比如/plan、/implement一个命令就是一个工作流入口。skill/放可复用的技能包hook/放自动化钩子脚本。这个结构看起来简单但好处非常实在。配置文件就是普通文本能够做差异化评审能够随代码一起发布。谁改了什么、为什么改Git历史里都查得到。这也为后面团队化落地埋下伏笔。3. 设计并搭建自己的Agent团队3.1 角色矩阵怎么定先回答三个问题搭建AgentTeam之前先别急着写Prompt。我建议先用表格把角色盘出来每个角色回答三个问题它拥有什么上下文它只能动哪些工具它的产出物落在哪里我这边最常用的角色矩阵是这样角色核心职责模型偏好建议工具产品Agentpm需求拆解、用户故事、验收标准推理强、上下文大read、write架构Agentarchitect技术方案、目录结构、接口设计推理强read、grep、glob开发Agentcoder实现功能、补单测、自测速度优先read、write、edit、bash测试Agenttester按验收标准补测试、跑回归速度优先read、bash审查Agentreviewer代码审查、规范检查、边界扫漏推理强read、diff、bash角色数量我建议控制在3到5个不要一上来就整十个。我最早试着定义了十个角色结果大部分时间都在调角色之间的协作关系真正的编码工作反而进展很慢。砍到五个人核心角色之后链路才顺起来。AgentTeam的价值是分工清晰不是角色越多越好。3.2 用Markdown定义Agent角色先从一个PM写起在agent/pm.md里写这样一段定义--- description: 需求负责人负责把模糊输入转成可执行PRD model: strong-reasoning mode: read-write tools: - read - write --- 你叫PM是团队的需求负责人。 你负责把用户的一句话需求拆成 1. 背景与目标 2. 用户故事 3. 验收标准 4. 影响范围与风险 工作约定 - 先读项目根目录的 AGENTS.md - 产出物写入 .agent-tasks/prd.md - 验收标准必须写清楚前置条件、操作动作和预期结果这里面frontmatter的几个字段值得解释一下。description是给使用者看的方便在交互界面里认出这个角色。model不是具体模型名我建议做成一个“模型别名”比如strong-reasoning和fast-code然后在全局配置里把别名映射到真正的模型服务上。tools是白名单只写这个角色允许使用的工具。mode控制读写权限范围PM不需要执行shell命令那就别给它开bash权限。产出物写到哪里也必须在角色定义里约定清楚。我统一放在.agent-tasks/目录每个角色有自己的产出文件名。这样后面的Agent只需要知道约定路径就能找到前面的产出物不需要在对话里反复传一大段上下文。3.3 用AGENTS.md沉淀团队规则别在角色里重复造轮子AGENTS.md是每个Agent启动时都会自动读取的公共上下文。我把项目级规则都写在这里而不是塞进每个角色的定义里。当时我的项目是一个内部CLI工具AGENTS.md长这样# Mock CLI 项目规则 ## 协作约定 - 新会话先读 .agent-tasks/ 目录下的最新任务文档 - 所有功能变更必须补单测测试命令pytest tests/ - 改动涉及对外参数时必须同步更新 --help 文案 ## 禁止事项 - 禁止直接修改 lock 文件 - 禁止绕过校验器直接写核心逻辑公共规则集中放的最大好处是“只改一处”。比如某天团队决定测试命令从pytest换成别的只需要更新AGENTS.md所有Agent下一次会话自然沿用新规则。如果你把规则分散写在每个角色Markdown里改一次就要改五个文件还容易漏。另外一个经验是AGENTS.md要写“可验证”的规则不要写“写高质量代码”这种空话。宁可写成“所有函数必须带类型注解”“新增对外参数必须更新文档”这种能检查的条目Agent才有执行依据。3.4 用斜杠命令把Agent串成流水线角色定义好了接下来要解决“怎么触发”。我建了几个斜杠命令本质上是流水线入口。command/plan.md是这样--- title: plan description: 让PM Agent把需求拆成PRD agent: pm --- 读取用户输入的需求按PRD模板写入 .agent-tasks/prd.mdcommand/implement.md则会这样写--- title: implement description: 让Coder Agent按PRD实现 agent: coder --- 先读 .agent-tasks/prd.md再实现完成后调用 /verify这样设计背后的逻辑是把复杂的内部协作链路收敛成几个简单的用户入口。使用者在终端只需要敲/plan 给某个模块增加参数校验内部由PM、Coder、Tester这些角色自动接力体验上就像在跟一个团队对话。斜杠命令本身也可以进入Git仓库团队可以共同迭代命令集。4. 一次完整协同从需求到交付4.1 场景设定一个真实的CLI需求为了让你更直观地看到这套流程怎么跑我拿一个具体场景来演示。假设我现在维护一个内部CLI工具模拟项目X工具名暂时叫mock-cli用Python写的。用户反馈说执行mock-cli run --config时如果传了一个不存在的配置文件路径程序只输出一句“Error”完全看不出是路径问题、权限问题还是格式问题。在OpenCode里我直接发起需求/plan 给 mock-cli 的 --config 参数增加路径存在性校验错误信息要友好覆盖空字符串、不存在、目标是目录三种情况4.2 PM Agent产出一份能验收的PRDPM Agent读取AGENTS.md和项目结构后生成了一份PRD核心内容是这样## PRDmock-cli config路径校验 ### 用户故事 作为mock-cli使用者当我传入不存在的配置文件路径时我希望得到明确提示 以便我快速修正命令。 ### 验收标准 - 传入不存在的路径时输出“config file not found: path”退出码非0 - 传入目录路径时输出“expected a file, got directory” - 传入空字符串时输出“--config is required”这一步看起来只是写文档其实非常关键。如果让AI直接写代码它大概率只处理“路径不存在”这一种情况但验收标准一旦写清楚后面的Coder和Tester就有了明确分工。PRD是最容易被偷懒跳过的一步但我建议你一定保留。它相当于给整个AgentTeam装上了“瞄准镜”。4.3 Coder Agent落地实现执行/implementCoder Agent按照PRD新建了一个校验模块核心实现是from pathlib import Path class ConfigPathError(Exception): def __init__(self, message: str, hint: str ): super().__init__(message) self.hint hint def validate_config_path(path: str) - Path: if not path or not path.strip(): raise ConfigPathError(--config is required) p Path(path).expanduser() if not p.exists(): raise ConfigPathError(fconfig file not found: {path}, hintuse --init to create one) if p.is_dir(): raise ConfigPathError(fexpected a file, got directory: {path}) return pCoder完成实现后自己也会追加一份测试文件把PRD里的验收标准转成pytest用例并跑一遍测试。这个“自测”环节很重要它让Coder进入下一步审查之前先把明显问题筛掉。实测下来加了自测这一步之后Reviewer阶段发现的问题数量明显变少。4.4 Tester和Reviewer交叉验证最后把好关实现和自测都过了我执行/verify和/review让Tester和Reviewer分别进场。Tester会重新读一遍.agent-tasks/prd.md对照验收标准补测试、跑回归。Reviewer则会检查错误处理、命名、边界条件当时它给出的审查意见包括抛出异常时没有显式设置退出码shell里可能拿到0需要修正提示信息里“not found”和“expected a file”的文案风格不统一expanduser之后缺少对应的路径解析测试这些意见虽然不是致命问题但都很实际。Coder再修一轮测试重新通过我人工确认一遍改动范围没越界才合并代码。整个链路跑完我想特别提醒一点AgentTeam是辅助最终合并权还是应该握在人手里尤其是对外行为有变化的场景。5. 常见问题与排查技巧实录5.1 Agent之间“失联”上下文漂移的根源AgentTeam里每个Agent都有自己的独立上下文它不会自动继承上一个Agent的对话历史。所谓“团队记忆”本质上靠的是磁盘文件。如果你发现Coder Agent说“没看到PRD”或者“需求文件为空”先不要怀疑模型智商大概率是文件路径没有落到约定目录或者产出文件太大被截断了。我的经验是在AGENTS.md里加一条硬性约定“新会话先读.agent-tasks/目录下的最新任务文档”。这条用文字写出来比在命令行里反复粘贴需求可靠得多。另外PRD文件不要写得太长尽量控制在200行以内必要信息可以用分文件组织避免上下文窗口被大段文档占满。5.2 工具调用和权限配置不匹配你会遇到Agent想执行命令、写文件但被权限系统拦下来的情况。OpenCode对工具调用有权限模型默认行为偏向保守。我习惯先在opencode.json里配置一个最小授权集合{ permissions: { allow: [read, write, bash, edit], deny: [rm -rf, git push --force] } }这里的原则是“能不开就不开”。写代码的Agent需要bash权限那单独给Coder开PM Agent只负责写文档只需要read和write。权限开得太大一旦某个Agent误触危险命令代价会被放大。每次Agent报权限不足不要第一时间全放行先看这个工具是不是它职责内必需的。5.3 多Agent同时改同一个文件冲突怎么破我最初踩过最深的坑是并行冲突。两个Agent同时收到指令一个在改配置一个在补测试结果两个会话同时写入同一个文件后写的人把先写的内容覆盖了。这问题在文件系统层面不会像Git合并那样给你提示它是直接覆盖。我的解法是设计上默认串行一条命令只激活一个主Agent主Agent内部连续调用工具没问题但不要同时启动两个都会写同一目录的命令。如果确实需要并行只允许只读类Agent并行写操作严格排队。更细一步我给每个角色定义了“文件所有权”谁产出谁负责别人要改也必须先通过职责内的命令入口而不是直接编辑。5.4 模型能力不均导致的输出波动不同角色如果共用同一个模型性能和成本的矛盾会很明显。我当时试过给所有角色都用同一个强推理模型结果Coder阶段每一步都很慢体验非常难受。后来我把模型拆成“强推理”和“快速编码”两类PM、Reviewer用强推理模型Coder、Tester用更快的模型整体效率立刻上来了。这里我把最容易遇到的问题整理成速查表几张表放在一起方便你以后排查问题现象可能原因处理建议Agent输出与PRD无关没有先读任务文件检查AGENTS.md协作约定工具调用反复报错模型不支持工具调用换支持工具调用的模型上下文被截断PRD或项目文件太长拆小文件按需引用两个Agent互相覆盖文件并行写同一目标文件改串行定义文件所有权审查意见不痛不痒Reviewer上下文视野太窄让它读diff和变更文件而不是只看单文件6. 进阶扩展把AgentTeam沉淀成团队资产6.1 用Hooks加一道自动化护栏当AgentTeam开始被多人使用时难免有人临时改配置或者Agent执行了超出预期的命令。我建议在.opencode/hook/里加一些生命周期脚本监听工具执行事件在操作落地前做一次检查。比如禁止强制推送到共享分支、禁止删除关键目录这类规则用钩子脚本写下来最可靠。钩子机制有个好处它不依赖模型“守规矩”而是在执行链路上做硬约束。团队规则从“靠AI自觉”升级成“靠系统拦截”安全感完全不一样。注意钩子脚本要放在配置目录里跟其他配置一起走版本管理否则每台机器都要手动同步一份。6.2 用MCP扩展工具集但要克制OpenCode支持通过MCP方式接入外部工具集比如内部文档库、测试平台、监控系统、数据库查询工具。接入之后Agent可以调用这些工具完成更复杂的闭环操作。但是这里我要劝你克制每接入一个MCP工具都会占用Agent的上下文空间接入太多反而降低主任务质量。我个人的经验是每个角色的工具集控制在5个以内MCP工具只在特定角色里开启。比如Tester Agent可以接测试平台工具Coder Agent没必要看到所有测试数据。工具的接入也要写进角色定义的白名单里不能让所有Agent都能调用所有工具。6.3 把整份配置纳入版本管理新成员秒上手最后一个进阶建议是把.opencode/整个目录纳入Git仓库。角色文件、命令文件、AGENTS.md、hooks、权限配置全部都可以走代码评审和版本回滚。新成员加入时只需要clone仓库、安装OpenCode、配置环境变量里的密钥就能获得和团队完全一致的AgentTeam。这里有个重要禁忌任何密钥类信息都不要提交到仓库。环境变量、密钥管理工具、本地未跟踪文件才是密钥该待的地方。配置文件里只保留模型别名和工具白名单真正敏感的信息通过外部环境注入。我实际测试下来一个新成员从clone到第一次跑通完整命令链路半小时以内是完全可以做到的。我实际搭完这套AgentTeam之后最深的体会是花时间的不是写角色Prompt而是想清楚每个角色的输入、输出和边界。开始我设计了十个角色结果大部分精力都在调协作砍到五个核心角色之后链路才真正顺畅。最后再分享一个小技巧把AGENTS.md里的公共规则当成测试用例标准来写AgentTeam的产出稳定性基本跟着这套规则的清晰度走。规则越明确角色越专注团队就越像一个真正的团队。
先交代一个背景。我平时写代码有一半时间都耗在“来回切换上下文”上需求从文档里来编码前要脑补设计写完要自己补测试最后还要过一遍代码审查。后来我把这套流程整体搬进了终端里的AgentTeam初步跑通了从需求拆解到代码审查的完整链路。下面这篇实战记录就是我在OpenCode上搭AgentTeam的全过程适合已经用过AI编程助手、但觉得单个Agent输出不够稳定的人也适合想把团队开发规范固化到AI协作流程里的同学。我会从OpenCode到底是什么讲起一路讲到角色设计、配置写法、一次完整需求怎么从拆解走到交付再附上我踩过的坑和排查思路。全程不涉及复杂架构只要你有一个能跑Node的终端加上一个支持工具调用的模型服务就可以按步骤复现。1. 先搞清楚OpenCode和AgentTeam到底是什么关系1.1 OpenCode不是又一个聊天窗口OpenCode是一个在终端里运行的AI编码代理形态上很像命令行工具但它不是简单的“问答框”。它能拿到你的项目目录能读文件、改文件、执行命令、搜索代码并且根据你的自然语言指令决定调用哪些工具。你可以把它理解成一个“有手有脚”的实习生你给它一个任务它能自己去翻代码、跑测试、改文件然后把结果汇报给你。它的核心优势是“一切皆文件”。OpenCode的Agent、命令、规则、权限、自动化钩子都是用一个一个Markdown或JSON文件定义的。这一点很关键你能像管理代码一样管理你的AI协作流程而不是每次都在GUI界面里点点点。配置可以进Git仓库可以走代码评审可以版本回滚新同事clone下来就能复用。AgentTeam不是OpenCode官方造的词而是我在实践中给它起的模式名。说的是把一个原本“什么都干”的Agent拆成多个角色Agent比如产品Agent、开发Agent、测试Agent、审查Agent。用户只给一句需求团队里的Agent按角色链路依次或按需接管而不是一个Agent从头包到尾。1.2 为什么要组团队而不是用单Agent单Agent最大的问题不是能力而是上下文负担。一个Agent既要理解产品意图又要设计技术方案还要写代码、跑测试、自查风格所有信息都堆在同一个上下文窗口里。一旦对话变长或者任务变复杂它很容易“忘掉”最开始的约束输出变得随意。你可以想象让一个人同时做产品经理、开发、测试、运维而且这个人还特别自信做完了根本不自查。AgentTeam把职责切开了。每个Agent的上下文入口很小只需要关注自己负责的那一段。产品Agent只需要把模糊需求拆成可验收的PRD开发Agent只需要照着PRD实现测试Agent只需要照着验收标准去验证。上下文负担下降输出质量自然更稳定。两种模式的差异我可以直接拿实际体验说模式上下文负担质量稳定性可维护性适合阶段单Agent直出大依赖输入顺序容易中途漂移低规则全塞在对话里一次性脚本、临时需求AgentTeam流水线小高每个环节有明确输入输出高角色规则全部文件化产品功能、长期项目、多人协作所以我的建议很直接如果你只是让AI写个一次性处理脚本单Agent够用如果你是在正经项目里做功能迭代而且希望产出能被后来人接手那非常值得把AgentTeam这套模式建起来。1.3 这套方案适合谁、需要什么前置条件适合人群主要有三类。第一种是已经在用AI编程助手、但觉得输出不够稳的人尤其是同一个需求要反复“喂”给AI的情况。第二种是团队里想统一编码规范、但不想靠口头传达的人把规则写成AgentTeam的公共配置每次协作自动生效。第三种是想做自动化试点的人比如把“需求到PRD到实现”这条链路沉淀成团队资产。前置条件真的不高。你需要一个能跑Node的终端环境一个支持工具调用的模型服务以及基础的Markdown读写能力。不要求你会Kubernetes不要求你懂微服务也不需要额外起一套服务端。OpenCode自己就是个命令行客户端所有Agent逻辑都跑在你本地。2. 环境准备与基础配置5分钟跑通OpenCode2.1 安装和初始化一步都不能省我这里以npm全局安装为例因为跨平台最简单。你可以打开终端执行npm install -g opencode-ai opencode --version正常能看到版本号就说明装好了。如果你的包管理器是Homebrew也可以尝试用brew安装具体以你用的版本所对应的官方安装文档为准不用在一个安装方式上死磕。装好之后先初始化opencode init这个命令会在项目根目录生成一个.opencode/配置目录里面通常包含默认的opencode.json、示例AGENTS.md以及一些子目录。首次执行时我建议你直接回车用默认配置先把基础链路跑通再去做定制。一个实操小经验不要在项目根目录里直接初始化就完事应该先确认这个目录确实是你接下来要做的项目目录。因为OpenCode的Agent会基于当前目录感知项目结构如果在错误目录初始化后面Agent读取上下文时容易“找错家”。2.2 模型接入和密钥管理别把Key写进配置文件OpenCode本身不绑定某个固定模型它支持接入多种兼容主流协议的模型服务。你需要把模型服务的接口信息配置好。我习惯的做法是优先使用环境变量而不是把密钥写进配置文件export LLM_PROVIDERyour-provider export LLM_API_KEYsk-xxxx export LLM_MODELyour-model-name如果你用的是本地模型服务还需要额外配置服务的本地地址把provider指到对应的本地服务名上。配置完成后可以随便发一句“你好”测试一下通不通。第一次跑通的时候OpenCode会列出当前可以选用的模型和工具确认模型支持工具调用即可。我把密钥管理单独拿出来强调是因为很多人为了方便喜欢直接把API Key填到opencode.json里。一旦这个文件进了Git仓库等于把钥匙交给了所有能看仓库的人。环境变量虽然也没多复杂但至少不会因为一次误提交就泄露。2.3 认识配置目录一切皆文件一切可Git初始化之后你的配置目录大概长这样项目根目录 └── .opencode/ ├── opencode.json ├── AGENTS.md ├── agent/ │ ├── pm.md │ ├── architect.md │ ├── coder.md │ ├── tester.md │ └── reviewer.md ├── command/ │ ├── plan.md │ ├── implement.md │ ├── verify.md │ └── review.md ├── skill/ └── hook/opencode.json是主配置负责模型、权限、工具开关这类全局项。AGENTS.md是所有Agent共享的项目规则和上下文你可以把它理解成“团队的入职手册”。agent/目录下每个Markdown文件就是一个角色定义了角色的职责、可用工具、模型偏好。command/目录是斜杠命令比如/plan、/implement一个命令就是一个工作流入口。skill/放可复用的技能包hook/放自动化钩子脚本。这个结构看起来简单但好处非常实在。配置文件就是普通文本能够做差异化评审能够随代码一起发布。谁改了什么、为什么改Git历史里都查得到。这也为后面团队化落地埋下伏笔。3. 设计并搭建自己的Agent团队3.1 角色矩阵怎么定先回答三个问题搭建AgentTeam之前先别急着写Prompt。我建议先用表格把角色盘出来每个角色回答三个问题它拥有什么上下文它只能动哪些工具它的产出物落在哪里我这边最常用的角色矩阵是这样角色核心职责模型偏好建议工具产品Agentpm需求拆解、用户故事、验收标准推理强、上下文大read、write架构Agentarchitect技术方案、目录结构、接口设计推理强read、grep、glob开发Agentcoder实现功能、补单测、自测速度优先read、write、edit、bash测试Agenttester按验收标准补测试、跑回归速度优先read、bash审查Agentreviewer代码审查、规范检查、边界扫漏推理强read、diff、bash角色数量我建议控制在3到5个不要一上来就整十个。我最早试着定义了十个角色结果大部分时间都在调角色之间的协作关系真正的编码工作反而进展很慢。砍到五个人核心角色之后链路才顺起来。AgentTeam的价值是分工清晰不是角色越多越好。3.2 用Markdown定义Agent角色先从一个PM写起在agent/pm.md里写这样一段定义--- description: 需求负责人负责把模糊输入转成可执行PRD model: strong-reasoning mode: read-write tools: - read - write --- 你叫PM是团队的需求负责人。 你负责把用户的一句话需求拆成 1. 背景与目标 2. 用户故事 3. 验收标准 4. 影响范围与风险 工作约定 - 先读项目根目录的 AGENTS.md - 产出物写入 .agent-tasks/prd.md - 验收标准必须写清楚前置条件、操作动作和预期结果这里面frontmatter的几个字段值得解释一下。description是给使用者看的方便在交互界面里认出这个角色。model不是具体模型名我建议做成一个“模型别名”比如strong-reasoning和fast-code然后在全局配置里把别名映射到真正的模型服务上。tools是白名单只写这个角色允许使用的工具。mode控制读写权限范围PM不需要执行shell命令那就别给它开bash权限。产出物写到哪里也必须在角色定义里约定清楚。我统一放在.agent-tasks/目录每个角色有自己的产出文件名。这样后面的Agent只需要知道约定路径就能找到前面的产出物不需要在对话里反复传一大段上下文。3.3 用AGENTS.md沉淀团队规则别在角色里重复造轮子AGENTS.md是每个Agent启动时都会自动读取的公共上下文。我把项目级规则都写在这里而不是塞进每个角色的定义里。当时我的项目是一个内部CLI工具AGENTS.md长这样# Mock CLI 项目规则 ## 协作约定 - 新会话先读 .agent-tasks/ 目录下的最新任务文档 - 所有功能变更必须补单测测试命令pytest tests/ - 改动涉及对外参数时必须同步更新 --help 文案 ## 禁止事项 - 禁止直接修改 lock 文件 - 禁止绕过校验器直接写核心逻辑公共规则集中放的最大好处是“只改一处”。比如某天团队决定测试命令从pytest换成别的只需要更新AGENTS.md所有Agent下一次会话自然沿用新规则。如果你把规则分散写在每个角色Markdown里改一次就要改五个文件还容易漏。另外一个经验是AGENTS.md要写“可验证”的规则不要写“写高质量代码”这种空话。宁可写成“所有函数必须带类型注解”“新增对外参数必须更新文档”这种能检查的条目Agent才有执行依据。3.4 用斜杠命令把Agent串成流水线角色定义好了接下来要解决“怎么触发”。我建了几个斜杠命令本质上是流水线入口。command/plan.md是这样--- title: plan description: 让PM Agent把需求拆成PRD agent: pm --- 读取用户输入的需求按PRD模板写入 .agent-tasks/prd.mdcommand/implement.md则会这样写--- title: implement description: 让Coder Agent按PRD实现 agent: coder --- 先读 .agent-tasks/prd.md再实现完成后调用 /verify这样设计背后的逻辑是把复杂的内部协作链路收敛成几个简单的用户入口。使用者在终端只需要敲/plan 给某个模块增加参数校验内部由PM、Coder、Tester这些角色自动接力体验上就像在跟一个团队对话。斜杠命令本身也可以进入Git仓库团队可以共同迭代命令集。4. 一次完整协同从需求到交付4.1 场景设定一个真实的CLI需求为了让你更直观地看到这套流程怎么跑我拿一个具体场景来演示。假设我现在维护一个内部CLI工具模拟项目X工具名暂时叫mock-cli用Python写的。用户反馈说执行mock-cli run --config时如果传了一个不存在的配置文件路径程序只输出一句“Error”完全看不出是路径问题、权限问题还是格式问题。在OpenCode里我直接发起需求/plan 给 mock-cli 的 --config 参数增加路径存在性校验错误信息要友好覆盖空字符串、不存在、目标是目录三种情况4.2 PM Agent产出一份能验收的PRDPM Agent读取AGENTS.md和项目结构后生成了一份PRD核心内容是这样## PRDmock-cli config路径校验 ### 用户故事 作为mock-cli使用者当我传入不存在的配置文件路径时我希望得到明确提示 以便我快速修正命令。 ### 验收标准 - 传入不存在的路径时输出“config file not found: path”退出码非0 - 传入目录路径时输出“expected a file, got directory” - 传入空字符串时输出“--config is required”这一步看起来只是写文档其实非常关键。如果让AI直接写代码它大概率只处理“路径不存在”这一种情况但验收标准一旦写清楚后面的Coder和Tester就有了明确分工。PRD是最容易被偷懒跳过的一步但我建议你一定保留。它相当于给整个AgentTeam装上了“瞄准镜”。4.3 Coder Agent落地实现执行/implementCoder Agent按照PRD新建了一个校验模块核心实现是from pathlib import Path class ConfigPathError(Exception): def __init__(self, message: str, hint: str ): super().__init__(message) self.hint hint def validate_config_path(path: str) - Path: if not path or not path.strip(): raise ConfigPathError(--config is required) p Path(path).expanduser() if not p.exists(): raise ConfigPathError(fconfig file not found: {path}, hintuse --init to create one) if p.is_dir(): raise ConfigPathError(fexpected a file, got directory: {path}) return pCoder完成实现后自己也会追加一份测试文件把PRD里的验收标准转成pytest用例并跑一遍测试。这个“自测”环节很重要它让Coder进入下一步审查之前先把明显问题筛掉。实测下来加了自测这一步之后Reviewer阶段发现的问题数量明显变少。4.4 Tester和Reviewer交叉验证最后把好关实现和自测都过了我执行/verify和/review让Tester和Reviewer分别进场。Tester会重新读一遍.agent-tasks/prd.md对照验收标准补测试、跑回归。Reviewer则会检查错误处理、命名、边界条件当时它给出的审查意见包括抛出异常时没有显式设置退出码shell里可能拿到0需要修正提示信息里“not found”和“expected a file”的文案风格不统一expanduser之后缺少对应的路径解析测试这些意见虽然不是致命问题但都很实际。Coder再修一轮测试重新通过我人工确认一遍改动范围没越界才合并代码。整个链路跑完我想特别提醒一点AgentTeam是辅助最终合并权还是应该握在人手里尤其是对外行为有变化的场景。5. 常见问题与排查技巧实录5.1 Agent之间“失联”上下文漂移的根源AgentTeam里每个Agent都有自己的独立上下文它不会自动继承上一个Agent的对话历史。所谓“团队记忆”本质上靠的是磁盘文件。如果你发现Coder Agent说“没看到PRD”或者“需求文件为空”先不要怀疑模型智商大概率是文件路径没有落到约定目录或者产出文件太大被截断了。我的经验是在AGENTS.md里加一条硬性约定“新会话先读.agent-tasks/目录下的最新任务文档”。这条用文字写出来比在命令行里反复粘贴需求可靠得多。另外PRD文件不要写得太长尽量控制在200行以内必要信息可以用分文件组织避免上下文窗口被大段文档占满。5.2 工具调用和权限配置不匹配你会遇到Agent想执行命令、写文件但被权限系统拦下来的情况。OpenCode对工具调用有权限模型默认行为偏向保守。我习惯先在opencode.json里配置一个最小授权集合{ permissions: { allow: [read, write, bash, edit], deny: [rm -rf, git push --force] } }这里的原则是“能不开就不开”。写代码的Agent需要bash权限那单独给Coder开PM Agent只负责写文档只需要read和write。权限开得太大一旦某个Agent误触危险命令代价会被放大。每次Agent报权限不足不要第一时间全放行先看这个工具是不是它职责内必需的。5.3 多Agent同时改同一个文件冲突怎么破我最初踩过最深的坑是并行冲突。两个Agent同时收到指令一个在改配置一个在补测试结果两个会话同时写入同一个文件后写的人把先写的内容覆盖了。这问题在文件系统层面不会像Git合并那样给你提示它是直接覆盖。我的解法是设计上默认串行一条命令只激活一个主Agent主Agent内部连续调用工具没问题但不要同时启动两个都会写同一目录的命令。如果确实需要并行只允许只读类Agent并行写操作严格排队。更细一步我给每个角色定义了“文件所有权”谁产出谁负责别人要改也必须先通过职责内的命令入口而不是直接编辑。5.4 模型能力不均导致的输出波动不同角色如果共用同一个模型性能和成本的矛盾会很明显。我当时试过给所有角色都用同一个强推理模型结果Coder阶段每一步都很慢体验非常难受。后来我把模型拆成“强推理”和“快速编码”两类PM、Reviewer用强推理模型Coder、Tester用更快的模型整体效率立刻上来了。这里我把最容易遇到的问题整理成速查表几张表放在一起方便你以后排查问题现象可能原因处理建议Agent输出与PRD无关没有先读任务文件检查AGENTS.md协作约定工具调用反复报错模型不支持工具调用换支持工具调用的模型上下文被截断PRD或项目文件太长拆小文件按需引用两个Agent互相覆盖文件并行写同一目标文件改串行定义文件所有权审查意见不痛不痒Reviewer上下文视野太窄让它读diff和变更文件而不是只看单文件6. 进阶扩展把AgentTeam沉淀成团队资产6.1 用Hooks加一道自动化护栏当AgentTeam开始被多人使用时难免有人临时改配置或者Agent执行了超出预期的命令。我建议在.opencode/hook/里加一些生命周期脚本监听工具执行事件在操作落地前做一次检查。比如禁止强制推送到共享分支、禁止删除关键目录这类规则用钩子脚本写下来最可靠。钩子机制有个好处它不依赖模型“守规矩”而是在执行链路上做硬约束。团队规则从“靠AI自觉”升级成“靠系统拦截”安全感完全不一样。注意钩子脚本要放在配置目录里跟其他配置一起走版本管理否则每台机器都要手动同步一份。6.2 用MCP扩展工具集但要克制OpenCode支持通过MCP方式接入外部工具集比如内部文档库、测试平台、监控系统、数据库查询工具。接入之后Agent可以调用这些工具完成更复杂的闭环操作。但是这里我要劝你克制每接入一个MCP工具都会占用Agent的上下文空间接入太多反而降低主任务质量。我个人的经验是每个角色的工具集控制在5个以内MCP工具只在特定角色里开启。比如Tester Agent可以接测试平台工具Coder Agent没必要看到所有测试数据。工具的接入也要写进角色定义的白名单里不能让所有Agent都能调用所有工具。6.3 把整份配置纳入版本管理新成员秒上手最后一个进阶建议是把.opencode/整个目录纳入Git仓库。角色文件、命令文件、AGENTS.md、hooks、权限配置全部都可以走代码评审和版本回滚。新成员加入时只需要clone仓库、安装OpenCode、配置环境变量里的密钥就能获得和团队完全一致的AgentTeam。这里有个重要禁忌任何密钥类信息都不要提交到仓库。环境变量、密钥管理工具、本地未跟踪文件才是密钥该待的地方。配置文件里只保留模型别名和工具白名单真正敏感的信息通过外部环境注入。我实际测试下来一个新成员从clone到第一次跑通完整命令链路半小时以内是完全可以做到的。我实际搭完这套AgentTeam之后最深的体会是花时间的不是写角色Prompt而是想清楚每个角色的输入、输出和边界。开始我设计了十个角色结果大部分精力都在调协作砍到五个核心角色之后链路才真正顺畅。最后再分享一个小技巧把AGENTS.md里的公共规则当成测试用例标准来写AgentTeam的产出稳定性基本跟着这套规则的清晰度走。规则越明确角色越专注团队就越像一个真正的团队。
