企业官网建设流程全解析

上周处理了一桩挺典型的线上问题：推荐接口在凌晨流量高峰出现缓存穿透，客户端超时率直线拉高。当时我在外面，手边只有手机，代码全在工作站的台式机里。搁以前只能干等回公司，但那次我硬是用手机上的 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 60s，key 规则 `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 官方 API，Codex 走 OpenAI 官方 API，同时预留一套 OpenAI 兼容端点用于切换模型。

Codex CLI 支持在配置文件中自定义模型提供方，格式大致如下，放到~/.codex/config.toml：

model = "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 :9xxx，macOS 用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 claude's 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-code@latest

如果重装完还报同样的错，清一下~/.claude下与版本缓存相关的目录，再启动。需要提醒的是，清缓存前先看一眼里面有没有你本地的自定义配置，别一股脑全删。

这类问题看起来像黑魔法，其实跟“浏览器版本更新后插件全挂”是一个道理。CLI 工具内部也是组件化的，版本不同步就会报 RPC 错误。解决办法永远是：全退、重装、清缓存，三件套。

5.4 Codex 上下文溢出与模型不支持报错

Codex 跑长任务时会遇到一个提示：

error running remote compact task: codex ran out of room in the model's 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 模式把它自动化。我自己就是这么一步步走过来的，目前这套范式还在持续演进，尤其是规约文件模板，基本每跑两三个项目就会改一版。但这恰恰是它最有意思的地方。