A new developer's first week decides more about your codebase's future than any architecture diagram. Trace a request end to end by lunchtime and they'll write code that fits. Spend three days guessing and they'll write code that fights everything around it, and you'll live with that mismatch for years.
This chapter covers the first hour on a new codebase, why setup has to be one command, how conventions let a newcomer guess correctly instead of asking, why documentation has to survive the code changing under it, what an error owes the person reading it, why tooling has to agree with itself, and how a team stops relitigating style in review.
Developer experience is a property of the code, not a document about the code. You can't bolt it on with a wiki page after the fact. It's built the same way everything else in this book gets built: one boring, repeatable decision at a time.
The First Hour on a New Codebase
What does a new developer actually do in the first hour on api-license? They clone it, they open one file, and they need that one file to tell the truth about the whole system.
<!-- README.md -->
## Project Review Summary
- Framework and runtime: Laravel 13, PHP 8.4.
- Route surface: 4 API routes, one public health check and three behind bearer auth.
- Integration pattern: `LicenseFacade` -> `LicenseManager` -> driver (`StatamicAPI`).
- Test status: `95 passed (332 assertions)` via `php artisan test --compact`.
Four routes. One integration pattern. A test count they can reproduce in thirty seconds. That's not marketing copy, it's a map, and unlike a stale onboarding doc, every number in it is something the newcomer can verify themselves in the next five minutes.
The same README lists the request flow for every protected route as a straight pipeline, not a paragraph:
SetRequestLocaleMiddleware
↓
GzipResponseMiddleware
↓
EnsureTokenIsValidMiddleware
↓
throttle:api-token
↓
AddRateLimitHeadersMiddleware
↓
LogApiRequestsMiddleware
↓
Controller → Facade → Manager → Driver
Read that once and you know where a request goes before it reaches business logic, and which layer to touch when the chain needs to change. Someone who understands this diagram understands more than someone who's read every controller, because the diagram is the shape and the controllers are just the detail filled in.
Alongside the README sits AGENTS.md, the guidelines file this repository ships for humans and coding agents alike, documenting the manager/facade/driver contract and the middleware ordering in prose a newcomer can search instead of infer. Two files, five minutes, and they know more about api-license than a week of tribal knowledge would have given them elsewhere.