2026/9/9 6:01:17
FEATURED · 精选文章 
让 Codex 一口气把一个完整前端生成出来第一眼效果确实唬人页面有了、按钮能点了、列表也出来了。但等你真正开始接手问题会一个接一个冒出来——样式和逻辑混在一个巨型文件里、状态管理随手 new 一个全局变量、测试一个都没写、构建脚本还是脚手架自带的默认值。你越是让它接着改它越是把代码搅成一锅粥。我自己踩过这个坑之后现在的做法完全反过来了不让 Codex 当“全栈独狼”而是让它当一个“有分工的团队”。具体手段就是给它配 5 组 Skills把页面、逻辑、测试、构建这些职责彻底拆开每一步都在明确边界内工作。这篇文章就把这套打法的完整思路、Skills 写法和实操流程全部拆给你看。1. 先回答一个问题为什么不能让 Codex 一口气写完1.1 一次性生成的最大问题不是代码是认知断点很多人以为“让 AI 一口气写完”省事其实只是把成本延后了。代码生成的那一刻很爽但项目不是靠“生成出来”就能运行的它要靠人理解和维护。Codex 在一次超长上下文里连续生成几十个文件之后前面的设计意图基本就丢了——它只记得自己刚刚写了什么但记不得“为什么这么写”。举个例子我让 Codex 一次性生成过一个带筛选、排序、分页的表格页面。它确实把所有功能都写出来了但用的是三个useState加一堆内联函数数据请求直接写在组件里没有任何 hook 抽象。等我想加一个导出功能时发现业务逻辑完全没法复用只能把整块代码抽出来重构。这还只是一个小页面如果是整个前端项目后果可想而知。另一个更隐蔽的问题是一致性。一次性生成多个文件时Codex 经常会“自创”一些共享类型、工具函数或接口命名但这个定义散落在不同文件里前后版本可能还不一致。你用 A 文件里的User类型它却在 B 文件里定义了一个UserInfo字段还不一样。这种问题靠肉眼很难全部发现跑起来才报错回头排查成本极高。1.2 拆分的正确姿势不是按文件而是按“工作边界”所以关键不是“少让 Codex 写代码”而是“每次只让 Codex 干一类活”。人写代码也是这么分工的先设计页面结构再写业务逻辑再补测试最后配构建。AI 也一样只不过我们需要用 Skills 给它划出清晰的边界。我的划分方式是 5 组 Skills每组的职责边界如下Skill 名称职责范围不负责什么ui-architect页面结构、组件拆分、样式、响应式不写数据请求、不写状态管理logic-owner业务逻辑、hooks、状态流转、数据接口适配不写 DOM 和样式test-suite单测、组件测试、端到端测试用例不改业务实现build-pipeline构建配置、类型检查、Lint、产物优化不写业务代码gatekeeper代码评审、兼容性检查、变更记录不直接改大逻辑这样拆完Codex 每一次的工作目标都非常收敛生成页面时它不用想数据从哪来只用约定好的接口写逻辑时不用纠结长什么样只关心状态和数据写测试时不会顺手去改实现。这个模式本质上就是把一个“全栈工程师 AI”拆成了“一个前端小组”。2. 开工之前把全局规则和上下文喂给 Codex2.1 AGENTS.md 先定“法律”再谈具体开发Skills 解决的是“这一类活怎么干”但 Codex 还需要知道“这个项目本身有什么规矩”。这一步靠项目根的AGENTS.md有些工具叫CODEX.md原理一样。这个文件要做的不是写作文而是把所有 Codex 需要“默认遵守”的规则钉死。越具体越好写清楚也不会伤感情。我最基本的AGENTS.md长这样# 项目指令 ## 技术栈 - 前端React 18 TypeScript 5 Vite 5 - 样式CSS Modules禁止使用 Tailwind - 状态Zustand禁止使用 Redux - 测试Vitest React Testing Library - 包管理pnpm ## 目录约定 - 页面组件放 src/pages/ - 业务组件放 src/components/ - hooks 放 src/hooks/ - API 相关放 src/api/ - 页面内一次性组件就近存放 ## 开发命令 - 安装依赖pnpm install - 启动开发pnpm dev - 类型检查pnpm typecheck - 运行测试pnpm test - 构建pnpm build ## 编码红线 - 不要新增没用的依赖 - 不要写内联样式特殊情况除外 - 组件默认使用函数组件禁止 class 组件 - 类型定义必须使用 interface不要用 type 定义对象这段规则看着简单但价值巨大。它保证了不管哪个 Skill 在执行任务Codex 都默认按统一标准产出代码。如果你不做这一步就会出现 ui-architect 写出来的组件用了 Tailwindlogic-owner 写的状态管理却想引入 Redux最后整个项目风格割裂。2.2 Skills 目录结构与命名约定Skills 本质上是一组带说明文档的指令文件。我沿用的是社区里比较通用的目录约定在项目根目录建一个.codex/skills/目录每个 skill 一个子目录里面必须有一个SKILL.md做入口。目录结构大致如下项目根目录/ ├── AGENTS.md ├── .codex/ │ └── skills/ │ ├── ui-architect/ │ │ ├── SKILL.md │ │ └── references/ │ │ └── component-patterns.md │ ├── logic-owner/ │ │ └── SKILL.md │ ├── test-suite/ │ │ └── SKILL.md │ ├── build-pipeline/ │ │ └── SKILL.md │ └── gatekeeper/ │ └── SKILL.mdSKILL.md的开头建议写清楚几个字段name技能名、description什么时候用、when_to_use什么时候不该用、steps执行步骤。description 一定要写得像给搜索引擎看的摘要因为 Codex 读取 Skills 的时候很依赖这段描述来决定是否启用它。我之前吃过亏描述写得模糊结果我明明要生成页面它却去调了 logic-owner产出一堆 hooks 文件页面结构完全没动。2.3 把脚本和依赖也统一“喂”给它还有一个容易忽略的点Codex 默认情况下并不知道你的项目有哪些命令和依赖。如果你不在 AGENTS.md 里写清楚依赖管理用pnpm、测试工具是 Vitest它很可能默认用 npm 或 Jest。一旦生成的文件里带package.json或配置文件后面就非常被动。所以我在 AGENTS.md 里除了写命令还会把关键依赖的版本都列出来甚至注明“新增依赖必须经我手动确认”。这样 Codex 在测试或构建时就会去用现有工具链而不是自己再造一套轮子。这个细节看起来很小但实际能挡住很多坑。3. 五组 Skills 的职责拆解和写法3.1 第一组ui-architect只管页面长什么样ui-architect是前端的“门面担当”负责页面结构、组件拆分、样式、响应式布局。这组 skill 的核心要求是不要碰数据请求不要碰状态管理。UI 组件需要数据时用 props 或约定好的 hooks 接口占位即可。一个精简版SKILL.md模板--- name: ui-architect description: 用于生成页面结构、React 组件、样式与响应式布局。当需要从零搭建 UI、拆分组件、调整视觉表现时使用。 when_to_use: 创建新页面、重构组件结构、修复样式问题 when_not_to_use: 修改业务数据流、编写 API 请求、调整状态管理逻辑 --- # UI 架构与实现 ## 执行步骤 1. 先阅读 AGENTS.md确认技术栈和目录规范。 2. 根据需求拆分组件层级一个组件文件只做一个核心功能。 3. 使用 CSS Modules 编写样式禁止 Tailwind 和内联样式。 4. 所有数据展示通过 props 传入不在组件内直接请求接口。 5. 输出文件清单和组件关系说明。 ## 产出约束 - 每个组件必须声明 props 的 interface。 - 列表渲染必须有 key且 key 不使用数组 index。 - 通用组件放 components 目录页面一次性组件就近创建。实际使用的时候我会在 prompt 里加一句“请列出组件拆分的理由”这样我能看出它是不是真的理解了页面结构而不是机械地切块。ui-architect 最重要的产出不是代码而是组件结构——结构对了后面的逻辑和样式调整都好办。3.2 第二组logic-owner把数据和业务状态管起来logic-owner负责的是业务逻辑、自定义 hooks、状态管理、数据请求和接口适配。它和 ui-architect 是天然搭档ui 组件只负责“长得好看”logic-owner 负责“背后怎么运转”。我给它写的 SKILL.md 核心约束包括所有数据请求走src/api/下的统一封装不直接在页面组件里fetch状态管理用 Zustand且 store 要按业务领域拆分业务逻辑尽量抽象成 hooks让组件保持薄。同时每个 hook 都要返回清晰的类型定义方便 ui-architect 那边用起来不迷糊。这组 skill 还有一个任务把接口数据“翻译”成页面需要的结构。比如后端返回的字段是user_name页面里想用userName这个映射逻辑就应该放在 logic-owner 层而不是让页面组件去处理。做到这一点后面换后端字段、加缓存、做权限控制都只需要动 hooks 或 store不用波及 UI。3.3 第三组test-suite把测试补成“安全网”测试这组 skill 的定位是“监督者”。它负责读现有代码然后生成单元测试、组件测试、交互测试。我要求它遵循几个原则测试文件与被测文件同目录命名统一为xxx.test.ts(x)测试里不 mock 自己写的 hooks而是真实调用除非涉及外部 API每个测试只验证一个行为测试用例的描述必须是“用户语言”而不是“实现语言”。为什么强调这一点因为 Codex 写测试最容易犯的毛病是“为了覆盖而覆盖”——给每个函数写一堆断言但测的全是内部实现实际上一点保护作用都没有。比如它测一个addTodo函数断言的是“调用了 setTodos”而不是“点击添加按钮后列表出现新条目”。这种测试对重构毫无帮助改一下实现就全红了。我在 SKILL.md 里专门写了一条优先测行为不测实现细节。3.4 第四组build-pipeline让构建和工程化跑起来build-pipeline负责工程化相关的脏活累活构建配置、TypeScript 类型检查、ESLint 规则、环境变量管理、产物优化。这组 skill 不需要频繁调用但一旦调用就要确保整个项目“可交付”。它的 SKILL.md 我会写得偏“检查清单化”比如执行pnpm typecheck确认无类型错误执行pnpm build确认产出成功检查dist/产物大小是否异常确认构建产物中无console.log残留检查是否能部署到静态服务器预览。此外还要求它把 CI 里的命令写成一行一个方便我复制到流水线里。这里有个实操技巧build-pipeline 的 output 写成“结论 日志摘要”模式让它告诉我“构建通过”“类型检查通过”“产物体积为 230KB比上次增加 12KB”这种结论我只关心结果和异常。它给出原始日志太长了反而不好排查。3.5 第五组gatekeeper质量的最后一道闸门gatekeeper是五组里最特殊的一个它不做“创作”只做“评审”。它需要读一遍改动过的代码按一套规则挑毛病有没有不合理的any、有没有重复代码、有没有未使用的变量、props 传递是否过大、组件是否过度复杂、有没有引入不必要的依赖。我用它来替代“人工 code review 的前置过滤”。每次 Codex 干完活我先让 gatekeeper 看一遍把明显的问题打回重做再自己人工 review。这比直接人肉检查高效太多。它的 SKILL.md 核心是让它输出“问题清单 建议修改方案 影响范围”而不是直接改代码。直接让 AI 又评审又修改很容易引入新的问题因为它的“判断脑”和“生成脑”切换容易出错。4. 完整实操把一个“用户管理页”拆给 Codex4.1 初始化项目与全局配置我假设你要做一个“用户管理页”新仓库技术栈 React TS Vite Zustand Vitest。第一步先把项目初始化和 AGENTS.md 写好然后再让 Codex 介入。pnpm create vite codex-split-demo --template react-ts cd codex-split-demo pnpm install pnpm add zustand pnpm add -D vitest testing-library/react testing-library/jest-dom然后按第 2 节的内容写好 AGENTS.md。这里的关键是让你的项目从一开始就有“规矩”而不是先让 Codex 自由发挥后面再驯服它。4.2 用 ui-architect 生成页面骨架配置好之后第一条指令我给 ui-architect请使用 ui-architect skill实现“用户管理页”。 需求左侧为筛选区按姓名、状态筛选右侧为用户表格顶部有新增按钮。 要求先输出组件拆分清单再生成代码。Codex 读取 ui-architect 之后会先给出一个类似这样的拆分方案UserManagementPage ├── UserFilterForm姓名输入框、状态下拉 ├── UserTable表格展示、分页、排序 └── CreateUserButton触发新增弹窗随后生成对应组件。这个阶段生成出来的表格里没有真实数据只用 props 接收users和loading。UI 层不关心数据从哪来这正是我想要的。4.3 用 logic-owner 把数据和状态接上页面骨架生成之后让 logic-owner 干活请使用 logic-owner skill为“用户管理页”补齐数据流。 要求封装 useUserList hook处理筛选、分页、排序用 Zustand 管理用户列表状态API 请求放在 src/api/user.ts。它生成的核心 hook 大概长这样示意export function useUserList() { const { list, loading, fetchUsers } useUserStore(); const [keyword, setKeyword] useState(); const [status, setStatus] useStateUserStatus | (); const [page, setPage] useState(1); useEffect(() { fetchUsers({ keyword, status, page }); }, [keyword, status, page]); return { list, loading, keyword, setKeyword, status, setStatus, page, setPage }; }有了这个 hookui-architect 之前写的占位 props 就能改成真实的数据流。此时再让 ui-architect “小改”一下页面把 props 替换成 hook 返回值就能把两端接起来了。注意这里我给的是两次独立调用而不是让一次对话连续完成所有事这样 Codex 在每一阶段都保持清晰上下文。4.4 用 test-suite 补测试页面和数据流都通了接下来让 test-suite 写测试请使用 test-suite skill为 UserManagementPage 和相关 hooks 编写测试。 要求覆盖筛选交互、分页、空状态、加载状态用 Testing Library 模拟用户操作。Codex 会生成类似这样的测试describe(UserManagementPage, () { it(输入姓名关键字后表格只展示匹配用户, async () { render(UserManagementPage /); fireEvent.change(screen.getByPlaceholderText(请输入姓名), { target: { value: 张三 }, }); expect(await screen.findByText(张三)).toBeInTheDocument(); expect(screen.queryByText(李四)).not.toBeInTheDocument(); }); });如果测试跑不过我一般不会让 test-suite 去改业务代码而是把失败信息反馈给 logic-owner 或者 ui-architect让他们改完再回来跑测试。这两组的边界必须分清楚不然 test-suite 一会儿改测试、一会儿改实现最后你都不知道代码为什么变绿。4.5 用 build-pipeline 做交付前验证最后一步让 build-pipeline 收尾请使用 build-pipeline skill执行完整的交付前检查typecheck、lint、build、测试并输出结论和产物信息。Codex 会执行命令并汇报结果。如果中间有失败就根据报错内容打回给对应 skill 修复。等这一轮全绿代码才能算“完成”。现实里很多 AI 生成的代码就是死在构建这一步——组件导出来是undefined、类型对不上、CSS Modules 的interface没导出这些都要靠构建验证兜住。4.6 用 gatekeeper 做最后评审构建通过不代表代码质量 OK。我最后会让 gatekeeper 看一下整体 diff请使用 gatekeeper skill评审本次“用户管理页”的全部改动。 重点关注类型安全、重复代码、组件复杂度、props 传递合理性、是否有不必要的依赖。 输出格式问题清单按严重程度排序 每条的修改建议。这一轮经常能抓出一些“能跑但不优雅”的问题比如列表 key 用了 index、hooks 里塞了多个不相干功能、any偷偷出现。没过 gatekeeper 的代码我会让对应 skill 修完再走一遍构建验证。5. 常见问题与排查技巧实录5.1 Codex 调用时本地通道报错、provider 校验不过这是我自己用 Codex 时遇到过比较烦的问题调用到一半客户端直接报一段codex endpoint /responses相关的错误后面跟着provider字样任务中断。第一次遇到还以为是网络不稳定重启了好几回后来才发现是本地服务通道状态的锅。排查思路一般分三步第一检查本地服务端口是否正常启动有没有被杀掉第二重启客户端让配置重新加载第三检查 provider 端的 API Key 或 baseUrl 是否写错、是否过期。这里要特别提醒如果你配置了第三方模型服务模型切换后旧会话的连接信息可能失效最稳妥的办法是新起一个会话再继续。5.2 Skills 不生效指令总是被忽略很多人配置了 Skills 但发现 Codex 根本不调用十有八九是 description 写得太泛。比如你写“用于前端开发”那它根本不知道该在什么时候启用相反如果你写“当需要生成页面组件、拆分 UI 结构时使用不要用于数据逻辑”命中率会高很多。另外确认一下文件路径是不是项目根目录下被 Codex 默认扫描到的地方。有时候你放在src/下面或者放错层级工具根本读不到。还有一个常见问题是 SKILL.md 的 frontmatter 格式不标准字段名写错了解析器没法识别。我一直用name / description / when_to_use / when_not_to_use这套结构暂时没出过问题。5.3 上下文溢出和“重复劳动”Codex 在超长对话里会变笨最常见表现是同一个需求反复改、越改越乱。我的应对措施是把任务拆得更小一次会话只处理一个 skill 范围内的一个明确目标。比如“实现用户管理页”这种指令还是太大可以继续拆成“先实现表格组件”“再实现筛选表单”。另外建议每完成一个阶段就做一次 commit。这样即使 Codex 后面改崩了也能快速回退到上一个稳定版本而不是在它的错误思路上反复纠缠。我的经验是Context 省着用Codex 的状态才稳。该开新会话就开新会话不用觉得浪费。5.4 测试组和逻辑组“打架”测试失败的原因经常不是测试写错而是生产代码行为变了。比如 logic-owner 把fetchUsers从“同步返回”改成了“异步加载”导致 test-suite 里原有的断言超时。这时候不要手动改测试掩盖问题正确的流程是看改动是不是预期行为如果是就让 test-suite 按新行为更新测试如果不是就让 logic-owner 修复实现。这套流程走顺之后测试组和逻辑组会形成一种“你写实现、我补断言”的良性循环前提是别让两边跨边界改代码。5.5 构建环境差异本地构建过了CI 却挂了这种问题在 AI 生成代码的项目里特别常见。原因多半是 CI 环境的 Node 版本、包管理器版本和本机不一致或者某个依赖是 AI 自动加的、你没手动确认结果锁文件和 package.json 对不上。build-pipeline的检查清单里建议加一条检查 Node 版本声明、检查packageManager字段、确认 pnpm-lock.yaml 已提交。这些小细节能省掉大量“本地能跑、线上必挂”的尴尬时刻。6. 最后分享一点我自己的实践体会这套五组 Skills 的流程跑下来我最明显的感觉是Codex 从“一个容易上头的大聪明”变成了“一个可以按节奏协作的同事”。它不再一口气给你整一堆看似完整、实则脆弱的代码而是每一步都给出边界清晰、可校验的产物。我踩过几次坑之后已经习惯了这种节奏UI 出来后先看结构逻辑接完先试用测试写完先跑一遍构建全绿才合代码——每一步都有验证节点每一步翻车都在可控范围内。如果你现在的项目还没用过 Skills我建议不要一上来就配五组太重的体系反而让你不想维护。先把test-suite或build-pipeline单独拎出来用感受一下“边界如何约束 AI 发挥”再逐渐把页面、逻辑、评审各组补齐。等你真的习惯了这种“拆开来干活”的方式你会发现 Codex 写前端的上限比自己瞎指挥高不少而你作为开发者也终于能把精力放在真正需要判断力的事情上而不是追着它的烂摊子到处救火。
Codex写前端总是一团糟？5组Skills把它拆成高效团队
让 Codex 一口气把一个完整前端生成出来第一眼效果确实唬人页面有了、按钮能点了、列表也出来了。但等你真正开始接手问题会一个接一个冒出来——样式和逻辑混在一个巨型文件里、状态管理随手 new 一个全局变量、测试一个都没写、构建脚本还是脚手架自带的默认值。你越是让它接着改它越是把代码搅成一锅粥。我自己踩过这个坑之后现在的做法完全反过来了不让 Codex 当“全栈独狼”而是让它当一个“有分工的团队”。具体手段就是给它配 5 组 Skills把页面、逻辑、测试、构建这些职责彻底拆开每一步都在明确边界内工作。这篇文章就把这套打法的完整思路、Skills 写法和实操流程全部拆给你看。1. 先回答一个问题为什么不能让 Codex 一口气写完1.1 一次性生成的最大问题不是代码是认知断点很多人以为“让 AI 一口气写完”省事其实只是把成本延后了。代码生成的那一刻很爽但项目不是靠“生成出来”就能运行的它要靠人理解和维护。Codex 在一次超长上下文里连续生成几十个文件之后前面的设计意图基本就丢了——它只记得自己刚刚写了什么但记不得“为什么这么写”。举个例子我让 Codex 一次性生成过一个带筛选、排序、分页的表格页面。它确实把所有功能都写出来了但用的是三个useState加一堆内联函数数据请求直接写在组件里没有任何 hook 抽象。等我想加一个导出功能时发现业务逻辑完全没法复用只能把整块代码抽出来重构。这还只是一个小页面如果是整个前端项目后果可想而知。另一个更隐蔽的问题是一致性。一次性生成多个文件时Codex 经常会“自创”一些共享类型、工具函数或接口命名但这个定义散落在不同文件里前后版本可能还不一致。你用 A 文件里的User类型它却在 B 文件里定义了一个UserInfo字段还不一样。这种问题靠肉眼很难全部发现跑起来才报错回头排查成本极高。1.2 拆分的正确姿势不是按文件而是按“工作边界”所以关键不是“少让 Codex 写代码”而是“每次只让 Codex 干一类活”。人写代码也是这么分工的先设计页面结构再写业务逻辑再补测试最后配构建。AI 也一样只不过我们需要用 Skills 给它划出清晰的边界。我的划分方式是 5 组 Skills每组的职责边界如下Skill 名称职责范围不负责什么ui-architect页面结构、组件拆分、样式、响应式不写数据请求、不写状态管理logic-owner业务逻辑、hooks、状态流转、数据接口适配不写 DOM 和样式test-suite单测、组件测试、端到端测试用例不改业务实现build-pipeline构建配置、类型检查、Lint、产物优化不写业务代码gatekeeper代码评审、兼容性检查、变更记录不直接改大逻辑这样拆完Codex 每一次的工作目标都非常收敛生成页面时它不用想数据从哪来只用约定好的接口写逻辑时不用纠结长什么样只关心状态和数据写测试时不会顺手去改实现。这个模式本质上就是把一个“全栈工程师 AI”拆成了“一个前端小组”。2. 开工之前把全局规则和上下文喂给 Codex2.1 AGENTS.md 先定“法律”再谈具体开发Skills 解决的是“这一类活怎么干”但 Codex 还需要知道“这个项目本身有什么规矩”。这一步靠项目根的AGENTS.md有些工具叫CODEX.md原理一样。这个文件要做的不是写作文而是把所有 Codex 需要“默认遵守”的规则钉死。越具体越好写清楚也不会伤感情。我最基本的AGENTS.md长这样# 项目指令 ## 技术栈 - 前端React 18 TypeScript 5 Vite 5 - 样式CSS Modules禁止使用 Tailwind - 状态Zustand禁止使用 Redux - 测试Vitest React Testing Library - 包管理pnpm ## 目录约定 - 页面组件放 src/pages/ - 业务组件放 src/components/ - hooks 放 src/hooks/ - API 相关放 src/api/ - 页面内一次性组件就近存放 ## 开发命令 - 安装依赖pnpm install - 启动开发pnpm dev - 类型检查pnpm typecheck - 运行测试pnpm test - 构建pnpm build ## 编码红线 - 不要新增没用的依赖 - 不要写内联样式特殊情况除外 - 组件默认使用函数组件禁止 class 组件 - 类型定义必须使用 interface不要用 type 定义对象这段规则看着简单但价值巨大。它保证了不管哪个 Skill 在执行任务Codex 都默认按统一标准产出代码。如果你不做这一步就会出现 ui-architect 写出来的组件用了 Tailwindlogic-owner 写的状态管理却想引入 Redux最后整个项目风格割裂。2.2 Skills 目录结构与命名约定Skills 本质上是一组带说明文档的指令文件。我沿用的是社区里比较通用的目录约定在项目根目录建一个.codex/skills/目录每个 skill 一个子目录里面必须有一个SKILL.md做入口。目录结构大致如下项目根目录/ ├── AGENTS.md ├── .codex/ │ └── skills/ │ ├── ui-architect/ │ │ ├── SKILL.md │ │ └── references/ │ │ └── component-patterns.md │ ├── logic-owner/ │ │ └── SKILL.md │ ├── test-suite/ │ │ └── SKILL.md │ ├── build-pipeline/ │ │ └── SKILL.md │ └── gatekeeper/ │ └── SKILL.mdSKILL.md的开头建议写清楚几个字段name技能名、description什么时候用、when_to_use什么时候不该用、steps执行步骤。description 一定要写得像给搜索引擎看的摘要因为 Codex 读取 Skills 的时候很依赖这段描述来决定是否启用它。我之前吃过亏描述写得模糊结果我明明要生成页面它却去调了 logic-owner产出一堆 hooks 文件页面结构完全没动。2.3 把脚本和依赖也统一“喂”给它还有一个容易忽略的点Codex 默认情况下并不知道你的项目有哪些命令和依赖。如果你不在 AGENTS.md 里写清楚依赖管理用pnpm、测试工具是 Vitest它很可能默认用 npm 或 Jest。一旦生成的文件里带package.json或配置文件后面就非常被动。所以我在 AGENTS.md 里除了写命令还会把关键依赖的版本都列出来甚至注明“新增依赖必须经我手动确认”。这样 Codex 在测试或构建时就会去用现有工具链而不是自己再造一套轮子。这个细节看起来很小但实际能挡住很多坑。3. 五组 Skills 的职责拆解和写法3.1 第一组ui-architect只管页面长什么样ui-architect是前端的“门面担当”负责页面结构、组件拆分、样式、响应式布局。这组 skill 的核心要求是不要碰数据请求不要碰状态管理。UI 组件需要数据时用 props 或约定好的 hooks 接口占位即可。一个精简版SKILL.md模板--- name: ui-architect description: 用于生成页面结构、React 组件、样式与响应式布局。当需要从零搭建 UI、拆分组件、调整视觉表现时使用。 when_to_use: 创建新页面、重构组件结构、修复样式问题 when_not_to_use: 修改业务数据流、编写 API 请求、调整状态管理逻辑 --- # UI 架构与实现 ## 执行步骤 1. 先阅读 AGENTS.md确认技术栈和目录规范。 2. 根据需求拆分组件层级一个组件文件只做一个核心功能。 3. 使用 CSS Modules 编写样式禁止 Tailwind 和内联样式。 4. 所有数据展示通过 props 传入不在组件内直接请求接口。 5. 输出文件清单和组件关系说明。 ## 产出约束 - 每个组件必须声明 props 的 interface。 - 列表渲染必须有 key且 key 不使用数组 index。 - 通用组件放 components 目录页面一次性组件就近创建。实际使用的时候我会在 prompt 里加一句“请列出组件拆分的理由”这样我能看出它是不是真的理解了页面结构而不是机械地切块。ui-architect 最重要的产出不是代码而是组件结构——结构对了后面的逻辑和样式调整都好办。3.2 第二组logic-owner把数据和业务状态管起来logic-owner负责的是业务逻辑、自定义 hooks、状态管理、数据请求和接口适配。它和 ui-architect 是天然搭档ui 组件只负责“长得好看”logic-owner 负责“背后怎么运转”。我给它写的 SKILL.md 核心约束包括所有数据请求走src/api/下的统一封装不直接在页面组件里fetch状态管理用 Zustand且 store 要按业务领域拆分业务逻辑尽量抽象成 hooks让组件保持薄。同时每个 hook 都要返回清晰的类型定义方便 ui-architect 那边用起来不迷糊。这组 skill 还有一个任务把接口数据“翻译”成页面需要的结构。比如后端返回的字段是user_name页面里想用userName这个映射逻辑就应该放在 logic-owner 层而不是让页面组件去处理。做到这一点后面换后端字段、加缓存、做权限控制都只需要动 hooks 或 store不用波及 UI。3.3 第三组test-suite把测试补成“安全网”测试这组 skill 的定位是“监督者”。它负责读现有代码然后生成单元测试、组件测试、交互测试。我要求它遵循几个原则测试文件与被测文件同目录命名统一为xxx.test.ts(x)测试里不 mock 自己写的 hooks而是真实调用除非涉及外部 API每个测试只验证一个行为测试用例的描述必须是“用户语言”而不是“实现语言”。为什么强调这一点因为 Codex 写测试最容易犯的毛病是“为了覆盖而覆盖”——给每个函数写一堆断言但测的全是内部实现实际上一点保护作用都没有。比如它测一个addTodo函数断言的是“调用了 setTodos”而不是“点击添加按钮后列表出现新条目”。这种测试对重构毫无帮助改一下实现就全红了。我在 SKILL.md 里专门写了一条优先测行为不测实现细节。3.4 第四组build-pipeline让构建和工程化跑起来build-pipeline负责工程化相关的脏活累活构建配置、TypeScript 类型检查、ESLint 规则、环境变量管理、产物优化。这组 skill 不需要频繁调用但一旦调用就要确保整个项目“可交付”。它的 SKILL.md 我会写得偏“检查清单化”比如执行pnpm typecheck确认无类型错误执行pnpm build确认产出成功检查dist/产物大小是否异常确认构建产物中无console.log残留检查是否能部署到静态服务器预览。此外还要求它把 CI 里的命令写成一行一个方便我复制到流水线里。这里有个实操技巧build-pipeline 的 output 写成“结论 日志摘要”模式让它告诉我“构建通过”“类型检查通过”“产物体积为 230KB比上次增加 12KB”这种结论我只关心结果和异常。它给出原始日志太长了反而不好排查。3.5 第五组gatekeeper质量的最后一道闸门gatekeeper是五组里最特殊的一个它不做“创作”只做“评审”。它需要读一遍改动过的代码按一套规则挑毛病有没有不合理的any、有没有重复代码、有没有未使用的变量、props 传递是否过大、组件是否过度复杂、有没有引入不必要的依赖。我用它来替代“人工 code review 的前置过滤”。每次 Codex 干完活我先让 gatekeeper 看一遍把明显的问题打回重做再自己人工 review。这比直接人肉检查高效太多。它的 SKILL.md 核心是让它输出“问题清单 建议修改方案 影响范围”而不是直接改代码。直接让 AI 又评审又修改很容易引入新的问题因为它的“判断脑”和“生成脑”切换容易出错。4. 完整实操把一个“用户管理页”拆给 Codex4.1 初始化项目与全局配置我假设你要做一个“用户管理页”新仓库技术栈 React TS Vite Zustand Vitest。第一步先把项目初始化和 AGENTS.md 写好然后再让 Codex 介入。pnpm create vite codex-split-demo --template react-ts cd codex-split-demo pnpm install pnpm add zustand pnpm add -D vitest testing-library/react testing-library/jest-dom然后按第 2 节的内容写好 AGENTS.md。这里的关键是让你的项目从一开始就有“规矩”而不是先让 Codex 自由发挥后面再驯服它。4.2 用 ui-architect 生成页面骨架配置好之后第一条指令我给 ui-architect请使用 ui-architect skill实现“用户管理页”。 需求左侧为筛选区按姓名、状态筛选右侧为用户表格顶部有新增按钮。 要求先输出组件拆分清单再生成代码。Codex 读取 ui-architect 之后会先给出一个类似这样的拆分方案UserManagementPage ├── UserFilterForm姓名输入框、状态下拉 ├── UserTable表格展示、分页、排序 └── CreateUserButton触发新增弹窗随后生成对应组件。这个阶段生成出来的表格里没有真实数据只用 props 接收users和loading。UI 层不关心数据从哪来这正是我想要的。4.3 用 logic-owner 把数据和状态接上页面骨架生成之后让 logic-owner 干活请使用 logic-owner skill为“用户管理页”补齐数据流。 要求封装 useUserList hook处理筛选、分页、排序用 Zustand 管理用户列表状态API 请求放在 src/api/user.ts。它生成的核心 hook 大概长这样示意export function useUserList() { const { list, loading, fetchUsers } useUserStore(); const [keyword, setKeyword] useState(); const [status, setStatus] useStateUserStatus | (); const [page, setPage] useState(1); useEffect(() { fetchUsers({ keyword, status, page }); }, [keyword, status, page]); return { list, loading, keyword, setKeyword, status, setStatus, page, setPage }; }有了这个 hookui-architect 之前写的占位 props 就能改成真实的数据流。此时再让 ui-architect “小改”一下页面把 props 替换成 hook 返回值就能把两端接起来了。注意这里我给的是两次独立调用而不是让一次对话连续完成所有事这样 Codex 在每一阶段都保持清晰上下文。4.4 用 test-suite 补测试页面和数据流都通了接下来让 test-suite 写测试请使用 test-suite skill为 UserManagementPage 和相关 hooks 编写测试。 要求覆盖筛选交互、分页、空状态、加载状态用 Testing Library 模拟用户操作。Codex 会生成类似这样的测试describe(UserManagementPage, () { it(输入姓名关键字后表格只展示匹配用户, async () { render(UserManagementPage /); fireEvent.change(screen.getByPlaceholderText(请输入姓名), { target: { value: 张三 }, }); expect(await screen.findByText(张三)).toBeInTheDocument(); expect(screen.queryByText(李四)).not.toBeInTheDocument(); }); });如果测试跑不过我一般不会让 test-suite 去改业务代码而是把失败信息反馈给 logic-owner 或者 ui-architect让他们改完再回来跑测试。这两组的边界必须分清楚不然 test-suite 一会儿改测试、一会儿改实现最后你都不知道代码为什么变绿。4.5 用 build-pipeline 做交付前验证最后一步让 build-pipeline 收尾请使用 build-pipeline skill执行完整的交付前检查typecheck、lint、build、测试并输出结论和产物信息。Codex 会执行命令并汇报结果。如果中间有失败就根据报错内容打回给对应 skill 修复。等这一轮全绿代码才能算“完成”。现实里很多 AI 生成的代码就是死在构建这一步——组件导出来是undefined、类型对不上、CSS Modules 的interface没导出这些都要靠构建验证兜住。4.6 用 gatekeeper 做最后评审构建通过不代表代码质量 OK。我最后会让 gatekeeper 看一下整体 diff请使用 gatekeeper skill评审本次“用户管理页”的全部改动。 重点关注类型安全、重复代码、组件复杂度、props 传递合理性、是否有不必要的依赖。 输出格式问题清单按严重程度排序 每条的修改建议。这一轮经常能抓出一些“能跑但不优雅”的问题比如列表 key 用了 index、hooks 里塞了多个不相干功能、any偷偷出现。没过 gatekeeper 的代码我会让对应 skill 修完再走一遍构建验证。5. 常见问题与排查技巧实录5.1 Codex 调用时本地通道报错、provider 校验不过这是我自己用 Codex 时遇到过比较烦的问题调用到一半客户端直接报一段codex endpoint /responses相关的错误后面跟着provider字样任务中断。第一次遇到还以为是网络不稳定重启了好几回后来才发现是本地服务通道状态的锅。排查思路一般分三步第一检查本地服务端口是否正常启动有没有被杀掉第二重启客户端让配置重新加载第三检查 provider 端的 API Key 或 baseUrl 是否写错、是否过期。这里要特别提醒如果你配置了第三方模型服务模型切换后旧会话的连接信息可能失效最稳妥的办法是新起一个会话再继续。5.2 Skills 不生效指令总是被忽略很多人配置了 Skills 但发现 Codex 根本不调用十有八九是 description 写得太泛。比如你写“用于前端开发”那它根本不知道该在什么时候启用相反如果你写“当需要生成页面组件、拆分 UI 结构时使用不要用于数据逻辑”命中率会高很多。另外确认一下文件路径是不是项目根目录下被 Codex 默认扫描到的地方。有时候你放在src/下面或者放错层级工具根本读不到。还有一个常见问题是 SKILL.md 的 frontmatter 格式不标准字段名写错了解析器没法识别。我一直用name / description / when_to_use / when_not_to_use这套结构暂时没出过问题。5.3 上下文溢出和“重复劳动”Codex 在超长对话里会变笨最常见表现是同一个需求反复改、越改越乱。我的应对措施是把任务拆得更小一次会话只处理一个 skill 范围内的一个明确目标。比如“实现用户管理页”这种指令还是太大可以继续拆成“先实现表格组件”“再实现筛选表单”。另外建议每完成一个阶段就做一次 commit。这样即使 Codex 后面改崩了也能快速回退到上一个稳定版本而不是在它的错误思路上反复纠缠。我的经验是Context 省着用Codex 的状态才稳。该开新会话就开新会话不用觉得浪费。5.4 测试组和逻辑组“打架”测试失败的原因经常不是测试写错而是生产代码行为变了。比如 logic-owner 把fetchUsers从“同步返回”改成了“异步加载”导致 test-suite 里原有的断言超时。这时候不要手动改测试掩盖问题正确的流程是看改动是不是预期行为如果是就让 test-suite 按新行为更新测试如果不是就让 logic-owner 修复实现。这套流程走顺之后测试组和逻辑组会形成一种“你写实现、我补断言”的良性循环前提是别让两边跨边界改代码。5.5 构建环境差异本地构建过了CI 却挂了这种问题在 AI 生成代码的项目里特别常见。原因多半是 CI 环境的 Node 版本、包管理器版本和本机不一致或者某个依赖是 AI 自动加的、你没手动确认结果锁文件和 package.json 对不上。build-pipeline的检查清单里建议加一条检查 Node 版本声明、检查packageManager字段、确认 pnpm-lock.yaml 已提交。这些小细节能省掉大量“本地能跑、线上必挂”的尴尬时刻。6. 最后分享一点我自己的实践体会这套五组 Skills 的流程跑下来我最明显的感觉是Codex 从“一个容易上头的大聪明”变成了“一个可以按节奏协作的同事”。它不再一口气给你整一堆看似完整、实则脆弱的代码而是每一步都给出边界清晰、可校验的产物。我踩过几次坑之后已经习惯了这种节奏UI 出来后先看结构逻辑接完先试用测试写完先跑一遍构建全绿才合代码——每一步都有验证节点每一步翻车都在可控范围内。如果你现在的项目还没用过 Skills我建议不要一上来就配五组太重的体系反而让你不想维护。先把test-suite或build-pipeline单独拎出来用感受一下“边界如何约束 AI 发挥”再逐渐把页面、逻辑、评审各组补齐。等你真的习惯了这种“拆开来干活”的方式你会发现 Codex 写前端的上限比自己瞎指挥高不少而你作为开发者也终于能把精力放在真正需要判断力的事情上而不是追着它的烂摊子到处救火。 
