r/programming • • 1d ago

Make yourself replaceable

https://maroun-baydoun.com/blog/make-yourself-replaceable/
227 Upvotes

48 comments sorted by

222

u/redhand0421 22h ago

I know this was written literally yesterday but I’m curious how this kind of thing sits in an increasingly AI-fueled software engineering world.

Well-documented systems where the agent can infer which if statement not to touch (because it can see the comment and the commit that produced it) or knows which system fails over every other week (because there’s a pattern in the error reporting) aren’t as precious or precarious as they used to be.

I would love to pair-program with someone to teach them a new system. By the time I’ve scheduled time with them, they’ve already sat down with Claude and put together a possible implementation/fix. They’re none the wiser (they don’t have any new context that I have to impart, nor did they need it) so my advice isn’t seen as valuable to them.

I go on vacation, prod falls over, and I come back to a clauded-together postmortem committed to a docs directory alongside a made-up history of ADRs that Matt Pocock told someone to write. They’re all inaccurate in their justification, but they successfully ward Claude away from deleting that database table.

89

u/elmuerte 21h ago

Well-documented

This is the key problem. Who can tell if something is (still) well-documented. Outdated documentation is worse than no documentation. Documentation which does not tell why, does not add much more value than the code.

And then we have these AI systems which ignore explicit instructions constantly. And at the same time accept everything as fact.

32

u/chucker23n 19h ago edited 18h ago

Documentation which does not tell why, does not add much more value than the code.

This. And yet I still see it taught that way in some schools.

In-code comments should state the why, and not exist when it's obvious; not the what; the code already says so. If the code is hard to read, adding a comment is merely a crutch; make it easier to read.

