开发环境治理 · 更新 2026-06-27

Project Setup Contract Checklist：mise、uv、工具版本、环境规则、Tasks、README 与 CI Parity

面向团队的实用清单：把项目 setup 变成可 review 的契约，而不是散落的 README 步骤、shell history、CI drift 和口口相传。

Project setup contract 是一份书面协议，告诉一台干净机器、新同事和 CI 如何进入 repository。它明确 tools、versions、environment rules、tasks、secrets boundaries 和 review owners，让开发环境可复现。

mise 是这份 checklist 的天然中心，因为它能 pin tools、加载项目环境规则并定义 tasks。uv 负责 Python dependency/project behavior。gstack 式 workstation baseline 与 Claude Code、Codex CLI 这类 coding agents 进一步放大了 setup contract 的重要性：如果 agents 和 humans 不是用同一环境进入项目，自动化结果就难以信任。

RepoDaily 判断

把 project setup 当成代码。用 `mise.toml` 这类可 review source of truth 写清工具版本、安全环境规则和常用 tasks；secrets 不进仓库；README 和 CI 使用同一组命令；setup 变更应像 build 或 deployment 变更一样认真 review。

快速矩阵

契约区域	定义什么	好默认值	Review 触发条件
Tools	Node、Python、uv、pnpm、Terraform、cloud CLIs、linters、formatters	在 `mise.toml` pin exact 或 policy-approved versions	Tool version change 影响 build、deploy、tests 或 generated output
Python workflow	uv commands、lockfile policy、Python version、private indexes	uv 负责 Python sync/run；mise pin uv 和 Python	Lockfile、index、Python version 或 publish behavior 改变
Environment	Non-secret defaults、local-only files、secret-manager boundaries	写 examples；绝不提交 real secrets	变量涉及 credentials、production、billing、user data 或 cloud accounts
Tasks	dev、test、lint、build、format、typecheck、docs、release	用 `mise run` 或同类方式暴露常用命令	Task 会 deploy、delete、migrate、改 infra 或 call external services
README	Single clean-machine path 和 fallback notes	README 调用与 CI 相同的 setup commands	Docs 偏离 `mise.toml`、uv lock 或 CI commands
CI parity	Install、cache、test、lint、build、release command alignment	CI 尽量 mirror documented local commands	CI 使用 hidden scripts 或不同 tool versions
Ownership	谁 review setup changes 和 tool upgrades	为 setup files 设置 CODEOWNERS 或明确 maintainers	任何 setup contract file changes
Agent readiness	Coding agents 是否能在此 repo 运行 tasks	Agents 使用相同 setup contract 和 denied-command policy	Agent tools 需要额外 env、MCP、hooks 或 secrets

Setup Contract 成熟度评分卡

在说 onboarding 可复现前，先给 repository 打分。

维度	0 分	1 分	2 分	Reviewer 问题
Single source of truth	README、CI、本地步骤不一致	有部分共享 commands	`mise.toml`/README/CI 对齐	新开发者从哪里开始？
Tool pinning	Versions 隐式	部分版本 pinned	Critical tools pinned 且有 owner	哪个 tool change 会破坏输出？
Env/secrets boundary	Secrets 不清楚	有 examples	Secret boundary 和 local overrides 已记录	什么可以安全提交？
Task authority	Tasks 散落各处	有 common tasks	Tasks 有 risk levels 和 owners	哪个 task 能修改 infrastructure？
CI parity	CI 用 hidden workflow	部分 mirror local	CI 和 README 共享 commands/versions	CI 能复现 local setup 吗？
Change review	Setup changes 无 owner	Ad hoc review	Setup files 有 owners 和 checklist	谁批准 `mise.toml` 变更？

30 分钟 Project Setup Contract 测试计划

在标准化 mise 或重写 onboarding docs 前使用。

0–5 分钟：setup inventory

列出 README commands、CI commands、tool versions、env files、task runners 和 release scripts。

成功标准当前 setup surface 可见。

5–12 分钟：contract draft

起草或检查 `mise.toml`，包含 tools、safe env defaults 和 dev/test/lint/build tasks。

成功标准新开发者能看到预期 setup path。

12–18 分钟：clean-machine thought test

假设机器没有 Node、Python、uv 和 secrets，会发生什么？

成功标准Install、secret 和 fallback 缺口明确。

18–24 分钟：CI parity check

