codex-plan

Codex 计划技能

你需要使用 Codex 制定一份详细的实施计划。你的任务是：

1. 理解用户的规划请求（如下方的 ARGUMENTS: 所示）
2. 使用 AskUserQuestion 提出澄清问题
3. 为 Codex 撰写一份出色、详细的提示词
4. 执行 Codex 以生成并保存计划

始终使用： gpt-5.4，并采用 xhigh 推理 输出： 当前目录中的 codex-plan.md

---

第 1 步：分析请求

用户的规划请求位于本指令末尾，格式为 ARGUMENTS: <request>。

请明确：

• 核心目标是什么？
• 涉及哪些技术／领域？
• 哪些方面含糊不清或说明不足？
• 哪些决策会对计划产生重大影响？

快速通道（简单任务）

如果任务极其简单——仅涉及单个文件的配置更改、拼写错误修正、影响文件少于 2 个，且没有架构决策——跳过 Codex。直接自行按照简化结构编写 codex-plan.md：

# Plan: [Task Name]
**Generated**: [Date]
**Estimated Complexity**: Low
## Overview
[1-2 sentences]
## Task
- **Location**: [file path]
- **Description**: [what to do]
- **Acceptance Criteria**: [testable criteria]

即使走快速通道，仍须在编写计划前至少提出 1 个澄清问题（第 2 步）。编写完成后，跳到第 6 步（验证输出）。

---

第 2 步：提出澄清问题（必需）

生成计划前，使用 AskUserQuestion 工具提出 1-5 个有针对性的问题。

先评估任务的模糊程度：

• 简单／明确的任务（范围清晰、方案显而易见）→ 提出 1-2 个问题
• 复杂／含糊的任务（存在多种方案、需求不明确）→ 提出 3-5 个问题
• 绝不能为 0——始终至少提出 1 个问题以确认理解

好的澄清问题应：

• 缩小范围并明确需求
• 澄清技术选择
• 了解约束条件（时间、预算、团队规模）
• 区分必需项与可选项
• 发现集成需求
• 确定安全／合规需求

示例问题模式

对于“实现身份验证”：

• 需要哪些身份验证方式？（邮箱／密码、OAuth、SSO、免密链接）
• 需要 RBAC，还是只区分已认证与未认证用户？
• 后端技术栈是什么？（Node/Express、Python/Django 等）
• 会话存储方式是什么？（数据库、Redis、无状态 JWT）
• 需要哪些功能？（密码重置、邮箱验证、双重身份验证）
• 有哪些合规要求？（SOC2、GDPR、HIPAA）

对于“构建 API”：

• 需要管理哪些资源／实体？
• 使用 REST 还是 GraphQL？
• 使用哪种身份验证方式？
• 预计规模／流量如何？
• 是否需要速率限制、缓存和版本控制？

对于“修复错误”：

• 如何稳定复现？（步骤、环境、发生频率）
• 预期行为与实际行为是什么？
• 是否有相关测试覆盖？（哪些现有测试本应发现此问题）
• 受影响的平台／浏览器／环境有哪些？

对于“重构”：

• 是否必须保持外部 API／接口兼容？
• 是否有现成的测试覆盖可供依赖？
• 有哪些性能约束？（不得出现性能退化）
• 采用渐进式还是一次性重构？（能否分阶段合并）

对于“基础设施／DevOps”：

• 目标环境是什么？（本地、预发布、生产）
• 是否已有 CI/CD 流水线？
• 如何管理密钥？
• 回滚要求是什么？（蓝绿发布、金丝雀发布、即时回滚）

---

第 3 步：定位目标文件

你是产品经理和文件定位者。你的任务是找到相关文件，而不是规划实施方案。

获得答复后，找出：

• 入口点：主文件、命令行入口、路由处理程序
• 待修改文件：任务会涉及的具体文件
• 关键导入项／依赖项：这些文件所依赖的模块
• 现有模式：命名约定、错误处理风格、架构

为 Codex 提示词生成 ## Target Files 列表：

## Target Files to Read
- `src/auth/login.ts` — current login handler, will be modified
- `src/middleware/session.ts` — session middleware, imports from login
- `src/types/user.ts` — User type definition, dependency

不要总结文件内容——只列出路径，并用一行说明其用途。Codex 会通过 <context_loading> 完整读取这些文件。

---

第 4 步：编写 Codex 提示词

创建一段详细的提示词，其中包括：

