Onboard AI To A New Codebase Like A Human
Don't let your AI write code in a repo it hasn't read yet. A new teammate doesn't push to main on day one — they read the manifests, poke at the entry points, run the tests, and shadow one real request through the system. Your coding agent needs exactly the same onboarding, in a fixed order, because an agent that guesses your conventions produces code that compiles but doesn't fit.
Why guessing breaks conventions
A model that hasn't read your repo falls back on the statistically popular answer: the most common framework idiom, the most common folder layout, the most common test style. If your project deviates anywhere — a custom error type, a house naming scheme, a wrapper around the HTTP client — the agent's first draft fights it. Anthropic's own guidance is blunt about this: letting the agent jump straight to coding "can produce code that solves the wrong problem," which is why the recommended workflow is explore first, then plan, then implement. Onboarding is the "explore" step made systematic.
The fixed recon order
Run these five reads in sequence, cheapest signal first. Each step narrows what the next one has to explain.
| Step | Read | What it tells the agent |
|---|---|---|
| 1 | Package manifests (package.json, pyproject.toml, go.mod, …) | Exact stack, versions, scripts, dev vs. prod dependencies |
| 2 | Framework config (framework files, lockfile, build config) | Which conventions are load-bearing vs. optional |
| 3 | Entry points (main, server bootstrap, route registration) | Where execution starts and how modules wire together |
| 4 | Test structure (test dirs, fixtures, the runner invocation) | How correctness is defined here, and what "done" looks like |
| 5 | Build & CI (Makefile, CI workflow files) | The checks a change must survive before merging |
The order matters. Manifests before framework, because the manifest names the framework. Entry points before tests, because tests reference the modules the entry points expose. CI last, because it's the summary of everything the team enforces.
Then trace one real request
Recon gives the agent a map; a trace gives it terrain. Pick one production code path — a login, a checkout, one API call — and have the agent follow it from entry point through middleware, business logic, and the database, and back out as a response. That single path anchors everything else: it shows the error-handling style, the logging shape, the transaction boundaries, and the layering rules that no README states out loud. New code written afterwards blends in, because the agent has seen what "in" looks like.
Power-user: write the onboarding down once
Onboarding an agent every session wastes tokens and time. Persist the result:
AGENTS.md— an open, tool-agnostic "README for agents" (build/test commands, code style, project overview) supported by Codex, Gemini CLI, Cursor, Copilot, and dozens more tools.CLAUDE.md— Claude Code's per-project memory file, loaded at the start of every session. It doesn't readAGENTS.mddirectly, but a one-line@AGENTS.mdimport (or a symlink) makes both tools share one source of truth..github/copilot-instructions.md— GitHub Copilot's repository custom instructions; GitHub recommends the same content this recon produces: build steps, test commands, validation pipeline, project layout.
Keep it short — Anthropic recommends staying under roughly 200 lines, and GitHub caps its guidance at about two pages — and include only what the agent can't derive by reading code: commands, gotchas, and conventions that differ from defaults. The recon order above is exactly the checklist for filling it in: run it once, save the answers, and every future session starts onboarded.
Resources
- How Claude remembers your project — CLAUDE.md memory files
- Claude Code best practices — explore, plan, then code
- AGENTS.md — the open format for guiding coding agents
- Adding repository custom instructions for GitHub Copilot
Building an AI feature? Yeda AI designs, audits, and ships production LLM systems.