Here is the order I go in, and what each thing tells you.

1. can I run it? (15 minutes)#

Clone it. Follow the README. Start a timer.

This is the single most informative test and most people skip it in favor of reading code.

• Under 10 minutes to a running application: the team cares about developer experience, and probably about a lot of other things.
• An hour, with several undocumented steps: onboarding costs a week and every new hire pays it.
• You cannot get it running: the only people who can work on this are the ones who already have it working. This is a serious risk and it is invisible from the outside.

Note every step that failed. That list is the health assessment.

2. the test suite (10 minutes)#

Run it. Then look at it.

Does it pass? On a clean checkout, first try. If not, that tells you the team has normalized a red build.

How long? Under two minutes is excellent. Over ten and people have stopped running it locally.

What is the ratio of assertions to setup? Read three test files. If setup dominates, the code is heavily coupled.

Are there tests for the error paths? Almost nobody writes these and their presence is a strong positive signal.

Is there a skip or xfail graveyard? Count them. A pile of disabled tests means the suite has been losing a slow argument with reality.

3. the shape of the repository (5 minutes)#

tokei .            # lines by language
git log --oneline | wc -l
git log --format='%an' | sort | uniq -c | sort -rn | head

Contributor concentration. If one person wrote 80% of it and they left, that is the largest risk in the codebase, larger than anything technical.

Language sprawl. Four languages in a small project usually means four sets of tooling and nobody who understands all of it.

Directory structure. Does it reflect the domain or the framework? models/, views/, controllers/ tells you nothing about what the software does. billing/, inventory/, shipping/ tells you everything.

4. the largest files (5 minutes)#

find . -name '*.py' -not -path '*/.venv/*' | xargs wc -l | sort -rn | head -20

Every codebase has a few enormous files. Open the biggest one.

• Is it generated? Fine, ignore it.
• Is it a god object? A 4,000-line service class is where all the complexity accumulated and where all the bugs live.
• When was it last changed? git log -1 on it. If it is huge and changes weekly, that is the hot spot, and any work you do will touch it.

5. dependencies (5 minutes)#

How many? Compare against similar projects. An unusual number in either direction is worth understanding.

How old? Anything more than two major versions behind is an upgrade project waiting for you.

Anything abandoned? Check the largest ones for last release date. A critical dependency with no release in three years is a fork you have not made yet.

Anything surprising? A cryptography library nobody has heard of. A vendored copy of something. A dependency on a specific fork.

6. the commit history (10 minutes)#

git log --oneline -50

Message quality. "fix", "wip", "asdf" versus real descriptions. This is a direct readout of the engineering culture and it is remarkably predictive.

Commit size. Are they atomic, or is every commit a 3,000-line dump?

Is there review? Merge commits from pull requests, or direct pushes to the main branch?

Cadence. Steady, or bursts separated by silence?

7. the things that are missing (5 minutes)#

Frequently the most informative part.

• No CI configuration. Nothing is checked automatically.
• No linter or formatter config. Every file is a different style and every review argues about it.
• No CONTRIBUTING.md or equivalent on a project with multiple contributors.
• No changelog. Nobody knows what changed between versions.
• No architecture documentation of any kind. The system exists only in people's heads.
• No .env.example. You cannot configure it without asking someone.

8. one real feature, end to end (10 minutes)#

Pick a user-visible feature and trace it from the entry point to the database.

This is the highest-value ten minutes. You learn: how many layers, how much indirection, where the business logic lives, whether the abstractions are consistent, and whether you could add a similar feature without asking anyone.

If you cannot follow it in ten minutes, neither can anyone else, and every change will be expensive.

the summary judgment#

After an hour I can usually say:

• How long until a new engineer is productive. (From step 1 and 8.)
• Whether changes are safe. (From step 2.)
• Where the risk is concentrated. (From steps 3 and 4.)
• What the team values. (From steps 6 and 7.)

None of that requires understanding what the software does. It is all structural, and structure is what determines the cost of working in something.

