Onboarding a New Developer to an Agent Codebase

Use this as a day-0 to week-2 ramp for engineers joining an agent product that already has packs, tools, evals, and production traffic.

Tick items only when the hire has done the step or produced the artifact - not when someone "mentioned it in standup."

How to Use This Checklist

Walk A → F in order. Access and local run block everything else.
Buddy owns unblocking; hire owns checking boxes with evidence (PR links, notes).
Adapt paths (agent_pack/, service names) to your repo; keep the structure.
Re-use completed evidence when onboarding the next hire - improve the docs where this list stalled.
Pair with Documenting Agent-Specific Conventions for New Team Members so tribal knowledge is written down.

A - Access, Safety, and Scope (Day 0)

1. Role and autonomy boundaries - what the hire may change alone vs needs review (prompts, tools, prod pins).
2. Accounts granted - git, CI, cloud, model provider (dev keys only), observability, ticket system.
3. Secret handling briefed - no keys in packs, prompts, screenshots, or chat logs.
4. Data classes explained - public / internal / PII; what may appear in eval fixtures.
5. Prod access policy - break-glass rules; no casual SSH edits of live prompts.
6. Incident channel + on-call ladder - where pages go and who the buddy is for week 1.
7. Non-goals listed - systems out of scope for the first month.

B - Repo Map and Local Bring-Up (Day 0-1)

8. Clone and branch protection understood - default branch, required checks, CODEOWNERS on packs.
9. Tree tour completed - host code, agent_pack/, evals, deploy pins, infra manifests.
10. Tooling versions match docs - Python/Node, package manager, container runtime (verify at build).
11. Local env from .env.example - keys present by name; values from vault, not Slack history.
12. One-command local run succeeds - documented script or compose file exits clean.
13. Health check verified - local /health or CLI "ping" path works.
14. Pack loader exercised - hire prints active pin fields (prompt_version, tool_schema_version, code_sha).
15. Test or eval smoke runs - at least a unit subset or tiny gold set without billing surprises.

C - Agent Behavior Literacy (Day 1-3)

16. Happy-path demo - hire runs a scripted user journey end to end.
17. Tool allowlist read - which tools exist, side effects, approval gates.
18. Prompt pack read - system prompt + major policies; notes questions in doc comments or ticket.
19. Model route known - where model IDs are pinned and how to swap in dev only.
20. Memory / RAG touchpoints (if any) - indexes, retention, tenant isolation notes.
21. Stopping conditions and budgets - max turns, timeouts, spend caps in host config.
22. Observability tour - find one production (or staging) run by run_id and read tool spans.
23. Failure demo - forced tool error or bad input; hire reads logs with the CLI sheet.

D - Git Workflow for Packs and Code (Day 2-5)

24. Branch naming practiced - prompt/, tools/, config/, agent/ prefixes as used by the team.
25. Small docs or test PR merged - proves CI and review path (not a prod behavior change).
26. Prompt-only change in staging - new version file or overlay per team rules; reviewed.
27. Eval gate interpreted - hire reads a CI eval report and explains pass/fail.
28. Conflict drill - resolve a synthetic conflict in a prompt or JSON schema without leaving markers.
29. Revert / pin rollback demo - staging only; hire follows the runbook once.
30. CODEOWNERS and review SLAs known - who must approve pack changes.

E - Production Readiness Touch (Week 1-2)

31. Deploy path explained - what ships a pin vs a container.
32. Canary / flag basics - how partial rollout works for behavior packs.
33. Kill switch location - how to disable tools or the agent without a full outage.
34. Shadow on-call or ticket shadow - one real or staged incident with buddy.
35. Cost awareness - where to see token spend and rate limits for dev keys.
36. Security checklist skim - link to agent security launch items relevant to this product.
37. Ownership boundaries - which services platform owns vs agent team owns.

F - First Value Delivery (Week 2)

38. First meaningful PR - bugfix, eval case, or scoped prompt improvement with metrics/notes.
39. Post-merge verification - staging pin, traces, and rollback plan written in the PR.
40. Doc gap filed - at least one improvement to onboarding or conventions from lived pain.
41. Buddy sign-off - hire can run, change pack safely, and debug with CLI without live prompting every step.
42. Calendar follow-ups - 30-day check on prod access expansion and remaining learning goals.

Evidence Pack (Buddy Keeps)

Artifact	Link / notes	Date
Access checklist complete
Local run screenshot or log snippet (redacted)
First merged PR
Staging prompt or config PR
Conflict drill notes
Observability run_id reviewed
Rollback drill notes
Doc improvement ticket

Suggested Calendar

When	Focus
Day 0	Access, secrets, clone, local run
Day 1	Pack tree, tools, one happy path
Day 2-3	Observability + small PR
Day 4-5	Prompt workflow + conflict drill
Week 2	Meaningful PR + rollback shadow

