Advanced Codex CLI Playbook: Layered AGENTS.md + config.toml + Research-to-Ship Workflow

Codex CLI 不只是能跑指令的聊天框。把上下文分層、把審批與沙箱設好、把每個任務跑成「先研究再計畫再執行再審查再上線」——讓代理可控、可重現、敢放手。MIT 授權。

[ Log in to see the full prompt ]

**What it is / what problem it solves** Telling OpenAI Codex CLI to just 'build this feature' often produces runaway results: it edits files carelessly, runs dangerous commands, or produces code that doesn't match team conventions. This playbook upgrades Codex CLI from improvised 'vibe coding' into a controllable, reproducible engineering-agent process — built on three things: writing project context into a layered AGENTS.md, managing approvals and sandboxing via .codex/config.toml, and running every task through one fixed workflow (Research → Plan → Execute → Review → Ship). **Why this source is worth using** shanraisshan/codex-cli-best-practice (MIT licensed) is one of the few repos that systematically organizes real-world Codex CLI practice: it compiles 50+ community tips and compares six mainstream agent workflows side by side (Superpowers, Spec Kit, gstack, Get Shit Done, oh-my-codex, Compound Engineering), distilling their common skeleton down to Research→Plan→Execute→Review→Ship. It also covers Codex's advanced mechanisms: subagents (purpose-built specialized agents rather than one generic role), skills (reusable, progressively-disclosed instruction packages), MCP server integration for external tools, hooks (shell scripts for logging / security scanning / validation), and memories (learning across sessions). This content has been rewritten and reorganized, not copied verbatim. **How to use it (key points)** 1. **Layered AGENTS.md**: keep a lean one at the root (in practice, roughly under 150 lines, hard-capped at 32 KiB) that clearly states setup / build / test commands — anyone should be able to read it and immediately run the tests. Don't put personal preferences into the team version; use an `AGENTS.override.md` instead. Keep the codebase clean (unfinished framework migrations mislead the model). 2. **.codex/config.toml**: set `approval_policy` (on-request by default / never / always), `sandbox_mode` (workspace-write + on-request is recommended), use profiles to switch between security levels (e.g. conservative / trusted), and optionally specify the model. 3. **Starlark command gating**: use `prefix_rule()` to classify command prefixes into allow / prompt / forbidden, and test rules with `codex execpolicy check`. 4. **Run the workflow**: for every task, follow Research (agentic search: glob + grep beats RAG for finding code) → Plan (use /plan to break down steps) → Execute → Review (have a second Codex or Claude Code review it like a senior engineer) → Ship. **When to use it** When you want Codex CLI to handle larger tasks autonomously while still being controllable and producing trustworthy output. Especially suited to team collaboration and situations where you want 'how to run this project' codified once and for all. 📎 Source: shanraisshan/codex-cli-best-practice (by shanraisshan, MIT licensed) — this piece is a rewritten and reorganized version; see the link above for the full tip list and workflow comparisons.