codely-plan-create-subagents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🧠 How to create a plan

🧠 如何创建计划

The structure of a plan, its sections and the rules to shape them are defined in

resources/plan-guidelines.md

. Read it before proposing anything.

Ask the user for the task to create a plan for if not specified.
Explore the codebase using subagents, as described in 🔍 Codebase exploration with subagents. Do not explore the codebase yourself: delegate it.
Define task phases, letting the user choose the amount of phases as described in the guidelines.
Specify the public contracts to be created/modified/deleted on each phase task, as described in the guidelines.
Propose the plan to the user for approval. IMPORTANT: Do not start creating the plan file until the user has agreed on the specific contracts to be considered and the implementation phases.

Save the plan in a new file inside a subfolder of

.agents/plans

with the current date and a semantic name based on the task description. The structure is:

.agents/plans/{plan-name}/{plan-name}-plan.md

. Example:

2026_01_16-create_embeddable_changelog_widget/2026_01_16-create_embeddable_changelog_widget-plan.md

Suggest next steps
- Once you create the plan file, ask the user what do they want to do:
  - Do not do anything else.
  - Commit the plan file to the repository by running the
```
/codely-git-conventional-commit
```
    skill. Consider plan file only changes as
```
docs
```
    type.
  - Implement the plan by running the
```
/codely-plan-phase-implement @plan-file-path
```
    skill.
  - Commit the plan file and then implement Phase 1 only.
[!IMPORTANT] If the user asks to "commit and implement", commit the plan file first, then implement only Phase 1. Never implement all phases at once. The
```
/codely-plan-phase-implement
```
skill handles one phase per invocation.

计划的结构、各章节及其编写规则由

resources/plan-guidelines.md

定义。在提出任何方案之前，请先阅读该文档。

如果未指定任务，请向用户询问需要为其创建计划的任务。
按照 🔍 使用 subagent 进行代码库探索中的说明，使用 subagent 探索代码库。不要亲自探索代码库；应将探索工作委派出去。
定义任务阶段，并按照指南中的说明让用户选择阶段数量。
按照指南中的说明，为每个阶段任务指定要创建、修改或删除的公共契约。
向用户提交计划以供审批。重要： 在用户就需考虑的具体契约和实施阶段达成一致之前，不要开始创建计划文件。
将计划保存到
```
.agents/plans
```
下的一个新子文件夹中，文件夹名称应包含当前日期，并基于任务描述采用语义化名称。结构为：
```
.agents/plans/{plan-name}/{plan-name}-plan.md
```
。示例：
```
2026_01_16-create_embeddable_changelog_widget/2026_01_16-create_embeddable_changelog_widget-plan.md
```
。
建议后续步骤
- 创建计划文件后，询问用户接下来想做什么：
  - 不做其他任何操作。
  - 运行
```
/codely-git-conventional-commit
```
    skill，将计划文件提交到仓库。如果变更仅涉及计划文件，则将其视为
```
docs
```
    类型。
  - 运行
```
/codely-plan-phase-implement @plan-file-path
```
    skill 实施计划。
  - 先提交计划文件，然后仅实施 Phase 1。
[!IMPORTANT] 如果用户要求“提交并实施”，请先提交计划文件，然后仅实施 Phase 1。绝不能一次性实施所有阶段。
```
/codely-plan-phase-implement
```
skill 每次调用只处理一个阶段。

🔍 Codebase exploration with subagents

🔍 使用 subagent 进行代码库探索

Gather the context needed for the plan (relevant files, existing conventions, current behavior, affected contracts) by delegating the exploration to subagents instead of reading the codebase yourself. Keep the main agent focused on reasoning and on writing the plan.

