--- title: "How to onboard an engineer when AI agents write half the code · Cork" description: "Onboard a new engineer on a codebase where AI agents write much of the code: agent instruction files, guardrails, ownership, and a first week plan that works." canonical: "https://corkcli.com/blog/onboard-engineers-ai-coding-agents" last_updated: "2026-11-14" published: "2026-10-03" author: "Kevin Vera" --- # How to onboard an engineer when AI agents write half the code Onboard a new engineer on a codebase where AI agents write much of the code: agent instruction files, guardrails, ownership, and a first week plan that works. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 7 min read To onboard an engineer onto a codebase where AI agents write half the code, you onboard two things at once: the person, and the agents they will run. Give the repo written instructions every agent reads (AGENTS.md or CLAUDE.md), put the rules that matter into hooks and CI instead of tribal knowledge, make ownership explicit, and spend the first week teaching the new engineer to review and steer agent output rather than to type every line. The hardest gap is not syntax, it is knowing why the code looks the way it does and who else (human or agent) is working on it right now. ## What changes when agents write the code On a traditional team, a new engineer learns the codebase by reading it, asking questions and shipping small changes. That still works, but three things are different when agents produce much of the diff: - **The "why" is thinner.** An agent's commit tells you what changed. The reasoning lived in a prompt and a conversation that the new hire never sees. - **More work is in flight at once.** Several agents, run by several people, may be editing the same modules in parallel. A new engineer does not yet know which areas are busy. - **The new engineer's agent is also new.** Each agent session starts with a fresh context. Claude Code's docs say it directly: "Each Claude Code session begins with a fresh context window." Whatever your team knows has to be written down somewhere the agent loads, or the new hire's agent will rediscover it the slow way. So onboarding is partly a documentation and tooling problem, not only a mentoring one. ## Step 1: write the instruction files every agent reads Most coding agents now read a project instruction file at session start. The open AGENTS.md format describes itself as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." As of October 2026, the main tools treat it like this: - **Codex** reads `AGENTS.md` (or `AGENTS.override.md`) from your Codex home directory, then walks from the project root down to your working directory, concatenating each file it finds. Files closer to your directory appear later and so take precedence. It stops once the combined size reaches `project_doc_max_bytes` (32 KiB by default). - **Claude Code** loads `CLAUDE.md` (or `.claude/CLAUDE.md`) from the project, and can read `AGENTS.md` instead when there is no `CLAUDE.md`. A `CLAUDE.md` can also import other files with `@path/to/file`. Running `/init` generates a starting `CLAUDE.md` from your codebase. - **Cursor** supports project rules in `.cursor/rules` and also reads `AGENTS.md` as "a simple alternative to `.cursor/rules`," including nested files in subdirectories. If your team uses more than one tool, keep one source of truth. A common pattern is a single `AGENTS.md` at the root, plus a `CLAUDE.md` that contains only `@AGENTS.md` and any Claude-specific notes. What to put in it, for the new engineer as much as for the agents: 1. Build, test and lint commands, exactly as typed. 2. Architecture in a paragraph: the main modules and what owns what. 3. Conventions an agent would not guess: error handling style, naming, which libraries are banned. 4. "Do not touch" areas and why (generated code, vendored code, migrations). 5. How to land a change: branch naming, PR size, who reviews. Keep it short. Claude Code's docs suggest targeting "under 200 lines per CLAUDE.md file," because longer files cost context and reduce adherence. ## Step 2: turn the important rules into guardrails Instruction files are advice. Claude Code's memory docs say it plainly: Claude treats them "as context, not enforced configuration." For anything that must never happen, use a mechanism that blocks. - **Agent hooks.** Claude Code `PreToolUse` hooks can block a tool call with exit code 2; Codex supports `PreToolUse` hooks that can deny a tool call; Cursor hooks can return `"permission": "deny"`. A hook that refuses edits to generated files protects the new hire's agent from day one. - **Permission rules.** In Claude Code, a deny rule such as `Read(./.env)` or `Read(./secrets/**)` keeps the agent away from secrets regardless of what it decides. - **Git hooks and CI.** A pre-commit hook or a required status check catches what slipped through, for humans and agents alike. See our guide on [pre-commit checks](https://corkcli.com/blog/pre-commit-checks-ai-generated-code) for code written by AI agents. The point for onboarding: a new engineer cannot break a rule that the tooling enforces, so you can give them real work sooner. ## Step 3: make ownership and activity visible A new engineer needs to know two things before touching a file: who owns it, and whether someone is changing it right now. A GitHub `CODEOWNERS` file (in `.github/`, the root, or `docs/`) maps paths to people or teams, and "code owners are automatically requested for review when someone opens a pull request that modifies code that they own." Branch protection can require that review. Live activity is harder. CODEOWNERS says who should review, not who has three agents refactoring the module this afternoon. Teams handle this with a channel where people post what they are working on, small and frequent PRs, and claiming issues before starting. These depend on people remembering to post; agents never do. ## Step 4: a first week plan - **Day 1: setup and reading.** Install the agent tools the team uses, clone the repo, run the test suite. Have the new engineer read `AGENTS.md` and then ask their agent to explain one module end to end. Check it with a senior engineer. - **Day 2: a guided change.** Pick a small, real bug. The new engineer writes the prompt, the agent writes the fix, the engineer reviews the diff line by line and runs the tests. Pair on the review, not the typing. - **Day 3: parallel work.** Let the new engineer run two agents on independent tasks. This is where they learn how parallel agents collide, and why your team splits work the way it does. - **Day 4: improve the instructions.** Ask them to add one thing to `AGENTS.md` that they wish had been there on day 1. New hires are the best editors of onboarding docs. ## How Cork helps Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned. For onboarding, that changes the two hardest gaps: - **Context the new hire's agent did not have.** When an agent starts or gets a prompt, Cork's hooks hand it the exact signatures, callers and recent changes of the code it is about to touch, so it searches less. Notes the team recorded with `remember` are anchored to code and come back with `recall`, and `recap` shows what happened recently and what it cost. - **Work in flight.** When another agent changes code the new engineer's agent depends on, the agent hears it on its next step. An edit against code another agent is changing right now is held until the agent has their version, so a new engineer cannot accidentally overwrite a teammate's live work. Cork does not run agents or replace your instruction files, code review or CI; it works alongside them. On one machine, Cork Free needs no account. Across a team's machines, Cork bills agent hours, not seats: $20 a month per 100, pooled across the workspace. Install with: ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` ## Frequently asked questions ### Should I use AGENTS.md or CLAUDE.md? If your team uses several tools, keep the content in `AGENTS.md`, which Codex and Cursor read, and import it from `CLAUDE.md` with `@AGENTS.md` for Claude Code. Claude Code can also read `AGENTS.md` directly when no `CLAUDE.md` exists. ### How do new engineers learn the codebase if agents write it? By reading and reviewing, not only by writing. Have them ask an agent to explain a module, then check that explanation against a senior engineer, and review every agent diff they ship line by line during the first weeks. ### How do I stop a new engineer's agent from editing the wrong files? Use enforcement, not instructions: a `PreToolUse` hook or permission deny rule in the agent, CODEOWNERS plus required reviews in GitHub, and a coordination layer for files other agents are editing right now. ## Sources - - - - - - - - - ## Related reading - [Multiplayer AI coding for remote teams](https://corkcli.com/blog/multiplayer-ai-coding-remote-teams): How remote teams run AI coding agents on one codebase: shared agent instructions, async handoffs, ownership, landing rules, and cross-machine awareness. - [Cork vs Cursor Projects: a coordinator for Cursor agents, or shared state for every agent](https://corkcli.com/blog/cork-vs-cursor-projects): Cork vs Cursor Projects: a Projects coordinator plans work and directs Cursor's agents with shared context files; Cork keeps any agents on one codebase aware of each other. - [Write gate: a check that holds an AI agent's edit before it lands](https://corkcli.com/blog/write-gate): A write gate checks each file edit an AI coding agent is about to make and holds or blocks it when it would collide with another agent's live work on that code. - [Code graphs for AI coding agents: why agents need one](https://corkcli.com/blog/code-graph-for-ai-coding-agents): Why AI coding agents work better with a code graph: fewer file reads, exact callers before an edit, and a map that stays current as several agents edit. [All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt) This page in HTML: https://corkcli.com/blog/onboard-engineers-ai-coding-agents