codex-loop

codex-loop 是一个可复用的 Codex 项目框架。它的目标不是写一次提示词，而是让一个长期项目在很多次 Codex 会话之后，仍然保留清晰的上下文、计划、决策、经验和交接入口。

它把容易丢失的聊天上下文沉淀为项目文件：

• AGENTS.md：Codex 每次进入项目时读取的长期规则入口。
• .agent/PLANS.md：复杂任务的执行计划标准。
• .codex-loop/*.md：项目长期记忆层。
• .agents/skills/*/SKILL.md：项目内可复用工作流。
• .agents/skills/prompt-refinement/SKILL.md：把用户原始需求转成更清晰的任务 brief、关键问题和执行计划。

快速使用

在任意目标项目里，可以直接把下面这段发给 Codex：

请把 https://github.com/lcq666666/codex-loop.git 的框架应用到当前项目。
要求：
1. 先读取该仓库的 README.md、docs/methodology.md 和 templates/。
2. 不要覆盖当前项目已有的 AGENTS.md 或同名长期记忆文件。
3. 如果已有文件冲突，请合并成项目专属规则，并说明合并点。
4. 初始化或更新 .codex-loop/PROJECT.md，写清项目主题、目标用户、当前阶段和成功标准。
5. 最后给出本次迁移摘要和后续建议。

也可以手动安装。

PowerShell：

git clone https://github.com/lcq666666/codex-loop.git
cd codex-loop
.\scripts\apply-codex-loop.ps1 -TargetPath C:\path\to\your-project

macOS/Linux：

git clone https://github.com/lcq666666/codex-loop.git
cd codex-loop
./scripts/apply-codex-loop.sh /path/to/your-project

安装脚本会把 templates/ 复制到目标项目。它不会覆盖已有文件；如果目标项目已经存在同名文件，会在目标项目生成 .codex-loop-merge-notes.md，提示需要手动合并的文件。

Codex 插件

本仓库已经包含可安装的 Codex 插件打包结构：

• 插件入口：.agents/plugins/plugins/codex-loop/
• Marketplace：.agents/plugins/marketplace.json
• 插件 manifest：.agents/plugins/plugins/codex-loop/.codex-plugin/plugin.json

插件包含以下能力：

• codex-loop-apply：把 codex-loop 应用到目标项目，并保持非覆盖安装语义。
• codex-loop-kickoff：初始化或刷新项目长期记忆。
• codex-loop-prompt-refinement：按需把原始 prompt 拆成目标、上下文、约束、完成条件，并先补齐关键问题。
• codex-loop-review：基于事实、风险和验证结果做阶段复盘。
• codex-loop-handoff：结束会话前更新任务、决策、经验和研究记录。
• assets/templates/：随插件分发的模板副本。
• scripts/apply-codex-loop.*：随插件分发的安装脚本。

本机个人插件可放在：

%USERPROFILE%\plugins\codex-loop
%USERPROFILE%\.agents\plugins\marketplace.json

安装后会添加什么

• AGENTS.md：项目级 Codex 入口和长期规则。
• .agent/PLANS.md：复杂任务计划模板。
• .codex-loop/PROJECT.md：项目使命、受众、阶段、成功标准。
• .codex-loop/TASKS.md：当前任务、阻塞、下一次会话入口。
• .codex-loop/DECISIONS.md：重要决策和原因。
• .codex-loop/LESSONS.md：反复踩坑后的长期规则。
• .codex-loop/RESEARCH.md：来源、证据、实验和结论。
• .agents/skills/*/SKILL.md：可复用的 Codex 工作流。

核心方法

把 Codex 当作循环系统使用，而不是一次性问答：

1. 每次会话先读取项目长期文件。
2. 任务输入尽量包含 Goal、Context、Constraints、Done when。
3. 用户开启 prompt-refinement 时，先把原始需求整理成专业 brief，必要时反问 1-3 个关键问题。
4. 复杂任务先写或更新执行计划。
5. 重要工作结束后更新项目记忆。
6. 重复出现且稳定的流程沉淀为 skill。
7. 依赖外部事实时使用 MCP、连接器或明确来源文件，不让 Codex 猜。
8. 只有稳定、重复、可验证的流程才适合自动化。

更多说明见：

• docs/methodology.md
• docs/prompts.md

方向分支

除了 main 的通用框架版，仓库还维护两个针对性方向分支：

• direction/development-tasks：面向软件开发任务，增加开发任务工作流。
• direction/research-tasks：面向科研项目，强化研究问题、假设、证据、实验和结论记录。

如果只需要通用项目记忆和交接框架，使用 main。如果目标项目明显偏工程开发或长期科研，可以从对应方向分支安装模板。

维护规则

这个仓库是模板框架，不是具体应用。维护时请遵守：

• 保持通用，不写入某个私有项目的假设。
• 文档和模板一起更新。
• 安装脚本必须保持非覆盖行为。
• 复杂任务仍通过 .agent/PLANS.md。
• 长期记忆仍通过 .codex-loop/*.md。
• 重复且稳定的流程优先沉淀为 .agents/skills/*/SKILL.md。
• 模板要足够简洁，保证 Codex 启动时真的会读。

参考

• OpenAI Codex best practices: https://developers.openai.com/codex/learn/best-practices
• OpenAI Codex customization: https://developers.openai.com/codex/concepts/customization
• OpenAI execution plans cookbook: https://developers.openai.com/cookbook/articles/codex_exec_plans
• 53AI Codex usage article: https://www.53ai.com/news/tishicijiqiao/2026062656813.html

License

MIT