The result is consistently: an architecture overview that is meaningless without context, a list of tools with no explanation of why, and no answer to any question a new person actually has.

what a new engineer actually needs, in order#

Day one: get something running.

Not understanding. Running. A new engineer who has the application running locally on day one is in a completely different position from one who is still fighting a dependency on day three.

This section should be a numbered list of commands that work. Tested. On a clean machine. Recently.

## get it running

1. Install prerequisites:  `brew bundle`   (or the equivalent — see below)
2. Copy the environment:   `cp .env.example .env`
3. Get secrets:            `./scripts/fetch-dev-secrets` (needs VPN)
4. Start dependencies:     `docker compose up -d`
5. Migrate:                `./scripts/db-reset`
6. Run:                    `pnpm dev`

You should see the app at http://localhost:5173 with seeded data.
Log in with dev@example.com / password.

If step 3 fails with "unauthorized", you need to be added to the
dev-secrets group — ask in #eng-onboarding.

That last paragraph — the anticipated failure with its resolution — is the part that separates a document that works from one that does not. Every step that has ever failed for anyone should have a note.

Day two: make a change and see it.

A guided first change. Something trivial and real: change a label, add a field, fix a typo in a template. All the way through: edit, test, review, merge, deploy.

The point is not the change. It is that they have now executed the entire delivery pipeline once, so every subsequent change is a variation on something they have done.

Day three to five: the map.

Now the architecture overview, and now it means something, because they have seen the system run.

Keep it to a page. What are the major pieces, what does each do, how do they talk. A diagram. Where the code for each piece lives.

Not a complete description. A map, at the resolution of "which building do I go to."

Week two: the why.

The decisions that are not obvious from the code. Why the database is structured that way. Why there is a queue between those two services. Why that module is frozen. Why the obvious approach to X does not work.

This is the highest-value and least-written documentation in any organization, because it exists only in the heads of people who were there. When they leave, it is gone, and the next person spends a year rediscovering it — usually by proposing the obvious approach and being told no.

the sections everyone forgets#

The glossary. Every organization has jargon: internal product names, acronyms, words used with a specific local meaning. A new person hears twenty of these in their first week and cannot ask about all of them without feeling stupid.

Write them down. This is a thirty-minute task with an outsized payoff.

Who to ask about what. Not the org chart. "Payments: ask Priya. Deploy pipeline: #platform-help. Anything about the legacy importer: Marcus, and be warned it is complicated."

The things that will surprise you. The test suite that fails on the first run until you seed a fixture. The service that takes four minutes to start. The one flaky test everyone knows about. The staging environment that resets on Sundays.

Every codebase has these. Writing them down converts "this is broken and I do not want to admit I cannot fix it" into "oh, that is expected."

What not to touch. Frozen modules, generated files, anything requiring a specific review.

the maintenance mechanism#

Onboarding docs rot faster than any other documentation, because the people who would notice the errors are the ones who no longer read it.

The fix: the last person onboarded owns it.

Every new engineer's first task is to follow the document, fix everything that was wrong, and add the things they had to ask about. Then they own it until the next person arrives.

This works because their frustration is fresh and their perspective is exactly the target reader's. It is the only mechanism I have seen that keeps these documents accurate.

the test#

Hand it to a new engineer and do not help them.

Time how long until they have the application running. Note every question they had to ask. Each question is a gap, with a measured cost.

Then fix them, and repeat with the next person.

Most teams have never done this and would be surprised by the result.

Here is an attempt at what the role actually is, based on watching people do it well.

what it is not#

Not "a senior engineer who has been there longer." Time in seat produces a senior engineer with more context, which is valuable and is not this.

Not "the best coder." The highest-output individual contributor is a valuable role and it is a different one. Staff engineers frequently write less code than seniors.

Not "a manager who did not want to manage." The scope is comparable to a manager's; the mechanism is entirely different.

what it is#

The concise version: a staff engineer is responsible for the technical success of work that spans more than one team, without having authority over those teams.

