Skip to content

principles.md

Latest commit

 

History

History
83 lines (57 loc) · 3.91 KB

principles.md

File metadata and controls

83 lines (57 loc) · 3.91 KB

CodeSee 设计原则

项目长期维护的硬约束。任何代码改动违反这里任一条都应该被打回重做。

核心原则

原则 1：语义控制权归 AI / features.json

项目长什么样、节点叫什么、谁先谁后、怎么分组、谁连谁——都由 AI 写进 features.json，不要写死在前端。

判断标准：如果这个决策"换个项目就要重新做一次"，它属于语义层，必须放 JSON 里。

原则 2：视觉与交互能力归前端

渲染、布局算法、拖动、缩放、动效、容错、视觉系统——前端独占。

判断标准：如果这个能力"任何 features.json 都需要"，它属于通用能力，写在前端。

原则 3：不确定就让 AI 显式写出来

前端不做启发式推断。AI 知道答案就让它写出来。

例如：

  • 不要在前端"按某种规则推断 Epic 之间的主线"——让 AI 写 epic_flow
  • 不要在前端"按目录路径猜业务名"——让 AI 写 epic.name
  • 不要在前端"按代码复杂度估算 confidence"——让 AI 自己评估

职责边界

| 类型              | 归属          | 例子                                            |
| ----------------- | ------------- | ----------------------------------------------- |
| 项目 / 业务相关   | features.json | 节点顺序、命名、分组、关系、注释、置信度        |
| UI 通用能力       | 前端          | 拖动、缩放、选中、详情面板、视图切换、搜索      |
| 视觉系统          | 前端          | 颜色、字体、间距、动效、暖白主题                |
| 兜底 / 容错       | 前端          | 未知 enum 不崩、ErrorBoundary、自适应布局       |
| 布局算法实现      | 前端          | ELK / dagre / 网格 / 测量后布局——但顺序由 JSON 决定 |

反例对照（违反原则的常见诱惑）

| 看起来"很聪明"的做法                              | 违反原则 | 正确做法                              |
| ------------------------------------------------- | -------- | ------------------------------------- |
| 前端启发式生成 epic_flow（看 cross_feature 推断） | 原则 3   | 让 AI 写 epic_flow                   |
| 前端按目录前缀自动分组                            | 原则 1   | 让 AI 写 epicId                       |
| 前端按节点边数算 confidence                       | 原则 3   | 让 AI 评估 confidence                 |
| 节点固定宽度 280px 写死                           | 原则 2   | 自适应宽度 + 测量后布局               |
| 前端按依赖路径自动推断 step 顺序                  | 原则 1   | 让 AI 写 flow 边                      |
| features.json 里写视觉相关字段（如颜色）          | 原则 2   | 视觉由前端按 role/kind 映射           |

自检清单

每次想在前端写 if (xxx) ... 或启发式逻辑前，问自己：

  • 这个决策换个项目会变吗？
    • 会变 → 应该让 AI 写进 features.json
    • 不会变 → 前端写
  • 这是"渲染怎么做"还是"渲染什么内容"？
    • 怎么做 → 前端
    • 什么内容 → JSON
  • AI 知道答案吗？
    • 知道 → 让它写出来，前端按字段渲染
    • 不知道（如视觉细节） → 前端硬编码

任一条命中"应该让 AI 写"，就别在前端写。

历史教训（违反原则导致的返工）

  • 力导向作为概览主布局：违反原则 3——力导向是探索算法，给不出"主线"。改为让 AI 写 epic.order，前端按 order 排。
  • 节点固定宽度：违反原则 2——视觉决策被语义文件影响（features.json 长度可能让节点超出固定宽度）。改为自适应 + 测量后布局。
  • 静态分析（早期 ts-adapter）：违反原则 1——结构层是代码事实，但语义层 AI 才知道。整套 ts-adapter 退役，改为 AI 直接产出 features.json。