标签：#codequality

In virtually every software engineering team, the temptation of the 'quick and dirty' fix surfaces sooner or later. The sprint deadline is looming, stakeholders are eager for a release, and a code snippet exists that barely passes the happy path. The logic is undocumented, edge cases remain unaddressed, and the design is brittle, yet the ticket can technically be moved to 'Done'. In the short term, everyone appears satisfied: the feature ships and the milestone is recorded. But before long, the consequences arrive: subtle bugs surface in production, extending the codebase becomes perilous, and teammates spend frustrating hours attempting to decipher undocumented logic. What began as a brief shortcut solidifies into technical debt and team friction. At the core of Christian ethics lies the command to love your neighbour as yourself. While that principle is often discussed in abstract theological terms, in modern software engineering it takes on direct, tangible significance. Who is your neighbour in a development team? Your neighbour is the colleague who will maintain, debug, or extend your pull request six months from now. Your neighbour is the junior engineer looking to existing code for guidance. And your neighbour is the end user relying on the system to function reliably and securely. When you deliberately invest effort in clear naming conventions, modular architecture, comprehensive documentation, and thorough automated tests, you provide genuine service to your peers. You choose to carry the cognitive burden today so that someone else does not suffer tomorrow. That is Christian care translated into code. Craftsmanship extends beyond syntax; it shapes the cultural atmosphere of an engineering team: Honesty regarding technical debt: Having the courage to articulate when architectural shortcuts threaten system sustainability, rather than passively allowing brittle code into production. Constructive peer reviews: Conducting code reviews with the intention of mento

There is a habit I have for other people's libraries that I do not have for my own code: before I call something, I read what it returns. With my own functions I skip that, because I wrote them, so I know. Three times in three days that turned out to be false, and the third time I caught it before it cost anything only because I had started treating my own modules like somebody else's. The version I had already been burned by twice I maintain qbofile , a set of browser-based converters between the file formats accounting software uses. It is a small codebase: a parser per input format, a generator per output format, and pages that wire one to the other. Wiring a new pair felt like plumbing, so I estimated it like plumbing. Two new pages, both reusing an existing parser and an existing generator: no new code. I said that out loud before opening either end. The generator had no column for the thing the parser produced. The parser could read the category a user had assigned to each transaction; the CSV generator emitted six fixed columns and category was not one of them. Not a bug — it had simply never needed one, because the format it was originally written for does not carry categories. That is a strange kind of wrong. Nothing was broken. The code did exactly what it always had. My model of it was built from the function name. The same evening, in the same pair of modules, the second one: L . push ( `P ${ sanitizeText ( tx . description )} ` ); P is the payee field in that output format. M is the memo. Two fields, and upstream, description was defined as memo || payee . So for any transaction that had a memo, the memo took the payee slot and the actual payee was dropped. Silently — the file is valid, it imports fine, and the missing name never announces itself. The two minutes that caught the third one After the second one I wrote down a rule and did not really believe I needed it: before wiring two components together, open both ends and read what actually crosses.

You said you'd remove that flag after launch. You lied. It's been six months and the flag is still in appsettings.json , the if statement is still in your controller, and nobody remembers which state is "on." This is how codebases turn into haunted houses. Why Cleanup Matters Dead feature flags are technical debt with teeth . They add branches to your code that nobody tests. They confuse new developers who don't know the history. They inflate configuration files and make deployments harder to reason about. And they compound. Every flag you don't clean up makes the next cleanup harder because the cognitive load of understanding the system keeps increasing. The cost of removing a flag is lowest immediately after the feature ships, while everyone still remembers what the thing does. Six months later? Good luck. Track Every Flag You can't clean up what you can't find. Maintain a registry of every active feature flag with: Name Purpose Owner Date created Expected removal date This can be a spreadsheet, an issue tracker, internal documentation, or a dedicated feature flag management system. The format doesn't matter nearly as much as the habit. When you add a flag, add it to the registry. When you remove a flag, remove it from the registry. If your registry contains flags with no owner or no removal date, congratulations: you've found your next cleanup project. Set Expiry Dates Every flag should have a planned removal date when it's created. For example: Release toggles: Remove shortly after the feature ships. Two weeks is a reasonable default. Experiment toggles: Remove when the experiment concludes. Ops toggles: May be permanent by design. Permission toggles: May also be permanent, but document that explicitly. If a flag has been alive longer than its planned expiry and nobody deliberately extended it, it's already a zombie. Treat it accordingly. Make Cleanup Part of the Process Flag cleanup doesn't happen unless someone owns it. Add a cleanup step to your feature compl