Everything distinctive about the role follows from "without authority." You cannot assign work. You cannot approve headcount. You cannot make a decision stick by deciding it. Every outcome has to be achieved through information, credibility, and persuasion.

the actual activities#

Finding the problem nobody owns. The most common form of staff-level impact. Every organization has problems that fall between teams: the shared library nobody maintains, the integration that fails and each side thinks is the other's, the performance issue that is caused by the interaction of three services.

Nobody owns these, so nobody fixes them, so they persist for years. Identifying one, proving it matters, and getting it fixed is a substantial contribution and it usually requires a person who is not on any of the teams involved.

Making a decision that spans teams. Which of three approaches, when each team has a preference and none of them can see the whole picture. This is where the "no authority" constraint bites hardest: the decision has to be made in a way that the people affected accept, which means the reasoning has to be visible and the objections have to be genuinely addressed.

Writing the document that ends the argument. A recurring disagreement that resurfaces every quarter because nobody wrote down the resolution. One good document — with the options, the trade-offs, the decision, and the reasoning — can end a multi-year debate.

Being the person who read the whole system. Most engineers know their team's code. Somebody needs to know how it all fits together, including the parts nobody has touched in three years. That knowledge is what makes the cross-cutting problems visible.

Raising the floor. Not by writing better code. By making the good pattern easy: a library that removes a class of bug, a template that encodes the right defaults, a lint rule that prevents the mistake, documentation that means nobody has to ask. Impact through leverage rather than output.

Mentoring, specifically on judgment. Not "how do I use this API." "Should we build this at all," "how do I disagree with my manager about a technical decision," "how do I tell if this design will be a problem in a year."

Saying no with a reason, at a level where it lands. Frequently the most valuable thing a staff engineer does, and the reason it requires seniority is that the no has to come with an alternative and with credibility behind it.

the day, concretely#

A real week looks roughly like:

• 20% writing code, usually the hard or risky part of something, or a prototype that settles an argument.
• 25% writing documents — designs, decisions, analyses, postmortems.
• 25% in conversations — reviews, one-on-ones, arguing about designs, being asked "does this seem right to you."
• 15% reading — code, incident reports, other people's designs, the thing everyone is complaining about.
• 15% on whatever is currently on fire.

The proportion of coding is the part that surprises people moving into the role, and the discomfort of not shipping visible code is the most common reason people bounce out of it.

how to tell if someone is good at it#

Do things get decided? Not "do they have opinions." Do arguments they are involved in reach a resolution that holds.

Do other engineers get better? Look at the people around them over a year.

Do they work on things nobody asked them to? The highest-value staff work is usually self-directed, because if it were obvious and assigned it would already have an owner.

Are they trusted by people who disagree with them? This is the real test. Someone who is only trusted by people who already agree has influence, not credibility.

the failure modes#

Becoming an architecture astronaut. Designs, diagrams, opinions, no contact with running code. The credibility runs out within about a year, and it is very hard to get back.

Becoming a very expensive senior engineer. Doing excellent work with single-team scope. Comfortable, valuable, and not the job.

Spreading too thin. Involved in twelve things, effective in none. The scope is tempting and the constraint is real: two or three significant efforts at a time is the realistic maximum.

Losing the ability to build. The role requires enough hands-on work to stay credible and calibrated. An engineer who has not shipped in a year is guessing.

The first part will recover. The second part is a mistake, and it is the kind of mistake that is invisible for four years and then extremely expensive.

the argument for not hiring juniors#

Stated honestly, because it is not stupid:

A junior engineer's first-year output is mostly small, well-specified tasks — the CRUD endpoint, the test coverage, the bug in a file someone pointed them at. That work is now substantially automatable. Meanwhile the junior requires mentoring time from senior engineers, which is the scarcest resource.

So the ROI on a junior looks worse than it did. That reasoning is coherent.

why it is wrong#

