LazyCodex 怎么用：Codex 项目记忆、规划和验收闭环

改动一个跨十几个文件的功能，Codex 报了“完成”，你信了，上线才发现漏了一个异常分支处理。这类问题在复杂代码库里很常见：每次开新对话，agent 都要重新理解项目；模型改动完只报告“做了什么”，不会主动告诉你边角逻辑有没有遗漏。

LazyCodex 是把 OmO（oh-my-openagent）中适合 Codex 的能力打包成轻量发行版的 agent harness，专注解决项目记忆、工作规划和验收闭环。读完本文，你会知道 $init-deep、$ulw-plan、$start-work、$ulw-loop 怎么配合，分层 AGENTS.md 如何帮大仓库建立上下文，以及即使不装这套工具也能借鉴哪些工程思路。

LazyCodex 是什么：OmO 面向 Codex 的轻量发行层

LazyCodex 可以类比成 LazyVim 之于 Neovim：核心能力来自 oh-my-openagent（OmO），LazyCodex 是面向 Codex 的发行层，把适合 Codex 插件系统的部分装进现有环境。项目在 GitHub 上开源并采用 MIT 许可证；截至 2026 年 7 月，官方把它称为 OmO 的 Codex Light 版，而不是 OmO Ultimate 的完整移植。

裸用 Codex 和 LazyCodex 的核心区别

问题维度	裸用 Codex	LazyCodex（Codex Light）
项目记忆	上下文主要靠当前仓库说明和会话；没有现成的深度初始化流程	$init-deep 生成分层 AGENTS.md，让复杂目录有局部指引
完成判定	是否主动做边界验证取决于任务说明和当前执行习惯	$start-work 的五道证据门与 $ulw-loop 的 oracle 验证把完成标准显式化
流程纪律	可以直接编辑，也可以由用户自行约束先规划再执行	$ulw-plan 只规划，$start-work 执行计划，$ulw-loop 做证据闭环
持久化	依赖 Codex 会话和项目文件保存上下文	.omo/boulder.json 保存计划执行状态，Stop hook 可继续推进未完成工作
工具层	使用 Codex 当前提供的 skills、MCP 和并行能力	额外安装 OmO 的 rules、hooks、skills、LSP、AST 搜索和模型路由配置

这套 harness 不改变 Codex 的核心模型能力，而是把“怎么用”规范化：先建立项目记忆，再规划、执行，最后按证据验收。需要注意的是，OmO Ultimate 的完整纪律 agent 编排和 team_* 工具不属于 Codex Light；LazyCodex 的并行任务能力要建立在 Codex 当前可用的 subagent 或 team surface 上。

安装：一行 npx，不做全局安装

LazyCodex 的官方主安装路径始终使用 npx，不需要 npm i -g：

# 标准安装
npx lazycodex-ai install

# 等价命令（直接指定 OmO 包和 Codex 平台）
npx --yes --package oh-my-openagent omo install --platform=codex

# 全自动模式（无交互，并显式开启自主权限配置）
npx lazycodex-ai install --no-tui --codex-autonomous

# 安装后检查
npx lazycodex-ai doctor

安装器会写入 Codex 插件缓存和相关配置。标准交互安装会询问是否配置自主权限；--codex-autonomous 会改变权限配置，因此只应在你理解本机安全边界时启用。安装或升级后还要在 Codex 启动审查中批准 OmO hooks，并重开会话加载新插件。

安装完成后，先记住四个核心命令：

1. $init-deep：生成分层 AGENTS.md
2. $ulw-plan：把需求转成待批准的决策完备计划
3. $start-work：执行计划并保存持久化进度
4. $ulw-loop：围绕单一任务持续执行和验证

如果你想先检查安装内容，可以运行 npx lazycodex-ai doctor，或阅读 LazyCodex 官方 README 和 官方文档。

项目记忆：用 $init-deep 生成分层 AGENTS.md

大仓库的典型问题是：你没法靠一次对话把项目讲清楚。一个仓库如果有几百个文件、十几个模块，agent 开新对话后要么重新探索一遍，要么在缺少局部约束时改错位置。

