Codex 进阶使用笔记

Codex 最适合放在真实仓库里做工程任务：读代码、改文件、跑检查、解释构建失败、做 review。不要把任务写成“帮我优化一下”，要给它目标、范围和验证方式。

我主要用它做什么

改 Astro / React / Node 项目里的具体文件
查清楚页面、组件、数据源之间的关系
写小脚本，例如抓取公开数据并落到 JSON
做代码审查，找构建风险、移动端溢出、数据源重复
根据 AGENTS.md 遵守项目规则

不建议直接交给它的任务：大范围重构、没有验收标准的视觉优化、需要删除大量文件的操作、网络不稳定但没有失败兜底的脚本。

启动前先让它读项目

在项目根目录运行：

codex

第一次不要急着让它改代码，可以先这样问：

先阅读 AGENTS.md、package.json、src/pages、src/components、src/styles。
不要改代码。
总结项目结构、路由、数据来源、构建命令和不能碰的目录。

如果只查一个问题：

只分析首页样式。
重点看 src/pages/index.astro、src/components/cards、src/styles。
不要修改，列出最值得改的 5 个点。

把仓库规则写进 AGENTS.md

AGENTS.md 应该写能执行的规则，不要写口号。这个博客里最重要的规则是：

不编辑 dist/、.astro/、node_modules/
内容优先改 site.config.ts、主题配置、状态配置、Markdown
UI 改动后要跑 npm run check 和 npm run build
新文章必须符合 src/content/config.ts 的 schema
不要乱改 overflow 和 grid 的 min-width: 0

给 Codex 的任务里也可以重复关键边界：

目标：更新 Codex 和 Claude 两篇文章。

范围：
- src/content/posts/tech/codex-advanced-notes.md
- src/content/posts/tech/claude-advanced-notes.md

约束：
- 不改组件和样式
- 不新增依赖
- 保留 frontmatter
- 内容要短，偏实战

验证：
- npm run check
- npm run build

我常用的提示词模板

改代码：

目标：[具体要做什么]

范围：[允许修改的文件]

约束：
- 遵守 AGENTS.md
- 不改 dist/.astro/node_modules
- 不新增依赖，除非先说明原因

验证：
- npm run check
- npm run build

输出：
- 改了哪些文件
- 验证是否通过
- 还有什么风险

做 review：

review 当前改动。
不要总结优点。
只列 bug、回归风险、缺失验证和需要人工确认的点。
按严重程度排序，带文件路径和行号。

写脚本：

新增 scripts/fetch-ai-rankings.mjs。
要求：
- Node 18+ 原生 fetch
- 不引入依赖
- 失败时写入 error 字段
- 不让 Astro build 因接口失败而中断
验证：
- node --check scripts/fetch-ai-rankings.mjs
- npm run build

几个实用习惯

先缩小范围。比如“只改 src/pages/ai.astro，不要碰别的文件”，效果通常比“优化 AI 页面”稳定。

让它先解释错误。构建失败时可以说：

先解释 npm run build 的错误原因。
不要继续改代码，直到你指出具体失败文件和修复方案。

把验证写进任务。Codex 会跑命令，但前提是你告诉它什么算完成。

参考资料

OpenAI Codex CLI：https://developers.openai.com/codex/cli
Codex AGENTS.md：https://github.com/openai/codex/blob/main/docs/agents_md.md
Codex 配置文档：https://github.com/openai/codex/blob/main/docs/config.md