Stop AI-written code from rotting: an ESLint + Prettier commit gate for your vibe project
Agents write code fast, change it often, and never keep one style. Prettier owns formatting, ESLint owns correctness, husky + lint-staged guard the commit, CI catches the rest: a gate in three days that keeps formatting noise and beginner mistakes out of the repo.

Scope: how this guide differs from the code-quality guides already published
First, let me place this guide. The site already has several code-quality guides, each covering its own area: vibe-project-ai-code-review-before-merge-guide is about doing AI code review before merging, looking at whether the logic and design are right; solo-ai-git-workflow-guide is about a one-person Git workflow, looking at the rhythm of branches, commits, and merges; reading-ai-generated-code-guide is about how to read AI-generated code, looking at understanding; vibe-project-ai-review-second-check-guide is about checking once more after review, looking at verification. This guide covers none of those. It covers exactly one thing: using machine-enforced rules to block formatting problems and beginner mistakes before they are committed, so that "code getting messier the longer it gets" is stopped before it ever reaches review.
This deserves its own guide because review and gates are two different lines of defence, and many people only build the first. Review is done by humans: a person can read a few hundred lines at a time, and their attention goes to "is this feature correct," not to "there is a missing semicolon here and two extra spaces there." A gate is run by machines: it never tires, never misses, plays no favourites, and scans a whole change in seconds, blocking formatting and beginner mistakes in one pass. In a project without a gate, half of every review is spent arguing about formatting; with a gate, review can actually talk about logic.
The sources are two official documents: ESLint's Getting Started (eslint.org/docs/latest/use/getting-started) and Prettier's Install guide (prettier.io/docs/install). The ESLint installation method, flat configuration, three severity levels, Prettier's installation and version pinning, .prettierignore, the difference between --write and --check, the husky and lint-staged pre-commit hook, and the role of eslint-config-prettier all come from these two documents. The rollout advice in this guide (for example, "start rules at warn, then move to error") is built on those mechanisms, and I will say which parts are direct documentation and which parts are advice. The "Little Ledger" project in the example is fictional and only there for demonstration.
Why vibe projects need a gate most
Code in vibe projects has a particular character: written fast, changed often, and inconsistent in style. The same feature written by an agent today comes out with two-space indentation and single quotes; written in a different session tomorrow it comes out with four-space indentation and double quotes; two lines you add yourself the day after are a third style again. An agent has no memory of "how this project always writes it" — each time it writes from whatever habit it has in the moment. A project written by one person drifts in style; a project written with an agent drifts faster.
The cost of inconsistent style is not just "it looks untidy." First, formatting noise drowns real changes in review: a file with 5 lines of logic changed and 40 lines of formatting changed hides those 5 lines completely. Second, merge conflicts multiply: two people change the same file, one with tabs and one with spaces, and Git flags the whole block as conflicting even though the logic does not conflict at all. Third, beginner mistakes slip through: unused variables, misspelled variable names, wrong comparisons — none of these stop the agent from handing the code over, but they blow up at runtime.
A gate fixes all three, and cheaply: the rules live in configuration files, the checking is done by machines, and a failed check blocks the commit. Once the rules are set, agent-generated code gets pulled into one consistent shape before every commit no matter how much its style drifts, and beginner mistakes are caught before commit instead of after a user reports an error. The gate is not there to "control the agent" — it is there to make the agent's output reliably usable. Let it be free with ideas, but not with formatting.
Two different things: formatting and rules are not the same job
Before touching anything, separate two concepts that people often mix up and then configure in the wrong place. Formatting is about what code looks like: how many spaces of indentation, single or double quotes, semicolons at line ends, how long a line can be before it wraps. Formatting problems do not affect whether the program runs, only whether a human can read it comfortably. Linting is about whether code is correct: whether a variable was defined before use, whether a defined variable is ever used, whether a dangerous pattern was written, whether a deprecated API was used. Rule problems can cause bugs directly.
Prettier handles formatting, ESLint handles rules — that is the standard division of labour. Prettier is an "opinionated" formatter: it does not negotiate, it always outputs the same shape for the same code, and you only decide a handful of options (indentation width, quote style) while it takes care of the rest. ESLint is a "pluggable" checker: every rule can be switched on or off individually, so you can enable only the recommended set or configure rules one by one to fit your needs. The Prettier documentation has one key sentence here: if you use ESLint, install eslint-config-prettier to make ESLint and Prettier play nice — it turns off all ESLint rules that are unnecessary or might conflict with Prettier, so the two tools never give opposite orders about the same code.
The classic symptom of a confused division of labour is using ESLint to enforce indentation and quotes, ending up with an ever-longer rules file while the agent gets blocked by formatting errors on every commit — or installing only Prettier and assuming the code has been "checked," while unused variables and misspelled names sail straight through. The correct setup is: Prettier owns formatting entirely, ESLint keeps only the rules about correctness, and the two tools stay in their own lanes.
Step one: install Prettier first and unify the formatting
Install Prettier first, because it is the simplest of the three steps and pays off fastest. Following the official installation guide, install it locally and pin the version:
npm install --save-dev --save-exact prettier@3.10.1
Note the --save-exact instead of a plain --save-dev. The documentation specifically warns that every Prettier release can format slightly differently, so a project should pin one exact version — otherwise different people install different versions and keep reformatting each other's code back and forth. The version number above is the one given in the documentation at the time of writing; use the version the documentation shows when you install.
After installing, create two files. The first is an empty configuration file, .prettierrc, which tells editors and other tools "this project uses Prettier":
node --eval "fs.writeFileSync('.prettierrc','{}\n')"
The second is .prettierignore, which tells Prettier which files not to touch, such as build output and coverage reports:
node --eval "fs.writeFileSync('.prettierignore','# Ignore artifacts:\nbuild\ncoverage\n')"
The documentation adds one practical detail: if the project already has a .gitignore, Prettier follows its rules automatically, and you can also base .prettierignore on .eslintignore. Generated files, third-party code, and very large data files all belong in the ignore list — do not let the formatter touch them.
Then run one full formatting pass to clear the accumulated formatting debt in one go:
npx prettier . --write
Commit this pass on its own, and do not mix it with a feature change. If the two are mixed, the commit's diff contains formatting changes and logic changes at the same time, and when something breaks later you cannot tell which line was formatting and which was logic. After a single standalone formatting commit, every later commit contains only real changes, and the history stays clean.
The command for checking formatting is --check, which only checks and never rewrites:
npx prettier . --check
The documentation puts it this way: --write and --check are the most common ways to run Prettier — the first rewrites files, the second only checks. The --check exit code can be used directly in CI: success when formatting is clean, failure when it is not, and the pipeline blocks the change. That is the command step four's CI gate will use — remember it here.
Step two: install ESLint and block beginner mistakes
With formatting unified, install ESLint. According to the official quick start, Node.js has a version requirement: ^20.19.0, ^22.13.0, or >=24 — check your Node version is new enough before installing. Install and configure with one wizard command:
npm init @eslint/config@latest
The wizard asks a few questions, such as where the code runs (browser or Node) and whether you use TypeScript, and then generates an eslint.config.js (or eslint.config.mjs) file. The documentation's example shows that after choosing the browser environment, the configuration contains a globals.browser entry, which tells ESLint which global variables exist in browsers (window, document, and so on) so using them does not count as "undefined."
import { defineConfig } from "eslint/config";
import globals from "globals";
import js from "@eslint/js";
export default defineConfig([
{ files: ["**/*.js"], languageOptions: { globals: globals.browser } },
{ files: ["**/*.js"], plugins: { js }, extends: ["js/recommended"] },
]);
Here js/recommended is ESLint's official recommended rule set: extending it turns on every rule marked as recommended. The documentation warns explicitly that ESLint will not lint your code unless you extend a shared configuration or explicitly turn rules on. Installing ESLint without configuring rules means it checks nothing — the most common beginner trap is running it once, seeing no errors, and assuming the code is clean.
Rules can also be configured one by one, each with three severity levels: "off" (0) turns the rule off, "warn" (1) turns it on as a warning that does not affect the exit code, and "error" (2) turns it on as an error with exit code 1. The documentation's example configures two rules:
{
rules: {
"no-unused-vars": "warn",
"no-undef": "warn",
},
}
no-unused-vars is "a variable that was defined but never used" and no-undef is "a variable that was used but never defined" — the two rules most worth enabling first in a vibe project. Agents often leave unused variables behind or invent a variable name from memory, and these two rules catch exactly those two kinds of mistakes. Start with warn, and once the team is used to it, promote the rules that catch real bugs to error.
The documentation also gives a manual setup path: install the eslint and @eslint/js packages, write eslint.config.js yourself, then run npx eslint against a file or directory. The wizard and the manual path produce the same result — pick whichever fits your habits. One thing to watch: if you use pnpm, the documentation requires a .npmrc file in the project containing auto-install-peers=true and node-linker=hoisted, otherwise dependencies may install in an incompatible way and produce errors.
Making the two coexist: do not let the tools fight each other
Once Prettier and ESLint are installed, the first job is to stop them fighting. Both tools have a say in the "what code looks like" area: ESLint has rules about indentation, quotes, and trailing semicolons too. If ESLint's formatting rules disagree with Prettier's output, the same code falls into a loop: Prettier rewrites it to shape A, ESLint says that is wrong and rewrites it to shape B, and next time Prettier changes it back to A.
The official fix is eslint-config-prettier. The Prettier installation guide states it plainly: if you use ESLint, install this package to make ESLint and Prettier play nice — it turns off all ESLint rules that are unnecessary or might conflict with Prettier. After installing it, formatting questions are decided by Prettier alone, and ESLint keeps only the rules about correctness. Once the division is set, the two tools never give opposite orders about the same code again.
There is a simple test for whether the division is set up correctly: run prettier --write, then run eslint. If ESLint still reports formatting problems, a conflicting rule was not switched off — go back and check that eslint-config-prettier is actually wired in. Conversely, if ESLint reports nothing at all, do not celebrate too quickly — first confirm the recommended rule set is actually extended, because an ESLint with no shared configuration checks nothing.
Step three: a pre-commit hook that only checks the changed files
With the tools installed and the rules configured, the next step is to make the checks run automatically before every commit instead of relying on someone to run them by hand. The Prettier installation guide gives the standard approach: use husky to manage Git hooks and lint-staged to check only the files changed in this commit. The install commands are:
npm install --save-dev husky lint-staged
npx husky init
node --eval "fs.writeFileSync('.husky/pre-commit','npx lint-staged\n')"
Then add a lint-staged section to package.json telling it what to do with the changed files:
{
"lint-staged": {
"**/*": "prettier --write --ignore-unknown"
}
}
This configuration means: before committing, run prettier --write on every changed file, fixing formatting on the spot before the commit goes in. The --ignore-unknown flag tells Prettier to skip file types it does not recognize, so it does not error on images or binary files. The documentation adds one specific warning: if you also use ESLint, make sure lint-staged runs it before Prettier, not after — fix correctness problems first, then unify formatting, with the formatting tool finishing last.
Why lint-staged instead of a full check in the hook? Because a full check is slow and also covers files other people have not finished changing. lint-staged only touches the files in this commit — change three files and it checks three files, finishing in seconds without delaying the commit. The difference is even clearer when an agent changes dozens of files at once: a full check scans the whole repository, lint-staged only scans what changed.
After installing the hook, verify it by hand: deliberately mess up one file's formatting, leave an unused variable in it, then commit, and watch whether the hook actually blocks, actually fixes the formatting, and actually reports the unused variable. An unverified hook is the same as no hook — husky may not have initialized, the hook file may be written wrong, or the lint-staged configuration may be in the wrong place, and any of these can silently disable the hook while you only discover months later that nothing was checked all along.
Step four: add CI as a second gate, with a full check as the safety net
A pre-commit hook is the first gate, but it has a weakness: hooks live on the local machine. Switch computers, re-clone the repository, or bypass the hook with git commit --no-verify, and the gate is gone. So add a full check in CI as a safety net. The Prettier documentation explicitly recommends that if you have a CI setup, run prettier --check as part of it to make sure everyone runs Prettier, avoiding merge conflicts and other collaboration issues.
The two commands to run in CI are:
npx prettier . --check
npx eslint .
The first checks formatting across the whole repository, the second checks rules across the whole repository. Both must pass for the change to merge; if either fails, the pull request cannot be merged. CI checks are full checks, which complement the hook's "only changed files" approach: the hook is fast and timely, CI is complete and catches everything. Code that bypassed the hook with bad formatting gets blocked by CI before merging; code committed from a fresh machine without hooks installed gets blocked the same way.
Rule severities in CI must match the local setup: a rule that is warn locally is warn in CI, and one promoted to error locally is error in CI. Mismatched severities produce strange results — green locally and red in CI, or the reverse. The single source of truth for rules should be the configuration file itself; local runs and CI are just two ways of running the same configuration.
How to set the rules: start loose, tighten gradually, never open everything as error on day one
How many rules to set and how strict to make them decides whether the gate succeeds or fails. The most common failure is turning every rule to error on day one: the first commit comes back covered in errors, and the agent starts changing code randomly to pass the checks, turning working code into broken code and warnings into bugs. The purpose of a gate is to make code better, not to make committing harder.
The recommended sequence is: in week one, enable only the recommended set (js/recommended), hand all formatting to Prettier, and set the rules that catch real bugs (such as no-undef) to warn first, so people see the problems and get used to being reminded. In week two, promote the warn rules that keep appearing and are genuinely errors — unused variables, undefined variables — to error. From week three on, add rules based on your own project's history of mistakes: wherever the agent keeps writing the same error, add the matching rule; whatever style the team agrees on, write it into the configuration.
Three kinds of rules should not start as error. First, anything about style belongs to Prettier — do not enable it again in ESLint. Second, rules the agent triggers often but that require structural changes to fix should start at warn and move to error later, giving the team time to adapt. Third, any rule you cannot explain with "which bug does it prevent" should not be enabled yet. Every rule in the configuration file should be able to name the class of real mistake it has prevented; a rule that cannot is noise, and people will eventually work around it.
Five traps: a gate can be installed and still be useless
The first trap: generated files left out of the ignore lists. Build output, third-party libraries, auto-generated type definitions, very large data files — none of these should be checked. Prettier has .prettierignore and ESLint has its own ignore configuration, and both need to be set. Miss them and checks get slower and slower until nobody wants to wait, and the hook gets bypassed.
The second trap: the editor plugin using a different version than the project. The Prettier documentation specifically warns that editor plugins pick up your local version of Prettier, and you do not want the editor accidentally using a newer version than the project — otherwise the format the editor produces on save disagrees with the project's version, the hook rewrites it back on commit, and the two fight each other. The fix is for the editor to use only the version installed in the project, following package.json.
The third trap: mixing a full formatting pass with a feature change in one commit. As noted earlier, the first full formatting pass must be its own commit, and the same applies afterwards: do not reformat a whole file inside a feature commit. Formatting changes mixed with logic changes hide what was actually changed from reviewers, and make rollbacks scary when something breaks. If you want to unify formatting, make a separate "formatting" commit and state clearly that it changes formatting only, not logic.
The fourth trap: too many rules, too many warnings, nobody reads them. Warnings do not affect the exit code, so a few hundred warnings will never block a commit, and after a while everyone learns to ignore them. Clear warnings regularly: spend ten minutes a week fixing recurring warnings, promoting a rule to error, or turning a rule off — pick one of the three, and do not let warnings sit there forever.
The fifth trap: rules for new code only, old code ignored. A gate only checks newly changed files, and the historical problems in old files are left alone — which is correct. Do not touch old code just to pass a check. But once an old file is changed, lint-staged checks the whole file, including its historical problems. When that happens, fix only the problems introduced by this change; note the historical ones down and schedule them separately.
A complete example: the fictional "Little Ledger" gets its gate in three days
Here is a full walkthrough with a fictional project called "Little Ledger." This example is invented — the project name, file names, and numbers are only for demonstration, not real data. Little Ledger is a small bookkeeping tool whose code was mostly generated by an agent and has been getting messier in style for three months.
Day one, install Prettier: follow the documentation to install and pin the version, create .prettierrc and .prettierignore, run npx prettier . --write for a full formatting pass, and commit it on its own. By the end of the day, every file in the repository is formatted the same way, the history has one extra "formatting" commit, and every later commit's diff contains only real changes.
Day two, install ESLint: run the wizard to generate eslint.config.js, extend js/recommended, install eslint-config-prettier to switch off conflicting rules, and set no-unused-vars and no-undef to warn first. The first run of npx eslint . reported 47 warnings: 31 unused variables and 16 undefined variable names. Forty of them were fixed directly; the remaining 7 were variable names the agent had invented from memory, fixed by checking what they were supposed to be. By the end of the day, beginner mistakes were at zero.
Day three, install the hook and CI: install husky and lint-staged as documented, configure the pre-commit hook, and verify it once — a commit deliberately left with an unused variable was blocked on the spot, and passed after fixing. Add prettier --check and eslint to CI. By the end of the day, the gate was live: every commit afterwards goes through the hook first and CI second, and formatting problems and beginner mistakes can no longer get into the repository.
Two things are worth noting in this example. First, the three steps run in order: formatting first, rules second, hooks last, and each step can be verified on its own without configuring everything at once. Second, the numbers are fictional, but the process follows the documentation: the install commands, configuration files, hook setup, and CI commands all come from the ESLint and Prettier official documentation and work when copied as-is.
Checklist: land it in three days with one table
Here is a checklist you can use directly. Day one: install Prettier and pin the version, create .prettierrc and .prettierignore, run one full formatting pass and commit it on its own. Day two: install ESLint, run the wizard to generate the configuration, extend the recommended rule set, install eslint-config-prettier to switch off conflicting rules, set no-unused-vars and no-undef to warn first, and clear the accumulated warnings. Day three: install husky and lint-staged, configure the pre-commit hook (ESLint first, Prettier second), verify by hand that the hook actually blocks, and add prettier --check and eslint as full checks in CI.
Three more items are for when the gate stops working. If a commit is not blocked, first check that the hook file exists at .husky/pre-commit, that the lint-staged configuration is in package.json, and that husky initialized successfully — if any one of the three is missing, the hook is dead. If ESLint and Prettier are fighting, first check that eslint-config-prettier is installed and wired in; formatting questions should be decided by Prettier alone. If CI is red while local is green, first compare whether the rule severities and versions match on both sides; unify the versions first if they differ, and unify the configuration first if the severities differ.
Comments (0)
Sources
Related articles
On 11 November 2026, AWS open-sourced UAEF: adapters turn traces from LangGraph, LangChain, Strands and Bedrock AgentCore into one format, then 36 metrics across 7 dimensions score them, flagging regressions past 5%. The judge model is hardened too — scores must cite verbatim evidence, and never decide safety.
You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.
Numbers in JavaScript are one type, Number, stored as 64-bit floats — which is why 0.1 + 0.2 is 0.30000000000000004. This guide follows MDN's Basic math in JavaScript, Math, and Number: one number type, float error, counting money in cents, converting strings, NaN and Infinity, safe integers, the four rounding methods, Math.random, the Math toolbox, and formatting for display.