有 pnpm-lock 就 pnpm

仓库有 pnpm-lock.yaml 用 pnpm，有 uv.lock 用 uv。不要对全局 pip install 来「先跑起来」。先跑起来的那几分钟很爽，后面的环境属于谁就说不清。说不清的环境，演示前一定会在评委眼前崩一次。崩的表面是缺包，底子是安装器不属于这个仓库。不属于的绿色，只在我这台机器上绿。绿给自己看可以。绿给评委看，要能换机器再绿一次。

锁文件是真源，口味不是

我更熟的命令会随月份变。有一段时间手写 npm，后来 pnpm，Python 那边有人用 poetry，有人用 uv。手熟不构成理由。理由在仓库根上那份锁文件。锁文件记录的是这个项目承认的安装器。

智链前端是 Vue3 加 TypeScript 加 Vite，按那个仓库的锁和脚本走。个人站是 Jekyll，跟 bundle。检测相关的 Python 仓库，有 uv.lock 就 uv，不要为了「我这台机器已经有一份全局包」就省掉项目环境。全局包版本一漂，别人复现不了，我自己两周后也复现不了。

A 仓库的 lint 规则、目录结构、commit 习惯，不要套到 B。我在同一台机器上同时有全站、智能体、训练、评测。混着用命令，是最常见的脏。脏了之后报错像业务 bug，其实是装错了树。

一次会话一个主仓库

第二个仓库必须点名。home 目录里改项目代码，搜索会扫到整个家。扫到整个家的后果我写过：找到好几份锁文件，改了眼熟的那一份。眼熟不等于当前任务。

cwd 在 $HOME 时，项目级的说明加载不到。agent 会用全局约定去改具体项目。全局约定管行为，不管某个仓库怎么构建。构建以那个仓库的 README 和锁文件为准。这一条我重复写，是因为每次在家目录里偷懒，都会再犯。

并行开两个项目时，我容易把 pnpm 的 --filter 习惯带到没有 workspace 的仓库。命令失败。失败之后若「改配置让它像 pnpm workspace」，就是用 A 的结构改造 B。改造一次，B 的原作者（可能是我自己）下次回来会迷路。

不要对全局 pip install

「先跑起来」的典型操作是：缺包，pip install 到用户环境，import 通了，开干。通了的是这台机器。CI、同学、评委的笔记本，没有这份用户环境。有效 run 的契约里有脚本、split、seed、checkpoint、日志目录。没有「我的 home 里装过什么」。

uv 的好处是项目环境看得见。看得见才谈复现。看不见的全局包，只能写进「我这台机器比较特殊」。特殊两个字不能出现在论文方法和站点对外的句子里。

Node 那边同样。没有锁文件时才谈选哪个安装器。有锁文件还 npm i，会另写一份 package-lock.json，两份锁打架。打架时谁赢取决于谁后写。后写的不一定对。

构建命令跟仓库走

仓库写了 pnpm test 就不要发明 npm test。写了 bundle exec jekyll serve --host 127.0.0.1 --port 4000 就不要直接 jekyll serve。命令能启动不等于链路通，但命令都敲错，链路更通不了。

我报完成之前，至少要有一条会因我写错而失败的检查。检查也要走仓库的门禁，不要走我随手写的脚本。随手脚本会迁就我刚装的全局包。迁就是造假。

给以后的我和以后的 agent

这是给以后的我和以后的 agent 看的。看到锁文件，先认安装器，再认脚本，再改代码。看到第二个仓库，先停。看到全局 install 的冲动，先问：这个包为什么不在项目依赖里。

限制：这篇不规定所有仓库必须 pnpm。有 npm 锁就 npm。有 yarn 锁就 yarn。有 Pipfile.lock 就用那个仓库已经在用的安装器。规定只有一条：别把 A 的习惯套到 B。套了，绿色是 A 的绿色，红的是 B 的现场。

我在 home 里偷懒改项目的次数，比我愿意承认的多。偷懒的标志是：终端提示符还在 ~，已经开始 pnpm i。装完才发现锁文件属于隔壁仓库。隔壁的 node_modules 被我弄脏，当前任务的依赖还没出现。脏一次，要花一晚解释「为什么这个包在，脚本却不认」。解释期间谁也不记得最初只是想改一行文案。所以锁文件不只是安装器的选择，也是 cwd 有没有钉对的检查。钉错了，先停。

一次会话不要混锁文件

智链、TextGuard、这个 Jekyll 仓，锁文件不是同一种。进错仓还按上一仓的习惯装包，会把 node_modules 或全局 pip 搞脏。脏了之后的报错看起来像代码错。先 ls 看锁文件，再决定 pnpm、npm 还是 bundle。cwd 必须是仓库根。在 $HOME 里装的包，不属于任何一个项目。 锁文件就是这个仓的安装器说明书。说明书在，就按说明书。按上一仓的记忆装，是在 $HOME 里改项目的另一种形式。