Back to Details

recipe

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

recipe

实施计划（recipe）

A recipe card is written so a cook who has never seen the dish can plate it exactly: exact quantities, exact pan, exact minutes, steps in order. "Season to taste" is how the same dish comes out different every night. This skill turns an approved spec into that card: an implementation plan a zero-context engineer or fresh agent session can execute with you unavailable for questions.
Assume the implementer is skilled but knows nothing about this codebase or problem domain, and has questionable taste in tests. The plan carries everything: which files each task touches, the actual code, the exact commands, the output to expect. DRY, YAGNI, test-first, frequent commits.
食谱卡的编写目的是让从未见过这道菜的厨师也能精准摆盘：精确的用量、指定的锅具、准确的时长、按顺序执行的步骤。“按需调味”会导致同一道菜每晚的味道都不一样。本技能将已获批的需求规格转化为这样的“食谱卡”：一份无需上下文的工程师或新Agent会话可直接执行的实施计划，即使你无法解答疑问也能顺利推进。
假设执行者具备专业技能，但对当前代码库或问题领域一无所知，且测试习惯欠佳。计划需包含所有必要信息：每项任务涉及的文件、实际代码、精确命令、预期输出。遵循DRY、YAGNI、测试优先、频繁提交的原则。

Preconditions

前置条件

  • An approved design or spec exists (mise's output, or equivalent). No spec? Run mise first. Recipe shapes decided work; it does not decide.
  • One plan per subsystem. If the spec spans several independent subsystems, say so and split before going deep; each plan must produce working, testable software on its own.
  • 已存在获批的设计或需求规格（即mise的输出或等效文档）。若无规格，请先执行mise。实施计划（recipe）仅负责规划工作，不负责决策。
  • 每个子系统对应一份计划。若需求规格涵盖多个独立子系统，请说明并拆分后再深入；每份计划必须能独立产出可运行、可测试的软件。

Steps

步骤

  1. Read the code you are planning against. The files the spec touches, one neighboring module that shows the house pattern, the test layout. A plan written from memory or a description of the codebase hedges ("if main returns the code, leave it; otherwise wrap it"), and every hedge is a decision forwarded to the implementer.
  2. Map the file structure. Before any tasks: every file the plan creates or modifies, and the one responsibility each holds. Prefer small focused files with clear boundaries; in an existing codebase, follow its patterns instead of restructuring. This map locks the decomposition. A file whose purpose needs "and" probably wants splitting.
  3. Open with the header. Goal in one sentence, architecture in two or three, key tech, and an instruction to agentic workers to execute task-by-task tracking the checkboxes.
  4. Decompose into tasks, each task into bite-size steps. A step is one action of a few minutes, written as a checkbox (
    - [ ]
    ): write the failing test (the actual test code), run it and watch it fail (the exact command and the expected failure), implement the minimal change (the actual code), run to green (command and expected output), commit (the command). Every task names its exact file paths up front.
  5. Pin every decision. Exit-code orderings, edge-case behavior, naming, where a helper lives: decided in the plan, with the reason when it is not obvious. A plan that says "your call", "adapt to taste", or ends with an open-questions section has pushed design onto the person with the least context. A decision that genuinely cannot be made yet goes back to pressure-test or the spec's author now, not into the plan.
  6. Self-review with fresh eyes, then fix inline:
    • Spec coverage: every requirement in the spec points to a task that implements it.
    • Placeholder scan: hunt the patterns under No placeholders below.
    • Consistency: names, signatures, and types used in later tasks match where earlier tasks defined them.
  7. Save to 
    docs/plans/YYYY-MM-DD-<topic>.md
    , commit, and hand off to fire.     It executes in two shapes: a fresh subagent per task with review between tasks (preferred), or inline in one session with checkpoints. Either way the plan, not memory of this conversation, is the source of truth.
  1. 研读待规划的代码：查看需求规格涉及的文件、一个体现项目架构模式的相邻模块，以及测试布局。仅凭记忆或代码库描述编写的计划会存在模糊表述（如“若main函数返回该代码则保留，否则进行封装”），而每一处模糊表述都是将决策推给了执行者。
  2. 梳理文件结构：在规划任务前，明确计划中创建或修改的所有文件，以及每个文件的单一职责。优先选择小而聚焦、边界清晰的文件；对于现有代码库，遵循其现有模式而非重构。此结构映射将锁定任务分解方式。若某个文件的职责需要用“和”来描述，大概率需要拆分。
  3. 添加头部信息：用一句话说明目标，两到三句话阐述架构，列出核心技术，并指示Agent执行者按任务逐一执行，跟踪复选框进度。
  4. 分解为任务，每个任务拆分为小步骤：每个步骤是耗时几分钟的单一操作，用复选框（
    - [ ]
    ）表示：编写失败的测试（实际测试代码）、运行测试并确认失败（精确命令及预期失败结果）、实现最小化修改（实际代码）、运行测试至通过（命令及预期输出）、提交代码（命令）。每项任务需预先明确涉及的精确文件路径。
  5. 明确所有决策：退出码顺序、边缘情况处理、命名规则、辅助函数的位置等，均需在计划中确定，非显而易见的决策需说明原因。若计划中出现“自行决定”“按需调整”或包含“待解决问题”章节，则是将设计工作推给了最缺乏上下文的人。若确实存在无法立即决定的问题，请返回pressure-test或需求规格的制定者处解决，而非放入计划中。
  6. 以全新视角自我审查，然后在线修正：
    • 需求规格覆盖：确保需求规格中的每一项要求都对应到一个实现任务。
    • 占位符检查：排查以下“禁止使用占位符”部分列出的模式。
    • 一致性：后续任务中使用的名称、签名和类型需与前面任务中的定义保持一致。
  7. 保存至
    docs/plans/YYYY-MM-DD-<topic>.md
    ，提交代码，并移交至fire    。有两种执行方式：为每个任务分配新的子Agent，任务间进行审查（推荐方式）；或在一个会话中按顺序执行并设置检查点。无论哪种方式，计划而非本次对话的记忆才是唯一依据。

Task format

任务格式

markdown
undefined
markdown
undefined

Task N: <component>

任务N：<组件名称>

Files:
  • Create: 
    exact/path/to/file.py
  • Modify: 
    exact/path/to/existing.py:123-145
  • Test: 
    tests/exact/path/test_file.py
  • Write the failing test
python
def test_specific_behavior(tmp_store):
    result = function(input)
    assert result == expected
  • Run it, watch it fail: 
    pytest tests/exact/path/test_file.py::test_specific_behavior -v
    - expect FAIL, "function not defined"
  • Implement the minimal change
python
def function(input):
    return expected
  • Run to green: same command - expect PASS
  • Commit: 
    git add -A && git commit -m "feat: <effect>"
undefined
文件：
  • 创建：
    exact/path/to/file.py
  • 修改：
    exact/path/to/existing.py:123-145
  • 测试：
    tests/exact/path/test_file.py
  • 编写失败的测试
python
def test_specific_behavior(tmp_store):
    result = function(input)
    assert result == expected
  • 运行测试，确认失败：
    pytest tests/exact/path/test_file.py::test_specific_behavior -v
    - 预期结果：失败，提示“function not defined”
  • 实现最小化修改
python
def function(input):
    return expected
  • 运行测试至通过：使用相同命令 - 预期结果：通过
  • 提交代码：
    git add -A && git commit -m "feat: <effect>"
undefined

No placeholders

禁止使用占位符

Each of these in a plan is a plan failure, not a shortcut:
  • "TBD", "TODO", "implement later", "fill in details"
  • "Add appropriate error handling" / "handle edge cases" without the cases and the handling
  • "Write tests for the above" without the test code
  • "Similar to Task N" instead of repeating the code; tasks get read out of order
  • A step that says what to do without showing how; code steps carry code blocks
  • A name, type, or function referenced but defined in no task
计划中出现以下任何内容均视为计划失败，而非捷径：
  • “TBD”“TODO”“后续实现”“补充细节”
  • “添加适当的错误处理”/“处理边缘情况”但未明确具体情况及处理方式
  • “为上述内容编写测试”但未提供测试代码
  • “与任务N类似”而非重复代码；任务可能会被无序阅读
  • 仅说明做什么却未展示怎么做的步骤；代码步骤需附带代码块
  • 引用了名称、类型或函数但未在任何任务中定义

Rules

规则

  • Exact paths, complete code, exact commands with expected output. Every step, no exceptions for the "obvious" ones.
  • The implementer makes zero design decisions. If writing a step surfaces an undecided question, decide it in the plan or take it back upstream; never forward it.
  • Test-first inside every task that changes behavior. The failing run is a step of its own, not an assumption.
  • Don't relitigate the spec. Decisions mise and pressure-test pinned arrive here settled; the plan implements them.
  • Scale ceremony to the work: a one-task plan still gets the header, the file map, and real code in its steps. What it skips is task count, not rigor.
  • 精确路径、完整代码、带预期输出的精确命令。每一步都必须遵循，即使是“显而易见”的步骤也不例外。
  • 执行者无需做出任何设计决策。若编写步骤时发现未确定的问题，请在计划中解决或向上反馈，绝不能推给执行者。
  • 所有修改行为的任务均遵循测试优先原则。运行测试确认失败是独立步骤，而非预设前提。
  • 无需重新讨论需求规格。mise和pressure-test阶段确定的决策在此处已定型；计划仅负责执行这些决策。
  • 根据工作规模调整流程严谨度：单任务计划仍需包含头部信息、文件结构映射及步骤中的真实代码。可简化的是任务数量，而非严谨性。

Common mistakes

常见错误

  • Describing tests in prose ("test that add is idempotent") instead of writing the test. The executor inherits a design job, not a recipe.
  • Steps without run commands or expected output, so the executor cannot tell a broken step from a broken codebase.
  • Component-sized "steps" that hide ten decisions, instead of checkbox actions of a few minutes each.
  • An "open questions" or "decide while building" section. That is the tell the planning was not finished.
  • Hedged structure: "put it in store.py, or a new helpers module if you prefer". The file map exists to settle exactly this.
  • Writing the plan for yourself-tomorrow instead of a stranger, leaning on context only this conversation holds.
  • 用文字描述测试（如“测试add操作的幂等性”）而非编写测试代码。这会让执行者承担设计工作，而非仅按食谱执行。
  • 步骤未包含运行命令或预期输出，导致执行者无法区分步骤错误与代码库本身的问题。
  • 将组件级别的“步骤”隐藏大量决策，而非拆分为耗时几分钟的复选框操作。
  • 包含“待解决问题”或“构建时决策”章节。这表明规划工作尚未完成。
  • 模糊的结构表述：“将其放入store.py，或若你偏好可放入新的helpers模块”。文件结构映射的作用就是明确此类问题。
  • 为“未来的自己”编写计划，而非陌生人，依赖仅本次对话才有的上下文信息。