How to Onboard a New Engineer's Coding Agent

Your senior backend engineer has told their coding agent, more than once, that every migration in this repository ships with a working down step. They have explained which test command passes in CI, and why the team looked at a particular queue library last spring and said no. The agent learned all of it.

Then a new hire clones the same repository, opens the same tool, and asks the agent to add a column to the orders table. It writes a migration with no down step, because nothing it can see says otherwise.

The corrections landed in scopes that are private by design, and the new laptop has none of them. Agent onboarding is mostly a question of which storage location a fact ended up in, and you can check where each fact landed today with a fresh session and a few built-in commands.

What a fresh agent loads, and what it never sees

Claude Code makes a useful worked example, because its memory documentation lists four instruction scopes and states who each one is shared with. For how each layer of shared context works across a team, see team memory for coding agents.

One row of that table travels through a clone. The documentation tells you to add CLAUDE.local.md to .gitignore, which is correct and also means the sandbox URL and the test command your senior engineer parked there are invisible to everyone else.

The automatic layer is the one that surprises teams. Claude Code's auto memory is on by default and writes notes from your corrections into ~/.claude/projects/<project>/memory/, indexed by a MEMORY.md whose first 200 lines or 25KB load into every session. The documentation is unambiguous about reach: "Auto memory is machine-local. All worktrees and subdirectories within the same git repository share one auto memory directory. Files are not shared across machines or cloud environments."

So the four memory types Claude Code records, covering your working preferences, the corrections you gave it, project decisions it cannot derive from the code, and where to find outside information, accumulate in a directory that ends at the machine boundary. Auto memory also survives the transcript retention sweep that cleanupPeriodDays governs, so a note outlives the conversation that produced it, stays until someone edits or deletes it, and still never leaves the laptop.

Cursor and Codex draw a similar line between committed and personal instruction scopes, and both read a repository AGENTS.md. OpenAI's own Codex repository commits one, and its contents are exactly the shape of onboarding knowledge that a new agent otherwise guesses at: which crate new code belongs in, that just test is the command rather than cargo test, and that snapshot tests are expected for UI changes. Their per-tool discovery order differs, though, so read the vendor documentation for the version you run rather than assuming one tool's precedence rules describe another's.

Sort the knowledge before you decide where to put it

Four kinds of context show up in onboarding, and they fail in different ways.

Repository mechanics are the setup, build, test, and run commands, including the working directory each one needs. The commands belong in the committed instruction file for whichever tool your team runs, and they are the cheapest thing to verify, because you can watch the agent execute them.

Conventions and house style are the rules an agent cannot infer by reading the code: use this migration pattern, never hand-edit generated files, prefix commit subjects with the package name. Claude Code's own guidance on trimming an oversized file is a good filter here. Its /doctor checkup "cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews, and keeps pitfalls, rationale, and conventions that differ from tool defaults." A generated architecture overview is the first thing to delete. The rule against hand-editing generated files is the thing to keep.

Architectural rationale is the reason behind a decision and the alternative that lost. Rationale is the category most likely to be trapped in a private scope, because it arrives through correction rather than authorship. Getting it into a reachable form is its own problem, covered in how to make coding agents remember architectural decisions.

Operational knowledge is the staging-versus-production difference, the recovery step that is not in any runbook, the flake everyone knows about. Commit the safe parts. Point at the approved location for anything with credentials in it rather than copying restricted content into a file every contributor can read.

Claude Code's documentation names the onboarding trigger directly in its list of reasons to add to CLAUDE.md: "A new teammate would need the same context to be productive." Use that line as the test. If you would say it out loud to a new hire in week one, it belongs in a file their agent reads.

Keep the result small. The documentation targets under 200 lines per file and says longer files consume more context and reduce adherence. In a monorepo, the guidance is to layer instead: a root file for repository-wide rules, a per-directory file for each area's conventions, committed "so teammates inherit them," with each directory's owner typically maintaining its own.

A first week you can run as written

Order these by impact, and pair every step with a check. What you are testing is whether the agent behaves differently, and a commit on its own does not show that.

Day one, commit the commands. Put the build, test, and run commands into the committed instruction file your tool reads, with working directories and any clean-checkout setup step. Then open a fresh session and, without naming the command in your prompt, ask the agent which command it would use to run one specific test file. Let it run that command against a clean checkout. A correct recitation can still hide a missing dependency.

Day two, promote one decision. Sit with a tenured engineer, open their auto memory and local instruction file, and pick the single decision that would most change a new hire's first pull request. Write it as the constraint, the choice, and the rejected alternative. Verify by asking a fresh session to plan the affected change and explain its reasoning. If the rationale lives in a nested file, open a file in that directory first, because Claude Code loads subdirectory instructions when it reads files there rather than at launch.

