# 评估"该不该改"前必须先看项目现有基础设施

**日期**: 2026-05-10
**触发场景**: simplify logging-system 模块时，AI 跳过基础设施核查直接给出错判
**类别**: 工作方式 / 决策过程

---

## 现象

simplify logging-system 模块时，前端发现两类"违规":

1. **125 处颜色硬编码** (`#3370ff` / `#f7f8fa` / `#1f2329` ...)
2. **7/8 page 完全没用 i18n**（locale 文件 zh.ts/en.ts 各 430 行 keys 闲置）

AI 第一次判断给用户的标签：
- 颜色硬编码 → "跨多页样式重构成本太大，**风险中**，下一轮再做"
- i18n 修复 → "工作量大，**单独大坑**"

用户追问"这两个改一下不更好吗"，AI 才去看 `frontend/src/app/globals.css`，结果发现：

```css
:root {
  --lark-blue: #3370FF;        /* ← 页面里的 #3370ff 硬编码 */
  --bg-primary: #FFFFFF;
  --bg-secondary: #F7F8FA;     /* ← 页面里的 #f7f8fa 硬编码 */
  --bg-tertiary: #EFF0F2;
  --text-primary: #1F2329;     /* ← 页面里的 #1f2329 硬编码 */
  --text-secondary: #646A73;
  --text-tertiary: #8F959E;
  --border-color: #E3E5E8;
  --success: #00B42A;
  --warning: #FF7D00;
  --error: #F53F3F;
  /* ... */
}
```

设计 token **早就完整定义好了**——9 类硬编码色号，~90% 直接对得上现成 `var(--xxx)`。这不是 "AI 自己定 token，未来跟设计师对齐时返工" 的风险——是**现有基础设施没用上**的违规。

判断从"风险中、下一轮再做" → "该改、机械化替换、本 PR 一起做"，结论 180° 反转。

---

## 根因

AI 评估"颜色 token 化成本"时，**默认假设了项目没有 design token 体系**——这是个未经核实的前提。代价：给用户一个偏保守、错误标签化为"另一个大坑"的判断。

类似的失误模式：
- "i18n 修复成本大" → 没先看 `locales/` 是否已有完整 keys
- "抽公共组件成本大" → 没先看 `components/common/` 是否已有可复用基底
- "改这个 utility 成本大" → 没先 grep 是否已有同义函数

---

## 学到的规则

**评估"该不该改 / 改得起"前，先用 ≤2 条命令核查项目是否已有基础设施**：

| 主题 | 核查命令（一条） |
|---|---|
| Design token | `grep -E "^\s*--" frontend/src/app/globals.css` 或 `cat tailwind.config.* \| grep -A20 colors` |
| i18n | `wc -l frontend/src/locales/<module>/{zh,en}.ts` + `grep -c "t\.<module>\." frontend/src/app/.../page.tsx` |
| 共用组件 | `find frontend/src/components -type f -name "*.tsx" \| xargs grep -l "<keyword>"` |
| 后端 utility | `grep -rn "function <keyword>" backend/src/common backend/src/core` |

**判定逻辑**：
- 基础设施已就绪 → 改动是"修复使用违规"，机械化、低风险，**该做**
- 基础设施缺失 → 改动是"建新体系"，需要 owner 对齐，AI 不该单方面定，**别做或先问**

成本估算的措辞要分清楚：
- ❌ "改动量大、风险中" — 模糊，把"建体系"和"修违规"混在一起
- ✅ "已有 design token，125 处机械替换 → 低风险" / "无 design token，要先跟设计师定 token 命名 → 不该单方面做"

---

## 适用范围

- 任何"该不该把 X 抽出来"的判断
- 任何"用现有规范还是新建一套"的判断
- 评估前端样式/i18n/utility/组件类改动成本时

不适用于：业务逻辑改动（业务规则不存在"现有基础设施"概念）。

---

## 相关 PR / commit

- 本次 PR: `chore/simplify-logging-system` (第一阶段 simplify 已提交)
- 后续 PR: 颜色 token 替换 / i18n 修复（用户拍板都走单独 PR）