What I look for in a codebase in the first hour

You have an hour with an unfamiliar codebase and you need to form a judgment: is this healthy, what will it cost to work in, what is the risk.

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.