Day three, give the agent real work. Pick a bounded task that touches both the commands and the decision. Do not coach around obstacles. Log every point where the agent asks a settled question, reaches for the wrong command, or proposes the rejected approach. Each entry is a gap with a known location.

Before the week ends, run the task again from a clean session. Two passes distinguish a missing instruction from a bad prompt. Keep the log for the next hire, because a question that repeats across two onboardings is a documentation gap and a question that appears once probably is not.

Proving the agent read it

A committed file is not a loaded file, and a loaded file is not an obeyed file. Both gaps are checkable.

Run /context at session start and read the list under Memory files. If a file you committed is missing there, the agent cannot see it. An AGENTS.md that Claude reads directly appears in that list from v2.1.280, so on an older build, ask Claude what its project instructions say instead. Run /memory to open and inspect what is available. Because nested files and rules carrying paths: frontmatter load only when Claude reads a matching file, repeat the check after opening a file in the package you care about.

Check instruction-file precedence on purpose. In Claude Code v2.1.277 and later, Claude reads a repository's AGENTS.md by default only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it. A single engineer adding a personal CLAUDE.local.md is enough to stop AGENTS.md loading for them while it keeps loading for everyone else. The Project instructions setting in /config controls this, and claude-md-and-agents-md reads both.

Contradiction is the other failure. Claude Code concatenates the files it discovers rather than letting one replace another, appending CLAUDE.local.md after CLAUDE.md in the same directory, so two files can assert two different test commands at once. The documentation is blunt about the result: "If two rules contradict each other, Claude may pick one arbitrarily." Running /doctor prompt-audit (Claude Code v2.1.283 or later) scans your CLAUDE.md, CLAUDE.local.md, and AGENTS.md files along with rules, skills, and commands, and reports files that contradict each other or reference things that no longer exist. The audit proposes edits and changes nothing until you ask.

Even a correctly loaded instruction is context rather than configuration. Claude Code's documentation says instruction content "is delivered as a user message after the system prompt" and that there is "no guarantee of strict compliance." For anything that must happen every time, a hook is the enforcement mechanism and the instruction file is not. So finish with behavior. Ask for a plan on a real change and read whether the conventions show up in it.

The same gap, pointed the other way

A departure is onboarding in reverse. The scopes a new agent could never reach are exactly the ones that leave with the hardware.

Run the departure checklist before the final day, not after:

• Open ~/.claude/CLAUDE.md, CLAUDE.local.md, and the auto memory directory through /memory. Strip personal preferences, sandbox URLs, and anything stale before promoting the rest.
• Move commands into the committed instruction file, and verify each one in a clean checkout instead of trusting the note.
• Move conventions to the file nearest the code they govern.
• Write the architectural decisions down as constraint, choice, and rejected alternative. A bare "keep migrations reversible" will be re-litigated within a quarter.
• Test the result from a different machine. If a clean environment cannot produce the test command and the rationale, the promotion did not work.

What tooling does and does not settle

Three categories help, and none of them makes the editorial decision for you.

Instruction-file tooling keeps the committed files current as the code moves, which is the maintenance problem covered in tools to keep AGENTS.md files up to date. Connected-source tools answer from repositories, docs, and tickets, which helps when the knowledge exists but is scattered, though retrieving a design document is not the same as the agent loading its guidance during the next task. Shared memory services carry facts across sessions and machines, and they need an owner for who can read what and how entries get corrected.

Dosu sits in the capture-and-maintain category. It reads from connected Sources, which today are GitHub, the web at query time, and, on the Teams plan, Slack and Notion. Dosu turns that activity into Documents inside a Library scoped to a team or product area. Coding agents read that knowledge over the Dosu MCP Server with read_knowledge, which is the part that matters for onboarding, because the new hire's agent queries the same Library as the tenured engineer's, rather than rebuilding an understanding privately. When an agent saves a correction with write_knowledge from a repository connected to the Library, the note is scoped to that repository and branch, and other members of the Library working on that branch can read it back. Topics group the Documents by area so someone new navigates by service instead of guessing filenames. With Monitors enabled, Dosu checks pull requests against published Documents and drafts edits when the code and the docs drift apart. Whether those edits wait for someone to approve them or publish with the merge is the per-Library Auto-Accept Review setting.

Run it again at the next hire

Treat the checklist as a test rather than a document. Run it when someone joins, log where the agent stalls, and commit the fix while the evidence is fresh. Claude Code's guidance on keeping instruction files current suggests reviewing edits to them in pull requests like any other documentation change, which is the habit that keeps the next run cheap.

Start with the cheapest possible version this week. Open a repository, run /context in a fresh session, and read what loaded. Then ask a tenured teammate to open their auto memory directory beside it. The difference between those two lists is your onboarding backlog.

If most of that gap is context one engineer's agent learned and no one else's agent can reach, Dosu is built for that problem. Connect a repository to Dosu so the next hire's agent reads the same Library as everyone else on day one.