Originally published at fathohm.dev . The term "comprehension debt" is Jason Gorman's, from September 2025, carried by Addy Osmani in March 2026 — this piece is about measuring it. There's a module in your codebase that shipped last month. It works. It has tests. It passed review. And if it breaks at 2am, nobody on your team can explain what it does. Ask "who understands this?" about any given file in an AI-native codebase and the honest answer, increasingly often, is no one — not because your engineers got worse, but because the code stopped passing through their heads on its way into production. The decoupling For seventy years, code getting written implied that somebody understood it. The implication was so reliable we never thought of it as an assumption: writing code was the act of understanding a problem precisely enough to express it. However bad the code, however absent the docs, there was at minimum one person — the author, at the moment of authorship — who knew what it did and why. Every practice we have for keeping teams oriented in a codebase quietly leans on that floor: review assumes the author can defend the change, onboarding assumes someone can explain the system, debugging assumes a colleague to ask. AI agents broke the implication. Code getting written and code getting understood are now separate events, and only one of them is scaling. An agent can produce in an afternoon what a team used to write in a month — and the afternoon does not come with a month's worth of understanding attached. The floor of "at least the author knows" is gone: for agent-authored code, the author isn't on your team. It isn't anyone. The gap between what a codebase does and what the humans responsible for it understand needs a name, because things without names don't get managed. It has one, and it has had one for a while. Jason Gorman named it comprehension debt in September 2025 — what happens "when teams produce code faster than they can understand it" — and Addy Osma

A month ago I shipped aicraft-code-review , an MCP server that reviews code locally. This week I added a CLI mode — because not everyone wants to wire up an MCP client just to check a diff. Now the same reviewer runs three ways: MCP tools — review_code / review_diff / review_file inside Claude Code, Cursor, Cline CLI — mcp-code-review review-file path/to/file.py CI — pipe git diff into it and branch on the exit code The CLI pip install aicraft-code-review # a single file (config auto-discovered from the file's directory upward) mcp-code-review review-file src/api.py # the current diff git diff | mcp-code-review review-diff # a snippet mcp-code-review review-code "import os; os.system('ls')" Exit codes are CI-friendly: Code Meaning 0 clean, or only info-level findings 1 high / medium issues found 2 critical issues found What it catches out of the box Security (OWASP patterns), performance (N+1, unbounded growth), quality (bare excepts, TODOs, missing type hints), style (naming, line length). Real output: ### 🟠 High (2) | Line | Issue | Category | Fix | | 4 | Command injection risk | security | subprocess.run with args list | | 9 | N+1 query in loop | performance | batch query / eager loading | ### 🟢 Info (2) — missing return type annotations Verdict: Conditional Pass — address high/medium issues Making it match YOUR rules The config file is the part I'd actually show a teammate: custom_rules : - name : no-console-log pattern : ' console\.log\(' severity : high category : quality issue : Console logging left in production code fix : Use a structured logger instead disabled_checks : - todo_comment severity_overrides : hardcoded_secret : critical .mcp-code-review.yaml is auto-discovered from the reviewed file's directory upward MCP_CODE_REVIEW_CONFIG points a whole team at one shared profile valid severities: critical / high / medium / info regex patterns work best in single quotes (double quotes will error on escapes like \. ) One caveat if you're also shipping Python

