# Code Renew

> 代码/项目升级手术——对"能跑但毛病多/死改改不出来"的项目做先诊断后分期的全面升级。用户说"全面升级/迭代升级/大重构/代码体检/这项目帮我做一次升级手术"时使用。流程：先备份→三路独立诊断（逐行审代码+浏览器截图巡检+关键数字独立核算）→分期施工提案拍板→每期改-守门-实测-commit→收工沉淀，绝不盲改。English triggers - "full overhaul", "code health check", "renovate this project", "I keep fixing this and it keeps breaking". Diagnose first, never patch blindly.

- Skill: `yiweicreates/code-renew` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yiweicreates/code-renew`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yiweicreates/code-renew/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: YiweiCreates (https://skillmd.com/u/yiweicreates)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yiweicreates/code-renew

---


# 代码升级（code-renew）· 代码/项目升级手术

> **一句话**：对一个"能跑但有很多毛病/死改改不出来"的项目，做一次**先看清、再设计、后动刀、步步验证**的全面升级手术。适用于网页/工具/脚本类项目；视角 = 资深工程师 + 高级审美设计师双线。
>
> 实战出身：一次真实项目的四期升级手术（41 项诊断 → 四期施工 → 全部实测验收），本文所有铁律和踩坑都来自那次手术及后续实战。

---

## 〇、定位与触发

**什么时候用**：
- 项目"能用但到处是小毛病"，零敲碎打改不动了
- 同一个问题反复改反复回潮（"死改改不出来"）
- 想把工具升格成作品（实用 + 审美双跃升）
- 接手一个别人/过去的自己写的、没人完全看懂的代码库

**什么时候不用**：单点小修（直接改）；纯新功能开发（不需要先诊断旧账）；纯数据录入。

**触发词**：全面升级 / 迭代升级 / 大重构 / 代码体检 / 这项目帮我做一次升级手术

---

## 一、八条铁律（违反任何一条 = 手术事故）

1. **备份先行**：动刀前整包 zip 进 `_backup/`（gitignore 掉），`unzip -t` 校验。出事解包回滚。
2. **先看清全貌，再动第一刀**：诊断与治疗严格分离。诊断期一行业务代码都不许改。
3. **找根因，不打症状**：症状在哪层，根因常在上一层。沿数据流问三次"这个值是谁给的"。
4. **用证据，不用感觉**：关键数字用独立实现对数；修复后用脚本/浏览器实测；"我觉得好了"不算数。
5. **机器查机械错，人查品味错**：穷举型问题（字号失控/死代码/硬编码色）交给 grep 和脚本；体验型问题（动效讲不讲故事/层级有没有焦点）必须亲眼看截图。
6. **死代码先清再建**："改了没反应"的第一嫌疑人是死代码和被覆盖的声明。先 grep 引用计数确认死透，再整块删。
7. **按依赖分期：地基(bug/性能) → 行为(交互/叙事) → 视觉(艺术层) → 精修(排版/模式/适配)**。在坏架构上调表层是"死改"的最大根源。
8. **每期一个 commit，每期独立实测验收**。损失隔离在一期内；commit 信息写清做了什么为什么。

---

## 二、五幕流程

### 第〇幕 · 备份与边界（10 分钟）
1. `zip -rq _backup/项目_升级前备份_$(date +%Y%m%d_%H%M).zip 项目目录 -x 排除项` + 校验 + gitignore。
2. **问用户拿决策**（一次问全）：施工优先顺序？技术栈边界（能否上构建工具/新依赖）？特殊模式需求（如展示/工作台分离）？移动端投入深浅？——拿到授权再开工，避免做完被推翻。

### 第一幕 · 三路独立诊断（核心，约占总时长 1/4）
并行三路，互相不通气，最后交叉：
- **路 A·代码审查**：派子代理**逐行读完**核心代码（大文件分给多个代理：逻辑 JS 一个、样式+结构一个）。指令要求：按严重度分组（必修 bug / 交互缺陷 / 性能 / 动效生硬 / 代码债），每条带行号和证据，"只报真实存在的问题，引用具体代码为证"。
- **路 B·亲眼巡检**：本体用自动化浏览器把**每一种页面状态**截图过目（每个 tab、每个弹窗、每个模式、播放中、窄屏 ≤430px）。看的是层级、对齐、焦点、文案、动效节奏——审美问题全在这一路。
- **路 C·数据核算**：对页面展示的关键统计数字，用 Python **独立实现同一套口径**算一遍对数。对不上的就是 bug（实战曾靠这一路抓到"停留记录双端 +1 导致全部计数虚高"）。

产出：**诊断文档落盘**（不是聊天里说说），全部问题编号、分级、注根因。

### 第二幕 · 提案与拍板（短）
把诊断收口成分期施工提案（每期：目标/清单/验收标准），连同关键概念决策（如双模式、技术栈）抛给用户拍板。**提案本身落盘**，将来可追溯"为什么这么改"。

### 第三幕 · 分期施工（主体）
每期固定节拍：**改 → 语法守门 → 浏览器实测 → commit**。
- 语法守门：`node --check`（JS）/ 括号配平脚本（CSS）/ `python3 -m py_compile`（Python），**每次保存后必跑**，秒级成本。
- 死代码清剿专用手法：grep 引用计数 → 全部引用都在死簇内 → 括号配平脚本整块删 → 残留引用清零检查 → 冒烟。
- 改任何函数前先 grep 它的**全部调用点**——实战中多次靠这个避免"修一处崩三处"（如一个播放停止函数有 8 个调用点、渲染与弹窗的开关顺序冲突）。
- 视觉/动效类改动**必须截图自验**，不能只看代码合理。

### 第四幕 · 收工沉淀
复盘文档（含**新架构速查表**——下个 AI 靠它不用重读全部代码）+ 项目 START_HERE/README 对齐 + push。把这轮学到的"项目特有耦合点"写进复盘，这是给未来省钱的最高杠杆动作。

---

## 三、工具链速查（首选 → 备选 → 兜底）

| 用途 | 首选 | 备选 | 兜底 |
|---|---|---|---|
| 代码全量审查 | 并行子代理（逐行读+行号证据） | 自己分段 Read（大文件按 grep 行号定位区段） | — |
| 视觉巡检/实测 | Chrome DevTools MCP（截图+evaluate+点击） | Playwright（容器版 **file:// 被挡**：起 `python3 -m http.server 8765`，容器内用 `http://host.docker.internal:8765`；截图遇"画面永不稳定"超时→先暂停动画再截） | `open` 给用户亲眼看并截图回传 |
| 语法守门 | `node --check` / `py_compile` | 括号配平脚本（CSS/JSON） | 浏览器 console 看报错 |
| 死代码确认 | `grep -c "\b符号\b"` 引用计数 | 子代理验证调用链 | 注释掉跑一轮（最慢） |
| 数据核对 | Python 独立实现口径对数 | 浏览器 evaluate 读页面值比对 | — |
| 批量机械改 | Python 脚本（正则/块替换，**改前 cp 备份**） | Edit 逐处（≤5 处时） | — |
| 版本管理 | 描述性 commit + push | 若仓库有自动提交插件会抢跑 → `--allow-empty` 打可检索标记 | zip 回滚 |