API docs should state the use cases and design considerations (e.g. edge cases, or explicitly what a method isn't for).

Commit messages should state why something was changed, not what was changed; the diff already says so.

Since LLMs are trained on shitty comments, that's what they themselves tend to generate: lots and lots of prose that tells me the obvious instead of making me aware of gotchas.

10

u/double-you 17h ago

Outdated documentation is worse than no documentation.

I don't agree at all. Basically all documentation is outdated. When reading it, we just need to keep that in mind. But even if the details (small or big) have changed, the material can give you a useful big picture or clues about what to consider next.

4

u/tarwn 14h ago

In fact, outdated documentation + git + agents means it's relatively easy for the agent to see how it was working back on that doc publish date and then highlight what major changes have occurred since that it has only partial context for. And possibly even closing some of that gap too, if engineers put context in tickets and those are accessible too.

4

u/max123246 9h ago

Or the ai takes the old documentation as fact and gets led astray. I've seen that way more often than it leveraging old info to pull in less context

1

u/fragglerock 15h ago

duh... you just ask claude to update the documentation...

simple as!

1

u/MeggaMortY 17h ago

The most up to date documentation I've seen in a codebase got stale in less than a week. Ain't nobody got time for that - said the PO and scheduled a bunch more feature tickets for the sprint instead.

14

u/maroun-baydoun 18h ago

I intentionally kept AI out the article, even though it's arguably very relevant to the problems I'm raising. Until the dust settles on AI adoption, and AI workflows become more standardised and universal, it'll be hard to talk about something that's moving so fast.

1

u/redhand0421 12h ago

I loved the article by the way. I agree with you 100% and think that this abundance mentality is almost exclusively upsides in an organization with good people that wants them to be great.

0

u/hey-rob 12h ago

What industry are you in where the dust hasn’t settled?

7

u/indearthorinexcess 10h ago

Anthropic lost $80B in the first half of 2026. The frontier companies have no clear path to profitability. Their valuations are made up and depend on almost immediately doing another 10x revenue. The dust won't settle until after the bubble bursts

1

u/currentscurrents 8h ago

Anthropic lost $80B in the first half of 2026

$72 billion of that is an accounting loss. They issued bonds that have the option to convert into Anthropic stock; now they believe Anthropic stock is worth more, so the bonds are worth more.

It is not a cash loss, and maybe not even a real loss if they don't IPO at the valuation they want.

Financials aside, I am sold that their product works. Coding agents really are here to revolutionize programming and probably other fields too. Someone will figure out a way to make a profitable business out of it.

3

u/frazell 5h ago

That just highlights the dust still being unsettled. During the dotcom bubble it was understood that the future was on the web. It was also understood that web applications would replace desktop ones and computing was shifting heavily.

The problem was predicting what that would look like. We’re in that future. It did pan out in many ways and not so much in others. The bubble also still burst.

Generative AI is definitely here to stay. It is still not clear what the long lasting form looks like. Is it hosted models at frontier companies like Anthropic pushing the needle forward? Or do they go bust because locally running models become “enough” due to costs or IP concerns or something else?

What do the more defined patterns look like for engineering with AI deeply embedded? It is very possible AI prompt patterns may become more guarded by companies as they aim to protect their businesses.

All up in the air still. Even as the underlying technology has staying power.

4

u/PresentationBorn6564 18h ago

Pocock out here catchin' strays.

3

u/TheRealUnrealDan 21h ago

great article but you're right times are changing

10

u/pydry 19h ago edited 19h ago

IME Sams hate pair programming and will find any excuse to avoid it (and they can always claim to be too busy...).

They generally got themselves into this position because they make systems deliberately obscure and hoard their knowledge jealously. A "Sam" who fastidiously documents everything obscure and is an open communicator won't end up being a Sam.

They like being "helpful" whenever there is a specific problem but when the problem is getting knowledge out of their head they often turn hostile because it undermines the security of their position and their investment in it. They're like Dario facing an open source AI model.

I had one flat out order me to delete comments in code on a pull request once. He was not a good dev and was massively in debt so the fear was real - if he got laid off from that job he was in trouble.

7

u/maroun-baydoun 19h ago

Sam is definitely responsible for the situation they created. And perhaps some personality types are more prone to becoming Sams over time. But Sams are also affected by their environment and the signals they receive from their manager and team, which end up creating a vicious cycle that's not easy to escape.

8

u/bogdanelcs 19h ago

The made-up ADRs are the part that worries me. They work as a fence today, but the next agent (or person) will treat that invented justification as fact, and when someone actually needs to remove the table the wrong reason sends them in the wrong direction. I’d have them marked as unverified until the person who knows the real story corrects them when they’re back from vacation.

48

u/trouthat 1d ago

I guess if Sam works somewhere that doesn’t support the idea of Sam knowledge transferring so he can work on something else he is just gonna have to rip the bandaid off and quit and get a new job making more money with the stellar recommendation from his current one

26

u/bzbub2 1d ago

no guarantee sam is actually recognized in a positive light despite being a 'hero'

14

u/pydry 19h ago edited 19h ago

Sams usually flourish where the layer of management above him doesnt understand tech.

Ive seen it most often in businesses like insurance, construction, etc. that have software engineers but aren't software engineering companies.

They're actually quite easy to deal with if you recognize the patterns (and perhaps have read the phoenix Project) but if you've spent your career as an insurance adjuster and are now running an insurance company's tech division you probably haven't.

I was brought in to reduce the company's reliance on a Sam once (not a good strategy, bringing in an individual) and I had to quit because the guy knew that was my purpose and was obstructive, rude and generally difficult as a result. management were too weak willed to do anything about it so I quit. probably he was delighted.

7

u/LordoftheSynth 20h ago edited 20h ago

You're a rock star until they realize you leaving means you did the work of two or more other devs.

Then it's gaslighting all the day (and night, you will work at night from home too you'reateamplayerright???) long.

17

u/SockMonkeh 16h ago

Next level Samming means you don't respond to shit on your vacation, everything goes wrong, and you look even more unfirable.

7

u/stipo42 15h ago

It literally happens all the time when I go away.

I'm the sole admin of like 4 of my companies systems, not by choice

1

u/robert_7524 13h ago

For four systems, naming a second admin and having them test recovery access is a concrete first step; otherwise the backup exists only on paper.

33

u/Piisthree 1d ago

Counterpoint: So, Sam can't be "promoted" to management and has to remain in a technical position he knows and loves, likely making twice what his peers do because any time he glances at another company, he gets a 10% raise. This is not a cut and dried problem, there are many different viable strategies and tradeoffs.

15

u/13steinj 17h ago

The modern company will not give Sam that 10% raise. They will not treat Sam with the same reverance his fellow engineers do, because upper management is out of touch. Sam will go to that other job, get his raise that way, become a legend again in 2-4 years (sometimes less), and the cycle will repeat itself.

You also don't have to promote Sam to management-- management is not the be all end all of an engineer's career. There exist IC tracks for the upper levels for a reason-- some people just are better at systems than people. Or they are fine with people but it doesn't make them happy. Or it does, but there's less value in splitting a team and making someone a manager or team lead for the gesturing lurpose of performing a corporate ritual.