Running LLM jobs over hundreds of items, the obvious shortcut is to collapse execution and verification into one model pass: one call, one output, ship it. It fails at scale, and a scoring system for 146 countries across 11 categories shows exactly why. Each score runs 0 to 100 on a single canonical dataset, the overall rating is the arithmetic mean of those 11, and there are no per-country exceptions. One yardstick, applied identically everywhere. Ask a cheap model to generate all 146 in one pass and you get speed with a hidden cost: drift. One country's "friendliness" score reads high because the model read it as social warmth rather than visa bureaucracy. Another's culture score inflates after the prompt happened to emphasize food over history. None of these are bugs, they're quiet inconsistencies, and at 146 items a 5% drift rate means seven countries silently failing the canonicity requirement while every individual score still looks reasonable. The pattern Step one: a cheap executor runs the mechanical pass. Fixed ruleset, all 146 countries in parallel batches, structured JSON out. No judgment calls, just apply rule X to field Y. Step two: a stronger gate verifies before anything ships. Same scale everywhere? Any statistical outlier? Did a category get reweighted mid-run? This is judgment work, holding many items in view at once, and it's what a single combined pass can't do reliably. A model doing both jobs at once optimizes for the wrong thing: it second-guesses the ruleset mid-run, adds nuance where the spec demanded consistency, and marks cases "exceptional" that shouldn't be. Splitting the two roles is faster and cheaper than one model trying to hold both contexts simultaneously. Where the consistency requirement bites The Country Comparison Tool's best-travel-months field works the same way: a month qualifies if it scores 70 or higher on a fixed weather index built from Open-Meteo data, no editorial override, no "tourists usually go in December anyway."

Part of "AI, engineering and what survives production", a series on the parts of building with AI that hold up once real traffic hits them. There is a claim going round that you have probably absorbed by now: AI-assisted development is making codebases worse. Refactoring is down, duplication is up, we are all writing more and revising less. The numbers behind it are real, the samples are enormous, and I found I had started repeating the conclusion in conversation without ever having checked it. Then it occurred to me that those figures are averages taken across hundreds of millions of changes from thousands of organisations, not one of which is mine. So what is the rate in your repository? Nobody has told you, and on current evidence nobody is going to. I set out to find mine, assumed it would take an afternoon, and spent three days discovering that the answer is far harder to get at than the confident version suggests. So this is not a piece about what AI does to code. It is about how to ask that question of your own repository without arriving at a wrong answer, which turned out to be the genuinely difficult part. The tool I built to do it is git-habits : free, local, and it reads no source code whatsoever. What git can actually tell you Git history is a surprisingly rich behavioural record. Not of quality, about which it knows nothing at all, but of habits: how often you commit, how large those commits are, whether you go back and change what you wrote last month, and whether anybody still touches the old code. That is a narrower thing than quality and it is the thing the industry claims has changed, so it is the thing worth measuring. Four signals are computable from commit metadata alone, without opening a single source file: Moved lines. The share of changed lines sitting in files git detected as renamed or copied. It is the closest thing history offers to "somebody went back and reorganised this." Legacy touch. The share of changes landing on files nobody has

Empirical research from ReWeaver AI. 42 identical prompts, across 5 tools and 8 production dimensions, compared to human baseline. One metric that changes how you see drift. Everyone knows AI-generated code has quality issues. What’s less understood is that the way most teams measure those issues — by how often they occur — systematically understates the risk. We ran a controlled study to find out how badly. The answer surprised us, particularly in one dimension. What We Did We gave five leading AI coding tools (Cursor, Claude Code, Lovable, Figma Make, and VS Code with Copilot) 42 identical prompts: realistic single-component builds — buttons, forms, dashboards, navs, modals, auth surfaces. We scanned every output with ReWeaver, our deterministic drift-detection engine, across eight production readiness dimensions: User Experience Security & Privacy Accessibility Design Consistency Reliability Maintainability Architecture Testability We also scanned six human-authored open-source repositories as a reference baseline. For each dimension, we calculated two things: Drift frequency — the percentage of lines containing at least one drift occurrence. Counts what went wrong. Production Drift Ratio (PDR) . The PDR is a metric that weights frequency by estimated remediation cost on a 0–1 scale. A PDR of 0.30 is roughly 45 minutes of cleanup per component; 0.70 is about 2.5 hours. The Finding That Stopped Us In Security & Privacy , AI tools produced 3× the human drift frequency . That looks manageable — a meaningful gap, but not alarming. The PDR was 22× the human reference . Not 22% more. 22 times more costly to fix. The frequency gap makes Security & Privacy drift look like a minor concern. The PDR reveals it’s the most expensive problem in the dataset. AI-generated security drift (client-side authorization gates bypassable in DevTools, raw PII and credentials passed through props without tokenization) is syntactically identical to safe code. It passes review, but the fixe