**MCP 浏览器踩坑备忘**：Chrome DevTools MCP 的标签页可能莫名关闭/实例卡死——`pkill -f chrome-devtools-mcp` 后重连；连续两次失败直接换 Playwright，别耗着。

---

## 四、审美准则（高级设计师视角的升级红线）

1. **Token 化**：字号收敛成阶梯（≤8 级）、间距走 4/8 网格、颜色全走变量（grep 硬编码色清零）、动效统一时长/曲线变量。系统混乱的页面，先立 token 再谈美。
2. **对齐是底线**：四角浮层同一内缩值；同级标题同字号字重；基线对齐。差 2px 也要修——细差最暴露功力。
3. **原生控件 = 廉价感最大来源**：select 必须 `appearance:none` + 自绘箭头；focus 环不许杀（改用 `:focus-visible` 区分鼠标/键盘）；按钮要有 `:active` 按压。
4. **空值优雅降级**："待补/null/undefined" 这类工作台词不许出现在展示面——省略或用"—"，必要时做"工作台/展示"双模式。
5. **动效要讲故事**：镜头跟随当前主体（不是累积范围）、时长随距离缩放、与节拍不打架；数据可视化要有层级（频率→粗细深浅），不能所有元素同权重。
6. **取景按数据不按行政区**：地图/图表的初始视野框"实际有数据的范围"，不为空白留面积。

## 五、反模式（看到自己在做这些就停手）

- 看到症状直接改参数（没读代码就调）
- 没备份就大改 / 没 grep 调用点就改共用函数
- 改完不验证就说"好了" / 验证只在桌面宽屏
- 在死代码或被覆盖的声明上反复改（"怎么不生效？"）
- 一个 commit 塞全部改动（出问题无法定位回滚）
- 用户没拍板就替用户做概念级决策（技术栈/模式/优先级）

## 六、交付验收清单

- [ ] 备份 zip 存在且校验通过
- [ ] 诊断文档落盘（编号+分级+根因）
- [ ] 每期独立 commit，信息可检索
- [ ] 全部修复有实测证据（截图/脚本输出）
- [ ] 窄屏（≤430px）过目
- [ ] 复盘文档含"新架构速查表 + 项目特有耦合点"
- [ ] START_HERE/README 已对齐，已 push

---

## 复制即用启动词

```text
使用 code-renew 对这个项目做一次全面升级手术：
1) 先整包备份 zip 进 _backup/ 并校验
2) 三路独立诊断：子代理逐行审代码 + 浏览器截图巡检全部状态 + 关键数字独立核算，诊断文档落盘
3) 出分期施工提案（地基→行为→视觉→精修），问我拍板优先级和边界
4) 每期：改 → 语法守门 → 浏览器实测 → commit；全部修复要有实测证据
5) 收工：复盘文档（含新架构速查表）+ START_HERE + push
```