If local run is not green by end of day 1, stop feature onboarding and fix the path for everyone.

FAQs

How long should full onboarding take?

Local productive in 1-2 days; safe pack changes in week 1; confident on-call shadow by week 2 for mid-level hires. Adjust for juniors and for system complexity.

What if the hire is framework-fluent but new to our packs?

Start at section B and C. Skip generic LangGraph tutorials; teach your pin loader and tools.

Should we give production model keys on day 1?

Prefer scoped dev/staging keys with spend caps. Production keys follow least privilege after buddy sign-off.

Can product managers use this checklist?

Use a shortened path: access to staging, pack edit workflow, review rules, and how to read eval summaries - not host debug.

What is the single best first PR?

An eval case for a known production bug or a docs fix in the pack README. Low risk, high learning.

How do coding agents change onboarding?

Teach verification earlier: read diffs, run evals, never merge assistant output without the same gates.

What if docs are wrong?

Fixing docs is part of onboarding success (item 40). Wrong docs are incidents for the next hire.

Do we need a full clone of prod data?

No. Use redacted fixtures and synthetic tenants. Prod data copies create compliance and injection risk.

When does the hire join on-call?

After buddy sign-off, kill-switch literacy, and at least one shadow. Autonomy of the agent raises the bar.

How do multi-agent repos differ?

Add a map of agents, handoff contracts, and which pack belongs to which service before any code change.

What belongs in week 1 vs later?

Week 1: run, read packs, small PR, observability. Later: deep framework internals, multi-region failover, advanced eval design.

How do we measure onboarding quality?

Time to first productive PR, number of doc gaps found, and whether the next hire is faster - not quiz scores on framework trivia.

Why Agent Teams Still Need Solid Git and Linux Fundamentals - skill baseline
Git & Linux Basics for Agent Developers - hands-on skills
Git Workflows for Prompt, Tool, and Config Changes - PR recipe
Linux CLI Essentials for Debugging Agent Processes - debug sheet
Documenting Agent-Specific Conventions for New Team Members - write conventions
Common Git Conflicts in Prompt and Config Files - conflict drill content
Git, Linux CLI & Team Onboarding Best Practices - keep onboarding current
CI/CD & Agent Lifecycle Basics - pipeline literacy
Security Checklist Before Shipping an Agent to Production - safety bar

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Onboarding a New Developer to an Agent Codebase

Use this as a day-0 to week-2 ramp for engineers joining an agent product that already has packs, tools, evals, and production traffic.

Tick items only when the hire has done the step or produced the artifact - not when someone "mentioned it in standup."

How to Use This Checklist

Walk A → F in order. Access and local run block everything else.
Buddy owns unblocking; hire owns checking boxes with evidence (PR links, notes).
Adapt paths (agent_pack/, service names) to your repo; keep the structure.
Re-use completed evidence when onboarding the next hire - improve the docs where this list stalled.
Pair with Documenting Agent-Specific Conventions for New Team Members so tribal knowledge is written down.

A - Access, Safety, and Scope (Day 0)

1. Role and autonomy boundaries - what the hire may change alone vs needs review (prompts, tools, prod pins).
2. Accounts granted - git, CI, cloud, model provider (dev keys only), observability, ticket system.
3. Secret handling briefed - no keys in packs, prompts, screenshots, or chat logs.
4. Data classes explained - public / internal / PII; what may appear in eval fixtures.
5. Prod access policy - break-glass rules; no casual SSH edits of live prompts.
6. Incident channel + on-call ladder - where pages go and who the buddy is for week 1.
7. Non-goals listed - systems out of scope for the first month.

B - Repo Map and Local Bring-Up (Day 0-1)

8. Clone and branch protection understood - default branch, required checks, CODEOWNERS on packs.
9. Tree tour completed - host code, agent_pack/, evals, deploy pins, infra manifests.
10. Tooling versions match docs - Python/Node, package manager, container runtime (verify at build).
11. Local env from .env.example - keys present by name; values from vault, not Slack history.
12. One-command local run succeeds - documented script or compose file exits clean.
13. Health check verified - local /health or CLI "ping" path works.
14. Pack loader exercised - hire prints active pin fields (prompt_version, tool_schema_version, code_sha).
15. Test or eval smoke runs - at least a unit subset or tiny gold set without billing surprises.

C - Agent Behavior Literacy (Day 1-3)

16. Happy-path demo - hire runs a scripted user journey end to end.
17. Tool allowlist read - which tools exist, side effects, approval gates.
18. Prompt pack read - system prompt + major policies; notes questions in doc comments or ticket.
19. Model route known - where model IDs are pinned and how to swap in dev only.
20. Memory / RAG touchpoints (if any) - indexes, retention, tenant isolation notes.
21. Stopping conditions and budgets - max turns, timeouts, spend caps in host config.
22. Observability tour - find one production (or staging) run by run_id and read tool spans.
23. Failure demo - forced tool error or bad input; hire reads logs with the CLI sheet.

