0–5 min: surface inventory
List README, mise.toml, pyproject/uv.lock, package scripts, Makefiles, CI YAML, env examples, and agent docs.
Success checkAll setup surfaces are visible.
Developer environment audit · Updated 2026-06-27
Developer Environment Drift Audit: README vs mise.toml vs CI vs Package Scripts vs Agent Tasks
A practical audit checklist for finding setup drift between local developer machines, README instructions, mise, uv, CI, package scripts, env examples, and coding-agent task rules.
Developer environment drift is what happens after a project setup contract is written but reality moves on. README says one thing, CI runs another, `mise.toml` pins different tools, package scripts hide extra commands, `.env.example` is stale, and coding agents learn the wrong workflow from old docs.
This audit gives teams a periodic way to compare the declared setup contract against what actually happens on clean machines, CI runners, local shells, and agent workspaces. It is the maintenance layer after adopting mise, uv, project setup contracts, and agentic coding governance.
RepoDaily verdict
Run a drift audit whenever tool versions, CI images, onboarding docs, package managers, environment variables, or agent task rules change. The goal is not a prettier README; it is one reproducible setup path that humans, CI, and coding agents can all follow without hidden tribal knowledge.
Quick matrix
| Drift surface | Compare | Healthy signal | Drift signal |
|---|---|---|---|
| Tool versions | `mise.toml`, lockfiles, CI image, README | Same pinned Node/Python/uv/pnpm/Terraform versions | README says Node 20, mise pins 22, CI uses latest |
| Python workflow | uv commands, pyproject, uv.lock, CI setup | README and CI both use `uv sync` / `uv run` | Local uses uv, CI still installs requirements manually |
| Package scripts | package.json, Makefile, mise tasks, docs | Tasks call one shared command path | npm scripts hide extra flags not in README |
| Environment variables | `.env.example`, mise env, CI secrets, docs | Variable names and secret boundaries match | CI needs variables never documented locally |
| Build and test commands | README, CI YAML, mise tasks, package scripts | One documented command reproduces CI core checks | CI fails only because hidden setup runs there |
| Agent task rules | CLAUDE.md, Codex policy, denied paths, task docs | Agents use the same safe commands and denied-path policy | Agents invent setup from stale README fragments |
| Release path | release scripts, CI deploy jobs, README, tasks | Deploy/release tasks are risk-labeled and owned | Release uses undocumented local credentials or versions |
| Onboarding evidence | fresh clone, clean machine, PR review notes | New developer can run setup without private context | Setup depends on asking the one person who knows |
Environment drift scorecard
Score each repo 0–2 before claiming setup is reproducible.
| Audit area | 0 points | 1 point | 2 points | Audit question |
|---|---|---|---|---|
| README parity | Outdated or incomplete | Mostly correct | Matches current setup and CI | Can a new teammate follow it today? |
| mise/uv alignment | Absent or contradictory | Partially aligned | Pins and commands match actual workflow | Do tool pins match what CI runs? |
| CI transparency | Hidden setup | Some docs | Core CI commands are documented locally | Can local dev reproduce CI failure? |
| Env hygiene | Variables unknown | Examples exist | Secret boundaries and examples maintained | Which variables are secret and where sourced? |
| Task ownership | No owners | Informal owner | Tasks and setup files have reviewers | Who approves setup drift fixes? |
| Agent compatibility | Agents use guesses | Some guidance | Agent rules mirror setup contract | Would Claude/Codex run the same safe path? |
30-minute developer environment drift audit
Use this plan for one repository before a release, onboarding push, or agent rollout.
5–12 min: local path check
Run or inspect the documented install, test, build, and dev commands from a clean perspective.
Success checkThe local happy path is known or gaps are explicit.
12–18 min: CI path check
Compare CI image, install steps, cache, commands, versions, and secret injection with local docs.
Success checkCI differences are named as intentional or drift.
18–24 min: env and agent check
Compare env examples with CI/runtime variables and check agent instructions for safe commands.
Success checkSecrets and agent commands match policy.
24–30 min: drift fix decision
Choose the source of truth, assign owner, open drift PR, or schedule a deeper audit.
Success checkThe audit produces a concrete next change, not only notes.
Drift audit flow
- Start from a clean clone and list every declared setup surface: README, `mise.toml`, uv files, package scripts, Makefiles, CI YAML, env examples, CLAUDE.md, and agent policy files.
- Record the actual local happy path: install tools, sync dependencies, run tests, run build, and start the dev server.
- Record the actual CI path: image, install steps, cache, commands, secret injection, build/test/deploy jobs, and version pins.
- Compare local, CI, docs, and agent rules line by line; mark differences as intentional, stale, unknown, or dangerous.
- Fix the smallest source of truth first: update `mise.toml`, uv lock, README, CI commands, or task definitions so one path is authoritative.
- Assign owners and a next audit date so drift does not return silently.
Scenario table
| Scenario | Audit focus | Fix pattern |
|---|---|---|
| New developer cannot start project | README vs clean-machine setup | Rewrite happy path and add missing tool pins |
| CI fails but local passes | CI image, cache, command flags, env vars, tool versions | Make CI mirror README or document intentional differences |
| uv migration partially done | uv.lock, pyproject, CI install, old requirements files | Choose uv as source of truth or mark it optional |
| mise adopted but ignored | mise.toml vs package scripts vs CI | Make README and CI call mise-backed commands |
| Agent-generated PR uses wrong command | CLAUDE.md/Codex policy vs setup contract | Update agent instructions and denied-command policy |
| Release depends on one laptop | release task, credentials, tool versions, CI deploy path | Move release into owned task/CI path with secret manager rules |
| Env examples are stale | .env.example, docs, CI secrets, runtime config | Regenerate example names and classify secret/non-secret values |
Drift risk checklist
False reproducibility
A green CI badge does not prove local setup works, and a working laptop does not prove CI can reproduce it.
README archaeology
Old setup instructions train humans and agents to run outdated commands.
Hidden CI behavior
Undocumented install flags, cache keys, and environment variables make failures hard to debug locally.
Secret drift
Environment variables can change name, source, or meaning without `.env.example` or docs being updated.
Tool version split-brain
Generated files and lockfiles drift when developers and CI use different tool versions.
Agent drift amplification
Coding agents amplify stale docs because they can run wrong setup steps faster than humans notice.
Audit implementation patterns
Clean-machine audit
Run the happy path on a machine or container without preinstalled project tools.
Command inventory
List every setup, test, build, dev, release, and deploy command from README, CI, package scripts, mise, and Makefiles.
Version diff
Compare tool versions from mise, package manager, lockfiles, CI image, and runtime logs.
Env diff
Compare `.env.example`, docs, CI secrets, runtime config, and secret-manager entries by variable name and meaning.
Agent dry run
Ask the coding-agent instructions which commands are safe, then verify they match the project setup contract.
Drift PR template
Every fix PR should state drift found, source of truth, files changed, local proof, CI proof, and next audit date.
FAQ
Short answers for teams auditing developer environment drift.
How often should we run a drift audit?
Run it before releases, after toolchain migrations, before onboarding cohorts, and before enabling coding agents on a repo.
Is drift always bad?
No. CI may intentionally differ from local setup. The problem is undocumented or unowned drift.
What is the best source of truth?
Usually a small combination: `mise.toml` for tools/tasks, uv files for Python dependencies, README for human path, and CI for enforcement.
Why include coding agents in an environment audit?
Agents read docs and run commands. If setup docs are stale, agents can multiply mistakes quickly.
Related radar
Related RepoDaily briefs
mise Explained: One Project Setup for Dev Tools, Runtime Versions, Environments, and Tasksjdx/mise · Developer tool / CLIuv Explained: Rust-Fast Python Package, Project, Tool, and Python Version Managementastral-sh/uv · Developer tool / CLIgstack: Garry Tan's Open-Source AI Engineering Toolkit for Claude Code and Beyondgarrytan/gstack · Dataset / Public directoryOpenAI Codex CLI Explained: Local Terminal Coding Agent, Sandboxes, Approvals, and Repository Workflowsopenai/codex · Developer tool / CLIClaude Code Explained: Agentic Coding in the Terminal, IDE, GitHub, Hooks, Plugins, and MCPanthropics/claude-code · Developer tool / CLI
Sources
Feedback
Did this page help you make a decision?
Anonymous feedback helps RepoDaily improve what is actually useful.