核心优先简化原则

用最小必要复杂度实现最大核心价值。

⚠️ 核心强制要求

1. 核心优先

• 任何设计都先回答：当前任务最重要的核心价值是什么？

• 无法直接强化核心价值的设计，默认不做或延后。

2. KISS 默认优先

• 有两种可行方案时，默认选择更简单、可验证、可维护的一种。

• 不为“未来可能需要”提前引入复杂抽象。

3. 复杂度准入门槛

仅当同时满足以下条件，才允许增加复杂度：

• 直接提升核心目标达成率。

• 存在明确证据（性能瓶颈、稳定性问题、用户痛点）。

• 复杂度可被局部封装，不扩散到全局。

4. 砍掉与延后

• 锦上添花但不影响核心价值：延后。

• 增加认知负担且收益不明确：砍掉。

• 没有完美方案时，优先“刚好能用”的可迭代版本。

AI Agent 行为要求

设计前（必问）

• 如果只能保留一个能力，应该保留什么？

• 当前方案是否比上一版更复杂？复杂度收益比是否成立？

• 是否存在更直接、更短路径的实现？

实施中（必做）

• 对每个新增模块/抽象说明其核心价值贡献。

• 若无法明确贡献，主动提出“删除或延后”建议。

• 当用户追求大而全时，优先提供“最小可行实现 + 后续迭代路径”。

评审时（必检）

• 是否出现了与核心目标无关的复杂度扩张。

• 是否可以通过减少层级/减少分支/减少接口来简化。

• 是否保留了清晰的默认路径（happy path）。

分层落地（Progressive Disclosure）

• references/project-level.md ：项目级聚焦与取舍

• references/system-level.md ：系统级复杂度预算与架构简化

• references/module-level.md ：模块级边界与依赖简化

• references/code-level.md ：代码级结构与抽象简化

• references/function-level.md ：函数级控制流与职责简化

反模式（必须避免）

• 为“以后可能会用”而提前设计复杂结构。

• 用高抽象掩盖尚未稳定的需求。

• 同时推进多个非核心优化导致主线停滞。

• 在没有证据时引入中间层、配置层、插件层。

参考资料

• 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

• 函数级落地