But Sam won't be promoted to those roles either. Because why pay Sam more for taking on more responsibilities, when you can give them to him anyway for the same pay. Worse yet, new engineers are now benchmarked, implicitly, against Sam. Teams stay understaffed, because the new guy doesn't work out, he just isn't on Sam's level, and Sam ended up doing the work anyway. Which ends up just another reason Sam burns out / looks for a new job.

2

u/Cautious_Implement17 12h ago

sam won’t get promoted because he isn’t “delivering through others” the way that is expected to progress past senior. I think that’s kinda the point of the article. sam has not enabled his colleagues to help themselves. he has become an expert on systems he ought to have replaced. he is simultaneously indispensable and a scaling bottleneck for his org/company. 

sam should probably get some kind of out-of-band bonus to prevent him from leaving. but he can’t do the same thing for ten years and expect to be a principal engineer at the end. 

1

u/13steinj 5h ago

I think you have a strange skew of what principal engineers do, or I do.

At 3 organizations I have been at, a significant number of principal engineers are more interested in acting as if they produce value, than actually doing so (through others or not). At the only one (which didn't have principal engineers by title), the structure waa flat and moving up past "engineer" meaned becoming a manager. There are non-mamagerial engineer career tracks, as I've mentioned. This isn't to speak lesser of those who are managerial track. Just that they produce a different kind of value.

5

u/maroun-baydoun 19h ago

I'd argue that being promoted to management is not the only, or recommended, way up for every engineer https://maroun-baydoun.com/blog/from-outstanding-engineer-to-mediocre-manager/

Getting a raise is definitely a perk, but it might end up compounding Sam's problems. The more their current company tries to keep them, the more difficult it becomes for them to take their career and skills elsewhere.

29

u/VeganForAWhile 17h ago

The non-Sams are also the problem. They ignore Sam’s “read-this-if-sams-not-here.docx” file he clearly left for them.

I’ve always been the Sam-ish person at my past jobs. But I swear, nobody’s ever read a word I’ve ever written. Emails, how-tos, cheat-sheets. They tell me to document, so I document. Every time I sit down to do it, I get really into it, all knowing it’s an academic exercise for an audience of exactly ONE.

19

u/dhruvin3 23h ago

Hope nobody harsh on me...

I am Sam in my workplace! Well actually I was up until my 9th year, suddenly my first ever overseas trip did something to me! Fuck teams, fuck email, for once let me enjoy my trip 11 days no more looking at work or related apps! Came back whole lot if disaster of course! But this time i still had vacation mode on, instead of solving everything started guiding, pointing to the document that no one bother to read (answers were right there) after couple months, went on another vacation for 1 month! Same thing, but little less disaster, manageable, came back updated the docs. Happily working in cross function team project, doing my own and everything. Fuck somehow Sam woke up again, none of the scenario was for job security, all of them was i was good at it and 8 hours becomes 9-10 hours easily. My project which is solving good deal of problem now i have been forced to hand over to person who viber codes because my expertise from putting out for need me again and the project i am building can be vibe coded... Fuck!

Who knew right!

I never become Sam by choice, simply taking responsibility and ownership cost me this!

8

u/erroronline1 21h ago

the document that no one bother to read

this right here. ignoring the setup and constantly asking for help from sam must at some point be considered intentional. and not the good kind. it is exploiting sams contribution of keeping shit running for the greater good for anyone else to have more time to complain about their workload.

7

u/bjarneh 19h ago

Nobody wants to be "Sam". This is just what happens with small organizations, where time (= money) short term, matters much more than documentation and proper procedures, i.e. quality.

This is classic straw man arguments from top to bottom, where the author (sorry u/maroun-baydoun) argues against a position nobody has.

1

u/maroun-baydoun 18h ago

I'm writing an article, not a book. So I definitely need to boil down the arguments and perhaps oversimplify some aspects of it.

One core component is human psychology, the desire to be recognised and praised, being the hero and save the day. Wanting to become Sam is not necessarily a conscious decision, but a reaction to certain incentives that animate a lot of human beings.

3

u/bjarneh 18h ago

the desire to be recognised and praised, being the hero and save the day.

This is true of course. People want praise and save the day, but not by being "Sam".

Sam sounds like an overworked one-stop-shop to fix everything because he works in a industry where margins are slim and they cannot afford to do stuff properly. I don't buy that people want to be that guy. Many people (myself included to some extent) are that guy, but it's certainly not something we enjoy :-)