$init-deep 用来给大仓库建立“地标”。它会：

1. 遍历仓库并读取决定项目真实工作方式的文件
2. 在根目录和复杂子目录生成分层 AGENTS.md
3. 把局部指引放在最接近相关代码的位置
4. 让后续 agent 在编辑前先读取适用范围内的规则

为什么分层重要：局部指引应该写在最需要它的代码旁，而不是全部塞进根目录。agent 进入某个模块时，能直接看到该目录适用的规则，不必从一份巨大的总说明里筛选。

这个思路和站内文章 Agent 记忆系统设计 里讲的长期记忆架构并不完全相同：AGENTS.md 更接近版本化的项目上下文，而不是自动召回的对话记忆。不过两者都强调分层、局部上下文和持久化。它也类似 用一个配置文件约束 Claude 中 CLAUDE.md 的作用——让 AI 动手前先读规则。

生成的 AGENTS.md 是普通 Markdown，必须由人复核。代码库重构、目录职责改变或命令更新后，应重新运行 $init-deep 或手动维护，不能把自动生成内容当成永久正确的事实源。

四个命令：记忆、规划、执行、验证各管一段

LazyCodex 的核心流程分为四段：先初始化项目记忆，再规划、执行，最后验证。真正处理一项开发任务时，后三个命令构成规划—执行—验证闭环。

$ulw-plan：只产出待批准计划

$ulw-plan "what to build"

这个命令只做规划，不写产品代码。流程包括：

1. 通过访谈澄清需求，不把模糊表述直接当成实现规格
2. 探索代码库，并把独立的检索任务分给并行 subagent
3. 分析现状与目标之间的缺口
4. 把计划写入 plans/<slug>.md，记录引用、验收标准、QA 方案和提交边界
5. 标记 status: awaiting-approval，等待用户批准

关键约束是规划阶段不执行产品改动。先把范围和验收标准讲清楚，再把计划交给执行阶段。站内文章 用 Subagent 拆任务 介绍了相近的任务拆分思想，但 LazyCodex 会把它嵌入计划工作流。

$start-work：持久化执行计划

$start-work [plan-name] [--worktree <absolute-path>]

这个命令执行已批准计划，直到顶层 checkbox 全部完成。关键特性包括：

1. 持久化 Boulder 状态：.omo/boulder.json 让执行进度跨 turn 和 session 存活
2. Stop hook：计划未完成时重新注入下一轮工作
3. 并行 subagent：独立子任务可以扇出执行，具体并行能力取决于当前 Codex surface
4. 严格 TDD 与五道证据门：计划复读、自动验证、人工 QA、对抗 QA、清理
5. 进度账本：保存执行过程和 checkbox 状态

全部完成时会打印 ORCHESTRATION COMPLETE。这个信号代表工作流宣称所有 checkbox 和证据门已完成，但仍应查看实际测试、人工 QA 和变更证据，而不是只相信一行状态文本。

$ulw-loop：围绕单一任务持续验证

$ulw-loop "task" [--completion-promise=TEXT] [--strategy=reset|continue]

这个命令适合范围已经清楚、但需要持续执行到证据验证通过的单一任务。它不会替你先做完整规划；模糊任务应先运行 $ulw-plan。

• 迭代上限：ultrawork 模式最多 500 次，普通模式最多 100 次
• 策略选择：reset 每次重置循环上下文，continue 延续现有状态
• completion promise：明确写出要收集的证据、必须通过的验证和缺失信息的处理方式
• 停止条件：由 oracle 根据证据判断是否满足完成承诺

迭代次数不是质量保证。完成标准写得含糊，循环只会更快地重复含糊判断。真正关键的是把测试、边界条件、人工 QA 和失败处置写进 completion promise。

验收为什么对复杂代码库重要

复杂代码库的典型风险是：改动跨十几个文件，主路径已经跑通，但异常分支、调用方、配置或文档没有同步。这不是单纯的模型能力问题，而是完成判定里缺少明确证据。

模型容易漏边角的场景：

