Back to Details

core-first-simplicity

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

核心优先简化原则

Core First Simplification Principle

用最小必要复杂度实现最大核心价值。
Deliver maximum core value with the minimum necessary complexity.

⚠️ 核心强制要求

⚠️ Core Mandatory Requirements

1) 核心优先

1) Core Priority

  • 任何设计都先回答：当前任务最重要的核心价值是什么？
  • 无法直接强化核心价值的设计，默认不做或延后。
  • For any design, first answer: What is the most important core value of the current task?
  • Designs that cannot directly enhance core value are not implemented or postponed by default.

2) KISS 默认优先

2) KISS Default Priority

  • 有两种可行方案时，默认选择更简单、可验证、可维护的一种。
  • 不为“未来可能需要”提前引入复杂抽象。
  • When there are two feasible solutions, the simpler, verifiable, and maintainable one is selected by default.
  • Do not introduce complex abstractions in advance for "possible future needs".

3) 复杂度准入门槛

3) Complexity Admission Threshold

仅当同时满足以下条件，才允许增加复杂度：
  1. 直接提升核心目标达成率。
  2. 存在明确证据（性能瓶颈、稳定性问题、用户痛点）。
  3. 复杂度可被局部封装，不扩散到全局。
Increased complexity is only allowed if all of the following conditions are met:
  1. Directly improve the achievement rate of core goals.
  2. There is clear evidence (performance bottlenecks, stability issues, user pain points).
  3. Complexity can be locally encapsulated without spreading to the global scope.

4) 砍掉与延后

4) Cut and Postpone

  • 锦上添花但不影响核心价值：延后。
  • 增加认知负担且收益不明确：砍掉。
  • 没有完美方案时，优先“刚好能用”的可迭代版本。
  • Icing on the cake features that do not affect core value: postpone.
  • Features that increase cognitive burden with unclear benefits: cut.
  • When there is no perfect solution, prioritize the "just usable" iterable version.

AI Agent 行为要求

AI Agent Behavior Requirements

设计前（必问）

Before Design (Mandatory Questions)

  1. 如果只能保留一个能力，应该保留什么？
  2. 当前方案是否比上一版更复杂？复杂度收益比是否成立？
  3. 是否存在更直接、更短路径的实现？
  1. If only one capability can be retained, what should it be?
  2. Is the current solution more complex than the previous version? Is the complexity-to-benefit ratio valid?
  3. Is there a more direct, shorter path implementation?

实施中（必做）

During Implementation (Mandatory Actions)

  • 对每个新增模块/抽象说明其核心价值贡献。
  • 若无法明确贡献，主动提出“删除或延后”建议。
  • 当用户追求大而全时，优先提供“最小可行实现 + 后续迭代路径”。
  • Explain the core value contribution of each new module/abstraction.
  • If the contribution cannot be clearly defined, proactively propose a "delete or postpone" suggestion.
  • When users pursue a large and comprehensive solution, prioritize providing "minimum viable implementation + subsequent iteration path".

评审时（必检）

During Review (Mandatory Checks)

  • 是否出现了与核心目标无关的复杂度扩张。
  • 是否可以通过减少层级/减少分支/减少接口来简化。
  • 是否保留了清晰的默认路径（happy path）。
  • Check if there is complexity expansion unrelated to core goals.
  • Check if simplification can be done by reducing layers/branches/interfaces.
  • Check if a clear happy path is retained.

分层落地（Progressive Disclosure）

Layered Implementation (Progressive Disclosure)

  • references/project-level.md
    ：项目级聚焦与取舍
  • references/system-level.md
    ：系统级复杂度预算与架构简化
  • references/module-level.md
    ：模块级边界与依赖简化
  • references/code-level.md
    ：代码级结构与抽象简化
  • references/function-level.md
    ：函数级控制流与职责简化
  • references/project-level.md
    : Project-level focus and trade-offs
  • references/system-level.md
    : System-level complexity budget and architecture simplification
  • references/module-level.md
    : Module-level boundary and dependency simplification
  • references/code-level.md
    : Code-level structure and abstraction simplification
  • references/function-level.md
    : Function-level control flow and responsibility simplification

反模式（必须避免）

Anti-patterns (Must Avoid)

  • 为“以后可能会用”而提前设计复杂结构。
  • 用高抽象掩盖尚未稳定的需求。
  • 同时推进多个非核心优化导致主线停滞。
  • 在没有证据时引入中间层、配置层、插件层。
  • Design complex structures in advance for "possible use in the future".
  • Cover unstable requirements with high abstraction.
  • Promote multiple non-core optimizations at the same time leading to stagnation of the main line.
  • Introduce middle layers, configuration layers, and plugin layers without evidence.

参考资料

References

  • KISS principle（背景）：https://en.wikipedia.org/wiki/KISS_principle
  • references/project-level.md
    - 项目级落地
  • references/system-level.md
    - 系统级落地
  • references/module-level.md
    - 模块级落地
  • references/code-level.md
    - 代码级落地
  • references/function-level.md
    - 函数级落地
  • KISS principle (background): https://en.wikipedia.org/wiki/KISS_principle
  • references/project-level.md
    - Project-level implementation
  • references/system-level.md
    - System-level implementation
  • references/module-level.md
    - Module-level implementation
  • references/code-level.md
    - Code-level implementation
  • references/function-level.md
    - Function-level implementation