开发环境审计 · 更新 2026-06-27

Developer Environment Drift Audit：README vs mise.toml vs CI vs Package Scripts vs Agent Tasks

一份实用审计清单：检查本地开发机、README、mise、uv、CI、package scripts、env examples 与 coding-agent task rules 之间的 setup 漂移。

Developer environment drift 发生在项目 setup contract 写完之后，但现实继续变化。README 写一套，CI 跑另一套，`mise.toml` pin 了不同工具，package scripts 藏着额外命令，`.env.example` 过期，coding agents 又从旧文档学到了错误 workflow。

这份 audit 给团队提供周期性方法，用来比较 declared setup contract 与 clean machines、CI runners、local shells、agent workspaces 上实际发生的事。它是采用 mise、uv、project setup contract 和 agentic coding governance 之后的维护层。

RepoDaily 判断

当 tool versions、CI images、onboarding docs、package managers、environment variables 或 agent task rules 变化时，就应运行 drift audit。目标不是更漂亮的 README，而是一条 humans、CI 和 coding agents 都能遵循的可复现 setup path。

快速矩阵

漂移表面	比较什么	健康信号	漂移信号
Tool versions	`mise.toml`、lockfiles、CI image、README	Node/Python/uv/pnpm/Terraform 版本一致 pinned	README 写 Node 20，mise pin 22，CI 用 latest
Python workflow	uv commands、pyproject、uv.lock、CI setup	README 和 CI 都用 `uv sync` / `uv run`	本地用 uv，CI 仍手动装 requirements
Package scripts	package.json、Makefile、mise tasks、docs	Tasks 调用同一 shared command path	npm scripts 藏了 README 没写的 flags
Environment variables	.env.example、mise env、CI secrets、docs	变量名和 secret boundaries 一致	CI 需要本地从未记录的变量
Build and test commands	README、CI YAML、mise tasks、package scripts	一个 documented command 能复现 CI core checks	CI 只因 hidden setup 才能跑
Agent task rules	CLAUDE.md、Codex policy、denied paths、task docs	Agents 使用相同 safe commands 和 denied-path policy	Agents 从 stale README fragments 猜 setup
Release path	release scripts、CI deploy jobs、README、tasks	Deploy/release tasks 标注风险并有 owner	Release 使用未记录的本地 credentials 或 versions
Onboarding evidence	fresh clone、clean machine、PR review notes	新开发者无需 private context 就能 setup	Setup 依赖问唯一知道的人

Environment Drift 评分卡

在声称 setup 可复现前，先给每个 repo 打 0–2 分。

审计区域	0 分	1 分	2 分	审计问题
README parity	过期或不完整	大体正确	匹配当前 setup 和 CI	新同事今天能照着做吗？
mise/uv alignment	缺失或矛盾	部分一致	Pins 和 commands 匹配真实 workflow	Tool pins 匹配 CI 跑的吗？
CI transparency	Hidden setup	有部分 docs	Core CI commands 已本地记录	本地能复现 CI failure 吗？
Env hygiene	变量未知	有 examples	Secret boundaries 和 examples 被维护	哪些变量是 secret，来自哪里？
Task ownership	无 owner	非正式 owner	Tasks 和 setup files 有 reviewers	谁批准 setup drift fixes？
Agent compatibility	Agents 靠猜	有部分 guidance	Agent rules mirror setup contract	Claude/Codex 会跑同一条 safe path 吗？

30 分钟 Developer Environment Drift Audit

在 release、onboarding 或 agent rollout 前，对一个 repository 使用。

0–5 分钟：surface inventory

列出 README、mise.toml、pyproject/uv.lock、package scripts、Makefiles、CI YAML、env examples 和 agent docs。

成功标准所有 setup surfaces 可见。

5–12 分钟：local path check

从 clean perspective 运行或检查 documented install、test、build、dev commands。

成功标准Local happy path 已知，或 gaps 明确。

12–18 分钟：CI path check

比较 CI image、install steps、cache、commands、versions 和 secret injection 与本地 docs。

成功标准CI differences 被标为 intentional 或 drift。

18–24 分钟：env and agent check