1

u/maroun-baydoun 18h ago

I'd argue that people who want to become Sams are exactly those who don't understand the full picture yet or don't grasp the dysfunction that led to Sam in the first place. Sams can have a certain aura about them, especially attractive to more junior engineers who might think that's what a successful career looks like.

3

u/bjarneh 15h ago

I'd argue that people who want to become Sams are exactly those who don't understand the full picture yet or don't grasp the dysfunction that led to Sam in the first place.

That is basically a jr wanting to become a sr though I guess, which is probably true. Most guys would probably like being the guy with all the answers, as opposed to a guy with no idea, and you are probably correct in assuming that the jr (in this case) do not always know how someone became the person with all the knowledge.

I steel feel you are preaching to the choir here. Most programmers know that being hard to replace means they are employed by someone with too little resources to do things properly.

4

u/Infotaku 18h ago

Sounds like Sam forgot he could just quit

3

u/maroun-baydoun 18h ago

The longer someone stays a "Sam" the more difficult it is for them to quit.

2

u/13steinj 17h ago

No, there are plenty of underpaid Sams that are underpaid due to organizational incompetence. When that happens it becomes very easy for Sam to quit.

Or Sam doesn't feel underpaid per se but is sufficiently annoyed by working with do nothings, pencil pushers, or other incompentents. Then it stings extra when he finds out some of them make far more than he does.

3

u/Anovadea 11h ago

This really reminds of me of one of the points of The Phoenix Project (which is basically a project management book in story form). There was a character called Brent, who was basically Sam in this blog.

That said, TPP was writing from a company point of view, so it wasn't really about the struggles Brent went through, but just pointing out how having a Single Point of Heroism like Brent or Sam was bad for the company's productivity/scalability.

I managed to get out of the Hero role a good few years ago. Now I'm being dropped from a customer project, while the customer is demanding that the Heroes stay on. I wish them luck, but even though I'm at risk of losing my job, I don't want to be stuck on a project team filled with Heroes.

2

u/rnelsonee 14h ago

I'm headed into the office a little early to demo my software to a couple of other people so when we need to use the software next month, three people will know how to use it. And my first question will be 'who wants to drive?' because the purpose really is transferring knowledge, not showing off what I've been working on the last month.

To me, cross-training is the responsibility of the software lead, and the project manager, and line management; it's a workplace culture thing. Documentation is good, but it doesn't replace someone sitting in a chair and using the software for 5 minutes.

I also find it a bit freeing; I was tech lead and project manager for something that was good, but after 10 years, it was time to move on. The transition was long, but the fact that I had the other engineer handle code changes, CM, and documentation for a year before made it easier. If I was Sam, I'd be stuck doing the same project.

1

u/dritmike 17h ago

Man I shoulda been a fire fighter. Instead all I became was a SAM

1

u/CherryLongjump1989 9h ago edited 9h ago

At the risk of misinterpreting it, here's the gist of what I got out of it: There's a whole section explaining that organisations reward visible heroics and ignore quiet prevention. Then his fix for Sam’s stalled career is... quiet prevention, plus giving the visible work to someone else.

Has "Sam" tried asking for a raise, or a promotion? Has Sam tried just quitting and getting another job? He's smart and knowledgable, so why doesn't he actually use that as leverage, rather than making himself "replaceable"?

I think the gap here is believing good behavior gets rewarded by default. If you have leverage, learn to use it, and don't fall into the trap of hoping that your employer will actually reward you for eliminating the leverage that you once had, but no longer do.

1

u/Primary_Ads 8h ago edited 8h ago

Why is Sam so capable at doing everything while also being made responsible for offloading herself? Maybe her boss should do their job of managing bus factor risk rather than asking Sam to take the initiative to take care of that too? Doesn't this industry already have enough burnout risk?

The engineer who cannot be replaced is stuck exactly where they are

This doesn't even make sense. Sam can know everything about how the system works while upgrading individual parts no one but her understands if she feels like it. It doesnt follow that her monopoly on understanding affects the quality or how modern her work is.

1

u/bogdanelcs 19h ago

The incentive problem is the real one: if promotions and praise go to whoever fights the fire at 2 a.m., documenting things yourself is a career risk, not just a good habit. A cheap way around that is writing the fix down during the incident itself, so the heroics and the runbook come out of the same hour. And replaceable in the system isn’t the same as replaceable in judgment, the engineer who has taught everyone else tends to be the one who gets pulled into the harder problems anyway.