Back to Details

structure-first

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: Structure First

技能：主流程优先结构化

Purpose

目标

Primary Flow: the top-down readable main path that orchestrates the logic
When generating, refactoring, or reviewing code, prioritize a readable success path (Primary Flow) first. Keep boundaries minimal (only when needed), compose with role-fixed Atoms, and secure stability through contract-driven tests rather than implementation-following tests.
Primary Flow：自上而下可读性强的核心逻辑编排路径
在生成、重构或评审代码时，优先打造可读性强的主成功路径（Primary Flow）。尽可能减少边界（仅在必要时添加），通过角色固定的原子单元（Atoms）进行组合，并通过契约驱动测试而非跟随实现细节的测试来保障稳定性。

When to Use

适用场景

  • When code does not read naturally from top to bottom
  • When function/module splitting becomes excessive and utilities start to spread
  • When tests are drifting toward implementation-following patterns
  • 代码无法自上而下自然阅读时
  • 函数/模块拆分过度，工具类开始分散时
  • 测试逐渐偏向跟随实现细节的模式时

Do Not Use

不适用场景

  • Throwaway experiments or one-off exploratory code
  • Tiny changes where structural intervention would be excessive
  • 一次性实验或探索性代码
  • 微小改动，进行结构化调整过于小题大做时

Priorities (Bias)

优先级（倾向）

  • Readable flow > structural simplicity > reusability > abstraction
  • Prefer clarity of the current code over speculative future needs
  • Splitting is not a goal; split only when it improves readability
  • 可读流程 > 结构简洁 > 可复用性 > 抽象性
  • 优先保证当前代码的清晰度，而非为未来可能的需求做投机性设计
  • 拆分不是目标；仅当拆分能提升可读性时才进行拆分

Work Routine

工作流程

  1. Fix Intent
  • State the intent of the change/code in one sentence.
  1. Minimize Boundaries
  • Classify steps as I/O, domain decision, or transform.
  • Do not add more boundaries than necessary.
  1. Primary Flow First
  • Make the success path readable in one top-down pass.
  • Keep branches/exceptions from breaking the main flow (early return or push downward).
  1. Extract Atoms
  • Split when a Primary Flow sentence becomes clearer as a function.
  • Atoms must have fixed roles and clear I/O.
  • Prefer pure functions when possible.
  1. Single Composition Point
  • Keep orchestration in one place.
  • Minimize direct dependencies/calls between Atoms.
  1. Push Side Effects to Boundaries
  • Gather side effects (I/O, state mutation) at boundaries.
  • Keep inner logic focused on computation and decisions.
  1. Align Read Order
  • Order code as: export/public -> orchestrator -> atoms -> utils.
  1. 明确意图
  • 用一句话说明代码/改动的意图。
  1. 最小化边界
  • 将步骤划分为I/O、领域决策或转换类型。
  • 仅保留必要的边界，不额外添加。
  1. 主流程优先
  • 让成功路径可通过一次自上而下的阅读理解。
  • 避免分支/异常打断主流程（提前返回或向下封装）。
  1. 提取原子单元
  • 当主流程中的某部分以函数形式呈现更清晰时，进行拆分。
  • 原子单元必须有固定角色和明确的I/O。
  • 尽可能使用纯函数。
  1. 单一组合点
  • 将逻辑编排集中在一处。
  • 尽量减少原子单元之间的直接依赖/调用。
  1. 将副作用移至边界
  • 将副作用（I/O、状态变更）集中在边界处。
  • 内部逻辑专注于计算和决策。
  1. 对齐阅读顺序
  • 代码顺序：导出/公开代码 → 编排器 → 原子单元 → 工具类。

Test Guidance (Unit tests for Atoms)

测试指导（原子单元的单元测试）

  • Write sufficient unit tests at Atom level whenever possible.
  • Validate contracts (I/O, invariants, edge cases), not internals.
  • Test code should remain readable:
    • Use 
      each
      /table cases to reduce duplication.
    • Small helpers/factories are fine, but stop when they blur structure.
    • Each test should expose one core assertion.
  • 尽可能为原子单元编写充分的单元测试。
  • 验证契约（I/O、不变量、边缘情况），而非内部实现细节。
  • 测试代码需保持可读性：
    • 使用
      each
      /表格用例减少重复。
    • 可以使用小型辅助函数/工厂，但不要让它们模糊结构。
    • 每个测试应聚焦一个核心断言。

Stop Rules / Anti‑patterns

停止规则 / 反模式

  • If splitting increases argument/state passing, roll it back.
  • Do not split functions/files for appearance only (avoid utility sprawl).
  • If names start turning into long explanations, re-check boundaries.
  • Avoid adding abstractions/layers for assumed future reuse.
  • Avoid over-abstracted tests and helper sprawl.
  • 如果拆分导致参数/状态传递增加，回退该操作。
  • 不要仅为了外观而拆分函数/文件（避免工具类泛滥）。
  • 如果命名开始变得冗长复杂，重新检查边界设置。
  • 不要为假设的未来复用添加抽象层。
  • 避免过度抽象的测试和辅助类泛滥。

Output Expectations

输出预期

  • Intent: (1 line)
  • Primary Flow: (top-down flow)
  • Boundaries: (I/O / domain / transform)
  • Atoms: (name + I/O)
  • Tests: (contract + edge cases, table cases)
  • Changes: (targeted changes that improve readable flow)
  • 意图：（一句话）
  • Primary Flow：（自上而下的流程）
  • 边界：（I/O / 领域 / 转换类型）
  • 原子单元：（名称 + I/O）
  • 测试：（契约 + 边缘情况，表格用例）
  • 改动：（针对性提升可读流程的修改）

Final Gates

最终检查项

  • Can the success path be seen in one top-down read?
  • Does splitting reflect real responsibility/boundary changes?
  • Can each Atom's I/O be explained in one line?
  • Are side effects concentrated at boundaries?
  • Are tests contract-focused and concise?
  • 能否通过一次自上而下的阅读理清成功路径？
  • 拆分是否反映了真实的职责/边界变化？
  • 每个原子单元的I/O能否用一句话说明？
  • 副作用是否集中在边界处？
  • 测试是否聚焦契约且简洁？

Completion Evidence

完成验证

Before declaring completion, provide these three lines:
  • Primary Flow:
    top-down in 3-6 lines
  • Boundaries:
    list of I/O boundaries
  • Tests:
    contract/edge-case summary
在宣布完成前，需提供以下三行内容：
  • Primary Flow:
    3-6行的自上而下流程描述
  • Boundaries:
    I/O边界列表
  • Tests:
    契约/边缘情况摘要