1. 为什么要在 Claude Code 和 Codex 之上再叠一层决策层先说结论单纯把 Claude Code 或 Codex 接进工作流能解决写代码的问题但解决不了该不该写、先写哪块、写到什么程度停手的问题。Jev 这个项目要做的就是在 Coding Agent 和实际任务之间插一层轻量决策逻辑让 Agent 在动手之前先想清楚路径而不是拿到一句话就开始疯狂输出。我最初接触这个思路是因为一个很现实的场景让 Agent 改一个跨模块的 bug它会在三个文件里来回横跳改完 A 发现 B 依赖 A 的旧签名改完 B 又发现 C 的测试挂了最后绕了一大圈回到原点。整个过程 token 烧得飞快产出却是一堆半成品。问题不在于模型能力不够而在于它缺少一个先规划、再执行、执行中校验的中间层。Claude Code 和 Codex 本身都带一定的 planning 能力但那是模型内部的隐式规划你没法干预、没法复用、没法针对自己的项目定制规则。Jev 的价值就在于把这层规划显式化、可配置化。这篇文章适合三类人看一是已经在用 Claude Code 或 Codex 做日常开发、但觉得能用但不够稳的工程师二是想给自己的 Agent 工作流加定制决策逻辑的团队三是对 Coding Agent 架构感兴趣、想理解决策层到底解决什么问题的人。下面我会从架构设计、接入方式、决策规则怎么写、实测中的坑这几个角度把整套东西拆开讲。需要提前说明的是Jev 不是一个现成的开源库它更像是一种架构模式——你可以用几十行胶水代码把它实现出来也可以用现成的编排框架搭。我下面给的方案是基于常见实践的合理设计具体实现细节你可以按自己的技术栈调整。2. Jev 决策层的核心架构与它到底管什么2.1 决策层不是再套一个模型很多人第一反应是决策层是不是再调一个 LLM 来做规划我的建议是尽量不要。原因很直接——多一次模型调用就多一次延迟、多一份不确定性而且规划模型和执行模型如果对项目上下文的理解不一致规划出来的东西执行模型根本落不了地。Jev 的决策层本质是一个规则引擎 轻量状态机。它不生成代码只做三件事判断任务类型、选择执行策略、在关键节点做校验和回退。真正写代码的活还是交给 Claude Code 或 Codex。这样设计的好处是决策逻辑完全可控、可测试、可版本管理不会因为模型抽风就整个流程崩掉。我把它拆成四个模块任务分类器拿到用户输入后先判断这是新增功能修 bug重构写测试还是纯问答。不同类别走不同策略。策略选择器根据任务类别和当前仓库状态决定用哪个 Agent、给多少上下文、要不要先出计划。执行编排器负责调用 Claude Code 或 Codex管理多轮交互处理中间产物。校验回退器在 Agent 声称完成后跑一遍预设的检查编译、测试、lint不通过就带着错误信息回退重试。2.2 为什么是快速决策而不是深度决策标题里快速决策这四个字很关键。我见过一些方案决策层做得极其复杂要分析依赖图、要跑静态分析、要生成完整设计文档结果决策本身花的时间比写代码还长。这在小任务上完全是负收益。Jev 的设计哲学是决策层的耗时必须控制在秒级且不能超过执行时间的 20%。所以它只做粗粒度判断不做细粒度分析。比如判断这个任务涉及几个文件不需要精确解析 AST扫一眼关键词和文件路径就够了。判断要不要先出计划看任务描述长度和涉及模块数就行。这种够用就好的决策反而比精确分析更实用因为它把时间留给了真正干活的 Agent。提示决策层的规则一定要能快速失败。如果规则匹配不上任何已知模式直接走默认策略交给 Agent 自由发挥不要卡在那里试图分析。我踩过的坑就是规则写太细遇到没覆盖的情况直接抛异常整个流程中断体验极差。2.3 和 Claude Code、Codex 原生能力的边界这里要说清楚一个容易混淆的点Claude Code 和 Codex 自己都有任务分解能力Jev 不是要取代它而是要在它之前和之后加东西。之前加的是入口决策决定这个任务要不要拆、拆成几步、每步给什么上下文。之后加的是出口校验Agent 说完成了到底算不算完成。中间那段怎么把任务做完还是交给 Agent 自己。打个比方Claude Code 和 Codex 像是两个手艺很好的工匠Jev 是站在门口的工头。工头不干活但工头决定这活派给谁、要带什么工具、干完了验收合不合格。没有工头工匠也能干但容易干错方向或者干过头。3. 把 Claude Code 和 Codex 接进决策层的具体做法3.1 两种 Agent 的调用方式差异Claude Code 和 Codex 在调用形态上不太一样这直接影响你怎么在决策层里封装它们。Claude Code 更偏向交互式 CLI你可以通过子进程调用把任务描述作为输入它会在当前工作目录里操作文件。它的强项是长上下文理解和多文件协同修改。Codex 则更偏向 API 式的补全和生成适合单点、明确的代码生成任务响应更快但上下文窗口相对小。我的封装策略是决策层统一抽象出一个AgentAdapter接口两个 Agent 各实现一份。接口方法就三个plan(task)返回执行计划、execute(plan)执行并返回结果、verify(result)做基础校验。这样决策层不用关心底层是哪个 Agent切换成本极低。class AgentAdapter: def plan(self, task, context): raise NotImplementedError def execute(self, plan): raise NotImplementedError def verify(self, result): raise NotImplementedError class ClaudeCodeAdapter(AgentAdapter): def execute(self, plan): # 通过子进程调用传入 plan 序列化后的指令 proc subprocess.run( [claude, --task, plan.to_prompt()], cwdself.workdir, capture_outputTrue, textTrue ) return proc.stdout3.2 上下文注入的粒度控制这是接入环节最容易做砸的地方。很多人图省事把整个仓库的文件列表甚至文件内容一股脑塞给 Agent结果 token 爆炸、Agent 注意力涣散。Jev 的做法是按任务类型决定上下文粒度任务类型注入内容大致 token 预算修 bug报错栈 相关文件路径 最近一次改动 diff2k-4k新增功能目标模块目录结构 接口定义文件4k-8k重构待重构文件全文 调用方列表8k-15k写测试被测函数签名 已有测试样例2k-3k这个表不是拍脑袋定的是我在实际项目里反复调出来的。核心原则是给 Agent 的信息刚好够它做决定多一分都是浪费。修 bug 时最有用的是报错栈和最近改动因为 bug 大概率就在最近改的那几行里。重构时才需要全文因为要理解整体结构。3.3 计划产物的结构化格式决策层让 Agent 先出计划这个计划不能是自由文本否则后续没法程序化处理。我定义了一个简单的 JSON schema{ steps: [ {id: 1, action: modify, target: src/auth.py, desc: 修复 token 校验逻辑}, {id: 2, action: test, target: tests/test_auth.py, desc: 补充边界用例} ], risk: medium, need_confirm: false }有了这个结构决策层就能做很多事比如发现risk是 high 就暂停等人工确认发现步骤超过 5 步就拆成两批执行发现某步 target 文件不存在就提前报错。这些都是自由文本计划做不到的。注意让 Agent 输出严格 JSON 是有技巧的。我在 prompt 里会明确说只输出 JSON不要任何解释文字并且在解析时做容错——如果解析失败用正则从文本里抠出 JSON 块再失败就降级为自由文本计划。硬解析失败直接报错是最蠢的做法。4. 决策规则怎么写才不沦为摆设4.1 规则的分层设计决策规则如果全写成一堆 if-else很快就会变成没人敢改的屎山。我采用三层结构第一层硬规则。基于确定事实的判断比如文件不存在就不能改测试没通过就不能提交。这层用代码写不依赖模型。第二层启发式规则。基于经验的概率判断比如任务描述里出现重构且涉及文件超过 3 个大概率需要先出计划。这层用配置写方便调整。第三层模型判断。实在拿不准的才调一次轻量模型做分类。这层是兜底用得越少越好。三层从下往上调用硬规则能定的绝不上升到启发式启发式能定的绝不调模型。这样既保证了速度又保证了覆盖率。4.2 一个真实的规则配置示例rules: - name: large_refactor_needs_plan when: keywords: [重构, refactor, 重新设计] file_count_gt: 3 then: action: require_plan agent: claude_code context_level: full - name: simple_bugfix_direct when: keywords: [修复, fix, 报错] file_count_lte: 2 then: action: direct_execute agent: codex context_level: minimal这套配置的好处是产品经理或者团队里不写代码的人也能看懂、能提修改意见。规则调整不需要改代码改 YAML 重启即可。4.3 规则冲突了怎么办多个规则同时命中是常态。我的处理顺序是优先级数值高的先匹配同优先级按配置顺序第一个命中的生效。听起来简单但实际用起来会发现第一个命中经常不是最优解。后来我加了一个规则投票机制让所有命中的规则各投一票票数最高的策略生效平票时走保守策略也就是需要更多确认的那个。这个改动让决策质量明显提升因为单条规则容易误判多条规则的综合判断更稳。5. 实测中暴露的问题和我的处理方式5.1 Agent 会假装完成了任务这是最坑的问题。Agent 返回已完成修改你去一看文件根本没动或者只改了一半。原因是它把我打算这么做和我已经这么做混为一谈了。我的解法是在校验回退器里加一道文件指纹检查执行前记录目标文件的 mtime 和 hash执行后对比。如果文件没变但 Agent 声称改了直接判定失败并重试。这个检查成本极低但拦住了大量假完成。5.2 多轮重试会陷入死循环Agent 改不对回退重试还是改不对再回退……我见过重试 8 次还在原地打转的情况。根因是每次重试给的上下文完全一样Agent 自然给出一样的错误答案。处理方式是重试时注入差异信息第一次重试告诉它上次这么改导致测试 X 失败第二次重试告诉它换个思路不要动 Y 文件。同时设一个硬上限重试 3 次还不行就停下来把问题抛给人。承认 Agent 有搞不定的情况比让它无限重试要诚实得多。5.3 决策层本身成了瓶颈有段时间我发现整体耗时变长了排查下来是决策层的规则匹配用了正则回溯遇到长任务描述时卡住。这个坑很隐蔽因为决策层代码量小谁也没想到它会慢。教训是决策层里任何可能随输入规模增长的操作都要设上限。正则加超时、文件扫描限制数量、模型调用设 deadline。决策层慢 1 秒整个流程的体验就垮了。5.4 两个 Agent 的输出格式不统一Claude Code 和 Codex 返回的结果结构不一样导致校验层要写两套解析逻辑。后来我在 Adapter 层做了归一化统一转成{status, files_changed, summary, raw}这个结构上层就干净了。这个改动不大但省了很多重复代码。6. 什么场景该用 Jev什么场景别用6.1 适合的场景多文件协同修改涉及 3 个以上文件的改动决策层的规划价值最明显。有明确验收标准的任务比如测试全绿编译通过校验回退器能自动判断成败。团队协作环境规则配置可以版本化团队共享一套决策逻辑新人也能受益。重复性任务比如每周的依赖升级、格式统一规则一次写好长期复用。6.2 不适合的场景探索性任务比如帮我看看这个模块怎么设计比较好这种没有明确终点的任务决策层反而添乱。单文件小改动改个变量名、修个 typo直接让 Agent 干就行套决策层是杀鸡用牛刀。强交互场景需要人机来回讨论的需求决策层的自动化逻辑会打断节奏。我的经验是任务越结构化、验收标准越明确决策层的收益越大。反过来越开放、越依赖人判断的任务越应该让 Agent 自由发挥。6.3 一个判断标准如果你发现自己在反复给 Agent 解释同样的规则、反复纠正同样的错误那就是该上决策层了。决策层的本质是把你脑子里的隐性规则显性化、自动化。如果这些规则本来就不存在或者每次都不一样那决策层也帮不了你。7. 落地时几个容易被忽略的细节7.1 日志要记全但别记敏感内容决策层的日志是排查问题的命根子。我记录每次决策的输入、命中的规则、选择的策略、执行结果、耗时。但要注意任务描述里可能包含业务敏感信息日志落盘前要做脱敏。这个在个人项目里容易忽略一旦上团队环境就是隐患。7.2 给决策层留一个手动挡再智能的决策也有翻车的时候。我在决策层上加了一个开关允许用户强制指定策略绕过所有规则。这个开关平时不用但关键时刻能救命。设计自动化系统时永远要留一条人工干预的通道。7.3 规则要定期清理规则只增不减是通病。我每个月会看一遍规则命中统计把连续一个月零命中的规则删掉。规则库越干净决策越可预测。留着没用的规则只会增加维护负担和误判概率。7.4 别追求一步到位我第一版 Jev 只有一条规则任务超过 3 个文件就先出计划。就这一条已经解决了我 60% 的痛点。后面是慢慢加规则、慢慢调优的。想着一开始就设计一套完美决策系统大概率会烂尾。先跑起来再迭代。这套东西我用了大半年最大的体会是Coding Agent 的能力上限由模型决定但它的稳定性下限由决策层决定。模型再强没有好的决策和校验产出依然不可靠。反过来哪怕模型一般只要决策层把任务拆得合理、校验做得扎实整体产出也能达到可用水平。Jev 这层东西不复杂但它把用 Agent从碰运气变成了一件可预期的事这才是它真正的价值所在。