Seniors come from juniors. There is no other supply. An organization that hires only seniors is free-riding on other organizations' training, and if everyone does it, the pipeline empties. This is a classic collective action failure and the industry is walking into it with open eyes.

The judgment that makes seniors valuable comes from doing the work. The ability to look at plausible code and know it is wrong comes from having written the wrong version and debugged it at 3 a.m. You cannot read your way to it and you cannot prompt your way to it.

If the apprenticeship stops, the next generation of senior engineers does not exist, and the current one retires.

Juniors are better at the new tools. Consistently, in my experience. They have no prior workflow to defend and they explore. A team of only senior engineers adopts new tooling slowly and grudgingly.

Mentoring makes seniors better. The engineer who has to explain why a design is wrong understands it better afterward. Teams with no juniors lose that forcing function and get sloppier about articulating their own reasoning.

what actually has to change#

The old model — hire a junior, give them small tickets for a year, gradually increase scope — does not work as well when the small tickets are automated. The model has to change, not the hiring.

Start them on reading, not writing. Give a new engineer a real system and a week to understand and explain it. Have them write the architecture document that does not exist. This builds the skill that actually matters now and it produces something useful.

Give them debugging, not features. Debugging is the skill that generalizes, that AI is least reliable at, and that cannot be learned from a course. Pair them on incidents. Give them the flaky test nobody wants.

Make them review agent output. Reviewing machine-generated code with a senior engineer walking through what is wrong with it is an extraordinarily efficient teaching mechanism. You get a stream of plausible-but-flawed code, which is exactly the training material you want and which used to be expensive to produce.

Require them to write the tests first. Specifying behavior before implementing teaches design, and it is the part of the workflow that has become more important rather than less.

Do not let them delegate the hard part. For the first year, some things get done by hand, deliberately, because the point is the learning rather than the output. Say this out loud so it does not feel like an arbitrary restriction.

the hiring signal that works now#

Traditional junior screens — implement this algorithm, complete this take-home — are substantially defeated and were never good predictors anyway.

What works better:

A code review exercise. Give them a pull request with three problems. Watch what they find and how they talk about it. This is the job.

A debugging exercise on a real repository. Failing test, thirty minutes, any tools they want including AI. Watch the process, not the outcome. Do they read the error? Form a hypothesis? Check it? Notice when the model's suggestion is wrong?

A conversation about something they built. Follow-up questions until you hit the edge of their understanding. Where that edge sits, and how they handle reaching it, tells you almost everything.

the case to make internally#

If you are arguing for junior headcount:

The cost of a junior is roughly a senior's partial attention for a year plus a below-market salary. The cost of a senior hire in three years, in a market where nobody trained anyone, is going to be considerably higher than it is now.

Every organization that stopped training in 2009 spent 2013 through 2016 paying enormous premiums for the engineers who had been trained elsewhere. It is the same trade and it is being made again.

The organizations that keep training through this period will have a meaningful advantage in five years, and it will be very hard to catch up to them quickly.

Then you get a job and spend, conservatively, eighty percent of your time reading: reading the existing system before you change it, reading a pull request, reading a library's source because the docs are wrong, reading a stack trace, reading a diff a machine produced.

The skill you were never taught is the one you use most. And it is a skill — it is learnable, it has technique, and people are dramatically better or worse at it in ways that have little to do with how well they write.

what good readers actually do#

I have watched a lot of people read unfamiliar code. The good ones have a method.

They find the entry points first. Not the top of the file. The place where control enters the system: main, the route handlers, the message consumers, the event listeners. Everything else is reachable from there and unreachable code is noise.

They read for shape before detail. A first pass that answers: how many layers? Where is the state? What talks to what? They will read a hundred files shallowly before reading one deeply, and they resist the urge to understand any single function completely on the first pass.

They follow the data, not the calls. Where does this value come from, where does it go, who mutates it. Call graphs tell you the structure; data flow tells you the behavior, and bugs live in behavior.