Reuse an existing exploration subagent if there is one.
Use cheaper models for the subagents. Pick a lighter/faster model from the same family whenever the tool allows overriding it. For example, in a session running Opus, Fable or Sonnet, launch the exploration subagents with Haiku.
Decide how many subagents to launch based on the task. A small, well-localized change may need a single subagent, while a task touching several bounded contexts, layers, or screens deserves one subagent per independent area of research. Max 4.
Launch independent subagents in parallel, in a single batch, so the exploration does not become sequential.
Give each subagent a narrow, self-contained assignment. e.g., explore architecture, frontend, backend, different features, separate repos…
Ask each one to report back the concrete file paths, the relevant existing contracts, and the conventions to follow, instead of dumping whole files.
Synthesize the subagent reports yourself before proposing the plan. Read directly only the specific files you still need to confirm a contract or a convention.

通过将探索工作委派给 subagent（而不是亲自阅读代码库），收集计划所需的上下文（相关文件、现有约定、当前行为、受影响的契约）。让主 Agent 专注于推理和编写计划。

如果已有探索用 subagent，请复用它。
使用成本更低的模型运行 subagent。只要工具允许覆盖模型，就应从同一模型家族中选择更轻量、更快的模型。例如，在运行 Opus、Fable 或 Sonnet 的会话中，应使用 Haiku 启动探索 subagent。
根据任务决定启动多少个 subagent。小型且范围集中的变更可能只需要一个 subagent；而涉及多个限界上下文、层级或界面的任务，则应为每个独立研究领域分配一个 subagent。最多 4 个。
在单一批次中并行启动相互独立的 subagent，避免探索过程变成串行执行。
为每个 subagent 分派范围明确且自包含的任务。例如，探索架构、前端、后端、不同功能或独立仓库……
要求每个 subagent 报告具体文件路径、相关的现有契约以及应遵循的约定，而不是直接输出整个文件的内容。
提出计划前，亲自综合分析 subagent 的报告。只直接阅读仍需用于确认契约或约定的特定文件。

🗃️ Frontmatter

The plan file should contain the following frontmatter:

markdown

---
name: "{ plan_name }"
description: "{ plan_description }"
created_at: "{ current_date }"

created_by:
  tool: "{ tool }"
  model:
    name: "{ model.name }"
    version: "{ model.version }"
    reasoning_effort: "{ model.reasoning_effort }"
---

```
current_date
```
: The current date in the format ISO 8601 RFC 3339 (
```
YYYY-MM-DDTHH:MM:SSZ
```
).

created_by.tool

: The AI coding tool used (e.g.

Claude Code

Cursor

Copilot

Codex

)

created_by.model.name

: The name of the model used to make the change (e.g.

Claude Opus

Cursor Composer

OpenAI GPT

)

```
created_by.model.version
```
: The version of the model used to make the change (e.g.
```
4.6
```
,
```
1.5
```
,
```
5.4
```
)
```
created_by.model.reasoning_effort
```
: The reasoning effort of the model used to make the change (e.g.
```
low
```
,
```
medium
```
,
```
high
```
)

计划文件应包含以下 Frontmatter：

markdown

---
name: "{ plan_name }"
description: "{ plan_description }"
created_at: "{ current_date }"

created_by:
  tool: "{ tool }"
  model:
    name: "{ model.name }"
    version: "{ model.version }"
    reasoning_effort: "{ model.reasoning_effort }"
---

```
current_date
```
：采用 ISO 8601 RFC 3339 格式的当前日期（
```
YYYY-MM-DDTHH:MM:SSZ
```
）。
```
created_by.tool
```
：用于进行更改的 AI 编程工具（例如
```
Claude Code
```
、
```
Cursor
```
、
```
Copilot
```
、
```
Codex
```
）。

created_by.model.name

：用于进行更改的模型名称（例如

Claude Opus

、

Cursor Composer

、

OpenAI GPT

）。

```
created_by.model.version
```
：用于进行更改的模型版本（例如
```
4.6
```
、
```
1.5
```
、
```
5.4
```
）。
```
created_by.model.reasoning_effort
```
：所用模型的推理强度（例如
```
low
```
、
```
medium
```
、
```
high
```
）。