A new engineer joined one of my teams years ago. Sharp, quick, eager to prove herself. On day three she asked me something simple: how big should a pull request be here?
I opened my mouth and nothing useful came out.
I knew the answer. Small. Reviewable in ten minutes. Refactors separated from behavior changes. I had held those standards for a decade. I had never written one word of them down. So she guessed. She guessed wrong for six weeks, ate a pile of grumpy review comments, and quietly decided the team disliked her.
She was not the problem. My head was the problem, and everything useful was locked inside it.
Osmosis Is Not an Onboarding Plan
Every engineering team runs on rules nobody wrote down.
When is it fine to interrupt someone. What "done" means before you move the ticket. Whether Friday afternoon deploys are brave or stupid. How much test coverage earns a review. Who gets woken at 2am and who never does. Which architectural decisions need a conversation first and which ones you make alone.
New people learn these by watching, guessing, and getting burned. We tell ourselves this works because it worked on us. It worked on us slowly, expensively, and unevenly.
Ambiguity does not hit everyone equally. Confident people guess out loud and get corrected in a friendly tone. Quiet people guess silently and get corrected in a code review with an audience. Remote people miss the corridor conversation where the real rule got explained. Your unwritten culture is a tax, and the people least able to afford it pay the most.
The bill shows up in the numbers. DX and Atlassian's State of Developer Experience research found 69% of developers lose eight or more hours every week to inefficiencies. A full working day, gone, mostly to friction nobody designed on purpose.
The Evidence on Writing It Down Is Almost Rude
I used to treat documentation as the chore you do after the work. Then I read DORA's research on documentation quality and felt personally attacked.
DORA found documentation quality drives the implementation of every single technical practice they studied. Not some. Every one.
Teams with above average documentation, paired with strong technical practice, saw lifts of 1525% for trunk-based development, 750% for continuous integration, 656% for continuous delivery, and 313% for loosely coupled teams. Teams with below average documentation, doing the same practices, saw lifts of 27% to 79%.
Read those two ranges again. Same practice. Same tooling. Same conference talks. The difference is whether anyone wrote down how it works here.
Documentation is not the paperwork wrapped around your engineering. It is the multiplier on all of it.
Your AI Agents Read Only What You Wrote
Here is the part where this stops being a nice-to-have and starts being infrastructure.
A meaningful chunk of your codebase is now written by agents. Those agents have no corridor. They never overhear the tech lead sighing about a 900-line pull request. They have zero social intuition, no memory of last quarter's incident, and no ability to read the room. They read files.
The industry worked this out fast. AGENTS.md, the open format for telling coding agents how your project works, is now in over 60,000 open source repositories. Its own guidance is blunt about what belongs in it: "anything you'd tell a new teammate belongs here too."
Sit with the phrasing. The file your agents need is the file your humans needed all along. You were happy to make people guess. The machine will not guess, it will invent, and then it will do so with total confidence across forty files.
DORA's 2025 State of AI-assisted Software Development report puts the pattern plainly: "AI's primary role is as an amplifier, magnifying an organization's existing strengths and weaknesses."
Clear teams get faster. Vague teams get more vagueness, quicker, in production. Then they blame the model and start shopping for a different one.
One Page. Ten Lines. Start There.
Nobody wants your forty-page handbook. Forty pages is a place standards go to die, and agents choke on it as badly as humans do.
Write one page. Ten lines is a fine first draft. Mine looks something like this:
- Done means merged, deployed to staging, and the ticket updated. Not "works on my machine."
- Pull requests stay under 400 lines. Split refactors from behavior changes.
- Reviews get a response within four working hours, even if the response is "give me until tomorrow."
- Tests cover the new path and the obvious failure. Coverage percentage is not the goal.
- Deploys happen any day before 3pm. Rollback is one command, and you know it by heart.
- Escalate after 30 minutes stuck. Asking early is a strength here, not an admission.
- Decide alone on anything reversible in a day. Anything else gets a short design note first.
- Disagreements end at a decision with a written reason, not at whoever talks longest.
- On call owns triage, not the fix. Wake the owner if the fix needs the owner.
- Interrupt anyone for production issues. For everything else, ask in the channel first.
Argue with my list. Yours will look different, and it should. The point is having one at all.
Put it in the repository, not the wiki. AGENTS.md, CLAUDE.md, CONTRIBUTING.md, whatever your tooling reads. One file, versioned with the code, reviewed like the code, read by people and agents alike. A wiki page nobody has opened since 2024 helps no one.
Why Leaders Resist This
I have watched capable leaders refuse to do this for years, and the stated reasons are never the real ones.
"We move too fast to document." You version your code. Version the page.
"Every situation is different." Then write the principle and let people apply it. Ten lines of judgment beats a hundred lines of procedure.
The honest reason sits underneath both. Unwritten rules are leverage. If the standard lives only in my head, everyone has to come to me. I get to feel needed. I get to approve things. Better still, I get to move the goalposts after the fact and call it judgment, because nothing was ever written down for anyone to point at.
My research with Step It Up HR found 99.5% of survey respondents had experienced one or more types of bad boss. A lot of what earns a boss the label is exactly this: standards revealed only at the moment of punishment. The rule appears after you break it.
Writing the rules down costs you the leverage. It also puts you underneath the same rules, in public, where your team gets to hold you to them. Plenty of leaders would rather keep the fog.
Do This Before Friday
Ask your three most recent hires one question: what did you have to guess in your first month?
Write down their answers word for word. Do not defend anything, do not explain, do not tell them the rule was obvious. Their list is your first draft, and it will be more accurate than anything you would write alone.
Then adopt one habit. When somebody asks you the same question twice, the answer stops being a conversation and becomes a line in the file.
Your team is guessing right now. Your agents are guessing too, at a rate of thousands of lines an hour. The difference between the teams pulling ahead this year and the ones flailing is not model choice or tooling budget. It is whether anyone bothered to write down how the work gets done here.
So what did your last hire have to guess... and what did the wrong guess cost you?