Back to Details

evanflow-writing-plans

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

EvanFlow: Writing Plans

EvanFlow：编写计划

Vocabulary

词汇表

See 
evanflow
meta-skill. Key terms: deep modules, interface, vertical slice, deletion test.
请查看
evanflow
元技能。关键术语：deep modules、interface、vertical slice、deletion test。

When to Use

适用场景

  • A spec or clear requirements exist
  • Multi-step task that benefits from upfront decomposition
  • About to touch ≥3 files
SKIP when: single-file change, typo fix, one-line config tweak. Just do it.
  • 已有明确的规格说明或需求
  • 多步骤任务，可通过前期分解获益
  • 将要修改≥3个文件
**跳过场景：**单文件修改、拼写错误修复、单行配置调整。直接执行即可。

The Flow

流程步骤

1. Scope Check

1. 范围检查

If the spec covers multiple independent subsystems, suggest splitting into separate plans. Each plan should produce working, testable software on its own.
如果规格说明涵盖多个独立子系统，建议拆分为多个独立计划。每个计划都应产出可运行、可测试的软件。

2. File Structure First

2. 先确定文件结构

Before any tasks, name the files that will be created or modified, with a one-line responsibility for each. This locks in decomposition decisions.
Example (adapt the paths to your project's structure):
<backend>/routers/foo.ts          — API router; thin, delegates to service
<backend>/services/foo.ts         — business logic; pure where possible
<backend>/services/foo.test.ts    — vertical-slice tests
<frontend>/pages/foo.tsx          — UI; consumes the API
Apply the deletion test: if a file would just shuffle complexity to its callers, fold it into the caller.
在制定任何任务之前，列出将要创建或修改的文件，并为每个文件添加一行职责说明。这能锁定分解决策。
示例（根据项目结构调整路径）：
<backend>/routers/foo.ts          — API 路由；轻量化，委托给服务层
<backend>/services/foo.ts         — 业务逻辑；尽可能保持纯函数
<backend>/services/foo.test.ts    — 垂直切片测试
<frontend>/pages/foo.tsx          — UI；调用API
应用deletion test：如果某个文件只是将复杂度转移到调用方，就将其合并到调用方中。

2.5. Parallelization Check (offer coder-overseer if applicable)

2.5. 并行化检查（适用时提供编码监督模式）

After the file structure is sketched, ask: does this plan have 3+ truly independent units that share a common interface contract?
If YES — offer 
evanflow-coder-overseer
to the user as the execution path:
"This plan has [N] independent units sharing [contract]. We could execute it sequentially via 
evanflow-executing-plans
, or in parallel via 
evanflow-coder-overseer
(one coder per unit + per-coder overseer + integration overseer + executable contract via integration tests). Parallel is faster for big plans and adds independent QA, but only works if the units are truly independent. Which?"
Signals that favor coder-overseer:
  • 3+ files/modules that don't import each other
  • A clear shared interface contract (types, naming, invariants)
  • Integration touchpoints that can be expressed as named integration tests
  • Plan would otherwise be tedious to execute serially
Signals that favor sequential 
executing-plans
:
  • Tasks have hidden dependencies (one's output feeds the next)
  • Fewer than 3 units
  • No shared contract surface — units don't need to interoperate
  • Risk-averse work (auth, payments, migrations) where a single careful pass beats parallelism
If the user picks coder-overseer, structure the plan with a per-coder section and the cohesion contract upfront. If sequential, continue to step 3 normally.
在草拟文件结构后，询问：此计划是否包含3个及以上共享通用接口契约的真正独立单元？
如果是——向用户推荐
evanflow-coder-overseer
作为执行路径：
"此计划包含[N]个独立单元，共享[契约]。我们可以通过
evanflow-executing-plans
顺序执行，或通过
evanflow-coder-overseer
并行执行（每个单元分配一名编码人员 + 编码监督人员 + 集成监督人员 + 通过集成测试实现可执行契约）。并行执行对于大型计划更快，且能添加独立QA，但仅适用于单元真正独立的情况。选择哪种方式？"
倾向于编码监督模式的信号：
  • 3个及以上互不导入的文件/模块
  • 清晰的共享接口契约（类型、命名、不变量）
  • 可表示为命名集成测试的集成触点
  • 否则按顺序执行会非常繁琐的计划
倾向于顺序执行
executing-plans
的信号：
  • 任务存在隐藏依赖（前一个任务的输出是后一个的输入）
  • 单元数量少于3个
  • 无共享契约面——单元无需互操作
  • 风险敏感型工作（认证、支付、迁移），此时单次谨慎执行优于并行执行
如果用户选择编码监督模式，需在计划中前置每个编码人员的职责部分和内聚契约。如果选择顺序执行，正常进入步骤3。

3. Embedded Grill

3. 内置压力测试

Stress-test the structure before writing tasks:
  • "Where does this go wrong if the user does X?"
  • "What happens if this fails halfway? What's the recovery?"
  • "Is there an existing service in the project that already does part of this?"
  • "Does the file structure follow project conventions documented in CLAUDE.md or visible in similar existing files?"
  • "Are we introducing or changing domain terms? Update 
    CONTEXT.md
    first?"
在编写任务前先对结构进行压力测试：
  • "如果用户执行X操作，这里会出什么问题？"
  • "如果中途失败会怎样？如何恢复？"
  • "项目中是否已有服务完成了部分此类工作？"
  • "文件结构是否遵循CLAUDE.md中记录的或在现有类似文件中可见的项目约定？"
  • "我们是否引入或更改了领域术语？是否需要先更新
    CONTEXT.md
    ？"

4. Bite-Sized Tasks

4. 细分任务

Each task is one focused unit (~15-30 min of work). Within each task, list bite-sized steps (~2-5 min each):
markdown
undefined
每个任务都是一个聚焦的单元（约15-30分钟工作量）。在每个任务中，列出更细化的步骤（约2-5分钟每个）：
markdown
undefined

Task 1: [Component Name]

任务1：[组件名称]

Files: Create 
path/to/foo.ts
, modify 
path/to/bar.ts:123-145
, test 
path/to/foo.test.ts
  • Write the failing test (one behavior — see evanflow-tdd)
  • Run test, confirm it fails for the right reason
  • Write minimal implementation
  • Run test, confirm it passes
  • Run the project's quality checks (typecheck / lint / test) — exact commands are project-specific; see CLAUDE.md or the project's README

After all tasks complete, the executor hands off to `evanflow-iterate` for self-review, then **stops and reports**. The plan does NOT include staging or committing — the user controls those.
文件： 创建
path/to/foo.ts
，修改
path/to/bar.ts:123-145
，测试
path/to/foo.test.ts
  • 编写失败测试（一个行为——参见evanflow-tdd）
  • 运行测试，确认因正确原因失败
  • 编写最小化实现
  • 运行测试，确认通过
  • 运行项目的质量检查（类型检查/ lint/测试）——具体命令因项目而异；参见CLAUDE.md或项目README

所有任务完成后，执行者将工作移交至`evanflow-iterate`进行自我审查，然后**停止并汇报**。计划不包含暂存或提交步骤——这些由用户控制。

5. Plan Header (lighter than upstream)

5. 计划标题（比上游简化）

markdown
undefined
markdown
undefined

[Feature Name] Plan

[功能名称] 计划

Goal: [one sentence] Architecture: [2-3 sentences] Files: [list from step 2]

**No "REQUIRED SUB-SKILL" header.** Sub-skills are suggestions documented inline at hand-off points, not mandates baked into the plan format.
目标： [一句话] 架构： [2-3句话] 文件： [步骤2中的列表]

**无需"REQUIRED SUB-SKILL"标题**。子技能是在移交点内联记录的建议，而非嵌入计划格式的强制要求。

6. Save the Plan

6. 保存计划

Default location: 
docs/plans/YYYY-MM-DD-<topic>.md
. If the user has a different preference, honor it. Don't write to any vendor-specific path unless explicitly asked.
默认位置：
docs/plans/YYYY-MM-DD-<topic>.md
。如果用户有其他偏好，遵循其要求。除非明确要求，否则不要写入任何特定供应商的路径。

Hard Rules

硬性规则

  • Never include staging or commit steps in the plan. Plans end at "verified, await user direction." The user decides when to stage, commit, push, merge.
  • No forced sub-skill chain. No "must use using-git-worktrees" or "must use subagent-driven-development" header.
  • Plans live where the user wants. Default 
    docs/plans/
    only if no preference stated.
  • TDD by default. Every code task is structured as test-first. Exceptions (configs, schemas, prototypes) are flagged inline.
  • 计划中绝不包含暂存或提交步骤。计划结束于"已验证，等待用户指示"阶段。用户决定何时暂存、提交、推送、合并。
  • 无强制子技能链。不得添加"必须使用using-git-worktrees"或"必须使用subagent-driven-development"标题。
  • 计划存储位置由用户决定。仅在用户无偏好时使用默认的
    docs/plans/
    。
  • 默认采用TDD。每个代码任务都以测试优先的方式构建。例外情况（配置、模式、原型）需内联标记。

Hand-offs

移交

  • Plan written → 
    evanflow-executing-plans
  • Need to design an API surface first → 
    evanflow-design-interface
  • Architecture concerns surfaced → 
    evanflow-improve-architecture
    first, then back here
  • 计划编写完成 → 
    evanflow-executing-plans
  • 需要先设计API表面 → 
    evanflow-design-interface
  • 发现架构问题 → 先执行
    evanflow-improve-architecture
    ，再返回此处