比较 README commands 与 CI commands，并记录每个有意差异。

成功标准CI 与 local setup 已对齐或差异已记录。

24–30 分钟：ownership decision

分配 setup files、task authority 和未来 tool upgrades 的 owners。

成功标准Contract 有 reviewers 和 next review date。

契约决策流程

盘点当前 setup：README commands、CI commands、package managers、Python versions、Node versions、env files、task runners 和 release scripts。
选择 contract surface：`mise.toml` 管 tools/env/tasks，uv 管 Python dependencies，语言 package-manager files 管依赖，README 管人类入口。
只把稳定、非 secret defaults 放入 contract。Secrets 放 secret manager 或 ignored local files，并提供文档 examples。
定义 task risk levels：safe local tasks、network tasks、mutation tasks、deploy/release tasks 和 prohibited commands。
让 CI 调用与 README 相同的核心命令，或记录每个有意差异。
分配 ownership 和 review rules，避免 setup changes 静默漂移。

场景表

场景	契约模式	不要这样做
Python application	mise pin Python 和 uv；uv 管 lock/sync/run；README 和 CI 用 `uv sync` / `uv run`	让开发者随机选 Python version，而 CI 用另一个
Polyglot web app	mise pin Node、pnpm、Python、uv、Terraform；tasks 暴露 dev/test/build	把一半 setup 藏进个人 shell aliases
Infra-heavy repo	Tasks 标注风险；deploy/migrate 需要 owners 和 approvals	把破坏性 deploy 命令藏在随意的 `run deploy` 后面
Agent-enabled repo	Coding agents 使用相同 setup contract，加 denied paths 和 command policy	让每个 agent 从 README 猜 setup commands
Open-source project	保持 setup minimal、portable，并提供 fallback commands	要求私有 workstation stack 却不解释
Notebook or learning repo	Pin Python 和 uv，记录 data source 和小型可复现命令	把大输出或 private datasets 当 setup shortcut commit
Legacy repo	分阶段引入 contract：先 pin tools，再 tasks，再 CI parity	无 fallback 或 owner review 就重写所有 setup 规则

Setup Contract 风险清单

Secret leakage

环境便利可能变成凭证泄露。不要把 real tokens、production URLs 或 private datasets 作为 defaults commit。

Task authority creep

无害 task runner 可能变成部署面。按风险标注 tasks，并对 mutation tasks 要求 review。

Duplicate sources of truth

如果 README、CI、mise、package scripts 和 Makefiles 互相矛盾，onboarding 又会变成猜谜。

Unowned tool upgrades

Tool versions 会改变 generated output、lockfiles 和 deploy behavior。Setup files 需要 owners。

Agent mismatch

Coding agents 只有在同一环境里运行、遵守同一 command policy 时才可靠。

Overfitted local setup

Contract 应该可复现，而不是把一个人的 laptop preferences 倒进去。

实施模式

`mise.toml` as contract

用 `[tools]` 管版本，`[env]` 只放 safe defaults，`[tasks]` 放 reviewed commands。

README mirrors contract

让第一 setup path 很短：install mise、run install、run test、run dev。例外情况放在 happy path 后面。

CI parity check

CI 应使用相同 pinned tools 和 core commands；若有差异，必须记录原因。

Risk-labeled tasks

把 tasks 标为 safe、network、mutation、deploy 或 release，让 humans 和 agents 知道哪些需要审批。

Secret boundary file

用 `.env.example` 或 docs 写变量名，真实 secrets 走 manager 或 ignored local file。

Setup change checklist

每个 setup change 回答：改了什么、谁受影响、CI 如何证明、如何 rollback。

常见问题

给把 setup 转成 contract 的团队提供简短答案。

`mise.toml` 是用来替代 README 吗？

不是。`mise.toml` 可以作为 executable contract，README 解释 happy path、prerequisites 和 exceptions。

Secrets 应该放进 mise env settings 吗？

只放 safe defaults 或非 secret examples。真实 secrets 应来自 secret manager 或 ignored local files。

uv 在 setup contract 里怎么分工？

uv 负责 Python dependency sync、lockfiles 和 Python project commands；mise 负责 pin uv、Python 以及其他 tools。

CI 应该使用 mise 吗？

如果 mise 是项目 source of truth，通常应该。若 CI 不同，记录原因并保持版本对齐。

来源

Feedback

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

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

报告过期或缺失的证据