1. 明确的目标 — 需要创建什么计划
2. 所有要求 — 从澄清问题中了解到的所有内容
3. 约束条件 — 技术选型、时间线、团队规模
4. 目标文件 — 第 3 步中的文件路径列表
5. 计划结构 — 从 references/plan-template.md 中读取并插入完整内容
6. 输出说明 — 写入当前目录中的 codex-plan.md

重要： 告诉 Codex 不要提出任何澄清问题——它已掌握所需的全部信息，只需编写计划并保存文件。

自适应模板： 对于轻微或琐碎的任务，告诉 Codex 必须省略不相关的部分（阶段、E2E 测试、回滚），也可以改为输出扁平的任务列表，以符合 <output_verbosity_spec>。

Codex 提示词示例

Create a detailed implementation plan for [TASK DESCRIPTION].

## Requirements
- [Requirement 1 from clarifying questions]
- [Requirement 2]
- [Requirement 3]
- NOT needed: [Things explicitly excluded]

## Target Files to Read
- `[path/to/file1]` — [one-line purpose]
- `[path/to/file2]` — [one-line purpose]
- `[path/to/file3]` — [one-line purpose]

## Plan Structure

Read and follow the exact template structure from `references/plan-template.md`.

Adapt the template to task complexity:
- For minor tasks, OMIT irrelevant sections (e.g., multiple Phases, E2E Tests, Rollback) and use a flat task list instead.
- For complex tasks, use the full phased structure with all sections.

## Behavioral Constraints

<output_verbosity_spec>
- Default: 3-6 sentences or <=5 bullets for typical answers.
- Simple yes/no questions: <=2 sentences.
- Complex multi-step or multi-file tasks:
  - 1 short overview paragraph
  - then <=5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.
- Avoid long narrative paragraphs; prefer compact bullets and short sections.
- Do not rephrase the user's request unless it changes semantics.
</output_verbosity_spec>

<design_and_scope_constraints>
- Implement EXACTLY and ONLY what the user requests.
- No extra features, no added components, no UX embellishments.
- Style aligned to the design system at hand.
- Do NOT invent colors, shadows, tokens, animations, or new UI elements unless requested or necessary.
- If any instruction is ambiguous, choose the simplest valid interpretation.
</design_and_scope_constraints>

<context_loading>
- Start by reading ALL files listed in "Target Files to Read" — in full, not just the sections mentioned in the task.
- Then expand to key files they import from or that depend on them.
- Absorb surrounding patterns, naming conventions, error handling style, and architecture before writing any code.
- Do not ask clarifying questions about things that are answerable by reading the codebase.
</context_loading>

## Instructions
- Write the complete plan to a file called `codex-plan.md` in the current directory
- Do NOT ask any clarifying questions - you have all the information needed
- Be specific and actionable - include code snippets where helpful
- Follow test-driven development: specify what tests to write BEFORE implementation
- Identify task dependencies so parallel work is possible
- Just write the plan and save the file

Begin immediately.

---

第 5 步：执行 Codex（必需）

使用你编写的提示词运行此确切命令：

codex exec --full-auto --skip-git-repo-check \
  -c model=gpt-5.4 \
  -c model_reasoning_effort=xhigh \
  -c model_reasoning_summary=concise \
  --output-last-message /tmp/codex-plan-result.txt \
  "YOUR_CRAFTED_PROMPT_HERE"

然后显示结果：

cat /tmp/codex-plan-result.txt

---

第 6 步：验证输出（必需）

Codex 完成后（或在快速路径中自行编写计划后）：

1. 读取生成的 codex-plan.md
2. 检查结构：文件存在、Markdown 有效，且至少包含：
   • # Plan: 标题
   • ## Overview 小节
   • 至少一个 ### Task 条目
3. 如果检查失败，或 codex exec 返回错误/超时：
   • 调整提示词（简化要求、消除歧义）
   • 重试执行一次
4. 如果重试仍然失败：向用户显示错误并说明出了什么问题
5. 如果检查通过：向用户显示计划结果

---

重要规则

1. 始终至少提出 1 个澄清问题 — 不要跳过第 2 步（根据复杂度提出 1–5 个问题）
2. 始终使用 gpt-5.4 和 xhigh 推理 — 快速路径除外
3. 始终告诉 Codex 不要提问 — 它应该直接执行
4. 始终使用 --full-auto 标志
5. 始终在第 6 步验证输出 — 检查结构，失败时重试一次
6. 输出文件：当前工作目录中的 codex-plan.md

---

现在开始执行

用户的规划请求显示在下方的 ARGUMENTS: 中。请分析并从第 1 步开始。