What must never be in the repo
Committed dependency and build directories — node_modules, dist, build, .next, venv, __pycache__, coverage — are the heavyweight offenders: thousands of generated files bloating every clone, burying real changes in diffs, and guaranteeing merge conflicts on files nobody wrote. They're reproducible by definition (that's what installs and builds are for), so committing them buys nothing and costs plenty.
Alongside them, the junk: .DS_Store, Thumbs.db, editor swap files, stray logs — and the leftover copies, utils copy.js and app-old.ts and final-v2.py, which are dead code at file scale. cleanvibes flags committed artifact directories as high severity and junk and copy-of files as medium, each with the path, so the cleanup is a short, satisfying deletion pass.
What must be in the repo
Three files carry most of hygiene. A README — even ten lines: what this is, how to run it, how to deploy it — because the alternative is that the knowledge lives in one person's head. A .gitignore at the root that covers your stack's artifacts, because it's the prevention layer for everything in the previous section: the junk that can't be committed never has to be cleaned up. And a lockfile, committed, exactly one — it's what makes installs reproducible, so today's deploy and next month's laptop get the same dependency tree.
Then there's the item that isn't a file: tests. cleanvibes checks whether the repo has any tests at all, and flags their total absence — not because a scanner can judge test quality, but because zero tests is a hygiene fact worth surfacing: it means every change is verified by hope. Even a handful of tests around the core logic changes how safely you (or an AI agent) can refactor.
Why hygiene is worth a fifteenth of the score
Individually these findings are small, which is why hygiene carries weight 15 rather than 20 — a missing README never broke production. But hygiene compounds differently from other categories: it's the multiplier on collaboration. The missing lockfile costs nothing until the second machine; the missing README costs nothing until the second person; the committed node_modules costs a little to everyone, forever.
It's also the natural first fixing session after a scan, precisely because it's mechanical: every finding has an unambiguous fix, most are deletions or one-file additions, and a coding agent can do the lot in one pass. cleanvibes ships a Claude prompt per finding and one tidy-everything plan — clearing hygiene first puts quick points on the score and clears the noise so the structural findings get your real attention.
how it works
- 01
Evict the artifact directories
Remove committed node_modules, dist, build, .next, venv, __pycache__, and coverage from git (git rm -r --cached), then make sure .gitignore covers them so they can't return.
- 02
Delete the junk and the copies
.DS_Store, Thumbs.db, stray logs, editor swap files — and the utils copy.js / app-old.ts leftovers. Pick the live version of each file; delete the rest.
- 03
Write the ten-line README
What it is, how to run it locally, how to deploy. You're writing it for a stranger, and the most likely stranger is you in six months.
- 04
Add a real .gitignore
Root-level, covering your stack's artifacts and env files. This is the prevention layer — every later hygiene problem is something a good .gitignore would have stopped.
- 05
Commit exactly one lockfile
package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock — whichever matches the package manager you actually use. Delete any competitors; one repo, one dependency tree.
- 06
Get a test in the building
If the repo has zero tests, add a few around the core logic. The goal isn't coverage; it's that refactors — human or agent — have something to fail.
- 07
Re-scan and bank the points
Paste the repo into cleanvibes and confirm the hygiene findings are gone. It's the easiest category to take to 100, and the score delta shows up immediately.
frequently asked
- I committed node_modules ages ago — does removing it now help?
- Yes. Unlike a leaked secret, committed artifacts aren't a security problem living in history — the cost is ongoing bloat and diff noise, and that ends the day you git rm --cached them and ignore them. (The old objects stay in history, so clones stay large until you rewrite it, but day-to-day pain stops immediately.)
- Is a missing README really a code-quality issue?
- It's a repo-quality issue, which is the layer hygiene measures. The code may be pristine, but a repo that can't tell a newcomer how to run it has a real, measurable onboarding cost — and the fix is ten lines.
- Why does cleanvibes care whether I have tests?
- Because zero tests is a different situation from few tests: it means nothing verifies behaviour, so every refactor — including the agent-driven fixes cleanvibes itself suggests — carries more risk. It's flagged as one medium finding, not a coverage crusade.
- Which hygiene findings are ranked most severe?
- Committed artifact directories (node_modules and friends) are high severity — they're the most costly and the most visible. Junk files, leftover copies, missing README, missing .gitignore, missing lockfile, and zero tests are medium. All feed the repo hygiene subscore at weight 15.
Last updated June 10, 2026