"The calculation logic for this batch process changes only at the end of the month—does anyone know why?" When taking over a system in custom development and starting modifications, work stalls not because of technical complexity, but because no one understands why the code was written this way. The code runs. However, the underlying business rationale—which regulation it complies with, why this specific customer tier is an exception, or what business convention dictates this rounding logic—is nowhere to be found in the code or documentation. The original engineers have long since left, and nobody remembers the context. Development halts not because of technical barriers, but due to a complete loss of domain knowledge.
A direct examination of this dilemma appears in the Zenn article, Where Should Knowledge Go If Refactoring Requires Domain Knowledge? (Zenn). Even in an era where AI generates code, the domain knowledge dictating why code should be written a certain way must be supplied from outside the code itself. Where that knowledge resides dictates future maintainability. In this article, we outline where and how to preserve the domain knowledge required for refactoring inherited client systems from a software engineering perspective.
Why domain knowledge gets lost
The channels through which domain knowledge leaks out of codebases follow predictable patterns.
First, working code remains, but the "why" is omitted. Business rules that were self-evident to the original implementer rarely get written down. Because code reveals only outcomes and hides motivations, the rationale vanishes when that developer leaves.
Second, knowledge clings to specific individuals. Relying on "just ask Person A about that routine" works while they are present, but when they transfer or leave, the organization loses that knowledge instantly. For teams taking over systems in client development, this is the most difficult situation to inherit.
Third, documentation drifts out of sync with code. Even when specifications exist, failing to update them alongside modifications turns them into unreliable documents that contradict the code. Developers stop reading them, and they fail as knowledge repositories.
Consequently, every code modification forces teams to start over by re-interviewing stakeholders about business rules, inflating development costs. While recording architectural choices was explored in our article on Architecture Decision Records (ADRs), this article addresses the prerequisite: where to store the domain knowledge explaining why the business logic exists in the first place.
Where to preserve domain knowledge: three repositories
Different knowledge repositories offer distinct advantages and drawbacks. The essential practice is to avoid relying on a single medium and leverage each according to the nature of the information.
| Repository | Best suited for | Weakness |
|---|---|---|
| Close to code (comments, naming, types) | "Why this line is necessary" | Cannot capture overarching background or big picture |
| Tests | "How it should behave (concrete examples)" | Difficult to express the underlying "why" |
| Documentation | Background, history, global rules | Rots without continuous updates |
The first location is right next to the code. Explain why a branch exists in a single-line comment, use domain terms in naming like taxExemptForSmallBusiness, and eliminate impossible values using types. Explanations of why a specific line is needed are least prone to rot when kept right beside the code.
The second location is tests. If a business rule states that calculation formulas change at month-end, writing an automated test asserting expected values for month-end inputs preserves behavioral specifications in an executable format. If modifying code breaks a test, developers immediately see that a business rule was violated. Tests serve as living, un-rotting documentation.
The third location is documentation. Historical context explaining why a customer tier requires exceptions or overarching business workflows cannot fit comfortably in code or tests. Document these in written specs. However, as noted below, this documentation decays unless tied to continuous maintenance processes.
Principles to prevent knowledge from rotting
Choosing locations is futile if knowledge is not updated. In client development, two principles ensure real-world effectiveness:
First, make code changes and documentation updates a single task. Include updates to relevant background documentation in the same pull request modifying the code. Splitting them into separate tasks guarantees documentation will be postponed and drift out of sync.
Second, prioritize documenting the "why." Anyone can inspect code to see what it is doing, but code cannot reveal why it does it. When deciding where to spend limited engineering capacity, documenting the business rationale behind a process saves future maintainers far more than explaining mechanics. Just as with isolating shared foundations, preserving high-impact knowledge matters most; the challenge noted in our article on returning wrong abstractions to duplication—where code cannot be safely untangled without historical rationale—is the flip side of missing domain knowledge.
Pitfalls When Integrating Agents in Custom Development
In an order management system GleamHub inherited for ongoing maintenance (client name withheld), shipping cut-off times were governed by complex branching logic, yet neither code comments nor documentation explained why those times existed or why specific regions received separate rules. Every release required telephone interviews with client staff to understand the business operations—a precarious tightrope walk. Had that staff member changed roles, modifying the system would have become nearly impossible.
We began by capturing the "why" in code comments and tests whenever touching an affected area. We added single-line comments explaining cut-off time rationales, renamed regional exceptions using domain terms, and codified rules like "this region closes one hour earlier" into automated test assertions. Broader history that could not live directly in code was gathered into documentation updated alongside each pull request. Consequently, subsequent releases eliminated the need for upfront operational discovery calls, keeping business knowledge embedded within the system even through staff changes. All we did was anchor ephemeral interview insights into durable code and tests.
The most impactful takeaway from this project was not attempting to catalog all domain knowledge at once. Trying to document an entire business operation upfront collapses under its own weight. Instead, record the "why" incrementally for areas touched during actual maintenance. This gradual accumulation mirrors the approach of modernizing systems without halting production—the same philosophy of incremental adoption covered in our article on managing dependencies in monorepos.
Where to begin
Inherited systems become maintainable when you stop blaming technical complexity for stalled updates and examine whether business rationale was preserved. Keep the "why" close to code, define expected behavior in tests, and store background history in documentation—distributing knowledge by type and updating it alongside code changes keeps domain knowledge fresh.
As a first step, identify one area from your most recent release that required asking the client to explain business rules, and anchor the answers you uncovered into code comments and test cases. That alone eliminates one round of re-discovery in the next release cycle.
If code updates stall because business rules must be re-discovered every time, if knowledge is locked inside specific individuals, or if decaying specifications cannot be trusted, please reach out via GleamHub's contact form. We can help you build operational workflows that incrementally capture domain knowledge across code, tests, and documentation while maintaining your live systems.