The Core Argument : AI agent reliability isn't achieved by "making the agent smarter" — it's achieved by the simple engineering principle of separating validation from generation . Quality isn't accidental. It's designed. What You'll Learn : Maker/Checker separation, 6 termination conditions, and an automated feedback loop — all with runnable code. 0. Prerequisites Python ≥ 3.10 OpenAI API Key (or compatible interface) pip install openai>=1.0.0 (Optional) pip install anthropic>=0.30.0 if using Claude as Checker 1. The Pain: Why "Agent Checks Itself" Is a Trap 1.1 The Copying of Cognitive Bias A team built a data-analysis agent. It pulled sales data from a database and generated business reports. The team added a "self-review" step: after generating, the agent told itself "please check if the data you just output is accurate." Result? The agent always replied "data is accurate." Even when the team deliberately injected obvious errors (e.g., monthly sales of -50M RMB), the agent confidently said everything was fine. This isn't the model being "disobedient." It's a more fundamental issue: when the generator and checker are the same entity, the check is just a restatement of the generation process — not real validation. The checker carries the exact same cognitive bias, knowledge boundaries, and reasoning path as the generator. 1.2 The Amplifier Effect of Confirmation Bias Self-checking also triggers a subtler problem: confirmation bias amplification. The model builds a "belief state" during generation; when re-examining, it tends to confirm rather than overturn. Experiment data (from Anthropic research): Same model does "generate → self-review": ~12% error-correction rate A separate model instance reviews: ~37% error-correction rate A different model family reviews: ~52% error-correction rate 1.3 The Value of Independence First principle of quality assurance: the checker must be independent of the generator. In agent architecture, the engineering expression of this is

How I Built a Full-Stack Quality Skill for AI Coding Agents AI coding agents are getting very good at writing code. But I kept running into the same problem: They can move fast, but without strong project rules they can also create messy architecture, duplicate utilities, inconsistent APIs, weak security checks, and frontend components that slowly drift away from the design system. So I built Full-Stack Quality Skill . It is a reusable AI coding skill for full-stack audits, architecture guidance, long-term project memory, and CI quality gates. Repo: https://github.com/lablnet/full-stack-quality-skill Website: https://skills.lablnet.com Why I Built It When I use AI agents like Cursor, Codex, Claude Code, Antigravity, or similar tools, I do not only want them to "write code". I want them to think like a careful senior engineer: Is the database normalized correctly? Are backend layers clean? Is business logic leaking into controllers? Are frontend components consistent? Are Vue components using composables? Are React components using hooks correctly? Are HTTP methods and status codes right? Is GraphQL safe from N+1 problems? Are security and privacy risks checked? Are tests missing for critical paths? Is documentation still matching the code? That is a lot to remember every time. So instead of repeating the same instructions in prompts, I turned them into a reusable skill. What It Covers The skill includes audit areas for: Database Backend Frontend Mobile HTTP APIs GraphQL Security Privacy Accessibility i18n Analytics Background jobs Infrastructure Testing Performance Observability Delivery / CI Multi-tenancy Payments Notifications Data import/export API compatibility Developer experience AI/LLM safety It also includes examples for common stacks: Node.js / TypeScript Python Django Laravel Java / Spring C# / ASP.NET Core Go Ruby on Rails React Next.js Vue Angular SvelteKit Flutter React Native Kotlin / Android Swift / iOS SQL GraphQL Read-Only Audits by Default One impo

If you’ve spent any time recently writing detailed product requirement documents or meticulously...

