A repository isn't a folder of files — it's a project's structure, history, and decisions in one place. How you organise it (one repo or many), how you branch, and how you document it decides whether the project stays navigable as it grows, and whether a newcomer — human or agent — can find their way in.
Open any healthy repository and a few things are always there: the source code, a README that explains what it is and how to run it, configuration (dependencies, build, CI), and the full version history. The good ones add more — an architecture note, a CONTRIBUTING guide, an agent-instructions file — because the repo is doing a second job beyond holding code: it's the onboarding surface for everyone who arrives later.
How those files are arranged is the repository's structure, and structure is a design decision, not an accident. A well-organised repo answers "where does X live?" without anyone having to ask. A badly-organised one forces every newcomer to reverse-engineer the layout — and "newcomer" now includes the coding agent you point at it.
Predictable layout, clear names, and a real README aren't tidiness for its own sake — they're what let a project scale past the person who started it. The test: could a competent stranger clone this repo and ship a small change today, using only what's in the repo? If yes, the structure is doing its job. If they'd need to ask someone, the knowledge is trapped in heads, not in the repo.
The biggest structural decision. A monorepo holds many projects (apps, services, libraries) in one repository; a polyrepo gives each its own. Both work; the trade-off is about coordination vs isolation.
| Approach | Strengths | Watch out for |
|---|---|---|
| Monorepo | One place for everything; atomic cross-project changes; shared tooling and CI; easy code reuse; one source of truth | Tooling has to scale (large checkouts, selective builds); access control is coarser; CI must be smart about what to rebuild |
| Polyrepo | Strong isolation; independent release cadence; per-repo permissions; simple, small checkouts | Cross-cutting changes span many PRs; version drift between repos; shared code needs publishing; harder to see the whole system |
The honest default for most teams: start with one repo (or a small number organised by clear boundary) and split only when a real pressure forces it — independent release cycles, separate security boundaries, or a team that genuinely owns a piece end-to-end. Splitting early buys isolation you don't need yet and pays for it in coordination overhead forever. The giants (Google, Meta) run enormous monorepos with custom tooling; most SA teams are better served by a sensible monorepo on stock GitHub.
A branching strategy is the agreed answer to "how does a change get from an idea to main?". Three patterns dominate; the trend is decisively toward the simplest.
Short-lived branches off main, merged via PR within a day or two. main is always shippable. Simple, fast, and what CI/CD assumes. The default for almost everyone.
Long-lived develop, release, and hotfix branches. Designed for versioned, scheduled releases. Mostly overkill now — adds ceremony most teams don't need.
Branches that live for weeks drift far from main and turn merges into archaeology. The thing every modern strategy is trying to avoid.
mainRequire PRs, passing CI, and review before merge. Branch protection is what makes the strategy real instead of aspirational.
The principle underneath all of them: keep branches small and short-lived. Small changes are easy to review, easy to test, and easy to revert. It's also exactly how agents work best — a focused branch, one reviewable PR, merged quickly. The branching strategy that's good for humans is the one that's good for agents.
Documentation that lives in the repo, in plain text, versioned alongside the code, is "docs-as-code". The README is the front door. An architecture note (or ADR — architecture decision record) captures why things are the way they are. A CONTRIBUTING guide tells a newcomer how to work. Because these are committed text, they get reviewed in PRs, they move in lockstep with the code they describe, and they never rot in a wiki nobody updates.
This is the same compounding principle that runs through the 2nth tree: capture knowledge as committed, reviewed text and it accumulates; leave it in someone's head or a Slack thread and it evaporates. A repo with good docs-as-code is an organisation's memory, queryable months later by anyone who shows up.
The newest member of the docs-as-code family is the agent-instructions file — CLAUDE.md, AGENTS.md, or similar — committed at the repo root. It tells a coding agent how the project is laid out, how to build and test, and what conventions to follow. It's docs-as-code aimed at a non-human reader, and it's fast becoming as standard as the README. A repo with a good agent-instructions file is one an agent can be productive in immediately; one without leaves the agent guessing.
An agent reads a repository the way a new hire does — it explores the layout, reads the docs, infers the conventions. Everything that helps a human onboard helps an agent onboard, and the effect is amplified because the agent does it on every task. Predictable structure, clear names, a real README, an agent-instructions file, and tests that document expected behaviour: these turn an agent from "guessing in an unfamiliar codebase" into "operating in a well-signposted one".
The pragmatic takeaway echoes the GitHub leaf: repo-ready is agent-ready. The work to make a codebase legible to a new engineer is the same work that makes it legible to an agent. You don't do a separate "AI enablement" project — you do good repository hygiene, and the agents come along for free.
SA teams are often small, and key-person risk is real — a great deal of how a system works lives in one or two people's heads. A well-structured repo with honest docs-as-code is the cheapest insurance against that: when someone leaves (or is unreachable during a load-shedding week), the knowledge is in the repo, not gone with them. For client work especially, a repo a new developer can pick up cold is the difference between a maintainable handover and a rewrite.