plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan

计划

Overview

概述

Draft structured plans that clarify intent, scope, requirements, action items, testing/validation, and risks.

Optionally, save plans to disk as markdown files with YAML frontmatter and free-form content. When drafting in chat, output only the plan body without frontmatter; add frontmatter only when saving to disk. Only write to the plans folder; do not modify the repository codebase.

This skill can also be used to draft codebase or system overviews.

草拟结构化计划，明确意图、范围、需求、行动项、测试/验证以及风险。

可选择将计划保存为带YAML前置元数据和自由格式内容的Markdown文件。在聊天中草拟计划时，仅输出计划主体，不包含前置元数据；仅在保存到磁盘时添加前置元数据。仅写入plans文件夹；请勿修改仓库代码库。

此技能也可用于草拟代码库或系统概述。

Core rules

核心规则

Resolve the plans directory as
```
$CODEX_HOME/plans
```
or
```
~/.codex/plans
```
when
```
CODEX_HOME
```
is not set.
Create the plans directory if it does not exist.
Never write to the repo; only read files to understand context.
Require frontmatter with only
```
name
```
and
```
description
```
(single-line values) for on-disk plans.
When presenting a draft plan in chat, omit frontmatter and start at
```
# Plan
```
.
Enforce naming rules: short, lower-case, hyphen-delimited; filename must equal
```
<name>.md
```
.
If a plan is not found, state it clearly and offer to create one.
Allow overview-style plans that document flows, architecture, or context without a work checklist.

当未设置
```
CODEX_HOME
```
时，将计划目录解析为
```
$CODEX_HOME/plans
```
或
```
~/.codex/plans
```
。
如果计划目录不存在则创建它。
绝不要写入代码仓库；仅读取文件以了解上下文。
磁盘上的计划必须包含仅包含
```
name
```
和
```
description
```
（单行值）的前置元数据。
在聊天中展示草拟的计划时，省略前置元数据，直接从
```
# 计划
```
开始。
遵循命名规则：简短、小写、连字符分隔；文件名必须等于
```
<name>.md
```
。
如果未找到计划，明确说明并主动提出创建新计划。
允许使用概述风格的计划，记录流程、架构或上下文，无需包含工作检查清单。

Decide the task

任务判定

Find/list: discover plans by frontmatter summary; confirm if multiple matches exist.
Read/use: validate frontmatter; present summary and full contents.
Create: inspect repo read-only; choose plan style (implementation vs overview); draft plan; write to plans directory only.
Update: load plan; revise content and/or description; preserve frontmatter keys; overwrite the plan file.
Delete: confirm intent, then remove the plan file if asked.

查找/列出：通过前置元数据摘要发现计划；确认是否存在多个匹配项。
读取/使用：验证前置元数据；展示摘要和完整内容。
创建：只读模式检查代码仓库；选择计划类型（实现型 vs 概述型）；草拟计划；仅写入计划目录。
更新：加载计划；修订内容和/或描述；保留前置元数据键；覆盖原计划文件。
删除：确认用户意图，然后按要求删除计划文件。

Plan discovery

计划发现

Prefer
```
scripts/list_plans.py
```
for quick summaries.
Use
```
scripts/read_plan_frontmatter.py
```
to validate a specific plan.
If name mismatches filename or frontmatter is missing fields, call it out and ask whether to fix.

优先使用
```
scripts/list_plans.py
```
快速获取摘要。
使用
```
scripts/read_plan_frontmatter.py
```
验证特定计划。
如果名称与文件名不匹配，或前置元数据缺失字段，需指出并询问是否修复。

Plan creation workflow

计划创建流程

Scan context quickly: read README.md and obvious docs (docs/, CONTRIBUTING.md, ARCHITECTURE.md); skim likely touched files; identify constraints (language, frameworks, CI/test commands, deployment).
Ask follow-ups only if blocked: at most 1-2 questions, prefer multiple-choice. If unsure but not blocked, state assumptions and proceed.
Identify scope, constraints, and data model/API implications (or capture existing behavior for an overview).
Draft either an ordered implementation plan or a structured overview plan with diagrams/notes as needed.
Immediately output the plan body only (no frontmatter), then ask the user if they want to 1. Make changes, 2. Implement it, 3. Save it as per plan.
If the user wants to save it, prepend frontmatter and save the plan under the computed plans directory using
```
scripts/create_plan.py
```
.

快速扫描上下文：读取README.md和明显的文档（docs/、CONTRIBUTING.md、ARCHITECTURE.md）；浏览可能涉及的文件；识别约束条件（语言、框架、CI/测试命令、部署方式）。
仅在受阻时提出跟进问题：最多1-2个问题，优先使用选择题。如果不确定但未受阻，说明假设并继续推进。
确定范围、约束条件以及数据模型/API影响（或为概述型计划记录现有行为）。
草拟有序的实现型计划或带图表/注释的结构化概述型计划（如有需要）。
立即仅输出计划主体（不含前置元数据），然后询问用户是否需要：1. 修改计划，2. 执行计划，3. 按计划保存。
如果用户希望保存，添加前置元数据并使用
```
scripts/create_plan.py
```
将计划保存到计算出的计划目录中。

Plan update workflow

计划更新流程

Re-read the plan and related code/docs before updating.
Keep the plan name stable unless the user explicitly wants a rename.
If renaming, update both frontmatter
```
name
```
and filename together.