They run it. Reading static text is a bad way to understand a dynamic system. Set a breakpoint, add a print, run the test with a debugger attached. Five minutes of watching it execute beats an hour of reading.

They read the tests first, when the tests are good. Tests are the spec written in a language the machine checks. A well-tested module's test file is the best available documentation of what it is supposed to do.

They read the history. git log -S for the function name. When was this added, what was the commit message, what else changed with it. The rationale for a weird piece of code is frequently in a commit from 2019, and nobody looks.

They accept partial understanding. The bad habit is trying to understand everything before touching anything. You cannot. Understand enough to make the change safely, make it, and let the tests and the review catch what you missed.

the techniques worth practicing deliberately#

Read a library you depend on. Pick something in your stack, one you use daily and have never opened. Read its source for an hour. You will learn more about your language's idioms than from any tutorial, and you will find at least one thing that changes how you use it.

Explain it to someone. The fastest way to discover you did not understand something is to try to say it out loud. This is why rubber-duck debugging works and it works just as well for comprehension as for debugging.

Reconstruct the design decision. For any piece of code that looks strange, ask: what problem would make this the right answer? Usually there was one. Code that looks stupid is either a workaround for something you cannot see, or a fossil of a requirement that no longer exists. Both are worth knowing.

Diff two versions of something. Reading the evolution of a file teaches you what the author learned. It is a much richer signal than the current state.

why this matters more now#

Because reading is now a much larger fraction of the job.

If a machine writes a substantial share of the code that lands in your repository, then your value-add is on the reading side of the transaction. The person who can read a 400-line diff and spot the one place that breaks under concurrency is worth enormously more than the person who can produce 400 lines.

And it compounds badly in the other direction: someone who never developed reading skill, in an environment where they write less code than any previous generation, will develop neither.

the thing I would change about how we teach#

Give students a real codebase and a bug report before you give them a blank file.

Have them find it. Have them explain what the system does. Have them make a one-line fix and defend why it is correct.

That is the actual job. We spend four years preparing people for the part of it that machines now do well, and zero hours on the part that they do not.

• Brainteasers measured whether you had heard the brainteaser. Replaced by algorithms.
• Algorithm puzzles measured whether you had ground a puzzle site. Replaced, partially, by take-homes.
• Take-homes measured how much unpaid time you had, which selects against people with children and second jobs. Replaced, partially, by pairing.
• Pairing is the best of them and it measures your comfort being watched, which is correlated with experience and confidence, which is correlated with demographics.

Now there is a new one, and it is genuinely novel.

the current problem#

A candidate with a model available can pass most remote technical screens. Not "can cheat" — can pass, because the tasks we set are exactly the tasks these tools are good at.

The industry response has been mostly bad. Return-to-office for interviews. Proctoring software. Increasingly hostile monitoring. All of it makes the experience worse for honest candidates and is defeated by anyone determined.

The response has been bad because the question was framed wrong. The question is not "how do we stop candidates using AI." It is "what are we actually trying to measure, given that the job now includes using these tools."

what the job actually is#

If you hired someone today, their work would involve:

• Understanding an existing system well enough to change it safely.
• Deciding what to build, which is mostly deciding what not to build.
• Using AI tools effectively, including knowing when the output is wrong.
• Communicating a technical decision to people who will be affected by it.
• Debugging something under time pressure with incomplete information.
• Reviewing someone else's code — increasingly, a machine's — and catching the problem.

Not one of those is measured by "implement an LRU cache in forty-five minutes."

interviews that measure the real thing#

Code review. Give them a 300-line pull request with three deliberate problems: one obvious bug, one subtle design issue, one thing that is fine but looks wrong. Ask them to review it.

This is excellent. It is exactly the job, AI does not obviously help, and the conversation about the third item — where they explain why the suspicious thing is actually correct — tells you more about their judgment than any implementation task.

Debugging a real system. Give them a repository, a failing test, and thirty minutes. Let them use whatever tools they want, including models. Watch how they narrow it down. Do they read the error? Do they form a hypothesis? Do they check it? Do they notice when the model's suggestion is wrong?

