My first 10 minutes in a new repository

The first ten minutes in a new repository can tell you a lot.

Sometimes, it tells you what the next six months will feel like.

Most engineers follow a similar pattern when they open a codebase for the first time: we skim the README, glance at the dependency file, poke around the folder structure, and try to get the project running locally.

Those early signals are surprisingly informative. Repositories tend to reveal their patterns quickly: how a team thinks about documentation, structure, automation, and the engineers who will work in the system after them.

As someone focused on Developer Experience, I pay close attention to those first few minutes. They often tell me more about a team’s culture and operational maturity than any architecture diagram or onboarding presentation.

Here are the first five things I look at when I open a repository for the first time.

A quick note on scope

For this discussion, I’m talking about internal repositories at existing companies, not open source projects. Open source repos tend to optimize heavily for external contributors and ease of onboarding, which changes the incentives and structure somewhat.

This could be a monorepo, a microservice, or a microfrontend. The exact architecture matters less than the signals the repository sends about how it is maintained.

The first 5 things I look at

1. README

Like most engineers, I start with the README.

A README should not just contain barebones setup instructions. It should act as a concise introduction to the system: why it exists and how it fits into the broader architecture.

Not all documentation belongs directly in the README. In fact, anything much longer than about a thousand words is usually better placed in a dedicated docs folder, wiki, or internal documentation system. But the README should link clearly to those resources.

Within the first minute, I want to understand:

• What this software is and what problem it solves
• How it fits into the larger system
• Any architectural or philosophical context behind the project
• How to get it running locally
• Major pitfalls, locked dependencies, or known issues

If the README doesn’t answer most of those questions, I start to get skeptical.

If there is no README at all—or perhaps even worse, a default README generated by the git hosting provider—I start to feel like a character in the first twenty minutes of a horror movie: the sense of dread is rising, but I’m not running screaming just yet.

2. Dependency files and utility scripts

Next, I usually look at the dependency file and any task or script definitions.

In JavaScript or TypeScript projects, these are conveniently co-located in package.json. But every ecosystem has its equivalent: pyproject.toml, Cargo.toml, Rakefiles, Makefiles, justfiles, or good ol’ shell scripts.

Dependencies give me insight into a team’s habits around maintenance and technical debt: How far behind is the project on major versions? Are security updates being applied regularly?

But scripts are far more revealing.

Scripts are the operational backbone of a repository. They show how a team actually works.

Looking at scripts answers questions like:

• How does the project build?
• What tests exist, and how are they run?
• Are linting and formatting enforced?
• Are there scripts for development environments, database seeding, or local tooling?

Automation is one of the clearest signals of engineering maturity. Teams that invest in scripts tend to value repeatability and shared workflows. Teams that rely on manual steps often accumulate operational friction over time.

Either way, the scripts are a window into the team’s daily work.

3. File and folder structure

Next, I start exploring the repository structure itself.

File structure is more than an aesthetic choice; for all that most backend engineers are adamant they don’t or can’t do visual work, a repo’s file structure is itself a user interface for the codebase.

I look at naming conventions, folder depth, how many files are grouped together, and whether similar concepts are organized consistently. Is the project structured around domains or features? Or is everything stuffed into mega-directories like utils or helpers?

The shape of a repository tells you how much cognitive overhead developers are carrying every day.

Five extra seconds to find a file might not sound like much. But when that delay happens dozens of times a day, it adds up—not just in time spent, but in frustration.

Good structure reduces the amount of thinking required to move through the system. When engineers spend less time navigating, they spend more time solving problems.

4. Tests

Tests are another strong signal about the health of a codebase.

I’m curious about what types of tests exist—unit tests, integration tests, end-to-end tests—and whether they appear to be actively maintained.

Coverage numbers can be useful, but I’m not a believer in chasing coverage percentages for their own sake. Aggressive coverage gating can easily lead to brittle tests or wasted engineering time.

What matters more is whether the tests are meaningful.

Do they help explain how features are supposed to behave?

Do they clarify edge cases?

Do they act as a form of documentation?

I also look for signs of fragility: magic numbers, overly specific assertions, or patterns that might cause flaky CI runs. Tests should reduce anxiety about making changes, not create new sources of instability.

In a healthy codebase, tests should make change feel safer.

5. Getting it running

While I’m exploring the repository, I’m usually simultaneously trying to follow the setup instructions and get the project running locally.

At first glance, this seems like an obvious inclusion to this list. Of course the project should run.

But in repositories with incomplete documentation, the definition of “running” can be surprisingly ambiguous.

I once worked at a large company with more than forty microfrontends. Each repository had slightly different setup instructions. Some had decent READMEs, some had poor ones, and some had none at all.

Even when you could piece together the basic setup, several of those repositories would launch into a blank white screen unless you had additional institutional knowledge passed down from a lead developer.

Unsurprisingly, this was not an organization that valued documentation or developer experience, and the rest of the work there reflected those values.

If I can’t get a repository running within a few minutes following its own instructions, the horror movie chase sequence has begun in earnest, and my character is headed for the hills.

What the first ten minutes tell you

The first ten minutes in a repository are rarely wrong.

They reveal whether a team values clarity, whether workflows are intentional, and whether future developers were considered when the system was built.

For someone focused on Developer Experience, those early signals often hint at what working inside the system will feel like over time.

Was the repository built only to ship features, or also to support the people who will maintain it?

The good news is that these signals are not permanent. Repositories can be reorganized. Documentation can be written. Scripts can be simplified. Structure can be improved.

And when that work happens, the next engineer who opens the repository will feel the difference almost immediately. A few tweaks can turn a horror story turned into something far more pleasant — a system that quietly does what it’s supposed to.