"Maintainable", "understandable", "scalable" and "reliable" sound like good rules for code, but nobody can check them in a review. This post replaces them with seven principles that a machine or a reviewer can check, explains why artificial intelligence (AI) coding assistants make each one matter more, and shows the lint rules, continuous integration (CI) steps and review questions that enforce them.
The gist
Write each code rule so that a tool or a reviewer can check it, make every automatic check block the merge, and spend human review on what tools can't judge.
- Replace vague words with seven checkable principles. Words like "maintainable" or "reliable" never stop a bad change. Simple, clear, consistent, verifiable, modular, reviewable, and secure and observable each come with a tool check and one review question.
- Make every automatic check block the merge. A check that only warns is soon ignored. Formatting, lint, types, tests, import rules and security scans should all stop the change when they fail.
- Keep human review for intent, design and simplicity. Tools judge consistency and correctness well, and simplicity badly. The reviewer's best question is "could this be done with less?"
- Write the project's rules and reasons where AI tools read them. An AI assistant starts every session with no memory. A conventions file and short decision records stop it from inventing a new style each time.
- Make a person answer for every merge. The AI proposes and a person decides. No change merges without a human review, and "the AI wrote it" is never an excuse.
The picture: a principle you can't check is only a wish
Many teams write down what good code should be. The list often looks like this: maintainable, understandable, scalable, reliable. It is a good list, and almost everyone agrees with it. That is part of the problem. Nobody disagrees with a word like "maintainable", so the word never stops a bad change.
The list has two weaknesses:
- The words overlap. Code that is easy to understand is most of what makes code easy to maintain. When two rules mean almost the same thing, a reviewer can't use them to point at a specific problem.
- The words can't be checked. Is this function "maintainable"? Two good developers can give two different answers, and both can be right. A rule that depends on taste leads to an argument in every review.
A principle works when someone can check it: a machine on every change, or a person with one concrete question in a review. That is the idea this whole post builds on. Each principle below comes with two things:
- an automatic check, something a tool runs on every change, such as a lint rule (an automatic check on how the code is written) or a test;
- a review question, one plain question a person asks when the machine can't judge.
The automatic checks run in continuous integration (CI): the server that builds and tests every change before it can join the main code. When a check fails, the change can't be merged. The review questions belong to the human reviewer, who reads the change in a pull request (PR), the page where a proposed change waits for review.
This split matters more now than it did five years ago, because a lot of code is no longer written by a person.
Why AI changes the list
AI coding assistants are tools that use a large language model (LLM), a program trained on huge amounts of text and code, to write code from a request in plain language. They are fast and often good. They also have habits, and each habit affects a different quality of the code.
- The code looks right even when it is wrong. An assistant writes code that is well formatted, well named and confident. Looking correct and being correct are different things, and the assistant is very good at the first one. A study at Stanford found that people who used an AI assistant wrote less secure code than people who didn't, and were more sure their code was secure[1]. Other researchers asked code models for more than half a million code samples and found that almost one in five of the packages they used (19.7 %) didn't exist at all[2].
- It adds more than the task needs. Ask for one function and you may get a helper class, three options nobody asked for and checks for cases that can't happen. Each extra piece looks reasonable alone. Together they make the code bigger and harder to change. GitClear, a company that sells code-analysis tools, studied 211 million changed lines from 2020 to 2024. Copied lines rose from 8.3 % to 12.3 % of all changes, and lines moved to improve existing code fell from 25 % to under 10 %[3].
- Every session starts from zero. The assistant doesn't remember the last conversation. Unless the project's rules are written somewhere it reads, each session invents its own style: a new way to fetch data, a new folder, a new naming pattern.
- It doesn't think about security unless you ask. Inputs from users, secrets in the code and the packages it adds are rarely its first concern.
- It doesn't know why. The reasons behind a design were said in a meeting, or in a chat with another assistant. The next person, and the next AI session, can't read that conversation.
- It produces a lot of code. More code means more changes to review. If the changes are big, people stop reading them carefully, and a change nobody read is a change nobody can trust. The 2024 DevOps Research and Assessment (DORA) report, a yearly study of how software teams deliver, found that more use of AI came with an estimated 1.5 % less delivery speed and 7.2 % less delivery stability[4].
Each habit points to one thing the code needs. The table puts them side by side.
| What AI tends to do | What the code needs | Principle |
|---|---|---|
| Writes code that looks correct | Proof that it works | Verifiable |
| Adds extra layers, options and checks | Only what the task needs | Simple |
| Invents a new style each session | One way of doing each thing | Consistent |
| Produces large changes | Changes a person can really read | Reviewable |
| Ignores security unless asked | Safe defaults, checked by tools | Secure and observable |
| Forgets the reasons | The reasons written down | Reviewable |
Some of these needs are new words on the old list. Others are the old words made more precise. The next section puts the whole list together.
The seven principles and one rule
Here is the list. Each line is short on purpose, so it is easy for a reviewer to remember.
- Simple: nothing that isn't needed.
- Clear: someone who didn't write it can understand it, whether the author was a person or an AI.
- Consistent: it follows the project's conventions.
- Verifiable: tests and types check it automatically.
- Modular: clear boundaries between parts, so a change stays in one place.
- Reviewable: small changes, with the reason written down.
- Secure and observable: it fails in a way people can see, and it exposes nothing it shouldn't.
On top of the seven there is one rule that crosses all of them: a person is accountable. The AI proposes; a person decides and answers for the result.
The old words are not lost. Each one is covered by one or more of the new principles, which are narrower and easier to check:
"Reviewable" has no old word above it. It is new, and it is the principle AI pushes hardest, because the amount of code grows faster than the time people have to read it.
The sections below take the principles in order. Each one says what the principle means, why AI makes it matter, how a machine checks it and what question a reviewer asks. The code examples use a TypeScript project with ESLint (the most common tool that checks JavaScript and TypeScript code for problems, called a linter), but every check has an equivalent in other languages.
Simple: nothing that isn't needed
Simple code is the smallest code that solves the problem in front of you. Not the problem you might have next year, and not every case you can imagine.
This is the principle AI breaks most often, because adding things feels helpful. Here is a typical request: "format a price in euros". A typical answer looks like this:
interface PriceFormatterOptions {
locale?: string;
currency?: string;
minimumFractionDigits?: number;
maximumFractionDigits?: number;
fallback?: string;
}
export class PriceFormatter {
constructor(private readonly options: PriceFormatterOptions = {}) {}
format(value: number | null | undefined): string {
if (value === null || value === undefined || Number.isNaN(value)) {
return this.options.fallback ?? '';
}
return new Intl.NumberFormat(this.options.locale ?? 'es-ES', {
style: 'currency',
currency: this.options.currency ?? 'EUR',
minimumFractionDigits: this.options.minimumFractionDigits ?? 2,
maximumFractionDigits: this.options.maximumFractionDigits ?? 2,
}).format(value);
}
}
The project only ever shows prices in euros, and the price is never empty. What it needed was this:
const euros = new Intl.NumberFormat('es-ES', { style: 'currency', currency: 'EUR' });
export function formatPrice(value: number): string {
return euros.format(value);
}
The first version isn't wrong. It just has five options (one of them a fallback), a class and a check for empty values that nobody asked for. Each of them is code someone has to read, test and keep working.
Automatic check. A linter can't know what your problem needs, but it can measure size and complexity, and it can find code nobody uses.
- Complexity limits. ESLint's
complexityrule counts the paths through a function (everyif, loop and&&adds one). This count is called cyclomatic complexity. Other rules limit how long a function or a file can be, how deep the nesting goes and how many parameters a function takes. - Unused code. Knip finds files, exports and dependencies that nothing uses. AI often leaves these behind: a helper it wrote and then stopped calling, or a package it installed for a first attempt.
// eslint.config.mjs (part of it)
export default [
{
rules: {
complexity: ['error', 10],
'max-depth': ['error', 3],
'max-params': ['error', 3],
'max-lines-per-function': ['error', { max: 50, skipBlankLines: true, skipComments: true }],
'max-lines': ['error', { max: 300, skipBlankLines: true, skipComments: true }],
},
},
];
npx knip
The numbers are a starting point, not a law. Pick limits that most of your current code passes, and lower them slowly.
Review question. Could this be done with less? One habit makes the question concrete: no abstraction (a general layer, such as an interface or a factory, that hides the details) without at least two real uses. An interface with one implementation, a factory that builds one kind of object or an option that only one caller sets is not an abstraction yet. It is a guess about the future. Write the simple version, and add the abstraction when the second real use arrives.
Simple code is also the first step to code that other people can read, which is the next principle.
Clear: understood without the author
Clear code can be understood by someone who didn't write it, without asking the author. With AI, "the author" may be a chat session that no longer exists, so there is often nobody to ask.
Clarity is mostly about two things: names that say what something is, and types that say what a value can be.
Automatic check. Machines can't judge whether a name is good, but they can block the worst cases and make sure the types are accurate.
- Strict TypeScript. The
strictoption intsconfig.jsonturns on a group of checks, such as refusing values that might benullwithout a check. A few more options add other useful checks. The type check runs withnpx tsc --noEmit(check the types, write no files). - No
any. Theanytype turns the type checker off for a value. AI uses it when it can't work out a type, which is exactly when a human needs to look. The@typescript-eslint/no-explicit-anyrule blocks it. - Naming rules.
@typescript-eslint/naming-conventionenforces the format of names (for example,PascalCasefor types). ESLint'sid-denylistbans names that say nothing, such asdata,temporobj.
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"noFallthroughCasesInSwitch": true
}
}
// eslint.config.mjs (part of it)
import tseslint from 'typescript-eslint';
export default [
...tseslint.configs.recommended,
{
rules: {
'@typescript-eslint/no-explicit-any': 'error',
'@typescript-eslint/naming-convention': [
'error',
{ selector: 'typeLike', format: ['PascalCase'] },
// PascalCase is allowed for React components
{ selector: 'function', format: ['camelCase', 'PascalCase'] },
{ selector: 'variable', format: ['camelCase', 'UPPER_CASE', 'PascalCase'] },
],
'id-denylist': ['error', 'data', 'temp', 'tmp', 'obj', 'foo'],
},
},
];
Review question. Does someone who didn't write this understand it without an explanation? The best test is the pull request itself. If the author has to explain in the PR description how a piece of code works, the explanation belongs in the code: better names, a smaller function, or a short comment that says why. A comment that repeats what the code does is a sign the code isn't clear yet.
Clear code is easier to read one file at a time. The next principle makes the whole project read the same way.
Consistent: follows the project's conventions
Consistent code does the same thing the same way everywhere in the project. One way to fetch data, one way to handle errors, one folder for each kind of file.
Consistency matters because a reader learns a pattern once and then recognises it everywhere. Without it, the reader has to learn each file from the start. AI breaks consistency without meaning to: it writes in the style it saw most often in its training data, not in the style of your project, unless something tells it otherwise.
Automatic check. Three layers, from the easiest to the most specific.
- A formatter. Prettier rewrites spacing, quotes and line breaks the same way for everyone, so nobody (and no AI) argues about them. In CI it only checks:
npx prettier --check .fails if a file isn't formatted. - A shared lint config, required in CI. The same rules for everyone, with no warnings allowed:
npx eslint . --max-warnings 0. A warning that never blocks anything is soon ignored. - Rules for your own conventions. This is the most useful layer and the least used. If the project has decided "all requests to the server go through our
apimodule", a lint rule can enforce it. ESLint'sno-restricted-importsblocks direct imports and tells the author, human or AI, what to use instead. (Theapimodule itself turns the rule off for its own files, since it is the one place allowed to use the library.)
// eslint.config.mjs (part of it)
export default [
{
rules: {
'no-restricted-imports': [
'error',
{
paths: [
{ name: 'axios', message: 'Use the api module in src/shared/api instead.' },
{ name: 'moment', message: 'Use date-fns, the date library this project uses.' },
],
},
],
},
},
];
One source of truth for conventions. Some conventions are too broad for a lint rule: how folders are organised, how tests are named, when to write a new module. These go in one short document in the repository. Today, most AI coding tools read a project instructions file before they start work: AGENTS.md, an open format several tools share[5], or a tool-specific one such as CLAUDE.md. If the conventions live in that file, every AI session starts from your rules instead of inventing new ones. People read it too.
Review question. Does this look like the rest of the project? If a change brings a second way of doing something the project already does, ask why. Sometimes the new way is better. Then it should replace the old one everywhere, with a decision written down, not live next to it.
Consistent, clear code is easier to check. The next principle is about checking it with tools instead of with eyes.
Verifiable: tests and types check it automatically
Verifiable code can be proved to work by running something: tests that check its behaviour and types that check its shape. Without tests and strict types, "reliable" is only a hope, and with AI it is a hope about code that looks more convincing than it is.
Automatic check. Three steps in CI, and each one blocks the merge when it fails.
- Tests are required. The test suite runs on every change, and a change with failing tests can't be merged.
- The type check blocks.
npx tsc --noEmitruns as its own step. Many projects only type-check in the editor, where it is easy to ignore. - Coverage where it matters. Coverage measures how much of the code the tests run. A single target for the whole project (for example, "80 % coverage") is easy to reach with tests that check nothing. AI is very good at writing those. A better target is high coverage for the domain logic, the code that holds the real rules of the business (prices, permissions, calculations), and no target for code that only connects things. Vitest, a test runner for JavaScript and TypeScript, accepts a threshold per folder:
// vitest.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
coverage: {
provider: 'v8',
include: ['src/**/*.ts'],
thresholds: {
'src/domain/**/*.ts': { lines: 90, branches: 85 },
},
},
},
});
A coverage target is a measure that easily becomes the goal itself. Once it does, people (and AI agents) raise the number without making the code safer. This effect is called Goodhart's Law, and Goodhart's Law and AI agents looks at it in detail.
Review question. Is there a test that would fail if this were wrong? One habit makes it concrete: every bug that is fixed comes with a test that reproduces it. The test fails before the fix and passes after it. It proves the fix works, and it stops the same bug from coming back when an AI rewrites the function six months later.
// Bug #142: a discount bigger than the order made the total negative.
it('never returns a negative total when the discount is bigger than the order', () => {
expect(totalWithDiscount({ subtotal: 3, discount: 5 })).toBe(0);
});
Tests are easy to write when the code is split into parts with clear edges. That is the next principle.
Modular: clear boundaries, local changes
Modular code is split into parts, called modules, with clear rules about which part may use which. A change to one part stays inside that part. This principle covers most of what people mean by "scalable" and a good part of "maintainable": a system grows well when each new feature touches one place, not twenty.
AI tends to take the quickest way to make the code work. If a screen needs a value from the database, the quickest way is to import the database code straight into the screen. It works, and it ties two parts together that should be separate. After a hundred shortcuts like that, every change needs edits all over the code.
Automatic check. Write the boundaries down as rules, and let a tool check them.
- Who may import from whom. dependency-cruiser reads every import in the project and fails when one breaks a rule you wrote. The example below says three things: the domain logic must not depend on the user interface (UI) or on infrastructure code, such as the database; one feature may use another only through its public entry file (
index.ts); and there are no import cycles. - No circular dependencies. A cycle is when module A imports B and B imports A, directly or through other modules. Cycles make it hard to change, test or understand one module alone.
// .dependency-cruiser.cjs
module.exports = {
forbidden: [
{
name: 'no-circular',
severity: 'error',
from: {},
to: { circular: true },
},
{
name: 'domain-stays-independent',
comment: 'Domain logic must not depend on the UI or on infrastructure.',
severity: 'error',
from: { path: '^src/domain' },
to: { path: '^src/(ui|infra)' },
},
{
name: 'features-use-each-other-through-index',
comment: 'One feature may use another only through its index.ts.',
severity: 'error',
from: { path: '^src/features/([^/]+)/' },
to: {
path: '^src/features/[^/]+/',
pathNot: ['^src/features/$1/', '^src/features/[^/]+/index\\.ts$'],
},
},
],
options: {
tsConfig: { fileName: 'tsconfig.json' },
},
};
npx depcruise src --config .dependency-cruiser.cjs
A warning sign, not a rule. Watch how many modules a small change touches. If fixing a label on one screen changes files in five folders, the boundaries are in the wrong place. No tool blocks this, but the list of changed files in a PR shows it immediately.
Review question. Does this change stay where it belongs? A new import across a boundary needs a sentence in the PR explaining why.
A modular change touches few files. That makes the next principle much easier.
Reviewable: small changes with the reason written down
A reviewable change is small enough for a person to read properly, and it explains why it exists. If a change can't really be reviewed, it can't be trusted, however good the tests are.
Size matters because attention runs out. SmartBear, a company that sells code-review software, studied 2,500 reviews by a team at Cisco. Its advice from that study is to review no more than 200 to 400 lines at a time, because reviewers find fewer problems after that[6]. Google's guide for code reviewers asks for small changes for the same reason, and also because small changes are faster to review and easier to undo[7]. AI makes this harder: producing a 2,000-line change takes it a few minutes, and reading one takes a person hours.
Automatic check. A size limit and a template.
- A warning on big PRs. Danger JS runs in CI and can comment on a pull request. The example warns above 400 changed lines and fails when the description is empty or very short. Generated files, such as
package-lock.json, make the count bigger, so a real setup leaves them out.
// dangerfile.ts
import { danger, fail, warn } from 'danger';
const pr = danger.github.pr;
const changedLines = pr.additions + pr.deletions;
if (changedLines > 400) {
warn(`This PR changes ${changedLines} lines. Can it be split into smaller PRs?`);
}
if (!pr.body || pr.body.trim().length < 50) {
fail('Please describe what this PR changes, why, and what it could break.');
}
- A PR template. GitHub fills a new pull request's description from
.github/pull_request_template.md. Three questions are enough:
## What changes
## Why
## What could break
The third question is the most useful one. It makes the author think about the risk before the reviewer has to.
Decisions are written down. Some reasons are bigger than one PR: why the project uses this database, why the domain logic can't import the UI. These go in an architecture decision record (ADR), a short file in the repository that records one decision, its context and its consequences. When an AI session or a new colleague asks "why is it done like this?", the answer is in a file they can read, not in a conversation they can't.
# 7. Domain logic does not import UI or infrastructure code
Status: Accepted
## Context
Screens imported database code directly, so every UI change risked breaking data access.
## Decision
src/domain may not import from src/ui or src/infra. dependency-cruiser enforces it in CI.
## Consequences
Domain code is tested without a browser or a database. New features need a small adapter.
Michael Nygard proposed architecture decision records in a short blog post in 2011[8]. His format (title, context, decision, status, consequences) is still the one most teams use.
Review question. Can I review this properly in one sitting, and do I know why it exists? If not, ask for it to be split, or for the reason to be written down, before reading the code.
Secure and observable: fails visibly, exposes nothing
Secure and observable code doesn't expose what it shouldn't (secrets, personal data, holes an attacker can use), and when it fails, people can see the failure and understand it. The two belong together: an error that disappears without a trace is a security problem as much as a quality one, because nobody knows something went wrong.
AI rarely thinks about either unless you ask. It may add a package because the name looked right, put an access key in the code to make a first version work, or wrap a risky call in a try with an empty catch so the error "goes away".
Automatic check for security. Three tools, each for a different kind of risk.
- Dependency audit.
npm audit --audit-level=highfails when a package the project uses has a known, serious security problem. - Secret detection. Gitleaks looks for keys, passwords and tokens in the code and in the git history. It works best twice: before each commit on the developer's machine, and again in CI. (Its author now ships only security fixes for it, so check the project page for its successor.)
- Static security analysis. These tools read the code without running it and look for dangerous patterns, such as user input that reaches a database query unchecked. CodeQL, GitHub's tool, and Semgrep are common choices.
Automatic check for observability. "Observable" means that from the outside (from logs and error reports) you can tell what the system did and why it failed.
- No empty
catch. ESLint'sno-emptyrule blocks empty blocks, including an emptycatch. Acatchthat holds only a comment still passes, but at least it makes the author say why the error is ignored. - Errors are captured and reported. An error-tracking service collects the errors that reach the top of the application, so people see them without waiting for a user to complain.
- Logs carry context. A log line that says "error" helps nobody. A log line with the order and the original error tells you where to look.
try {
await chargeCard(order);
} catch (error) {
logger.error({ err: error, orderId: order.id }, 'Card charge failed');
throw new PaymentError('Card charge failed', { cause: error });
}
The log line has context, the original error travels on as cause, and nothing is lost. Note what the log doesn't contain: the card number. Being observable never means logging everything.
Review question. What does this change trust, and what happens when it fails? Look at every new input from outside (a form, a request, a file) and every new package. Then look at what happens when it fails: if this call fails in the middle of the night, will anyone know, and will the logs say why?
The rule across all seven: a person is accountable
Every principle above can be checked, and most of the checks are automatic. None of them decides whether the change is a good idea. That is the job of the one rule that crosses all seven: the AI proposes, a person decides, and that person answers for the result.
In practice it comes down to two habits:
- No pull request is merged without a human review. GitHub's branch protection rules can require at least one approval before a change reaches the main branch[9], so the rule doesn't depend on anyone's memory.
- Whoever merges answers for the code, whoever wrote it. "The AI wrote it" is not an answer in a review after something breaks in production, just as "the intern wrote it" never was. If you can't explain a change, you don't merge it.
This rule is also what makes people follow the other seven. A team where people answer for what they merge has a reason to keep changes small, ask "could this be done with less?" and read the tests, not only check that they pass.
Putting it together
The table gathers the seven principles: what a machine checks, what a person asks and how much of the principle a machine can judge.
| Principle | Automatic check | Review question | How much a machine can check |
|---|---|---|---|
| Simple | Complexity and size limits, unused code (Knip) | Could this be done with less? | |
| Clear | Strict TypeScript, no any, naming rules | Does someone else understand it without an explanation? | |
| Consistent | Formatter, shared lint, rules for your own conventions | Does it look like the rest of the project? | |
| Verifiable | Required tests, blocking type check, domain coverage | Is there a test that would fail if this were wrong? | |
| Modular | Import boundaries, no cycles (dependency-cruiser) | Does this change stay where it belongs? | |
| Reviewable | PR size warning, PR template | Can I review it in one sitting, and do I know why? | |
| Secure and observable | Dependency audit, secret detection, static analysis, no empty catch | What does it trust, and what happens when it fails? |
The last column shows where human attention should go. Machines judge consistency and correctness well. They judge simplicity and intent badly. So the automatic checks take care of most of the first group, and the reviewer spends their time on the second.
That leads to the principle behind all the others: anything that can be automated should block the merge in CI, and human review is kept for what machines can't judge: intent, design and simplicity. A check that only warns is soon ignored. A rule that lives only in a reviewer's head is applied only when the reviewer remembers it.
Here is one CI workflow for GitHub Actions that runs all the automatic checks from this post. A failing step fails the whole job. The job only blocks the merge once the branch protection rules list it as a required check; then any failing step stops the change.
# .github/workflows/ci.yml
name: ci
on: pull_request
permissions:
contents: read
pull-requests: write # lets Danger comment on the PR
jobs:
checks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # full history, so Gitleaks can scan every commit
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
# Consistent
- run: npx prettier --check .
# Simple, Clear, Consistent, and no empty catch
- run: npx eslint . --max-warnings 0
# Clear and Verifiable
- run: npx tsc --noEmit
# Simple: unused files, exports and dependencies
- run: npx knip
# Modular
- run: npx depcruise src --config .dependency-cruiser.cjs
# Verifiable
- run: npx vitest run --coverage
# Secure
- run: npm audit --audit-level=high
- uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# repositories owned by an organisation also need a free GITLEAKS_LICENSE key
# Reviewable
- run: npx danger ci
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
The order of the steps matters a little: the cheap checks (format, lint) run first, so a simple mistake fails in seconds instead of after the whole test suite.
Where to start
Turning all of this on at once in an existing project would produce thousands of errors and a team that hates the checks. Add them one at a time, in an order where each step is useful on its own:
- Write the conventions file. A short
AGENTS.md(or your tool's equivalent) with how the project is organised and the few rules that matter. It costs an hour and changes every AI session from the next day. - Add the formatter and make lint block. Format the whole project in one commit, then fail CI on any lint warning.
- Make the type check and the tests block the merge. If they already run, this is one line in CI.
- Require one human approval on the main branch.
- Add the security checks. Dependency audit and secret detection are quick to set up and catch real problems in the first week.
- Add the PR template and the size warning.
- Write the module boundaries down with dependency-cruiser, starting with the one boundary you care most about.
- Turn on the complexity limits last, at values most of the current code already passes, and lower them over time.
None of these steps needs AI to be useful. Good teams have done most of them for years. What has changed is the cost of skipping them: when a machine writes a large part of the code, a rule that nobody checks is a rule nobody follows, including the machine.
References
- Neil Perry, Megha Srivastava, Deepak Kumar, Dan Boneh, Do Users Write More Insecure Code with AI Assistants? — arXiv
- Joseph Spracklen et al., We Have a Package for You! A Comprehensive Analysis of Package Hallucinations by Code Generating LLMs — arXiv
- GitClear, AI Copilot Code Quality: 2025 Data Suggests 4x Growth in Code Clones
- Google Cloud, Announcing the 2024 DORA report
- AGENTS.md — a simple, open format for guiding coding agents
- SmartBear, Best Practices for Code Review
- Google, Small CLs — Google Engineering Practices
- Michael Nygard, Documenting Architecture Decisions — Cognitect blog
- GitHub Docs, About protected branches