D - Git Workflow for Packs and Code (Day 2-5)

24. Branch naming practiced - prompt/, tools/, config/, agent/ prefixes as used by the team.
25. Small docs or test PR merged - proves CI and review path (not a prod behavior change).
26. Prompt-only change in staging - new version file or overlay per team rules; reviewed.
27. Eval gate interpreted - hire reads a CI eval report and explains pass/fail.
28. Conflict drill - resolve a synthetic conflict in a prompt or JSON schema without leaving markers.
29. Revert / pin rollback demo - staging only; hire follows the runbook once.
30. CODEOWNERS and review SLAs known - who must approve pack changes.

E - Production Readiness Touch (Week 1-2)

31. Deploy path explained - what ships a pin vs a container.
32. Canary / flag basics - how partial rollout works for behavior packs.
33. Kill switch location - how to disable tools or the agent without a full outage.
34. Shadow on-call or ticket shadow - one real or staged incident with buddy.
35. Cost awareness - where to see token spend and rate limits for dev keys.
36. Security checklist skim - link to agent security launch items relevant to this product.
37. Ownership boundaries - which services platform owns vs agent team owns.

F - First Value Delivery (Week 2)

38. First meaningful PR - bugfix, eval case, or scoped prompt improvement with metrics/notes.
39. Post-merge verification - staging pin, traces, and rollback plan written in the PR.
40. Doc gap filed - at least one improvement to onboarding or conventions from lived pain.
41. Buddy sign-off - hire can run, change pack safely, and debug with CLI without live prompting every step.
42. Calendar follow-ups - 30-day check on prod access expansion and remaining learning goals.

Evidence Pack (Buddy Keeps)

Artifact	Link / notes	Date
Access checklist complete
Local run screenshot or log snippet (redacted)
First merged PR
Staging prompt or config PR
Conflict drill notes
Observability run_id reviewed
Rollback drill notes
Doc improvement ticket

Suggested Calendar

When	Focus
Day 0	Access, secrets, clone, local run
Day 1	Pack tree, tools, one happy path
Day 2-3	Observability + small PR
Day 4-5	Prompt workflow + conflict drill
Week 2	Meaningful PR + rollback shadow

If local run is not green by end of day 1, stop feature onboarding and fix the path for everyone.

FAQs

How long should full onboarding take?

Local productive in 1-2 days; safe pack changes in week 1; confident on-call shadow by week 2 for mid-level hires. Adjust for juniors and for system complexity.

What if the hire is framework-fluent but new to our packs?

Start at section B and C. Skip generic LangGraph tutorials; teach your pin loader and tools.

Should we give production model keys on day 1?

Prefer scoped dev/staging keys with spend caps. Production keys follow least privilege after buddy sign-off.

Can product managers use this checklist?

Use a shortened path: access to staging, pack edit workflow, review rules, and how to read eval summaries - not host debug.

What is the single best first PR?

An eval case for a known production bug or a docs fix in the pack README. Low risk, high learning.

How do coding agents change onboarding?

Teach verification earlier: read diffs, run evals, never merge assistant output without the same gates.

What if docs are wrong?

Fixing docs is part of onboarding success (item 40). Wrong docs are incidents for the next hire.

Do we need a full clone of prod data?

No. Use redacted fixtures and synthetic tenants. Prod data copies create compliance and injection risk.

When does the hire join on-call?

After buddy sign-off, kill-switch literacy, and at least one shadow. Autonomy of the agent raises the bar.

How do multi-agent repos differ?

Add a map of agents, handoff contracts, and which pack belongs to which service before any code change.

What belongs in week 1 vs later?

Week 1: run, read packs, small PR, observability. Later: deep framework internals, multi-region failover, advanced eval design.

How do we measure onboarding quality?

Time to first productive PR, number of doc gaps found, and whether the next hire is faster - not quiz scores on framework trivia.

Why Agent Teams Still Need Solid Git and Linux Fundamentals - skill baseline
Git & Linux Basics for Agent Developers - hands-on skills
Git Workflows for Prompt, Tool, and Config Changes - PR recipe
Linux CLI Essentials for Debugging Agent Processes - debug sheet
Documenting Agent-Specific Conventions for New Team Members - write conventions
Common Git Conflicts in Prompt and Config Files - conflict drill content
Git, Linux CLI & Team Onboarding Best Practices - keep onboarding current
CI/CD & Agent Lifecycle Basics - pipeline literacy
Security Checklist Before Shipping an Agent to Production - safety bar

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Onboarding a New Developer to an Agent Codebase

Search Documentation

Onboarding a New Developer to an Agent Codebase