改动类型	容易漏的地方
改了主流程	网络失败、参数校验、权限不足等异常分支
新增接口	仍使用旧签名的调用方和测试替身
重构模块	测试、配置、文档和生成产物
删除功能	依赖入口、埋点、日志和迁移兼容层

LazyCodex 的增量不在于保证“绝不遗漏”，而在于把检查动作固定进工作流。五道证据门要求重新读计划、跑自动验证、做人工 QA、做对抗检查并清理遗留；$ulw-loop 则让单一任务持续运行到约定证据满足。它把“模型自报完成”变成“按预先定义的证据判断完成”。

证据门仍然需要项目自己的事实源和高质量验收标准。例如接口签名变化要查所有调用方，删除功能要查依赖入口，UI 改动需要真实交互而不只是单元测试。harness 提供流程约束，但不会自动知道你的业务风险。

OmO 纪律 agent 与 LazyCodex skills 层

LazyCodex 来自 OmO，但两者的能力范围要分开看。OmO Ultimate 提供完整的纪律 agent 编排；Codex Light 只携带能适配 Codex 插件系统的组件，并利用 Codex 自身的 agent surface。

纪律 agent：属于 OmO Ultimate 的完整编排

agent 名称	职责	LazyCodex Light 边界
Sisyphus	编排者，调度执行和验证工作	角色配置可能可见，但 Light 不提供 OmO Ultimate 的完整 agent orchestration
Hephaestus	执行者，写代码改文件	独立任务由当前 Codex 可用的 subagent 能力承接
Oracle	验证者，按证据判定完成	$ulw-loop 保留证据验证习惯，但不等于拥有 Ultimate 全部编排工具
Librarian	记录和检索上下文	项目记忆主要通过 $init-deep 与分层 AGENTS.md 落地

因此，不能把 OmO Ultimate 的 Team Mode、完整纪律 agent 团队或 team_* 工具直接算成 LazyCodex Light 的内建能力。你实际能否并行创建团队成员，还取决于当前 Codex App 或 CLI 提供的功能。

skills 层：把专业判断下沉到可复用工作流

LazyCodex 会安装一组 skills 和组件。当前官方文档列出的代表性能力包括：

skill 或组件	用途
review-work	多通道复审实现结果
remove-ai-slops	保持行为不变地清理模板化 AI 痕迹
frontend	前端设计和 UI 实现约束
LSP	诊断、定义、引用和符号级操作
AST-grep	按语法结构搜索和改写代码
rules / comment-checker	项目规则加载和注释质量检查
git-bash	为需要 Bash 语义的环境提供兼容工具

这和站内文章 Claude 的 Skill 功能 中的设计思路类似：命令负责流程，skill 承载具体领域判断。具体 skill 名单会随版本变化，安装后应在 Codex 的 $ 菜单或 doctor 输出中查看当前实际状态。

多模型路由：按任务风险分配推理资源

LazyCodex 会配置模型路由，让不同角色或任务使用合适的模型和 reasoning level。它的目的不是保证省 token；官方文档反而明确提醒，LazyCodex 会为规划、执行和验证投入足够的模型与上下文。

更稳妥的使用原则是：

• 日常任务用中等推理强度
• 失败成本高、需要复审的任务提高推理强度
• 只有真正重的任务才使用最高推理档
• 长任务先拆分范围，避免一个 thread 被过多上下文压垮

具体模型名称和路由矩阵会变化，应以安装时的当前配置为准。不要把 README 中某个时间点的型号写进长期流程，也不要把“多模型路由”简单等同于“必然节省配额”。

不装这套工具，也能借鉴的 4 个工程思路

即使你不装 LazyCodex，它背后的四个工程思路也可以迁移到其他 agent 工作流里。

思路 1：给大仓库写分层上下文文件

LazyCodex 用 $init-deep 生成 AGENTS.md，本质是给大仓库建立版本化的分层上下文。你可以直接照搬：

• 给复杂目录写局部指引，不把所有规则堆在根目录
• 让 agent 进入目录时就看到适用规则
• 代码库结构或流程改变后同步更新
• 生成内容必须复核，不让陈旧说明成为新的错误来源

