AI agent codebase onboarding
Give an AI coding agent the right codebase context before it edits files: architecture, rules, commands, risks and examples.
Quick answer
AI agent codebase onboarding should teach the agent where the architecture lives, which commands prove changes and which files or operations are sensitive.
Context package
Include project instructions, folder boundaries, domain rules, examples of good local code, test commands, deployment constraints and forbidden shortcuts.
Success signal
The agent is onboarded when it can explain the likely edit path before changing files and choose a verification command after the edit.
FAQ
Should onboarding happen before every task?
The agent should at least read the project instructions and nearby code before every task. Deeper onboarding is useful for broad or risky changes.
Prepare agent context
Related guides
CLAUDE.md: A Guide for Every Developer
One markdown file that makes AI coding assistants actually understand your codebase. Here's what to put in it.
There's a reason Claude Code writes great code in some projects and generic boilerplate in others. It's not the model. It's CLAUDE.md . It is one part of my Claude Code workflow: project conventions reduce guesswork, but they do not guarantee a speedup or remove the need to review the change. What it is CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session. Think of it as the onboarding doc you'd give a senior contractor on day one: stack, conventions, rules, context. Without it, Claude infers patterns from what it sees in the codebase. Sometimes it infers correctly. Often it doesn't especially for implicit conventions your team just "knows". With a good CLAUDE.md , Claude outputs code that follows your rules without being told each time. What to put in it 1. Stack and versions Simple but important. Claude will use the right…
Read the guideClaude Code Agents: When to Use Them
Claude Code Agents (subagents) let you spawn isolated work threads from the main session. Full guide: what they are, when to use them, how to write a custom one, and the patterns that actually ship.
Claude Code is great when you're driving one thread of work. When you need to run three threads in parallel, or want a fresh pair of eyes on a decision, or need to scope out a large refactor without polluting your main session that's what Agents are for. This is what Claude Code Agents actually are, when to use them, and how to write your own. What Claude Code Agents actually are An Agent (sometimes called a subagent) is an isolated work thread you spawn from the main Claude Code session via the Agent tool. It has its own context fresh, with no visibility into your conversation. You hand it a self contained prompt; it does the work; it returns a single message at the end. Three things make this different from just asking Claude another question: 1. Isolated context. The agent doesn't see what you've been doing. It can't…
Read the guideBuilding AI agents that actually work
Most 'agents' are brittle pipelines dressed up with AI. Here's the anatomy of a reliable agent, three patterns that hold up in production, and when to use n8n vs code.
Everyone is building agents. Most of them break on the third run. The failure mode is always the same: the AI is asked to do too much, in the wrong place. The agent fails not because AI is unreliable it's because the architecture made reliability impossible. Here's what I've learned building agents that actually run week after week. The anatomy of a reliable agent Every agent that works has three parts, and only one of them should involve AI. Trigger something deterministic starts the agent. A schedule, a webhook, a file drop, a form submission. Not "whenever the AI decides it's time." Context the agent gathers what it needs before calling the AI. The document, the data, the user preferences, the constraints. The AI call happens with full context, not halfway through discovery. Action after the AI produces output, something deterministic happens with it. It gets saved, sent, logged, or…
Read the guide