Onboarding an AI Agent: Treat It Like a New Hire

Onboarding an AI agent means giving it the same things you give a new engineer on day one: the decisions behind the current system, the conventions the team actually follows, who owns what, and the runbooks for the things you do over and over. The model is already smart. What it lacks is everything that never made it into the repo. An agent fails the way a junior hire fails - not from missing intelligence, but from missing context.

Picture a Tuesday. A sharp new contractor joins to fix a flaky payments retry. She reads the code, opens a PR by lunch, and it is wrong in a way the code does not reveal. Six months ago the team decided retries must be idempotent, because a downstream provider double-charged a customer, and that decision lives in a Slack thread nobody pinned. Now drop a coding agent into the same task. Same PR. Same wrongness. The agent did not lack reasoning. It lacked the decision.

We already know how to onboard. We just stopped applying it to agents.

When a person joins, you do not hand them the git URL and walk away. You tell them why the service is split the way it is, which parts are load-bearing, who to ask about the billing flow, and how deploys actually work versus how the wiki says they work. Onboarding is the transfer of context that is true but unwritten.

Agents skipped this step. The industry shipped powerful models, wired them into editors, and expected them to be useful from a cold start. They are useful in the small - rename this, write that test - and unreliable in the large, because the large depends on knowing things the codebase does not state. A model with no team context is a brilliant new hire in their first hour, every single time you call it.

The fix is not a smarter model. It is onboarding: the same four things you give a person, given to the agent.

What onboarding an AI agent actually requires

Code tells you what. It rarely tells you why. The architecture decisions, the domain constraints, the history, the team conventions - none of that is in the source, and all of it is what makes a change land instead of break. Here is the why, in four parts, and where each one already lives once you have a team to capture it.

Decisions

Code shows the current state. It hides the path that got there and the options you rejected. That rejected path is exactly what an agent needs, because the obvious solution is often the one your team already tried and abandoned for a reason.

This is the old idea behind an Architecture Decision Record: capture the context, the decision, and the consequences, plus the alternatives you weighed and why you passed on them. An agent that can read your decisions does not re-propose the thing that double-charged a customer. It works downstream of your reasoning instead of upstream of your mistakes. Ody's Decisions module is built for this: a decision evolves with a before-to-after diff plus the reason and the date, so the agent reads what is true now, not what was true in Q1.

Conventions

Every team has a house style that is half-written at best. How you name things. Which library you standardized on after the great date-handling fight last spring. Whether errors bubble or get caught at the boundary. Whether a feature ships behind a flag or not at all.

A new hire absorbs this over weeks of code review. An agent absorbs it in one of two ways: badly, by guessing from whatever it can see in the file, or well, by reading the conventions the team has already made explicit. Code that follows your structure - tight modules, clear bounded contexts, schema in the repo - helps the agent generate code that fits. But structure is the floor. The convention is the reasoning on top of it.

Ownership

When the agent touches the settlement service, it should know that one person has held that surface for six months and everyone else is guessing. That is not a nicety. It is the difference between a change that gets a knowledgeable review and a change that ships into a blind spot.

Ownership is also the team's risk map. The surfaces with exactly one human who understands them are the surfaces where an agent's mistake is most likely to go uncaught. Ody's People module maps who-knows-what and surfaces that bus-factor risk directly, so both the agent and its reviewers know where the thin ice is before anyone steps on it.

Runbooks

The third time you run a database migration, a release, or an incident response, it is a procedure, not an adventure. People build this muscle memory and rarely write it down. An agent has no muscle memory. It has the runbook or it has nothing.

A procedure the team has run several times should become a self-sharpening playbook: the steps, the order, the checks, the place it usually goes wrong. Give the agent that and it executes the known-good path instead of reconstructing it from first principles, badly, at 2am.

The file is not the answer. The living source is.

The instinct is to write it all down. An AGENTS.md or a CLAUDE.md, a long prompt, a pinned doc. Useful as a starting point. Doomed as a system of record.

A static file rots the moment a decision changes in a thread nobody copied back into the file. You now have two sources of truth: the file the agent reads and the reality the team lives in. The gap between them grows every week. The agent confidently applies last quarter's decision to this quarter's code, and it is wrong in the most expensive way - plausibly.

What does not rot is a living source that updates as the team works. This is what a team knowledge graph is for. Ody captures the decisions, context, and runbooks scattered across Slack, Linear, GitHub, Google Docs, standups, and the coding agents themselves, and compiles them into one callable graph. The modules - Decisions, People, Runbooks, Threads - are lenses on that one graph, not separate apps. The agent reads the current state because the state is maintained by the team doing its job, not by someone remembering to update a markdown file.

How an agent actually reads it: MCP

The mechanism matters, so here it is plainly. The Model Context Protocol (MCP) is an open standard that lets an AI client connect to external tools and data sources in a session, the way a USB port connects a device to a machine. Coding agents like Claude Code and Cursor both speak it. Teams already share tool setups by committing a .mcp.json, so everyone gets the same servers on git pull.

Ody is callable over MCP, which means an agent in your editor reads the team graph directly - the decision, the owner, the runbook - without you pasting context into the prompt. Onboarding stops being a thing you redo every session and becomes a connection the agent holds. You can read more about what MCP means for a team and how it changes the unit of context from the individual to the group.

The line you should not let an agent cross

One honest caveat, because the failure mode here is real. An onboarded agent is more capable, which means its mistakes are more capable too. Reading the graph is not permission to rewrite it.

Ody draws the line on purpose: it senses continuously and automatically, but it acts only when a human says so. A nudge is the ceiling of its autonomy. No silent overwrites of your decisions or your code. The agent gets context to work from. What it does with that context stays under your review and your tooling, where it belongs. An agent that knows everything and changes nothing on its own is the one you can actually trust on a Tuesday.

Onboard the agent the way you onboard a person. Give it the decisions, the conventions, the ownership, and the runbooks, from a source that stays true. Then it works from the same ground your team does.

If you are wiring agents into a team of around twenty and want them reading from the same source of truth your people use, book a demo or join the waitlist.