最小形态是一份根 AGENTS.md 加少量关键子目录 AGENTS.md。站内文章 用一个配置文件约束 Claude 给出了类似做法。

思路 2：规划和执行分离

先让 agent 写一份 decision-complete 计划，包含范围、依赖、验收标准、QA 和提交边界；批准后再执行。关键不是一定使用 plans/*.md，而是计划阶段不悄悄开始产品改动。

思路 3：完成必须绑定证据

为多文件改动建立检查清单：接口变化查调用方，功能删除查入口，UI 变更做真实交互，数据迁移查回滚。让“完成”绑定具体测试、人工 QA 和边界证据，而不是一段总结。

思路 4：按任务风险分配模型和上下文

简单查询不需要最高推理档；架构变更、迁移和发布门禁需要更强推理和复审。长任务还要主动拆分，不能只靠增加 token budget。

最小可照搬形态

如果不想安装整套 harness，至少保留两份可版本化文件：

1. 一份计划清单，记录决策、步骤、验收标准和未决项
2. 一组分层 AGENTS.md，记录仓库级和目录级规则

再为每类改动配置对应的验证命令与人工 QA 清单，就已经覆盖了 LazyCodex 最容易迁移的核心思路。

它适合谁，不适合谁

LazyCodex 增加了 hooks、状态文件、skills 和工作流约束，不是所有项目都需要。判断是否值得安装，可以看下面这张表。

适用场景判断

场景维度	适合用 LazyCodex	直接用 Codex 更简单
仓库规模	大仓库，目录规则多，改动经常跨文件	小仓库或单文件项目
任务复杂度	需要规划、执行、验证的长任务	一次性小改或简单脚本
上下文问题	新会话经常要重新探索目录和规则	单次会话能完成，已有清晰 AGENTS.md
验收需求	容易漏异常分支，需要证据门和人工 QA	完成条件简单且检查成本低
流程需求	希望计划先审批、执行状态可持久化	希望直接编辑，不需要额外状态层
权限接受度	能审查 hooks、MCP 和自主权限设置	不希望安装额外插件或改变 Codex 配置

收益判断

仓库越大、任务越长、验收越复杂，LazyCodex 的流程约束越可能有价值。典型场景包括跨多文件重构、跨 session 的长任务、需要自动测试加人工 QA 的高风险修改。

它的代价同样明确：你要维护分层上下文，理解 hooks 和权限，接受 .omo/boulder.json 等状态文件，并复核 harness 产生的计划和验证结果。它不是安装后就能消除遗漏的自动保险。

不适合的场景

• 一次性小改：修改一个函数、一个字段或一段文案
• 简单脚本：工作集中在一两个文件，完成条件很清楚
• 已有成熟流程：仓库已经有可靠的 AGENTS.md、计划模板、CI 和人工验收门
• 不接受额外配置：不希望插件、hooks、MCP 或自主权限改变当前 Codex 环境

如果还在犹豫，可以先不装整套工具，先手工补一份分层 AGENTS.md 和证据清单。确认项目确实受困于跨会话上下文、计划执行和验收问题后，再评估 LazyCodex。

结论

复杂代码库使用 Codex 时，真正难的往往不是生成一段代码，而是让新会话快速理解局部规则，并证明跨文件改动没有漏掉关键边界。LazyCodex 把 $init-deep、计划审批、Boulder 状态和证据门组合成一套 Codex Light 工作流。

它值得关注的不是 Sisyphus、Boulder 这些命名，而是三个可验证的工程增量：上下文被写进分层文件，计划和执行有明确边界，完成判断绑定测试与人工 QA。与此同时，要记住 LazyCodex 不等于 OmO Ultimate，完整 agent orchestration 和 Team Mode 不能直接算进 Light 版能力。

下一步可以先运行 npx lazycodex-ai doctor 检查环境，再用 $init-deep 给一个真实大仓库建立上下文；选择一项范围明确的多文件任务，用 $ulw-plan、$start-work 和 $ulw-loop 走完一次闭环。对比直接使用 Codex 时的遗漏、上下文重读和验收成本，才知道这套 harness 是否适合你的项目。