Best Practices Are Ergonomics

The canon was always "best for humans." Nobody needed to say so until now.

"Don't repeat yourself."

Most famous principle in software engineering. Also two completely different arguments wearing one sentence.

Argument one: a single source of truth is architecturally desirable. When a fact exists in one place, consistency is guaranteed.

Argument two: humans will forget to update the third copy.

These have been bundled together for so long that most developers can't tell them apart. They didn't need to. When the human was always the one writing and maintaining code, "architecturally sound" and "compensates for human limitations" pointed the same direction. No reason to separate them.

Until the coder changed.

Five similar route handlers are more transparent than one abstracted handler with a configuration parameter. Your AI collaborator can see all five simultaneously, understand the pattern, and modify any of them without tracing through an abstraction layer. The repetition is a feature: everything is visible.

But isn't five copies worse? What if you need to change them all?

This is where the arguments split. The architectural argument says: a single source of truth prevents inconsistency. The human argument says: you'll forget to update the third copy.

AI doesn't forget. It can make the same change in five places with zero drift. The human argument evaporates. What remains is the pure architectural claim, and the pure architectural claim for DRY is weaker than most people assume. Sometimes five explicit things are better than one clever abstraction, because the abstraction hides what's actually happening.

Programming is symbolic reasoning. Humans are bad at sustained symbolic reasoning.

This isn't an insult. It's physiology. Working memory holds about seven items. Sustained attention on symbolic tasks is metabolically expensive. Error rates climb with fatigue, which for symbolic work sets in fast. Humans naturally drift toward narrative and pattern recognition, the things our cognition evolved for, and away from the precise symbol manipulation that programming demands.

Every serious programmer has felt this. The moment where you've been staring at code for too long, where variable names start to blur together, where you're not sure if you already made that change or just thought about making it. The moment where you copy a block, update three of the four variables, and miss the fourth. The moment where you're reading a function and forget what the caller expected by the time you reach the return statement.

The entire best practices canon is a response to these specific failure modes. Not to the intrinsic difficulty of software. To the specific ways human cognition fails at symbol manipulation over time.

Once you see the split, it's everywhere.

DRY. The architectural argument (single source of truth) is real but narrow. Data normalization is genuinely about consistency. Code-level DRY is mostly about humans who'll mess up the copies.

SOLID. Single Responsibility says a class should do "one thing." But "one thing" is relative to the reasoner. What overwhelms a human mind is perfectly legible to a collaborator holding full context. The principle isn't wrong, but the threshold moved. Open/Closed, design for extension without modification, only matters when modification is dangerous. When your collaborator can rewrite a module from a description in seconds, modification is cheap and safe. The principle was protecting against the cost of human error during modification. That cost collapsed.

Design patterns. Named solutions to recurring problems, most of which were problems of human cognitive management. Strategy pattern: extract varying behavior behind an interface, so a human can reason about each piece independently. In a language with first-class functions, it's just "pass a function." The pattern existed because the language lacked the primitive and the human needed the scaffolding. Both constraints relaxed.

Encapsulation. Hide internals so consumers don't depend on them. For humans, this is essential cognitive load management. For AI, it's a black box. Every sealed boundary is something your collaborator can't see through. The protection that helped humans manage complexity now prevents AI from understanding the system. At system boundaries, encapsulation is still architectural truth. Within a codebase, it was mostly accommodation.

Test suites. I've written about this before: the need for extensive behavioral testing is a symptom of tangled code, not a virtue. The deeper point is that comprehensive test suites exist because humans can't hold the whole system in their heads. You probe from outside because you can't reason from inside. AI can often do both. Tests that compensated for human inability to reason about the code are solving a problem the new reader doesn't have.

Code comments. Exist because the next human won't have the context of the person who wrote it. Context loss between humans is the problem. Your AI collaborator doesn't have this problem. You can provide context directly, or it can infer from the code. Comments for human context transfer are noise for a collaborator that doesn't need them.

Not everything in the canon is accommodation. Some things are architecturally true regardless of who's coding.

Clear naming survives and maybe intensifies. Names are the primary linguistic signal. A collaborator that thinks in language cares more about naming than a human who can rely on visual memory and spatial recall. Good names were always good. Now they're load-bearing.

Security practices survive. Input validation, principle of least privilege, defensive coding at trust boundaries. These aren't about human cognitive limits. They're about the adversarial nature of the environment.

Idempotency, correctness invariants, mathematical properties. Logical truths, not ergonomic aids.

Separation at system boundaries. Your database shouldn't know about your HTTP routes. This is genuinely architectural. But the careful layering of abstractions within a module to manage cognitive load? That's accommodation.

The hardest part of this isn't intellectual. It's identity.

"Senior engineer" means, in large part, having internalized the canon. You feel visceral discomfort at repeated code. You instinctively reach for abstraction. You see a class doing two things and it bothers you like a crooked picture on a wall.

That taste was hard-won. It came from years of maintaining code where the lack of DRY caused real bugs. Where the absence of encapsulation made changes terrifying. Where missing tests let regressions ship. The practices weren't theoretical. They were scar tissue.

And now someone is telling you the scars were from a constraint that no longer applies. That the taste you built over a career was indexed to limitations your collaborator doesn't share. That the instinct pulling you toward abstraction is the same instinct making AI collaboration feel like work.

This is harder than learning a new framework. It's not about acquiring a skill. It's about recognizing that a skill you already have was always an adaptation, not a truth. The practices were real solutions to real problems. The problems just aren't the binding constraint anymore.

The whole canon was always "best practices for humans writing and maintaining code." We dropped the qualifier because there was no other kind of coder. Now there is.

The practices that compensated for human memory, attention, and symbolic reasoning limitations don't transfer to the new collaborator. The practices that reflected genuine architectural truth do. Separating them is the work.

Nobody told us the furniture was ergonomic. We just thought it was what offices looked like.