比较 env examples 与 CI/runtime variables，并检查 agent instructions 的 safe commands。

成功标准Secrets 与 agent commands 匹配 policy。

24–30 分钟：drift fix decision

选择 source of truth，分配 owner，打开 drift PR，或安排 deeper audit。

成功标准Audit 产生具体 next change，而不只是 notes。

Drift Audit 流程

从 clean clone 开始列出所有 declared setup surface：README、`mise.toml`、uv files、package scripts、Makefiles、CI YAML、env examples、CLAUDE.md 和 agent policy files。
记录真实 local happy path：install tools、sync dependencies、run tests、run build、start dev server。
记录真实 CI path：image、install steps、cache、commands、secret injection、build/test/deploy jobs 和 version pins。
逐行比较 local、CI、docs 和 agent rules，把差异标为 intentional、stale、unknown 或 dangerous。
先修最小 source of truth：更新 `mise.toml`、uv lock、README、CI commands 或 task definitions，让一条路径权威。
分配 owners 和下一次 audit date，避免 drift 静默回来。

场景表

场景	审计重点	修复模式
新开发者无法启动项目	README vs clean-machine setup	重写 happy path，补 missing tool pins
CI fail 但 local pass	CI image、cache、command flags、env vars、tool versions	让 CI mirror README 或记录有意差异
uv 迁移只做了一半	uv.lock、pyproject、CI install、old requirements files	选择 uv 为 source of truth 或标记 optional
mise 被采用但没人用	mise.toml vs package scripts vs CI	让 README 和 CI 调用 mise-backed commands
Agent-generated PR 用错命令	CLAUDE.md/Codex policy vs setup contract	更新 agent instructions 和 denied-command policy
Release 依赖某台 laptop	release task、credentials、tool versions、CI deploy path	迁移到有 owner 的 task/CI path，并明确 secret manager rules
Env examples 过期	.env.example、docs、CI secrets、runtime config	重新生成 example names，并分类 secret/non-secret values

Drift 风险清单

False reproducibility

绿色 CI badge 不证明本地 setup 可用，一台能工作的 laptop 也不证明 CI 能复现。

README archaeology

旧 setup instructions 会训练 humans 和 agents 运行过期命令。

Hidden CI behavior

未记录的 install flags、cache keys 和环境变量让 failure 难以本地 debug。

Secret drift

Environment variables 的名称、来源或含义可能变化，而 `.env.example` 或 docs 没更新。

Tool version split-brain

Developers 和 CI 使用不同 tool versions 时，generated files 和 lockfiles 会漂移。

Agent drift amplification

Coding agents 会放大 stale docs，因为它们跑错 setup steps 比人类更快。

Audit 实施模式

Clean-machine audit

在没有预装项目工具的机器或 container 上跑 happy path。

Command inventory

从 README、CI、package scripts、mise 和 Makefiles 列出所有 setup、test、build、dev、release、deploy commands。

Version diff

比较 mise、package manager、lockfiles、CI image 和 runtime logs 里的 tool versions。

Env diff

按变量名和含义比较 `.env.example`、docs、CI secrets、runtime config 和 secret-manager entries。

Agent dry run

检查 coding-agent instructions 认为哪些命令安全，再确认它们匹配 project setup contract。

Drift PR template

每个修复 PR 写清 drift found、source of truth、files changed、local proof、CI proof 和 next audit date。

常见问题

给审计 developer environment drift 的团队提供简短答案。

多久做一次 drift audit？

Release 前、toolchain migration 后、onboarding 前，以及给 repo 启用 coding agents 前都应该做。

Drift 一定是坏事吗？

不一定。CI 可能故意不同于本地 setup。问题是 undocumented 或 unowned drift。

最好的 source of truth 是什么？

通常是小组合：`mise.toml` 管 tools/tasks，uv files 管 Python dependencies，README 管人类路径，CI 做 enforcement。

为什么 environment audit 要包括 coding agents？

Agents 会读 docs 和运行 commands。如果 setup docs 过期，agents 会很快放大错误。

来源

Feedback

这页是否帮助你做出决定？

匿名反馈只用于判断内容是否真正有用。

报告过期或缺失的证据