上周处理了一桩挺典型的线上问题推荐接口在凌晨流量高峰出现缓存穿透客户端超时率直线拉高。当时我在外面手边只有手机代码全在工作站的台式机里。搁以前只能干等回公司但那次我硬是用手机上的 Kiro 接进云端工作区让 Claude Code 先对现状做架构评审产出一份只动三个文件的规约再让 Codex 按规约在二十分钟内把修复写完连测试都补齐了。整个过程没有打开一次笔记本。这套玩法我前后跑了半年多从一开始的“两个 AI 各干各的”慢慢沉淀成一套相对固定的协作模式。核心就一句话Claude 负责想清楚Codex 负责写出来Kiro 负责让我在手机端掌握全部控制权。这篇文章不是介绍某个工具的说明书而是把整套“规约协同范式”从原理到落地、从配置到踩坑完整拆开讲一遍。适合远程办公的开发者、独立开发者以及所有想认真让 AI 代理干活而不是看热闹的人。1. 评审交给 Claude、编码交给 Codex这套分工背后的真实理由1.1 一个代理干所有事问题出在哪很多人刚接触 Claude Code 和 Codex 时的第一反应是既然这俩都是能读代码、写代码的 AI 代理那我挑一个顺手的用到死不就完了为什么要拆开我一开始也是这么干的。后来发现当任务比较复杂、涉及多个文件联动的时候单代理模式有两个很现实的问题。第一个是上下文预算。你让同一个代理既做架构分析又写全部实现它在分析阶段就要把整个项目的关键文件读一遍。等分析完上下文窗口已经被塞得差不多了真正写代码的时候反而开始“忘事”。最典型的表现就是前十分钟的方案说得头头是道后半小时实现的代码跟方案对不上。这不是模型笨是上下文分配不合理。第二个问题更致命缺乏可审计的中间产物。一个代理从分析到改代码一气呵成最后给你一个巨大的 diff。你 review 的时候根本不知道它当时为什么这么改。如果改错了你连回滚的依据都不好找。整个链路是一个黑盒你只有“开始”和“结果”两个控制点。1.2 Claude 的“慢思考”与 Codex 的“快实现”是互补关系把任务拆开之后两个模型的性格差异反而变成了优势。Claude Code 的长上下文能力和结构化输出让它天然适合做架构评审这类“想清楚再动手”的活。它能把一个模块的依赖关系、潜在风险、改动影响面梳理得比较完整。我用它评审过不少老项目的重构方案它给的 ADR架构决策记录和影响面分析直接拿给团队同事看都没有问题。Codex 的特性是执行链路短、迭代快写起代码来像子弹一样。让它做那种“需求已经很明确、照着清单填代码”的活效率非常夸张。尤其在规约文件已经把接口签名和改哪些文件都定死之后Codex 不需要再纠结设计问题只闷头实现就行速度自然快。这两个特性拆开用彼此都不浪费。Claude 不用一边分析一边赶工Codex 不用一边写代码一边猜方案。1.3 分工之后中间产物变成了资产这是我最想强调的一点把架构评审和编码拆给两个 AI最大的收益其实是中间那份规约文档。以前单代理干完活项目里除了代码 diff 什么都没留下。现在 Claude 评审完会产出一份规约文件这份文件会被 Codex 消费也会被提交到 git 仓库里。三个月后有人问“当时为什么要在 recommend 服务里加 Redis”你直接把这份规约甩给他里面写着决策理由、影响面、任务清单。这比翻聊天记录靠谱一万倍。规约同时是人的审查点。Codex 动手之前你可以在 Kiro 里打开这份规约看到底哪里改、哪里不许动。不满意就改规约改到满意再放行。所谓“掌控”掌控的就是这个节点。2. 把 Kiro 放进来手机端掌控的本质是“控制权”而不是“远程桌面”2.1 Kiro 在工作流里的位置云端工作区 会话编排一开始我接触 Kiro 时以为它就是个手机上的终端模拟器SSH 到服务器上敲命令。用了一段时间才意识到它的定位不太一样Kiro 更像个“AI 代理控制台”它负责的是云端工作区里的会话管理和操作审批而不是单纯给你一块屏幕敲键盘。一个直观的例子是我在手机 Kiro 里能看到 Claude Code 和 Codex 两个会话同时跑。Kiro 把任务列表和运行日志按会话分开我不用盯着终端输出刷屏只需要看哪个会话需要我确认操作以及关键节点的运行结果。它把“遥望式管理”变成了一种可能你不需要每时每刻都在看但你随时可以介入。Kiro 有 Windows 桌面端也有移动端。我个人的用法是桌面端做初始化配置把项目 clone 到云端工作区、装好依赖、配置好 Claude Code 和 Codex 的认证日常在外需要处理任务时就掏出手机连上同一个工作区直接干活。热词里经常有人搜“kiro windows 安装”说明很多人其实是先在电脑上接触它再开始用手机端。安装本身不复杂关键是把工作区网络、SSH 密钥、Git 身份这些一次性配置干净后面手机会省很多事。2.2 每次操作都要点 allow是麻烦还是安全底线如果你搜过“kiro 为什么每次都要点击 allow”说明你已经在真实使用中撞上了 Kiro 的权限设计。这个机制其实是故意的。AI 代理执行的每一条命令都有真实副作用改文件、删目录、装依赖、跑测试、push 代码。一旦放权它就可能在你看不见的地方把项目搞乱。手机端尤其危险因为屏幕小、误触概率高如果完全自动执行一条rm -rf下去可能整个工作区都没了。Kiro 的做法是把命令分成不同危险级别。比如git diff、ls这种只读命令通常不需要确认而npm install、git push、删除文件这类操作会弹确认窗。我遇到过不少人在网上抱怨“怎么每次都要点”其实解决方案不是关闭确认而是学会利用它的“记住选择”功能对同一个项目的同一条命令你可以在弹窗里选择“本次会话总是允许”这样 Claude 在一个会话内连续跑测试就不会反复打断你。安全底线这东西平时觉得烦真出事的时候才知道值钱。我建议确认级别设置成“只信任白名单命令”把npm test、git diff、npx eslint这类安全命令放行把rm、git push --force这类高危操作保持强制确认。这样既不烦人又守住了底线。2.3 用 Crew 模式把两个代理串成一个流水线Kiro 里有个我越用越依赖的能力Crew 模式。简单说它允许你预定义多个代理角色并且把它们编排成一条流水线。在我的用法里Crew 是这么配置的第一个角色是“架构评审员”绑定 Claude Code负责分析项目并输出规约文件第二个角色是“实现工程师”绑定 Codex负责读取规约并写代码。我在手机 Kiro 里启动一次 Crew 任务系统会先把任务投给 Claude等 Claude 完成评审并确认规约落盘后再自动把“执行规约”的指令发给 Codex。这个编排的价值在于它把我在 1.3 节说的“中间产物”变成了流水线的标准交接物。两个 AI 之间不需要在同一个上下文窗口里对话它们通过文件系统通信Claude 写文件Codex 读文件。Kiro 只是那个保证顺序和控制权的调度者。3. 规约文件两个 AI 之间那层“人话协议”3.1 规约不是需求文档是可执行契约很多团队也写需求文档但需求文档是给人看的里面有大量背景叙述、业务故事AI 读起来效率很低。我所说的规约是一份介于需求文档和代码之间的“可执行契约”。它必须满足三个条件第一足够具体每个改动点都能对应到具体文件和函数第二足够小一个规约只解决一个问题第三足够严格明确写出哪些事不许做。规约一旦落地Codex 其实不需要再做任何设计决策。这套范式的关键转折点就在这里Claude 的所有深度思考最终要转化为一份 Codex 不需要“思考”也能执行的文档。我经常跟朋友开玩笑说如果 Codex 读到规约还要停下来问你“这里的缓存 key 怎么设计”说明 Claude 的评审还没做透退回重写。3.2 一份规约文件长什么样以我处理过的 recommend 服务加 Redis 缓存为例Claude 最终产出的规约文件结构大概是这样# 规约recommend 服务引入 Redis 缓存改造 ## ADR-2024-008 - 状态已接受 - 决策采用 Redis 作为一级缓存TTL 60skey 规则 rec:{userId}:v1 - 理由当前 DB 查询耗时集中在热点用户写缓存穿透率为 37% ## 影响面 - src/services/recommend.js重写核心查询逻辑 - src/config/cache.js新增导出 Redis 客户端 - tests/integration/recommend.test.js新增缓存命中/穿透用例 ## 接口契约 - getRecommendations(userId, limit) 保持现有签名不变 - 返回值结构不变{ items, source: cache|db, ts } ## 任务清单 - [T1] 在 src/config/cache.js 中初始化 Redis 连接导出 get/set 封装 - [T2] 改造 recommend.js 查询链先查缓存miss 后查库并回填 - [T3] 补充集成测试覆盖命中、穿透、TTL 过期三条路径 ## 约束 - 不允许改动认证模块、API 路由文件 - 新增依赖必须同步更新 package.json 与 README - 不做与缓存无关的重构这份文件会提交到docs/specs/2024-cache-refactor.md。Codex 的执行指令非常简短读这个文件按任务清单逐个完成别越界。你可能已经注意到我把“接口签名不变”和“返回值结构不变”这种约束写得非常死。这是从多次踩坑里学来的。AI 代理的天性就是自由发挥你如果不把边界钉死它顺手就把你接口名改了然后一脸无辜地写进 changelog。3.3 CLAUDE.md、AGENTS.md、规约文档怎么各司其职有些项目里有 CLAUDE.md有些有 AGENTS.md很多人搞不清它们和规约文件的差别。我用的分层是CLAUDE.md 放在项目根目录给 Claude Code 看描述的是项目的长期事实技术栈、目录结构、编码规范、命令约定。它是静态的、很少变的。AGENTS.md 同样放根目录给 Codex 以及所有代理看内容侧重于“在这个仓库里干活时要注意什么”哪些目录不能动、测试怎么跑、依赖怎么装。它也是静态的。而规约文件是动态的、一次性的每个任务一份放在 docs/specs 下由 Claude 在评审时生成任务完成后归档。它是从“项目长期规范”到“本次任务约束”的桥梁。这三层各管各的不重叠。CLAUDE.md 解决“我是谁”AGENTS.md 解决“在这里怎么干活”规约解决“这次任务具体做什么”。如果你把所有东西都塞进一个文件代理会因为信息过载而选择性忽略反而起不到约束作用。4. 从零跑通手机 Kiro 联动 Claude 与 Codex 的完整配置记录4.1 环境准备Claude Code、Codex CLI、Kiro 三件套先把三个工具的安装说清楚都是我实际验证过的路径。Claude Code 官方推荐的是 npm 全局安装npm install -g anthropic-ai/claude-code安装完执行claude --version确认版本号正常。认证方式我用的是环境变量ANTHROPIC_API_KEY在 Kiro 的云端工作区里配置好后Claude Code 启动时自动读取。如果你是用 Claude 订阅登录的也可以在工作区里执行claude走交互式登录不过对远程工作区来说环境变量更省事。Codex CLI 同样是 npm 包npm install -g openai/codex或者从官方 release 直接下载对应平台的二进制。Windows 上我更推荐 npm 方式省去手动配 PATH 的麻烦。认证可以codex login用 ChatGPT 账户也可以用OPENAI_API_KEY。我建议用后者因为模型配置的灵活性更高后面 4.2 会细说。Kiro 的安装分两头Windows 桌面端从官网下载安装包手机端去应用商店搜。两端登录同一个账号后就能共享云端工作区列表和会话记录。4.2 认证与多模型接入官方 Key 与 OpenAI 兼容端点我的配置原则是Claude Code 走 Anthropic 官方 APICodex 走 OpenAI 官方 API同时预留一套 OpenAI 兼容端点用于切换模型。Codex CLI 支持在配置文件中自定义模型提供方格式大致如下放到~/.codex/config.tomlmodel gpt-5 model_provider openai [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY这样做的价值在于你可以通过修改model和model_provider两个字段在 OpenAI 官方模型和 DeepSeek 这类 OpenAI 兼容服务之间切换。比如做常规功能开发时用官方模型做批量琐碎编码时切换到成本更低的兼容端点。Codex 的输入端不变变的只是底层模型。需要提醒的是用 API Key 模式和用 ChatGPT 账户登录在 Codex 中对模型的支持范围是不一样的。账户登录时只能使用账户方案开放的模型子集手动指定一个不在白名单里的自定义模型名会直接报错。所以如果你需要灵活切换模型优先用 API Key 模式。4.3 在 Kiro 里绑定项目并定义运行目录Kiro 里每个项目都可以绑定一个云端工作区目录。我建议工作区结构尽量精简只放当前活跃项目不要把你所有仓库都塞进去。因为 Claude Code 和 Codex 在扫描文件时工作区里的无关目录会白白消耗上下文。我的标准结构是~/workspace/ recommend-service/ # 当前项目 specs/ # 规约文件归档项目 clone 完成后第一件事是把 AGENTS.md 和 CLAUDE.md 放进项目根目录再跑一次依赖安装确保工作区里的项目是可直接运行的。这一步如果不做后面 AI 代理跑测试时会因为缺依赖而反复失败浪费大量 token。4.4 一次完整的“评审→规约→编码→验证”实录拿真实的一次任务举例需求是给 recommend 服务加 Redis 缓存缓解 DB 压力。我在手机 Kiro 里向“架构评审员”角色发送了一条指令请对 src/services/recommend.js 做架构评审评估引入 Redis 缓存的影响面。需要覆盖查询链路上的热点方法、DB 连接池压力、返回结构兼容性。评审完成后按项目规约模板生成 docs/specs/2024-cache-refactor.md输出一份可被编码代理直接执行的规约。Claude Code 在云端工作区开始读代码、画依赖关系、评估影响。整个过程大概三分钟期间 Kiro 会推送“正在分析”的状态。评审完成后我在手机端打开了那份规约检查了接口契约和影响面确认没问题后点了“放行”。接着Kiro 的 Crew 流水线自动把规约路径发给了“实现工程师”角色也就是 Codex。Codex 的指令是阅读 docs/specs/2024-cache-refactor.md按任务清单实施。只改规约列出的文件不要做任何额外重构。完成 T1-T3 后运行 npm test确保全部通过。Codex 开始读规约、改代码、装 redis 依赖、写测试。期间 Kiro 弹了几次命令确认窗都是npm install redis和npm test这类操作我在手机上一路点了允许。大概十分钟后Kiro 推送了结果测试通过diff 涉及三个文件完全符合规约范围。这条流水线跑完我全程没有打开电脑。那个周末的线上问题就是在这条流程里被收掉的。5. 半年使用中的故障与排查笔记5.1 Kiro 的 allow 弹窗为什么它不肯记住我的选择这是社区里吐槽最多的点我在 2.2 节说过它是安全设计。但还有一层情况是Kiro 的 allow 策略是按“会话 命令模式”记忆的不是按“全局”记忆。也就是说你在会话 A 里允许了npm test切到会话 B 后它又会再问一次。这不是 bug是故意为之。因为会话 B 可能操作的是另一个项目或者同一个项目的另一个分支你上个会话的信任不能自动迁移。我现在的做法是在 Kiro 设置里把“命令确认策略”调整为“白名单模式”把只读操作和测试命令加入白名单。真正需要每次确认的只剩下少数高风险命令。这么调完之后烦人程度下降了一个量级同时安全底线还在。5.2 cc-switch 报 local proxy failed一条典型的端点转发排障链路cc-switch 是个管理 AI 代理供应商配置的社区工具它可以在 Claude Code、Codex 等多个 CLI 之间快速切换不同的 API 提供商。很多人喜欢在它里面配置本地转发地址统一管理多个模型的端点。但配置不当就会看到类似这样的报错cc switch local proxy failed while handling codex endpoint /responses. provider...第一次遇到时我以为是 cc-switch 本身坏了后来排查完发现是典型的本地端点连通性问题。这套排查链路我完整走了一遍直接分享给你第一步看报错发生在哪个环节。是启动时还是真正发请求时。如果是发请求时基本可以确认是端点转发失败不是认证问题。第二步检查那份 provider 配置里的 base_url。如果它指向类似http://127.0.0.1:9xxx/v1这种本地地址那它依赖的是一个本地转发服务不是官方端点。第三步确认转发服务到底有没有起来。Windows 上我用netstat -ano | findstr :9xxxmacOS 用lsof -i :9xxx一眼就能看到端口是否被监听。如果端口没监听说明转发服务没启动或已被杀掉。第四步验证转发服务本身是否健康。直接 curl 一下curl http://127.0.0.1:9xxx/v1/models如果能返回模型列表说明转发服务正常问题出在 cc-switch 转发链路上如果超时或拒绝连接问题就在转发服务自身。第五步检查 cc-switch 的“本地代理模式”是否被意外关闭。有些版本在切换供应商时会重置这个开关重新打开再切一次就好了。这条链路的本质是任何“本地端点”依赖都是脆弱的进程一挂、端口一占AI 工具就会立刻报错。排查时不要盯着 Codex 的报错看半天先确认底层转发服务活着没有。5.3 Claude Code 工作区 SDK 版本校验失败报错形态通常长这样failed to start claudes workspace rpc error -1: sdk version 2.1.260 not verified这个报错我遇到过两次都在claude升级之后。原因是 Claude Code 的 workspace 服务与它依赖的 SDK 版本没有对齐。升级过程中如果中断或者本地残留了旧版本的缓存就会出现“program 想用新 SDK但工作区服务还在旧版本”的撕裂状态。处理方式其实不复杂。先彻底退出所有正在运行的 claude 进程Windows 上用任务管理器macOS 上用pkill -f claude。然后重新执行全局安装npm install -g anthropic-ai/claude-codelatest如果重装完还报同样的错清一下~/.claude下与版本缓存相关的目录再启动。需要提醒的是清缓存前先看一眼里面有没有你本地的自定义配置别一股脑全删。这类问题看起来像黑魔法其实跟“浏览器版本更新后插件全挂”是一个道理。CLI 工具内部也是组件化的版本不同步就会报 RPC 错误。解决办法永远是全退、重装、清缓存三件套。5.4 Codex 上下文溢出与模型不支持报错Codex 跑长任务时会遇到一个提示error running remote compact task: codex ran out of room in the models context window意思是它想压缩旧上下文释放空间但压缩动作本身已经把剩余窗口占满导致压缩无法完成。这通常发生在单个会话里塞了太多任务或者项目里有大量文件被无关加载。我的解法就是把任务拆小用 3.2 节那种规约文件的 T1/T2/T3 粒度来控制会话规模。一个会话只做一件事做完立刻归档开新会话做下一件。Codex 的模型上下文是有限的你把评审和实现混在一个会话里跑它早晚会撞上这堵墙。这也是“规约协同范式”能少报错的原因之一。另一个常见报错是这种形式the gpt-5.6-sol model is not supported when using codex with a chatgpt account原因我前面提到过Codex 用 ChatGPT 账户登录时模型白名单是固定的你手动指定一个账户方案不支持的模型名它直接拒绝。解决方法是切回 API Key 模式然后用配置文件里自定义的 model_provider 指定模型。或者干脆把模型名改回官方支持的默认值。6. 什么项目适合这套范式、什么项目绝对别用6.1 我用下来最顺的三类场景第一类是中小型模块的功能改造。比如给现有服务加缓存、加消息队列、调整核心查询逻辑影响面可控可以写出清晰的规约文件。这类任务最贴合“Claude 评审 Codex 实现”的分工。第二类是带有明确技术约束的团队项目。规约文件本身就是可审计的产物评审结论、影响面、任务清单都存下来了。团队 review 时可以直接看规约再对照代码 diff比空对空聊“为什么要这么改”高效得多。第三类是远程和移动场景的应急响应。人不在电脑前但任务必须推进的时候Kiro 手机端的价值完全体现出来。你可以在地铁上完成一次评审放行在咖啡厅里看着 Codex 跑完测试。这种场景下规约范式不是效率优化而是“能不能干活”的差别。6.2 三类坚决不要上规约协同的场景第一一行两行的热修复。改个配置项、调个参数这种任务直接让 Codex 一把梭最快。你要是也走“评审→规约→编码”全流程光规约文件就比代码还长纯属浪费。第二探索性原型阶段。技术选型还没定的时候你根本无法写出稳定的规约。Claude 评审出来的结论可能第二天就被推翻Codex 按规约写的代码全变成废稿。我自己的经验是原型期别搞什么规约等方案收敛了再上体系。第三重度交互式探索任务。有些任务需要边问边改、反复沟通比如“看看这段代码为什么慢能优化就优化一下”。这种模糊任务没法落成规约硬拆反而会把 AI 的灵活性打没。遇到这种老老实实坐在电脑前跟 Claude Code 交互着聊比在手机上点 allow 舒服一百倍。6.3 我的最终判断用了小半年我最大的感受不是“AI 替我写代码”而是“AI 逼我把思路写清楚”。架构评审交给 Claude、编码交给 Codex中间必须有一份人和 AI 都能读懂的规约时项目质量的下限其实是被这份规约兜住的。它逼着我在动手前想清楚改哪些文件、不动哪些边界、怎么验证结果。这种习惯一旦养成了哪怕没有 AI 代理对写代码这件事本身也是有帮助的。如果你也想搭一套类似的流程我给一个非常实际的起步建议不要急着装一堆工具先在下一次稍微复杂一点的任务里手动让 Claude 写一份规约再手动把规约丢给 Codex 执行。跑通一次之后你再决定要不要上 Kiro 的 Crew 模式把它自动化。我自己就是这么一步步走过来的目前这套范式还在持续演进尤其是规约文件模板基本每跑两三个项目就会改一版。但这恰恰是它最有意思的地方。
手机Kiro联动Claude与Codex：规约协同范式实战拆解
上周处理了一桩挺典型的线上问题推荐接口在凌晨流量高峰出现缓存穿透客户端超时率直线拉高。当时我在外面手边只有手机代码全在工作站的台式机里。搁以前只能干等回公司但那次我硬是用手机上的 Kiro 接进云端工作区让 Claude Code 先对现状做架构评审产出一份只动三个文件的规约再让 Codex 按规约在二十分钟内把修复写完连测试都补齐了。整个过程没有打开一次笔记本。这套玩法我前后跑了半年多从一开始的“两个 AI 各干各的”慢慢沉淀成一套相对固定的协作模式。核心就一句话Claude 负责想清楚Codex 负责写出来Kiro 负责让我在手机端掌握全部控制权。这篇文章不是介绍某个工具的说明书而是把整套“规约协同范式”从原理到落地、从配置到踩坑完整拆开讲一遍。适合远程办公的开发者、独立开发者以及所有想认真让 AI 代理干活而不是看热闹的人。1. 评审交给 Claude、编码交给 Codex这套分工背后的真实理由1.1 一个代理干所有事问题出在哪很多人刚接触 Claude Code 和 Codex 时的第一反应是既然这俩都是能读代码、写代码的 AI 代理那我挑一个顺手的用到死不就完了为什么要拆开我一开始也是这么干的。后来发现当任务比较复杂、涉及多个文件联动的时候单代理模式有两个很现实的问题。第一个是上下文预算。你让同一个代理既做架构分析又写全部实现它在分析阶段就要把整个项目的关键文件读一遍。等分析完上下文窗口已经被塞得差不多了真正写代码的时候反而开始“忘事”。最典型的表现就是前十分钟的方案说得头头是道后半小时实现的代码跟方案对不上。这不是模型笨是上下文分配不合理。第二个问题更致命缺乏可审计的中间产物。一个代理从分析到改代码一气呵成最后给你一个巨大的 diff。你 review 的时候根本不知道它当时为什么这么改。如果改错了你连回滚的依据都不好找。整个链路是一个黑盒你只有“开始”和“结果”两个控制点。1.2 Claude 的“慢思考”与 Codex 的“快实现”是互补关系把任务拆开之后两个模型的性格差异反而变成了优势。Claude Code 的长上下文能力和结构化输出让它天然适合做架构评审这类“想清楚再动手”的活。它能把一个模块的依赖关系、潜在风险、改动影响面梳理得比较完整。我用它评审过不少老项目的重构方案它给的 ADR架构决策记录和影响面分析直接拿给团队同事看都没有问题。Codex 的特性是执行链路短、迭代快写起代码来像子弹一样。让它做那种“需求已经很明确、照着清单填代码”的活效率非常夸张。尤其在规约文件已经把接口签名和改哪些文件都定死之后Codex 不需要再纠结设计问题只闷头实现就行速度自然快。这两个特性拆开用彼此都不浪费。Claude 不用一边分析一边赶工Codex 不用一边写代码一边猜方案。1.3 分工之后中间产物变成了资产这是我最想强调的一点把架构评审和编码拆给两个 AI最大的收益其实是中间那份规约文档。以前单代理干完活项目里除了代码 diff 什么都没留下。现在 Claude 评审完会产出一份规约文件这份文件会被 Codex 消费也会被提交到 git 仓库里。三个月后有人问“当时为什么要在 recommend 服务里加 Redis”你直接把这份规约甩给他里面写着决策理由、影响面、任务清单。这比翻聊天记录靠谱一万倍。规约同时是人的审查点。Codex 动手之前你可以在 Kiro 里打开这份规约看到底哪里改、哪里不许动。不满意就改规约改到满意再放行。所谓“掌控”掌控的就是这个节点。2. 把 Kiro 放进来手机端掌控的本质是“控制权”而不是“远程桌面”2.1 Kiro 在工作流里的位置云端工作区 会话编排一开始我接触 Kiro 时以为它就是个手机上的终端模拟器SSH 到服务器上敲命令。用了一段时间才意识到它的定位不太一样Kiro 更像个“AI 代理控制台”它负责的是云端工作区里的会话管理和操作审批而不是单纯给你一块屏幕敲键盘。一个直观的例子是我在手机 Kiro 里能看到 Claude Code 和 Codex 两个会话同时跑。Kiro 把任务列表和运行日志按会话分开我不用盯着终端输出刷屏只需要看哪个会话需要我确认操作以及关键节点的运行结果。它把“遥望式管理”变成了一种可能你不需要每时每刻都在看但你随时可以介入。Kiro 有 Windows 桌面端也有移动端。我个人的用法是桌面端做初始化配置把项目 clone 到云端工作区、装好依赖、配置好 Claude Code 和 Codex 的认证日常在外需要处理任务时就掏出手机连上同一个工作区直接干活。热词里经常有人搜“kiro windows 安装”说明很多人其实是先在电脑上接触它再开始用手机端。安装本身不复杂关键是把工作区网络、SSH 密钥、Git 身份这些一次性配置干净后面手机会省很多事。2.2 每次操作都要点 allow是麻烦还是安全底线如果你搜过“kiro 为什么每次都要点击 allow”说明你已经在真实使用中撞上了 Kiro 的权限设计。这个机制其实是故意的。AI 代理执行的每一条命令都有真实副作用改文件、删目录、装依赖、跑测试、push 代码。一旦放权它就可能在你看不见的地方把项目搞乱。手机端尤其危险因为屏幕小、误触概率高如果完全自动执行一条rm -rf下去可能整个工作区都没了。Kiro 的做法是把命令分成不同危险级别。比如git diff、ls这种只读命令通常不需要确认而npm install、git push、删除文件这类操作会弹确认窗。我遇到过不少人在网上抱怨“怎么每次都要点”其实解决方案不是关闭确认而是学会利用它的“记住选择”功能对同一个项目的同一条命令你可以在弹窗里选择“本次会话总是允许”这样 Claude 在一个会话内连续跑测试就不会反复打断你。安全底线这东西平时觉得烦真出事的时候才知道值钱。我建议确认级别设置成“只信任白名单命令”把npm test、git diff、npx eslint这类安全命令放行把rm、git push --force这类高危操作保持强制确认。这样既不烦人又守住了底线。2.3 用 Crew 模式把两个代理串成一个流水线Kiro 里有个我越用越依赖的能力Crew 模式。简单说它允许你预定义多个代理角色并且把它们编排成一条流水线。在我的用法里Crew 是这么配置的第一个角色是“架构评审员”绑定 Claude Code负责分析项目并输出规约文件第二个角色是“实现工程师”绑定 Codex负责读取规约并写代码。我在手机 Kiro 里启动一次 Crew 任务系统会先把任务投给 Claude等 Claude 完成评审并确认规约落盘后再自动把“执行规约”的指令发给 Codex。这个编排的价值在于它把我在 1.3 节说的“中间产物”变成了流水线的标准交接物。两个 AI 之间不需要在同一个上下文窗口里对话它们通过文件系统通信Claude 写文件Codex 读文件。Kiro 只是那个保证顺序和控制权的调度者。3. 规约文件两个 AI 之间那层“人话协议”3.1 规约不是需求文档是可执行契约很多团队也写需求文档但需求文档是给人看的里面有大量背景叙述、业务故事AI 读起来效率很低。我所说的规约是一份介于需求文档和代码之间的“可执行契约”。它必须满足三个条件第一足够具体每个改动点都能对应到具体文件和函数第二足够小一个规约只解决一个问题第三足够严格明确写出哪些事不许做。规约一旦落地Codex 其实不需要再做任何设计决策。这套范式的关键转折点就在这里Claude 的所有深度思考最终要转化为一份 Codex 不需要“思考”也能执行的文档。我经常跟朋友开玩笑说如果 Codex 读到规约还要停下来问你“这里的缓存 key 怎么设计”说明 Claude 的评审还没做透退回重写。3.2 一份规约文件长什么样以我处理过的 recommend 服务加 Redis 缓存为例Claude 最终产出的规约文件结构大概是这样# 规约recommend 服务引入 Redis 缓存改造 ## ADR-2024-008 - 状态已接受 - 决策采用 Redis 作为一级缓存TTL 60skey 规则 rec:{userId}:v1 - 理由当前 DB 查询耗时集中在热点用户写缓存穿透率为 37% ## 影响面 - src/services/recommend.js重写核心查询逻辑 - src/config/cache.js新增导出 Redis 客户端 - tests/integration/recommend.test.js新增缓存命中/穿透用例 ## 接口契约 - getRecommendations(userId, limit) 保持现有签名不变 - 返回值结构不变{ items, source: cache|db, ts } ## 任务清单 - [T1] 在 src/config/cache.js 中初始化 Redis 连接导出 get/set 封装 - [T2] 改造 recommend.js 查询链先查缓存miss 后查库并回填 - [T3] 补充集成测试覆盖命中、穿透、TTL 过期三条路径 ## 约束 - 不允许改动认证模块、API 路由文件 - 新增依赖必须同步更新 package.json 与 README - 不做与缓存无关的重构这份文件会提交到docs/specs/2024-cache-refactor.md。Codex 的执行指令非常简短读这个文件按任务清单逐个完成别越界。你可能已经注意到我把“接口签名不变”和“返回值结构不变”这种约束写得非常死。这是从多次踩坑里学来的。AI 代理的天性就是自由发挥你如果不把边界钉死它顺手就把你接口名改了然后一脸无辜地写进 changelog。3.3 CLAUDE.md、AGENTS.md、规约文档怎么各司其职有些项目里有 CLAUDE.md有些有 AGENTS.md很多人搞不清它们和规约文件的差别。我用的分层是CLAUDE.md 放在项目根目录给 Claude Code 看描述的是项目的长期事实技术栈、目录结构、编码规范、命令约定。它是静态的、很少变的。AGENTS.md 同样放根目录给 Codex 以及所有代理看内容侧重于“在这个仓库里干活时要注意什么”哪些目录不能动、测试怎么跑、依赖怎么装。它也是静态的。而规约文件是动态的、一次性的每个任务一份放在 docs/specs 下由 Claude 在评审时生成任务完成后归档。它是从“项目长期规范”到“本次任务约束”的桥梁。这三层各管各的不重叠。CLAUDE.md 解决“我是谁”AGENTS.md 解决“在这里怎么干活”规约解决“这次任务具体做什么”。如果你把所有东西都塞进一个文件代理会因为信息过载而选择性忽略反而起不到约束作用。4. 从零跑通手机 Kiro 联动 Claude 与 Codex 的完整配置记录4.1 环境准备Claude Code、Codex CLI、Kiro 三件套先把三个工具的安装说清楚都是我实际验证过的路径。Claude Code 官方推荐的是 npm 全局安装npm install -g anthropic-ai/claude-code安装完执行claude --version确认版本号正常。认证方式我用的是环境变量ANTHROPIC_API_KEY在 Kiro 的云端工作区里配置好后Claude Code 启动时自动读取。如果你是用 Claude 订阅登录的也可以在工作区里执行claude走交互式登录不过对远程工作区来说环境变量更省事。Codex CLI 同样是 npm 包npm install -g openai/codex或者从官方 release 直接下载对应平台的二进制。Windows 上我更推荐 npm 方式省去手动配 PATH 的麻烦。认证可以codex login用 ChatGPT 账户也可以用OPENAI_API_KEY。我建议用后者因为模型配置的灵活性更高后面 4.2 会细说。Kiro 的安装分两头Windows 桌面端从官网下载安装包手机端去应用商店搜。两端登录同一个账号后就能共享云端工作区列表和会话记录。4.2 认证与多模型接入官方 Key 与 OpenAI 兼容端点我的配置原则是Claude Code 走 Anthropic 官方 APICodex 走 OpenAI 官方 API同时预留一套 OpenAI 兼容端点用于切换模型。Codex CLI 支持在配置文件中自定义模型提供方格式大致如下放到~/.codex/config.tomlmodel gpt-5 model_provider openai [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY这样做的价值在于你可以通过修改model和model_provider两个字段在 OpenAI 官方模型和 DeepSeek 这类 OpenAI 兼容服务之间切换。比如做常规功能开发时用官方模型做批量琐碎编码时切换到成本更低的兼容端点。Codex 的输入端不变变的只是底层模型。需要提醒的是用 API Key 模式和用 ChatGPT 账户登录在 Codex 中对模型的支持范围是不一样的。账户登录时只能使用账户方案开放的模型子集手动指定一个不在白名单里的自定义模型名会直接报错。所以如果你需要灵活切换模型优先用 API Key 模式。4.3 在 Kiro 里绑定项目并定义运行目录Kiro 里每个项目都可以绑定一个云端工作区目录。我建议工作区结构尽量精简只放当前活跃项目不要把你所有仓库都塞进去。因为 Claude Code 和 Codex 在扫描文件时工作区里的无关目录会白白消耗上下文。我的标准结构是~/workspace/ recommend-service/ # 当前项目 specs/ # 规约文件归档项目 clone 完成后第一件事是把 AGENTS.md 和 CLAUDE.md 放进项目根目录再跑一次依赖安装确保工作区里的项目是可直接运行的。这一步如果不做后面 AI 代理跑测试时会因为缺依赖而反复失败浪费大量 token。4.4 一次完整的“评审→规约→编码→验证”实录拿真实的一次任务举例需求是给 recommend 服务加 Redis 缓存缓解 DB 压力。我在手机 Kiro 里向“架构评审员”角色发送了一条指令请对 src/services/recommend.js 做架构评审评估引入 Redis 缓存的影响面。需要覆盖查询链路上的热点方法、DB 连接池压力、返回结构兼容性。评审完成后按项目规约模板生成 docs/specs/2024-cache-refactor.md输出一份可被编码代理直接执行的规约。Claude Code 在云端工作区开始读代码、画依赖关系、评估影响。整个过程大概三分钟期间 Kiro 会推送“正在分析”的状态。评审完成后我在手机端打开了那份规约检查了接口契约和影响面确认没问题后点了“放行”。接着Kiro 的 Crew 流水线自动把规约路径发给了“实现工程师”角色也就是 Codex。Codex 的指令是阅读 docs/specs/2024-cache-refactor.md按任务清单实施。只改规约列出的文件不要做任何额外重构。完成 T1-T3 后运行 npm test确保全部通过。Codex 开始读规约、改代码、装 redis 依赖、写测试。期间 Kiro 弹了几次命令确认窗都是npm install redis和npm test这类操作我在手机上一路点了允许。大概十分钟后Kiro 推送了结果测试通过diff 涉及三个文件完全符合规约范围。这条流水线跑完我全程没有打开电脑。那个周末的线上问题就是在这条流程里被收掉的。5. 半年使用中的故障与排查笔记5.1 Kiro 的 allow 弹窗为什么它不肯记住我的选择这是社区里吐槽最多的点我在 2.2 节说过它是安全设计。但还有一层情况是Kiro 的 allow 策略是按“会话 命令模式”记忆的不是按“全局”记忆。也就是说你在会话 A 里允许了npm test切到会话 B 后它又会再问一次。这不是 bug是故意为之。因为会话 B 可能操作的是另一个项目或者同一个项目的另一个分支你上个会话的信任不能自动迁移。我现在的做法是在 Kiro 设置里把“命令确认策略”调整为“白名单模式”把只读操作和测试命令加入白名单。真正需要每次确认的只剩下少数高风险命令。这么调完之后烦人程度下降了一个量级同时安全底线还在。5.2 cc-switch 报 local proxy failed一条典型的端点转发排障链路cc-switch 是个管理 AI 代理供应商配置的社区工具它可以在 Claude Code、Codex 等多个 CLI 之间快速切换不同的 API 提供商。很多人喜欢在它里面配置本地转发地址统一管理多个模型的端点。但配置不当就会看到类似这样的报错cc switch local proxy failed while handling codex endpoint /responses. provider...第一次遇到时我以为是 cc-switch 本身坏了后来排查完发现是典型的本地端点连通性问题。这套排查链路我完整走了一遍直接分享给你第一步看报错发生在哪个环节。是启动时还是真正发请求时。如果是发请求时基本可以确认是端点转发失败不是认证问题。第二步检查那份 provider 配置里的 base_url。如果它指向类似http://127.0.0.1:9xxx/v1这种本地地址那它依赖的是一个本地转发服务不是官方端点。第三步确认转发服务到底有没有起来。Windows 上我用netstat -ano | findstr :9xxxmacOS 用lsof -i :9xxx一眼就能看到端口是否被监听。如果端口没监听说明转发服务没启动或已被杀掉。第四步验证转发服务本身是否健康。直接 curl 一下curl http://127.0.0.1:9xxx/v1/models如果能返回模型列表说明转发服务正常问题出在 cc-switch 转发链路上如果超时或拒绝连接问题就在转发服务自身。第五步检查 cc-switch 的“本地代理模式”是否被意外关闭。有些版本在切换供应商时会重置这个开关重新打开再切一次就好了。这条链路的本质是任何“本地端点”依赖都是脆弱的进程一挂、端口一占AI 工具就会立刻报错。排查时不要盯着 Codex 的报错看半天先确认底层转发服务活着没有。5.3 Claude Code 工作区 SDK 版本校验失败报错形态通常长这样failed to start claudes workspace rpc error -1: sdk version 2.1.260 not verified这个报错我遇到过两次都在claude升级之后。原因是 Claude Code 的 workspace 服务与它依赖的 SDK 版本没有对齐。升级过程中如果中断或者本地残留了旧版本的缓存就会出现“program 想用新 SDK但工作区服务还在旧版本”的撕裂状态。处理方式其实不复杂。先彻底退出所有正在运行的 claude 进程Windows 上用任务管理器macOS 上用pkill -f claude。然后重新执行全局安装npm install -g anthropic-ai/claude-codelatest如果重装完还报同样的错清一下~/.claude下与版本缓存相关的目录再启动。需要提醒的是清缓存前先看一眼里面有没有你本地的自定义配置别一股脑全删。这类问题看起来像黑魔法其实跟“浏览器版本更新后插件全挂”是一个道理。CLI 工具内部也是组件化的版本不同步就会报 RPC 错误。解决办法永远是全退、重装、清缓存三件套。5.4 Codex 上下文溢出与模型不支持报错Codex 跑长任务时会遇到一个提示error running remote compact task: codex ran out of room in the models context window意思是它想压缩旧上下文释放空间但压缩动作本身已经把剩余窗口占满导致压缩无法完成。这通常发生在单个会话里塞了太多任务或者项目里有大量文件被无关加载。我的解法就是把任务拆小用 3.2 节那种规约文件的 T1/T2/T3 粒度来控制会话规模。一个会话只做一件事做完立刻归档开新会话做下一件。Codex 的模型上下文是有限的你把评审和实现混在一个会话里跑它早晚会撞上这堵墙。这也是“规约协同范式”能少报错的原因之一。另一个常见报错是这种形式the gpt-5.6-sol model is not supported when using codex with a chatgpt account原因我前面提到过Codex 用 ChatGPT 账户登录时模型白名单是固定的你手动指定一个账户方案不支持的模型名它直接拒绝。解决方法是切回 API Key 模式然后用配置文件里自定义的 model_provider 指定模型。或者干脆把模型名改回官方支持的默认值。6. 什么项目适合这套范式、什么项目绝对别用6.1 我用下来最顺的三类场景第一类是中小型模块的功能改造。比如给现有服务加缓存、加消息队列、调整核心查询逻辑影响面可控可以写出清晰的规约文件。这类任务最贴合“Claude 评审 Codex 实现”的分工。第二类是带有明确技术约束的团队项目。规约文件本身就是可审计的产物评审结论、影响面、任务清单都存下来了。团队 review 时可以直接看规约再对照代码 diff比空对空聊“为什么要这么改”高效得多。第三类是远程和移动场景的应急响应。人不在电脑前但任务必须推进的时候Kiro 手机端的价值完全体现出来。你可以在地铁上完成一次评审放行在咖啡厅里看着 Codex 跑完测试。这种场景下规约范式不是效率优化而是“能不能干活”的差别。6.2 三类坚决不要上规约协同的场景第一一行两行的热修复。改个配置项、调个参数这种任务直接让 Codex 一把梭最快。你要是也走“评审→规约→编码”全流程光规约文件就比代码还长纯属浪费。第二探索性原型阶段。技术选型还没定的时候你根本无法写出稳定的规约。Claude 评审出来的结论可能第二天就被推翻Codex 按规约写的代码全变成废稿。我自己的经验是原型期别搞什么规约等方案收敛了再上体系。第三重度交互式探索任务。有些任务需要边问边改、反复沟通比如“看看这段代码为什么慢能优化就优化一下”。这种模糊任务没法落成规约硬拆反而会把 AI 的灵活性打没。遇到这种老老实实坐在电脑前跟 Claude Code 交互着聊比在手机上点 allow 舒服一百倍。6.3 我的最终判断用了小半年我最大的感受不是“AI 替我写代码”而是“AI 逼我把思路写清楚”。架构评审交给 Claude、编码交给 Codex中间必须有一份人和 AI 都能读懂的规约时项目质量的下限其实是被这份规约兜住的。它逼着我在动手前想清楚改哪些文件、不动哪些边界、怎么验证结果。这种习惯一旦养成了哪怕没有 AI 代理对写代码这件事本身也是有帮助的。如果你也想搭一套类似的流程我给一个非常实际的起步建议不要急着装一堆工具先在下一次稍微复杂一点的任务里手动让 Claude 写一份规约再手动把规约丢给 Codex 执行。跑通一次之后你再决定要不要上 Kiro 的 Crew 模式把它自动化。我自己就是这么一步步走过来的目前这套范式还在持续演进尤其是规约文件模板基本每跑两三个项目就会改一版。但这恰恰是它最有意思的地方。
