A Singapore product team I worked with hired two strong senior engineers inside a month. Both took roughly seven weeks before they shipped anything that touched a core service. Neither was slow and neither was badly onboarded in the usual sense. They had laptops on day one, access on day two, a buddy, a checklist, the whole programme. What they did not have was any way to find out why the system was built the way it was, so they spent seven weeks asking, and the two people who could answer were the two people least able to spare the time.
The fix was not a documentation initiative. It was a one page file format and a rule about when to write one. Here is the version that survived, with the parts that failed first time included, because those are the useful bit.
What a Decision Record Is, and What It Is Not
An architecture decision record is a short note written at the moment a technical choice is made. It captures the situation that forced the choice, the options that were on the table, which one was taken, and what the team accepted as a consequence. It lives beside the code and it is reviewed in the same pull request as the change it explains.
It is not design documentation, which describes how a system works and goes stale the week after it is written. It is not a specification, which describes what should be built. A decision record is the only artefact in an engineering team whose value increases with age, because it is a snapshot of reasoning under constraints that no longer exist. Six months later the constraints are invisible and the decision looks arbitrary. The record is the thing that stops a new senior engineer quietly rewriting a module to fix a problem that was already considered and deliberately left alone.
That is the hiring connection, and it is the whole reason I care about this practice. You hire senior people so they will disagree with things. Without records, their disagreement arrives at week six, after they have reverse engineered the reasoning by interrupting four colleagues. With records, it arrives on day four, cheaply, in writing, where it is useful.
Step 1: Keep 5 Fields and Refuse the Sixth
Context. Options considered. Decision. Consequences. Date and author. That is the template and it fits on one page.
Every team that adopts this will try to add a field within the first month. Status workflow. Stakeholder sign-off. Risk rating. Related tickets. Each addition sounds harmless and each one costs you records, because a template with fields people cannot fill in confidently is a template people put off filling in at all. The first time I ran this I accepted three extra fields to get buy-in from a programme manager, and the practice was dead in five weeks. Nobody announced it. The records just stopped.
The options field is the one that carries the value, and it is the one everybody writes badly. Two rejected options with one honest sentence each about why they lost is worth more than three paragraphs of context. If a record lists no rejected options, it is not a decision record, it is an announcement.
Step 2: Write a Trigger Rule, Not a Culture Statement
Here is the instruction that fails: document important architectural decisions. It fails because nobody believes their own decision was important at the time they made it. Importance is visible only in retrospect, which is exactly when the record cannot be written.
Here is the instruction that works, in one sentence: write a record when the choice would be expensive to reverse in six months, or when a new joiner would reasonably ask why it was done this way.
Both halves matter. The first catches the obvious structural choices: a datastore, a queue, a boundary between services, a build tool everybody will live with. The second catches the much larger category of decisions that are cheap to reverse technically but expensive socially, because nobody remembers the reason and nobody wants to be the one who breaks something. The second half is also the one that directly serves onboarding, which is the return you are buying.
Step 3: Put Them in the Repository, Never in the Wiki
Records go in a plain directory of markdown files next to the code, numbered sequentially, and they are reviewed in the pull request that contains the change. Not a wiki. Not a shared drive. Not a project management tool.
The reason is not aesthetic. A record in the repository is reviewed by the people who will be affected by it, at the moment they can still argue, by the same mechanism they already use every day. A record in a wiki is written after the fact by whoever remembered, read by nobody, and silently becomes untrue. I have never seen a wiki-based decision log survive a leadership change. I have seen repository-based ones survive two.
There is a secondary benefit for distributed teams, which in Singapore means most teams. When part of your engineering group sits in another timezone, the pull request is already the place where context gets transferred asynchronously. Putting decisions there costs nothing extra and removes one more reason for someone to wait eleven hours for an answer. If your team is distributed, this pairs naturally with the practices in our note on reducing bus factor in an engineering team.
Step 4: the Decider Writes It, a Sceptic Reviews It
Two role assignments, and both of them matter more than they look.
The person who made the call writes the record. Not the tech lead collecting notes afterwards, not a technical writer, not the most junior person as a learning exercise. Only the decider knows what was rejected, and the rejected options are the asset. A record written secondhand always has a thin options section, because the writer is reconstructing a shortlist rather than remembering one.
Then assign exactly one reviewer, with a brief that is not what you would expect. Their job is to attack the options section: what else was on the table, what was the cheapest thing you did not do, what would have to be true for the rejected option to win. Their job is explicitly not to improve the writing. Review comments about prose quality are how this practice turns into a chore, and a chore it becomes optional, and optional means gone.
đź’ˇ Our Expert Take
The sceptic reviewer is also the best interview signal you will ever get from a probationary senior hire. Give a new joiner the reviewer role on the third or fourth record after they arrive. Someone who asks what would have to be true for option B to win is a systems thinker, and you will know that in week two instead of month four. Someone who writes nice work and approves it is telling you something too. It costs nothing, it is real work rather than an exercise, and it happens in public.
Step 5: Backfill Exactly What New Joiners Trip Over
The temptation at this point is to start a documentation project: go back through the system, catalogue every significant decision, produce a complete set. Do not. That project has never once finished in any team I have watched attempt it, and the half-finished version is worse than nothing because it implies completeness that does not exist.
Do this instead. Take your last two hires. Ask them, or look at the channel where they asked questions, and collect every question of the form why is it like this. You will get a list. In my experience it is between six and ten entries, it is remarkably consistent between the two people, and it is almost never the decisions a tech lead would have chosen to document.
Write one record per question. Stop when the list is done. That set is the entire useful backfill, and it is a week of part-time work rather than a quarter. It also has the advantage of being demonstrably valuable on the day you finish it, because the next hire stops asking those questions. Fold the directory into your developer onboarding sequence as reading for days two and three and the effect compounds.
Hiring senior engineers into an undocumented codebase?
The seven week ramp is not a candidate quality problem and no amount of extra screening will fix it. HireDeveloper.sg places pre-vetted senior engineers with Singapore employers, and part of the brief we write before sourcing is an honest look at what a new joiner will hit in their first month. Sometimes the right advice is to spend a week on decision records before we start the search.
Talk about your next hireStep 6: Supersede, Never Edit or Delete
When a decision changes, and they do, write a new record that names the one it replaces, and add one line to the old record marking it superseded with a link forward. Never rewrite the original to match current reality, and never delete it.
This is the step teams argue with, usually on the grounds that a directory full of outdated records is confusing. It is the opposite. The sequence is the value. A new senior engineer who reads record 11, then record 24 which supersedes it, has learned something no current-state document could have taught them: that this team tried the obvious thing, found a specific problem with it, and moved. That is the fastest possible transfer of hard-won context, and it takes them four minutes.
A directory containing only decisions that are still true is a snapshot. A directory containing the whole sequence is an explanation. You are not maintaining documentation here, you are keeping a log, and logs do not get tidied.
Step 7: Measure 2 Signals and Ignore the Count
The number of records is a vanity metric and tracking it will push your team toward writing thin ones. Track two other things instead.
Signal one: how often a record gets linked in an argument. When someone in a code review or a design discussion drops a link to record 17 instead of retelling the story, the practice is working. This is easy to notice and impossible to game. If three months in nobody has ever linked one, the records are being written and not read, which means the trigger rule is catching the wrong decisions.
Signal two: time from a senior joiner’s start date to their first merged change in a core system. Write down your current figure before you start, even if it is a rough recollection. This is the number you are actually trying to move, and it is the number a finance conversation understands. The same instinct applies to any engineering practice you introduce: our note on setting an error budget policy makes the same argument about picking a measurable before picking a process.
đź’ˇ Our Expert Take
If you take one thing from this, take the backfill shortcut in step five. Most teams never start because they imagine the full catalogue and correctly conclude they do not have time for it. The list of questions your last two hires actually asked is six to ten items, it takes a week of spare hours, and it produces visible value on the day the next person joins. Everything else here is maintenance of a habit. That one week is the part that changes a ramp time, and it is the part you can start on Thursday.
FAQ: Architecture Decision Records in Practice
What is an architecture decision record?
A short written note, usually one page, capturing a technical decision at the moment it is taken: the context that forced the choice, the options considered, the decision, and the consequences accepted. It lives in the code repository and is reviewed in the same pull request as the change. It is not design documentation and not a specification. It exists to answer one question later: why this and not the other thing.
How do decision records help with hiring and onboarding?
A senior engineer spends their first month reconstructing reasoning that already happened. Without records that reconstruction happens by interruption, usually of the two busiest people, one of whom is on leave. Records turn it into reading. The practical effect is that a new hire can disagree with a choice on day four rather than discovering it on day forty, and early disagreement is what you hired them for.
Who should write architecture decision records?
The engineer who made the decision. Not a tech lead collecting notes afterwards and not a technical writer. Only the decider knows what was rejected, and the rejected options are the most valuable part. Assign one reviewer whose brief is to challenge the options section rather than to approve the wording, because review comments about prose are how the practice turns into a chore and then disappears.
How many decision records should a team have?
Fewer than most teams expect. A product team of eight engineers typically settles at one to four a month, plus a backfill of six to ten covering what new joiners keep tripping over. One a day means the trigger rule is too loose and the records will stop being read. None in a quarter means the practice has quietly died and nobody has said so out loud.
Start the week before your next senior hire arrives
Whether you are bringing in a senior TypeScript engineer or rebuilding a platform team, the week you spend on the backfill is the cheapest ramp time you will ever buy. HireDeveloper.sg handles the sourcing and the screening for Singapore employers, and will tell you plainly when the bottleneck is your codebase rather than the candidate market.
Plan the hire with us