There’s a particular kind of sentence you only encounter in codebases maintained by people who know what they’re doing. It looks simple. It reads like a rule. But if you handed it to a junior developer and asked them to explain why it’s true, they’d need a paragraph — maybe two.
Split when a second concern appears, not when the file gets long.
A junior reads that and thinks: size doesn’t matter, got it. A senior reads it and recognizes ten past mistakes — the 800-line file that was fine, the 150-line file that was a disaster, the refactor that turned a length problem into a responsibility problem and made everything worse.
The sentence is compressed. The compression holds a decade of pattern recognition in twelve words.
This is what deep domain knowledge looks like when it’s working. Not frameworks, not tooling, not the ability to implement fast. The ability to write that sentence — and know, without explaining it, exactly why it’s true.
Why This Matters Now
AI can follow that sentence. Given “split when a second concern appears,” a model applies it correctly across thousands of files, consistently, without forgetting.
What AI cannot do is write it.
Writing it requires having watched the 150-line disaster happen. Having refactored the 800-line file and found it didn’t need splitting. Having argued with someone who thought size was the signal and seen why they were wrong. The compression is made of those incidents. You can’t derive it from first principles.
This is what changes in the age of AI. The execution layer gets cheap. The steering layer — the person who can write the sentence — becomes the scarce resource. Domain knowledge doesn’t become worthless. It becomes the thing that determines what all the execution is for.
The following sentences come from one project: a mixin-based business framework built over eleven phases. Each one took real work to earn.
The Collection
On architecture:
Split when a second concern appears, not when the file gets long. Length is a symptom; mixed responsibility is the cause.
What it compresses: the number of times a long file turned out to be fine, and the number of times a short file was two things pretending to be one. Size is observable but irrelevant. Responsibility is the actual signal — and it requires understanding what the code does to see it.
An escape hatch belongs in the spec, not discovered in the code. A developer who can’t find the override mechanism will rewrite the layer instead.
What it compresses: the pattern where a framework provides a way out but doesn’t document it, so the next developer concludes there is no way out and builds a competing implementation. The escape hatch that isn’t findable doesn’t exist.
Prototype chain metadata is always more reliable than a registry. Before reaching for a Map to track what was applied, ask whether the information already exists in the object graph.
What it compresses: the instinct to add a tracking layer when the structural information is already present. In a mixin system, every applied mixin leaves a static getter on the prototype chain. Walking that chain costs nothing and can’t go out of sync. A separate registry can.
On testing:
A fake adapter is not a mock. A mock returns what you tell it to return. A fake implements the full interface. Tests that pass against the fake will pass against the real adapter — because both honor the same contract.
What it compresses: the incident where mocked tests passed but the production migration failed. A mock tests that your code calls the right methods. A fake tests that your code produces the right outcomes. Only one catches a real regression.
Test count is the only honest exit criterion for a phase. “Feature works” is an opinion. “37 tests passing” is a fact.
What it compresses: every time a feature was declared done before edge cases were found, and every time a vague “done” caused a phase to drag without a finish line. The number forces you to define done before you start.
On code generation:
Every generator has two parts: the pure derivation and the impure shell. Test the derivation. Trust the shell. Never mix them.
What it compresses: the generator that wrote files during tests, requiring temp directories and filesystem mocking just to verify that column names were derived correctly. Separating the pure function from the I/O means the logic is testable in two lines.
toSource()output must round-trip. Ifeval(toSource(def))doesn’t equaldef, the generator is lossy.
What it compresses: the generator that produced syntactically valid code that silently dropped a field type or coerced a default value. The round-trip test is the only way to verify the serialization is complete.
On documentation:
A decisions file records what was rejected and why. The implementation already documents what was chosen. Only the decisions file can recover the road not taken.
What it compresses: every codebase where someone rewrote a component not knowing the original approach was tried and abandoned for a good reason that was never written down. Six months later, someone considers it again.
Write the spec before asking if it makes sense. A written spec exposes gaps. A verbal description hides them.
What it compresses: the planning session where everything seemed clear, the implementation session where four ambiguities surfaced immediately, and the realization that all four would have been visible if the spec had been written rather than discussed.
On Git:
Every commit body must be written as if it will be used as tutorial source material — because it will be. A commit that says only “add registry” is not acceptable anywhere.
What it compresses: the project history that reads like a changelog instead of a story. A commit body that names design decisions turns git log into documentation. A commit body that lists files turns it into noise.
The Thesis
Each of these sentences required something to go wrong first.
The fake-vs-mock rule required a test suite that passed against mocks and failed in production. The escape-hatch rule required a framework that got rewritten instead of extended. The round-trip rule required a generator that silently dropped data. The spec-before-discussion rule required a planning session that felt complete and wasn’t.
You cannot write these sentences from documentation. You can learn what a mock is from a textbook. You cannot learn when the distinction between a mock and a fake becomes a production incident — not until you’ve had the incident.
This is what software craftsmanship actually is. Not the ability to implement. The ability to compress what you’ve learned into a sentence that prevents the next developer from repeating the same mistake.
AI changes who does the implementing. It does not change who earns the right to write the sentence.
If anything, it raises the stakes. When execution is cheap and fast, the sentence matters more — because it’s the sentence, not the implementation, that determines whether all that execution goes somewhere worth going.
The developers who will matter most are not the ones who can prompt most fluently. They’re the ones who have been burned enough times to write sentences like these — and know, without explaining it, exactly why they’re true.