i went back to a project i shipped three years ago. most of the code is gone. rewritten in a different framework, restructured across different services, owned by a team i've never met. but the project is still running. the schemas are the same. the boundaries are the same. the one doc in the repo that starts with "why we decided" is still pinned in their onboarding.
that was the first time i really understood what outlasts you in a codebase. it isn't the code. the code gets rewritten. the code always gets rewritten. what outlasts you is the set of constraints, names, and decisions that future engineers either inherit or fight.
this post is about what i actually try to leave behind. and the one part of stewardship nobody talks about, which is that most of it is deletion.
what actually outlasts you
if you zoom out five years on any living codebase, here's the honest list of what survived and what didn't.
code that survived:
- a few core abstractions that nailed the domain
- the data model (approximately)
- the public api shape (approximately)
- a handful of utility functions everyone grew attached to
code that got rewritten:
- almost everything else
but here's the thing. the rewrites weren't arbitrary. they were shaped. shaped by:
- the names you picked for things (a good name survives a dozen rewrites; a bad name gets carried forever because nobody wants to do the rename pr)
- the boundaries you drew between services or modules (those are load-bearing; rewriting them is a quarter of work, not an afternoon)
- the tests you wrote that captured intent instead of implementation
- the decisions you wrote down, and the ones you didn't
the code is soft. the structure is hard. stewardship is about the hard layer, not the soft one.
the artifact that matters most
if i had to pick one thing to leave behind on any project, it wouldn't be clean code. it wouldn't be great test coverage. it would be a single document that answers: "why is it this way?"
not "how does it work." anyone can read the code and figure out how it works. the question that eats future engineers alive is why. why did we pick postgres over dynamo. why is the retry logic exponential with a floor of 2 seconds. why does the worker pool default to 8. why do we denormalize the user table. why did we reject the obvious idea that every new engineer suggests in their first week.
the "why" doc is the artifact with the longest half-life in the entire repo. code decays in weeks. readmes decay in months. the "why" doc, written well, outlives the codebase itself. i've seen teams rewrite an entire system from scratch and keep the "why" doc verbatim because the reasoning was still right.
and yet almost nobody writes them. we write adrs that get filed and forgotten. we write comments that get lost in refactors. we write commit messages that nobody reads six months later. the "why" doc is different. it's one living page that answers every question that starts with "why on earth did we."
on regent, i have one of these. it's called decisions.md. it has maybe 30 entries. it takes me five minutes to update when i make a call. it has saved me hours every time a new contractor or collaborator asks an obvious question with a non-obvious answer.
the part of stewardship nobody talks about
here's the contrarian take: most of stewardship is deletion.
we talk about stewardship like it's about building well-crafted things that endure. but the bigger threat to a codebase isn't bad code. it's too much code. dead endpoints, half-finished features, unused config flags, abandoned experiments, "just in case" abstractions, dependencies nobody remembers adding, folders named /legacy that are load-bearing and nobody knows it.
every piece of code you leave behind is a tax on whoever comes next. they have to read it. they have to decide if it matters. they have to be afraid of deleting it because they don't know what it does. they have to carry it through every migration, every upgrade, every rewrite.
the most generous thing you can do for future engineers is not leave them more. it's leave them less. delete the dead code. remove the flag. consolidate the three near-duplicate helpers. rip out the feature nobody uses. write the "we removed this because" note in your commit so it doesn't come back.
on mailpilot i had a whole subsystem for "draft recovery" that sounded useful in design but had maybe two users ever hit the code path. i kept it around for six months because i was being a good steward. then i deleted it, wrote two paragraphs in the commit message explaining why, and the codebase got measurably easier to reason about that week. that deletion was the most generous thing i did for the project that month.
the "just in case" trap
good stewards fall into a specific failure mode. it's not "i wrote messy code." it's "i kept things just in case."
just-in-case is how codebases die. you keep the old handler because you might need it. you keep the feature flag because someone might flip it. you keep the parameter because a caller somewhere might depend on it. you keep the config value because you don't remember where it's referenced. you keep the table because you're not sure the cleanup job caught everything.
each individual keep looks responsible. cumulatively it's how a 2-year-old project turns into a 5-year-old swamp.
the discipline is: if you can't explain in one sentence why it's still there, it shouldn't be. "i might need it" is not a sentence. "team x depends on it until january" is a sentence. "it's the fallback when the main pipeline fails" is a sentence. "i forgot" is not.
what i actually leave behind
when i hand off a project or step back from one, here's my checklist. it's five things. none of them are "clean code."
-
a decisions.md. the why doc. 20 to 40 entries, one paragraph each, written in plain language. why we picked this, why we rejected that, what we'd revisit later.
-
a runbook. not "how to deploy." that's in the ci file. the runbook is "what to do when things go wrong at 2am." every alert the system can throw, with the actual first step. not "investigate the issue." something concrete.
-
a data model diagram. current, not from six months ago. the schemas are what outlast the code, so the diagram of them is the map future engineers actually need.
-
a deletion log. a commit history tag for every major thing i removed and why. so when someone asks "didn't we used to have x," the answer lives in the repo, not in someone's memory.
-
three names i'm proud of. this sounds silly but it's real. if i named the core abstractions well, engineers five years from now will inherit a codebase where things mean what they say. a good name is the cheapest, longest-lasting gift you can give a codebase.
what's not on that list: beautiful code, exhaustive tests, detailed javadoc, a comprehensive wiki, a perfect folder structure. those things are nice. they don't have long half-lives. the things above do.
the half-life of your work
everything you write has a half-life. some things decay in weeks, some in years. stewardship is the practice of investing your time in the parts with the longest half-life.
short half-life, don't overinvest:
- implementation details
- test fixtures
- configuration scaffolding
- naming inside a single function
- comments that restate what the code does
long half-life, invest hard:
- data model
- public api shape
- module boundaries
- the "why" doc
- names of core types and concepts
- the delete list
engineers with a stewardship instinct do this automatically. engineers without one polish the short-half-life things until they shine, and leave the long-half-life things undefined. you end up with a codebase that's beautiful in the small and incoherent in the large.
the monument vs the road
jeremy's framing is that craftspeople build things to last. that's true. but there are two kinds of things that last. monuments last because nobody can touch them. roads last because everybody uses them, and they get resurfaced constantly, and the route doesn't change.
monuments are dead. roads are alive. the code that outlasts you isn't a monument to your craft. it's the route, the decisions, the name. the code itself will be resurfaced a hundred times. if you built the route well, none of those rewrites will feel like a loss. if you didn't, every rewrite is a quiet tragedy.
build roads. write down why the road went there. delete the cul-de-sacs you added "just in case." hand over the map, not the pavement.
that's the part that outlasts you. and honestly, most of it fits in a single markdown file.