on-site-project

Files (1)

• SKILL.md

SKILL.md (first lines)

# 驻场外部项目工作方法论

外部项目（非本仓库、陌生代码、第三方工具链）的最大风险不是"活难"，而是三件事：**不了解就动手、上下文丢失、改坏回不去**。这套方法论就围绕化解这三个风险，并且**保持轻量——只做必要动作，不为了做而做**。

| 风险               | 后果                              | 对应的原则                 |
| ------------------ | --------------------------------- | -------------------------- |
| 不了解上下文就动手 | 改错模块 / 改坏无关功能           | **先了解，再动手**         |
| 长会话上下文丢失   | 新开会话不知道之前确认/排除了什么 | **留过程文档**，不靠记忆   |
| 改坏无法回退       | 用户真实数据受损                  | **先确认版本控制，再备份** |

## 一、先了解，再动手（动手前的必做清单）

在改任何东西之前，先建立"我到底改的是什么"的认知。**没有这个认知，后面一切排查都是盲试。**

1. **项目是什么 / 技术栈**：类型、构建/运行/启动方式、入口；数据与资源格式（能否解包/打包？有无现成工具链？）
2. **改动目标**：用户到底要什么**结果**（行为级表述，不是"改某文件"）；需求原始来源。
3. **改动影响面**：动的是哪一层（数据 / 逻辑 / 资源 / 引擎）？**哪些模块与当前改动相关**——改 A 会不会连带 B？列出相关模块清单并逐一确认。
4. **术语表（领域词汇）**：外部项目有行话（引擎 / 脚本 / 资源名 / 编号……），建术语表让长会话里所有人说同一种语言。
5. **文件位置清单**：目标文件、工具链、`_catwork` 工作区、备份/基线各在哪。

## 二、先确认版本控制，再决定备份方式

**不要假设外部项目有没有版本控制。** 先确认，再按结论做事——两个方向是完全不同的做法：

| 情况           | 做法                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| **有版本控制** | 优先用它：开分支 / 建 worktree 做隔离，改动可 diff、可回退，**通常无需手动备份**（但仍要记录"改了哪些文件"） |
| **无版本控制** | 必须手动建基线 + 备份每个要覆盖的文件                                                                        |

无论哪种，都要**记录当前状态**（关键文件 md5 / 版本 / 字节数）。这是"能否放心改"的地基。

## 三、可逆性（仅无 VCS 时需要）

只在确认**无版本控制**时才需要这层手动安全网（有 VCS 走分支即可）：

- 改前备份每个要被覆盖的文件（`xx.bak` / `xx.orig-backup`）
- 无损切换：切换前确认原版备份在、切换后确认新版 md5
- 保留多个版本（全量 / 隔离 / 原版），可随时回切
- **没有备份就改外部项目 = 拿用户数据冒险**

注意：备份是**为了能大胆试错**，不是目的本身——**不要制造一堆没人用的备份给用户添负担**。

## 四、工作隔离 + 驻场工作区（集中 + 持久，重点）

外部项目往往有"用户真实数据"或"运行进程监控的目录"，**隔离做不好，实验产物会污染目标、触发自动构建，或被版本管理扫走**。同时驻场是**跨长会话**的事——不能下次再来时，上次的产物和结论丢得干干净净。

**工作隔离**：

- 动手前先造一条可回退路径，**确认能还原之前，不动目标的原始数据**。
- 一次实验只改一个隔离变量（见第六节单变量隔离）；隔离包/隔离目录单独命名（如 `iso-variant-XX`），**不覆盖当前生效的那个**。

**驻场工作区（我们自己的地盘，一个文件夹装一切）**：

- **给这个外部项目建一个专属工作区 `_catwork`**，这是**我们在项目里的地盘**。全部临时/分析产物（分析脚本、解包产物、对比结果、隔离包、过程文档）都收进这一个文件夹——**集中度，不散落**。找数、清理、交接都只认这一个路径。
- **它是跟着外部项目走的持久工作区，不是一次性 scratch**：下次继续驻场，回到这个项目就能在工作区里找回上次的所有产物和结论——**不然内容就全丢了**。所以它放在**稳定、可再次定位**的位置；所在目录若在某 VCS 内**立即 gitignore**（防止自己被版本管理扫走、或污染项目仓库——这是放项目里唯一要防的，用 gitignore 解决，而不是靠搬到项目外）。
- 结构：`<外部项目>/_catwork/`（或项目同级 `<外部项目>_catwork/`），一个项目一个工作区，多项目互不混。
- **把 `_catwork` 的绝对路径记进过程文档**（"文件位置清单"），长会话 / 下次驻场靠它找回一切。
- 文件名清晰：`_deployed_` / `_verify_` / `_tmp_` 前缀 + 用途，避免与正式产物混淆。

## 五、过程文档（让工作持续可信）

**铁律：长会话靠文档续命，不靠记忆。** 会话到一定长度必须沉淀成一份"过程文档"，新开会话先读它才不跑偏。

必备章节：

| 章节               | 内容                          |
| ------------------ | ----------------------------- |
| 一句话现状         | 改到哪了、卡在哪              |
| 已完成链路         | 已验证通过的改动链            |
| **已确认的事实链** | 每个测试/结论标 ✅/❌         |
| **已排除的假设**   | 走错过的方向 + 证伪方式       |
| **工作教训**       | 自己犯的错、被纠正的点        |
| 下一步             | 明确待办 / 分支               |
| 文件位置 + 术语表  | 工具 / 数据 / 临时产物 / 词汇 |

**关键：事实链用表格 + ✅/❌ 标记**，让"哪个确认了、哪个还没确认"一目了然。术语表单独存放、长期维护，与正文隔开（它不随单次排查结论变化）。

## 六、单变量隔离（排障的黄金法则）

一次只改一个变量：

- 不要同时改多个潜在因素
- 构造"只改 A、其余保持原样"的对比包
- 用 ✅/❌ 对比结果锁定触发变量

**用数据逼近真相，而不是重复猜测。**

## 七、实测验证，不轻信工具

**工具（尤其启发式/自写的）不等于系统真实解析器。** 自写/第三方工具的判定逻辑，先想清楚"它真的是系统在用的那个吗？"

- 结论能用**实测结果**（用户运行不崩/崩、真实报错）验证的，就不要停在"工具说干净"
- **用户的实测反馈是最硬的证据**，用户的方向常比静态扫描准

## 八、诚实认错，从失败中修正

外部项目最忌"死要面子继续猜"：

- 承认"这条线走错了"、"这个工具不可靠"、"你的方向对"
- 把"走错的路"写进过程文档的"工作教训"，避免自己或下一会话重蹈覆辙

---

## 工作流

```
接外部项目任务
  ↓
【先了解】技术栈 / 改动目标 / 影响面 / 相关模块 / 术语表 / 文件位置（先不动手）
  ↓
【确认 VCS】有无版本控制 → 有则开分支，无则手动基线+备份
  ↓
【隔离】建 `_catwork` 驻场工作区（项目自己的地盘，集中+持久，gitignore 防污染）→ 记录路径
  ↓
【改动】改 → 打包 → 部署 → 记录（确认 / 未确认）
  ↓
每次实测反馈 → 更新过程文档（事实链）→ 需要时做单变量隔离
  ↓
遇到反复失败 → 载入 break-tunnel-vision skill

From JianHun101/catStudio, MIT.

More from JianHun101/catStudio