更新前重新读取计划及相关代码/文档。
保持计划名称稳定，除非用户明确要求重命名。
如果重命名，同时更新前置元数据中的
```
name
```
和文件名。

Scripts (low-freedom helpers)

脚本（低自由度辅助工具）

Create a plan file (body only; frontmatter is written for you). Run from the plan skill directory:

bash

python ./scripts/create_plan.py \
  --name codex-rate-limit-overview \
  --description "Scope and update plan for Codex rate limiting" \
  --body-file /tmp/plan-body.md

Read frontmatter summary for a plan (run from the plan skill directory):

bash

python ./scripts/read_plan_frontmatter.py ~/.codex/plans/codex-rate-limit-overview.md

List plan summaries (optional filter; run from the plan skill directory):

bash

python ./scripts/list_plans.py --query "rate limit"

创建计划文件（仅主体；前置元数据会自动添加）。从计划技能目录运行：

bash

python ./scripts/create_plan.py \
  --name codex-rate-limit-overview \
  --description "Scope and update plan for Codex rate limiting" \
  --body-file /tmp/plan-body.md

读取计划的前置元数据摘要（从计划技能目录运行）：

bash

python ./scripts/read_plan_frontmatter.py ~/.codex/plans/codex-rate-limit-overview.md

列出计划摘要（可选过滤；从计划技能目录运行）：

bash

python ./scripts/list_plans.py --query "rate limit"

Plan file format

计划文件格式

Use one of the structures below for the plan body. When drafting, output only the body (no frontmatter). When saving, prepend this frontmatter:

markdown

---
name: <plan-name>
description: <1-line summary>
---

使用以下结构之一作为计划主体。草拟时仅输出主体（不含前置元数据）。保存时，添加以下前置元数据：

markdown

---
name: <plan-name>
description: <1-line summary>
---

Implementation plan body template

实现型计划主体模板

markdown

undefined

markdown

undefined

Plan

计划

<1-3 sentences: intent, scope, and approach.>

<1-3句话：意图、范围和方法。>

Requirements

需求

<Requirement 1>
<Requirement 2>

<需求1>
<需求2>

Scope

范围

In:
Out:

包含：
排除：

Files and entry points

文件和入口点

<File/module/entry point 1>
<File/module/entry point 2>

<文件/模块/入口点1>
<文件/模块/入口点2>

Data model / API changes

数据模型 / API变更

<If applicable, describe schema or contract changes>

<如适用，描述 schema 或契约变更>

Action items

行动项

[ ] <Step 1> [ ] <Step 2> [ ] <Step 3> [ ] <Step 4> [ ] <Step 5> [ ] <Step 6>

[ ] <步骤1> [ ] <步骤2> [ ] <步骤3> [ ] <步骤4> [ ] <步骤5> [ ] <步骤6>

Testing and validation

测试与验证

<Tests, commands, or validation steps>

<测试、命令或验证步骤>

Risks and edge cases

风险与边缘情况

<Risk 1>
<Risk 2>

<风险1>
<风险2>

Open questions

待解决问题

<Question 1>
<Question 2>

undefined

<问题1>
<问题2>

undefined

Overview plan body template

概述型计划主体模板

markdown

undefined

markdown

undefined

Plan

计划

<1-3 sentences: intent and scope of the overview.>

<1-3句话：概述的意图和范围。>

Overview

概述

<在高层次描述系统、流程或架构。>

Diagrams

图表

<如有帮助，可添加文本或Mermaid图表。>

Key file references

关键文件参考

<File/module/entry point 1>
<File/module/entry point 2>

<文件/模块/入口点1>
<文件/模块/入口点2>

Auth / routing / behavior notes

认证 / 路由 / 行为说明

<Capture relevant differences (e.g., auth modes, routing paths).>

<记录相关差异（如认证模式、路由路径）。>

Current status

当前状态

<What is live today vs pending work, if known.>

<当前已上线内容 vs 待完成工作（如已知）。>

Action items

行动项

None (overview only).

无（仅为概述）。

Testing and validation

测试与验证

None (overview only).

无（仅为概述）。

Risks and edge cases

风险与边缘情况

None (overview only).

无（仅为概述）。

Open questions

待解决问题

None.

undefined

无。

undefined

Writing guidance

撰写指南

Start with 1 short paragraph describing intent and approach.
Keep action items ordered and atomic (discovery -> changes -> tests -> rollout); use verb-first phrasing.
Scale action item count to complexity (simple: 1-2; complex: up to about 10).
Include file/entry-point hints and concrete validation steps where useful.
Always include testing/validation and risks/edge cases in implementation plans; include safe rollout/rollback when relevant.
Use open questions only when necessary (max 3).
Avoid vague steps, micro-steps, and code snippets; keep the plan implementation-agnostic.
For overview plans, keep action items minimal and set non-applicable sections to "None."

以1段简短文字开头，描述意图和方法。
保持行动项有序且原子化（发现 -> 变更 -> 测试 -> 上线）；使用动词开头的表述。
根据复杂度调整行动项数量（简单任务：1-2项；复杂任务：最多约10项）。
必要时包含文件/入口点提示和具体验证步骤。
实现型计划中必须包含测试/验证和风险/边缘情况；相关时需包含安全的上线/回滚步骤。
仅在必要时使用待解决问题（最多3个）。
避免模糊步骤、微步骤和代码片段；保持计划与实现方式无关。
对于概述型计划，尽量减少行动项，将不适用的部分设置为“无”。