用途
create-plan 用于把用户的提示或规格说明转化为一份可执行的计划,供用户据此执行。它适用于用户明确要求制定计划,或任务明显是多步骤的场景。目标是让输出无需额外解释即可执行。
主要能力
- 生成单一计划文档,包含清晰的范围边界、有序的原子步骤、明确的验证命令,以及已知风险和待解决问题。
- 以只读模式运行,不写入或更新文件。
- 仅在真正阻塞时提出最多 1–2 个澄清问题;若不确定但不阻塞,则说明假设并继续。
- 优先采用仓库本地事实(文档、配置、profile),而非猜测。
- 不臆造命令,使用 profile 值、已发现的工具链,或标记为未知。
输入
- 用户请求 / 规格 / 验收标准(如提供)。
- 仓库上下文(如存在 README、ARCHITECTURE、AGENTS、CALIBRATION、ROADMAP)。
- 仓库 profile(如存在则为权威):
<repo>/REPO_PROFILE.json。 - 全局参考 profile(仅作回退参考):
~/.codex/repo_profile.json。
输出
一份严格遵循指定格式的单一计划文档。
Profile 解析顺序
- 若
<repo>/REPO_PROFILE.json存在,则将其视为权威,用于:技术栈形态、路径(frontend_root/backend_root)、命令(lint/typecheck/test/build)、质量门槛(required_checks)。 - 否则若
~/.codex/repo_profile.json存在,则仅将其视为默认值的参考模板。 - 否则以最小假设继续,并明确记录未知项。
绝不静默合并 profile。若两者冲突,优先采用仓库本地 profile,并将冲突记录为风险。
最小工作流
- 快速扫描上下文(只读):阅读 README 和明显文档(README、docs/、CONTRIBUTING、ARCHITECTURE、AGENTS、CALIBRATION、ROADMAP);识别可能涉及的领域/文件;从仓库结构和/或 profile 判断技术栈形态(前端/后端/单体仓库);确定规范验证命令(优先使用
<repo>/REPO_PROFILE.json中的命令,缺失时仅在显而易见时推断,例如存在 package.json scripts,否则将验证命令标记为未知并列入待解决问题);识别约束(语言/框架、部署形态、CI 门槛、风险姿态)。若<repo>/REPO_PROFILE.json存在,将其命令和路径视为权威。 - 规划工作:保持步骤原子且有序(发现 → 变更 → 验证 → 发布);默认 6–10 个行动项;动词开头的动作(Add…、Refactor…、Verify…、Ship…);至少包含一个测试/验证步骤;适用时至少包含一个边界情况/风险步骤;必要时可在括号中标注相关技能名(例如
[ ] Add endpoint contract (api/contract-update)),但保持轻量,不要变成技能注册表堆砌;若存在仓库 profile,优先采用尊重其边界和约定的步骤。 - 记录未知项:若仍有未知项,保留在 Open questions 中(最多 3 个);若未知项真正阻塞,提出最多 1–2 个澄清问题;若命令未知,不要猜测,将缺失命令记录为 Open question。
验证要求
Validation 部分必须包含:来自 <repo>/REPO_PROFILE.json 的可运行命令(如存在),或明确的占位符:缺失时为 unknown (needs repo command),不适用时为 none (repo does not use this)。优先至少包含:一个快速检查(lint/typecheck)和一个正确性检查(tests)。
输出格式(严格遵循)
Plan
<1–3 sentences: what we’re doing, why, and the high-level approach.>
Scope
In:
Out:
Action items
[ ] <Step 1>
[ ] <Step 2>
[ ] <Step 3>
[ ] <Step 4>
[ ] <Step 5>
[ ] <Step 6>
Validation
<Command or validation step 1>
<Command or validation step 2>
Edge cases / risks
<Risk 1>
<Risk 2>
Open questions
<Question 1>
<Question 2>
<Question 3>
适用场景
- 用户明确要求为编程任务制定计划。
- 任务明显包含多个步骤,需要有序执行。
- 需要明确范围边界、验证命令和风险,以便直接执行。
限制
- 只读模式,不写入或更新文件。
- 不臆造命令;缺失命令标记为未知。
- 澄清问题最多 1–2 个,且仅在真正阻塞时提出。
- Open questions 最多 3 个。
- 不静默合并 profile;冲突时优先仓库本地并记录为风险。
- 关于收费、价格、平台、效果等信息暂未提供。