Watching someone debug with AI assistance is a much better signal than watching them code without it, because it is the actual work.

Design discussion on their own past work. "Tell me about a system you built. What would you change?" The follow-up questions are where the signal is. People who genuinely understood their system can answer six levels deep. People who did not, cannot, and it becomes clear quickly.

A short, paid, scoped project. Four hours, paid at a real rate, on something close to the actual work. This is the highest-signal option and the least scalable, and it is worth it for senior roles.

what to stop doing#

Stop asking people to implement data structures from memory. They will not do this in the job, and if they need one they will look it up, correctly.

Stop the six-round loop. Every round is a coin flip with a false-negative rate. Six rounds does not make the signal six times better; it makes the process long enough that good candidates take another offer.

Stop pretending the whiteboard measures anything but whiteboard performance.

the thing nobody wants to hear#

Interviews have a low ceiling on signal. The correlation between interview performance and job performance is weak in every study anyone has run.

The highest-signal thing is working with someone. Everything else is a proxy. Which argues for: shorter processes, more willingness to take a chance, and robust ways to correct the mistake — a real probation practice, honest early feedback, and the organizational nerve to act on it.

That is a harder cultural change than redesigning the interview loop, which is why everyone redesigns the interview loop instead.

The memo is better written and more reasonable than the headlines about it. It is also going to be misapplied everywhere it gets copied, and it is going to get copied everywhere.

the defensible core#

Two claims in the memo are correct.

"Try the AI first" is good engineering hygiene. Before you build the internal tool, before you write the script, before you file the ticket — spend ten minutes seeing whether an existing model handles it. Often it does. The cost of checking is near zero and the expected value is high.

Stagnation is a choice. A team that has not changed how it works in two years during a period of rapid tooling change is not being careful, it is being incurious. That is a fair thing to name.

the failure mode#

"Prove AI cannot do it" is an unfalsifiable standard, and unfalsifiable standards in an organization become political tools.

You cannot prove a negative about a capability that changes monthly. Any manager who wants to deny headcount now has an infinitely flexible reason, and any manager who wants to grant it will produce a document explaining why AI cannot do it. The document is not evidence. It is theater. Every organization that has ever required a justification memo for headcount has produced a genre of justification-memo prose, and this is just the newest style.

The real question — "what is the highest-leverage use of an additional engineer" — was always the question. Adding an AI framing does not make it easier to answer, it makes it easier to obscure.

the second-order effect nobody plans for#

If teams are evaluated on AI usage, teams will use AI, including in places where it is worse. This is Goodhart's law with a new coat of paint. You will get:

• Code review comments generated by a model that read fine and check nothing.
• Documentation nobody reads, generated because generating it is cheap.
• Test suites with impressive coverage numbers and no assertions that would fail.
• Postmortems written by a model that faithfully summarize the incident and identify no real cause.

All of that is measurable AI adoption. None of it is value.

what a better version looks like#

If you want the outcome the memo is aiming at, ask for the outcome directly:

• Cycle time, not tool adoption. If the team ships faster with the same quality, they are using their tools well, and it does not matter which ones.
• Toil reduction as a named goal, with a quarterly review of what got automated. That surfaces the same opportunities without the unfalsifiable test.
• A budget and permission, not a mandate. The blocker in most organizations is not enthusiasm, it is that the good tools are not approved and the data policy is unclear. Fix that and adoption happens without a memo.

the part I actually agree with#

The memo says learning to use these tools well is now part of the job. That is true and it is not controversial in the way people are treating it.

Getting good output from a model is a skill — knowing what context to provide, how to decompose a task, when the answer is wrong in a way that looks right. It is closer to being a good technical lead than to typing a search query. People who have developed it are meaningfully more effective, and people who dismissed the whole category in 2023 and never revisited it are falling behind in a way that is going to be uncomfortable to talk about at review time.

That is worth saying out loud. It just does not require a headcount policy.