This is the workflow I follow before I use AI agents to implement any feature or bug fix. 🧭 Requirements/Specification ↓ Design/Architecture ↓ AI Code Generation ↓ Human Review ↓ Build & Static Analysis ↓ Testing & Validation ↓ Defect Resolution ↓ Security & Compliance Review ↓ Release ↓ Production Monitoring vs Claude Code ↓ Implements feature ↓ Codex QA Agent ↓ Runs application ↓ Tests happy path ↓ Tests edge cases ↓ Tests error handling ↓ Produces QA report This will resolve the self-review bias, confirmation bias, or AI-to-AI bias. 1️⃣ Understand Before Writing Code Before touching any code, I try to understand what I'm building and why . I usually start by reading: specs/<module>/<TICKET>-<slug>.md plan/<module>/<TICKET>-<slug>.md status.md Then I review the project conventions: specs/CONVENTIONS.md specs/conventions/core-porting.md Finally, I read the existing implementation (entities, services, mappers, etc.) so my changes follow the existing architecture instead of introducing a new style. 💡 Pro-Tip Good code fits into the codebase. Great code looks like it was always there. 2️⃣ Plan the Change Once I understand the requirements, I identify which architectural layers are affected. I always respect the dependency order: Schema / Entities / DAOs ↓ Mappers / DTOs ↓ Service Layer ↓ Application Layer ↓ Controllers I don't jump ahead of dependencies. If a change is complicated or ambiguous, I document the approach before writing code. --- ## 3️⃣ Write the Code While implementing, I follow the repository's rules. Some examples: | Rule | Detail |---|---|---| | DTOs | Generated from `schema.yml` — never handwritten | | Status values | Sourced only from the Core Porting specification | | Traceability | Every ported behavior includes a source citation | Citation formats I use: - `← Source <path>` - `← PS §...` - `← BR-###` Beyond repository rules, I also try to: - ✅ Match existing naming conventions - ✅ Keep comments minimal and meaningful - ✅ Make small, focused chang

A developer added an AI reviewer to a small Node and React project expecting an easy win. At first, the comments looked useful. Then the reviewer started repeating style complaints, commenting on code that had already changed, and missing a misplaced null check that crashed the application in staging. The team still had to perform a complete human review. That experience, shared in a public DevOps discussion, captures the real question engineering leaders should ask before adding an AI reviewer to every pull request: Did the reviewer remove work from the team, or did it create another thing the team had to review? The problem is not that AI review never works Developers report genuinely useful results too. In one Experienced Developers discussion, engineers described AI reviewers catching privacy leaks, incorrect data-flow assumptions, and logic errors that human reviewers had missed. In the same discussion, another engineer said their review bot was useful but produced plausible, inaccurate comments about one-third of the time. These are anecdotes, not a benchmark. But together they explain why the debate feels confused. AI review is not simply good or bad. Its value depends on the codebase, the context available to the reviewer, the kind of issue being reviewed, and how much verification its output requires. A tool can catch one subtle bug and still make the overall review process slower. It can also say nothing on several pull requests and then save a team from a serious failure. Counting comments cannot distinguish between those outcomes. Comment volume measures activity, not value GitHub says Copilot code review has completed more than 60 million reviews. Its definition of a good review has changed as that volume has grown. The team says it moved from optimizing for thoroughness to optimizing for accuracy, signal, and speed. GitHub reports actionable feedback in 71% of Copilot reviews. In the other 29%, the reviewer says nothing. That silence is intentional: if

Gone are the hours of careful thought and planning that go into coding a new feature. Vibe coding is too risky though, so another Driven Development was created. I'm referring to SDD (Spec Driven Development) of course. The vibe coding approach is great for prototypes and throwaway code, but this way of working falls apart when teams realise that the code needs to be maintained. So the thing that helps fix this is SDD. Create a spec once from clear technical specs and then generate some high quality code. Sounds great, right. Reminds me of IaC, where you use a templating language to create infrastructure. Software as Code maybe. SaC anyone? Unfortunately, in practice it's not that straightforward. Thoughtworks have placed SDD into an "Assess" category and warned that it could be an anti-pattern for releasing software. Deterministic vs Probabilistic This article isn't about SDD. I'm more interested in discussing the output of SDD and how that is tested. Code can now be generated fast these days. So what better to test AI-written code than with AI itself. There are a lot of concepts and technical terms for the Quality Assurance part of AI generated code. One of these is the LLM-as-a-Judge idea. This idea is used to score the output of an LLM based on some explicit criteria. Traditionally, the way to evaluate an LLM was to judge its output on the helpfulness or faithfulness (using something called "exact-match" metrics). Sometimes it was usually down to a human to do this. It also changes the way that Quality is Assured when dealing with AI-written code. Traditional QA is built on deterministic checks; either something does or does not fail. Something like expect(x).toContainText(y); . A failing test means that something is wrong. Then the bug can be fixed in the code and the test will pass. However, the outputs of an LLM are probabilistic , so it breaks the traditional pass/fail model. This is where a judge comes in. Instead of pass/fail, it can assign a score based o

There is a growing sentiment in engineering circles right now that documentation is a relic of the past. The argument usually goes something like this: We’re living in the era of agent-driven development. If an AI agent can read the raw source code or parse an OpenAPI specification instantly, why waste human engineering hours writing prose? Code churns too fast anyway, and human-written docs are outdated the second they’re committed. It’s an attractive, black-and-white view of the world. It’s also completely wrong. Chasing strict determinism in your source of truth is a pipe dream. Code and specs tell a system how something works, but they are fundamentally incapable of explaining why it was built that way in the first place. The Intent Gap: Why Code Isn't Enough Even if you’re building entirely for a downstream consumer of AI agents, there is a massive, structural gap between a raw API specification and an operational reality. Agents are phenomenal at pattern matching and syntax execution, but they struggle with architectural philosophy and human intent. We still need words to contextualize the boundaries. A spec can define an endpoint, its parameters, and its payload. What it can't capture is the nuance of why a specific architectural trade-off was made, or the implicit historical context of a legacy edge case. Prose provides the guardrails for non-deterministic systems. Even if that prose is ultimately consumed by a machine rather than a human, the written word remains the highest-leverage way to transmit intent. The Danger of Slop Describing Slop This doesn't mean we need to return to the days of manually maintaining massive, static wiki pages. Automation has a massive role to play here. Cascading automation—where documentation is dynamically generated alongside code changes—is incredibly powerful. But there’s a trap here: slop describing slop is entirely useless. If we completely hand off documentation generation to unchecked LLMs, we end up with a feedback loo

A while back I set three targets for my engineering team. Not velocity. Not story points. Not "things shipped." Just three numbers. Together they tell me whether the work is moving the way it should, or whether next week is shaping up to be a fire-fighting week. I check two of them most days. The third I used to watch closely...until we lost the tool that measured it. Here they are, and why they earned their spot. Why these and not just velocity The first metric most engineering managers reach for is velocity. Story points completed, tickets closed, work merged. Velocity is worth watching. It is a lagging indicator...it tells you what already happened...but it still shapes what comes next. When a sprint's work doesn't get finished, it rolls into the following one, and that rollover eats into whatever you had planned. What velocity doesn't tell you is how the work moved...whether it moved in a way that's going to come back and bite you. For that you need numbers that describe the shape and quality of the work, not just the amount of it...ideally ones that flag a problem while there's still time to act. These three do that. 1. Average PR size Target: under 300 lines changed per PR. What it tells me: how well the team is decomposing work. A team consistently shipping oversized PRs isn't producing more... they're producing PRs that no reviewer can read carefully. Big PRs get rubber-stamped. Rubber-stamped PRs are where production bugs hide. The 300-line target isn't magic. It's roughly the size below which most reviewers will actually read every line. I tell my team to aim for under 300 changes and to treat 500 as a hard ceiling, give or take a handful of genuine exceptions. Past 500 changes, I consistently see quality, review time, and thoroughness all drop sharply...the PR stops getting read and starts getting skimmed. When the team's average creeps up over a few weeks, I have an early signal that one of three things is happening: Stories are too coarse. The work does