Dev onboarding time — sub-day setup with bootstrap script

Question 19 (Org enablement): How long is “time to productive AI workflow” for a new engineer?

Max-score answer: <1 day: bootstrap script installs CLAUDE.md, hooks, skills, MCP; buddy + sample sessions on day 1.

Why it matters: Setup friction is invisible to the org but visible in the new hire’s first review. Sub-day onboarding dramatically affects retention.

Why this matters in 2026 (retention impact)

By mid-2026, the difference between a strong engineering org and a struggling one isn’t whether they use Claude Code or Cursor — every serious team does. The difference is how long a new hire takes to reach the same per-day productivity as your median engineer. In 2023 that gap was measured in months. In 2024 it shrank to weeks. In 2026, on teams that have invested in AI-native onboarding, it’s measured in hours — and the teams that haven’t invested are losing senior engineers who refuse to spend their first week debugging dotfiles.

The mechanism is simple and brutal: setup friction is invisible to leadership but loud inside the new hire’s head. A senior engineer joining your team has just left a place where they were productive on day one. They are calibrating against that experience. Every hour they spend on “wait, how do you get the MCPs to authenticate?” or “what’s the canonical CLAUDE.md for this repo?” reads, internally, as “this place is not serious.” Multiply that across the first week and you’ve already made the retention conversation harder than it needs to be — even if the engineer never says it out loud.

The 2026 reframe is that “time to productive AI workflow” is a first-class onboarding metric, sitting alongside time-to-first-commit and time-to-first-PR. The teams treating it that way report numbers that would have been unthinkable two years ago. Public write-ups from teams using bootstrap-script onboarding describe replacing “a 12-page setup wiki with a single bootstrap script that does everything — the script is the documentation, and onboarding went from weeks to under 5 minutes.” Industry data on AI-augmented onboarding more broadly points the same direction: structured AI-driven onboarding programs are credited with reducing time-to-productivity by roughly 50% versus the legacy “read the wiki, ask in Slack” pattern, and with measurable lifts in 90-day retention.

There’s a second-order effect that matters even more for engineering leadership: an org that can onboard a senior engineer to “productive AI workflow” in under a day is an org that has also solved most of its internal tooling problems. The bootstrap script can’t lie. If it works on day one, it means your CLAUDE.md is canonical, your hooks are versioned, your skills repo is real, your MCP catalog is curated, and your sample workflows are documented. Every Q19 max-score org is implicitly hitting Q5, Q6, Q7, Q17, and Q18 — that’s why this question is a strong proxy for org-wide maturity.

What “max score” actually looks like (bootstrap + buddy + sample sessions on day 1)

Three components, designed to compress what used to be a week into a single working day:

1. A bootstrap script that installs CLAUDE.md, hooks, skills, and MCP. A single command — curl -fsSL https://acme.dev/dev-bootstrap | bash, or npx @acme/dev-setup, or ./bootstrap.sh from the org’s dotfiles repo — that takes a freshly-imaged laptop and turns it into a fully configured AI development environment. It clones the company dotfiles into ~/.claude/ and ~/.codex/, plants a canonical project CLAUDE.md when the new hire clones the first repo, registers the SessionStart and PreToolUse hooks the org standardizes on, symlinks the shared skills repo, and writes the MCP catalog into the right config files with placeholders for the per-user secrets the new hire fills in once.

2. A buddy paired for the first week. A named senior engineer whose job for week one is the new hire’s first call. The buddy isn’t a code reviewer or a manager — they’re the person you ask the “is this normal?” questions without feeling stupid. They sit through the bootstrap with the new hire on day 1, watch the first agent session, and check in twice a day for the first three days. The buddy role is rotated quarterly so the same person isn’t always carrying it, and so every senior engineer has been on both sides of the relationship.

3. Sample sessions on day 1. Three to five recorded “show me how to ship a small feature” videos or live walkthroughs that demonstrate the house style of working with the agent on your codebase. Not “how to use Claude Code” in general — that’s table stakes — but “here’s how we prompt for a route handler change in this repo, here’s the plan-mode flow we use for migrations, here’s how we use the worktree skill to ship two parallel changes.” These aren’t documentation, they’re examples. The new hire watches them on day 1 and copies the patterns.

4. Day-1 deliverable goal. A small, real PR that goes all the way through the loop — branch, agent session, code review (human + bot), CI, merge — by the end of day 1. Not a contrived task. Something genuinely small from the backlog that the buddy has pre-vetted as “this is doable in four hours with the agent.” Shipping a real merged PR on day 1 is the single best signal that the onboarding actually worked.

The clean version of the new-hire timeline:

Day 0 (laptop arrives)
  └─ Laptop is imaged with the company dev image. Nothing else.

Day 1, hour 0–1
  └─ Bootstrap script runs.
     - Dotfiles cloned to ~/.claude, ~/.codex
     - Shared skills symlinked
     - Hooks registered in settings.json
     - MCP catalog written; secrets prompted
     - Agent verified working with /skills, /mcp checks

Day 1, hour 1–3
  └─ Buddy walks through 1 sample session live.
     - New hire watches the worktree + plan-mode flow.
     - New hire opens their first agent session in a sandbox repo.

Day 1, hour 3–7
  └─ New hire ships a small pre-vetted PR end-to-end.
     - Branch, agent session, PR open, review, CI, merge.
     - Buddy is on-call for blockers but does not drive.

Day 1, end of day
  └─ Merged PR. Working AI workflow. Same productivity surface
     as everyone else on the team.

That last line is the goalpost. The new hire ends day 1 with the same productivity surface as everyone else — same skills loaded, same hooks running, same MCP catalog, same prompting house style. From day 2 onward, they’re a regular team member who just happens to be new.

Current landscape (web-search-verified)

Bootstrap script (clones dotfiles, installs ~/.claude, ~/.codex, sets up MCPs, plants CLAUDE.md)

The 2026 pattern is the single-command, idempotent, multi-tool bootstrap. Teams that ship one publicly — the open-source alinaqi/claude-bootstrap repo is a representative example — describe it as “an opinionated Claude Code setup kit that turned into an autonomous AI engineering command center.” The structural elements are now well-established:

One entry point. curl | bash or npx @org/dev-setup or ./bootstrap.sh. The new hire never has to read setup docs to know what to run.
Dotfiles, not copies. The script clones the org’s dotfiles repo into a stable location (~/.acme-dotfiles) and symlinks ~/.claude/, ~/.codex/, ~/.cursor/, etc. from there. A git pull updates every tool simultaneously, and the new hire never edits the agent config dirs directly.
Idempotent. Run it five times in a row and the end state is identical. This matters because the buddy will inevitably re-run it during week 1 to fix something, and you can’t have it leave the laptop in a half-broken state.
Plants the project CLAUDE.md. When the new hire clones the first work repo, a setup step (a make setup target, a package.json postinstall script, or a git config core.hooksPath pointing into the dotfiles) drops the canonical project CLAUDE.md into place if it isn’t there. This is the bridge between the org-level dotfiles and the repo-level rules.
MCP catalog with secrets prompts. The org maintains a curated list of approved MCP servers (see Q7). The bootstrap writes the catalog into the right config files and prompts the new hire for any per-user secrets (their personal API tokens, OAuth flows for Linear/GitHub/Sentry, etc.). The new hire never has to know the schema — the script does.
Verification step. The script ends by launching a non-interactive agent session that runs /skills, /mcp, and a tiny “hello world” tool call, then prints a green checklist. If something failed, the script says exactly what and how to fix it.

Sub-5-minute installs are reported by the teams that have invested in this pattern. The teams that haven’t tend to have a “setup wiki” instead — a Notion or Confluence page with twenty-seven manual steps, four of which are out of date at any given moment. The wiki approach is what the bootstrap script replaces, and the gap is the whole reason Q19 separates Optimized from Strategic Leader orgs.

Buddy system (paired senior for first week)

The buddy pattern is older than AI-native dev, but it’s been re-imagined in 2026 specifically around agent workflows. The point isn’t to teach the new hire how to write code — they already know — it’s to transmit the tacit prompting style of the team. The buddy explains things like:

“We always run plan-mode before any migration. There’s a hook that enforces it but here’s why.”
“When you’re refactoring an API route, load the refactor-auth skill — it has our conventions baked in.”
“Don’t pipe the agent through --dangerously-skip-permissions on this repo, the SessionStart hook will flag it.”
“If the agent suggests adding a new MCP, ask in #ai-tooling first. We have a catalog for a reason.”

These are the rules that don’t fit cleanly in CLAUDE.md or a skill — the cultural ones. A buddy transmits them in days instead of months.

Published 2026 write-ups describe a parallel evolution: AI-onboarding-buddy systems where the AI itself becomes the buddy, answering “is this normal?” questions from a curated corpus of internal docs. Manychat’s engineering team described one such system that uses an AI buddy to answer the first wave of onboarding questions, freeing the human buddy for the things only a human can do (judgment calls, context on team dynamics, “you should talk to X about this”). The strong pattern in 2026 is both: an AI buddy that answers FAQs instantly, plus a human buddy who carries the relationship and the cultural transmission.

Sample sessions (recorded “show me how to ship a small feature”)

The single highest-leverage onboarding artifact in 2026 is a small library of recorded sessions. Three to five videos, ten to fifteen minutes each, of senior engineers actually shipping a small feature with the agent — narrated, end-to-end, in the company’s actual codebase. The genre that works:

“Add a column to a D1 table and surface it in the API.” Demonstrates the migration flow, plan-mode, the schema-check hook, and the convention for updating tests.
“Fix a Polar webhook bug.” Demonstrates how senior engineers use the worktree skill, the agent’s debugging flow, and the team’s “always write a test first” pattern.
“Refactor a slow React component.” Demonstrates Cursor + Claude Code in parallel, performance-test conventions, and how the team uses Sentry in the loop.
“Ship a small landing page.” Demonstrates the Astro/Next house style, the design-system imports, and what gets blocked by the linter.
“Triage an inbound bug report.” Demonstrates the Sentry MCP integration, the issue-to-PR pipeline, and how the team writes commit messages.

These aren’t training videos. They’re examples. The new hire watches them on day 1 with the buddy and learns the company’s prompting style by osmosis. The teams that have invested in this corpus consistently report the highest day-1 productivity numbers. The teams that haven’t end up doing the same explanation live, one new hire at a time, forever.

Day-1 deliverable goal (one small PR through the full loop)

The single sharpest test of whether the onboarding worked is whether the new hire ships a real, merged PR on day 1. Not a “hello world.” Not a sandbox. A genuine, small PR from the backlog that the buddy has pre-vetted as four-hour-doable with the agent.

The candidates that work as day-1 PRs:

A copy or i18n fix flagged in last week’s bug triage.
A small refactor the linter has been complaining about.
A test that’s been on the backlog because nobody had a spare hour.
A doc fix in the internal docs site.
A minor UI tweak that the design team has already specified.

The PR is the artifact that proves the loop closed. Bootstrap ran. Hooks fired. Skills loaded. MCP authenticated. Agent shipped code. CI passed. Reviewer (human or bot) signed off. Merge happened. Every step in the AI workflow was exercised. If any step would have silently failed in the legacy onboarding pattern — a missing MCP token, a stale skill, a hook the new hire didn’t know about — it surfaces here, on day 1, with a buddy in the room to fix it.

Step-by-step: building sub-day onboarding

Write the bootstrap script and dogfood it on a clean laptop.

The hard part isn’t writing the script — it’s testing it on a truly clean machine. Borrow a fresh laptop, do not run any of your usual dotfile setup, and time how long it takes from “open the terminal” to “agent shipping a working command.” If it’s over an hour, the script isn’t done. The end state should be: ~/.claude/ populated, ~/.codex/ populated, hooks registered, skills symlinked, MCP catalog written with secret prompts, and a verification step that confirms every piece works.
Pick the org’s canonical CLAUDE.md template.

The bootstrap script needs something to plant when the new hire clones their first repo. That something is the org’s canonical project CLAUDE.md template — see Q5 for the long version. Keep it short and project-shaped: tech stack, key commands, architecture, conventions. The bootstrap doesn’t write a CLAUDE.md from scratch — it copies the template if the repo doesn’t already have one, and otherwise leaves it alone.
Curate the MCP catalog and write it into the bootstrap.

Every approved MCP server the org uses goes into a single config the bootstrap writes. Per-user secrets are prompted interactively (or pulled from 1Password / a secret manager). The catalog is curated by the AI platform team — new hires never have to ask “which MCPs do we use here?” because the bootstrap installed all the right ones.
Record three to five sample sessions in your codebase.

Pick the most common kinds of work on your team — route handler, migration, UI fix, debugging session, doc update. Have senior engineers record themselves shipping each one with the agent, narrating as they go. Ten to fifteen minutes each. Host them on Loom, internal Wiki, or a shared Drive folder. Link the library from the onboarding doc.
Designate the buddy program and rotate it quarterly.

For each new hire, name a buddy from a senior engineer rotation. The buddy’s first week duties are explicit: sit through bootstrap on day 1, walk the new hire through one sample session, be on call (Slack DM, Zoom available within 15 min) for the first three days, twice-daily check-ins for the first week. Rotate buddies quarterly so the load is shared and so every senior has been on both sides.
Curate a backlog of day-1-PR-grade tickets.

Engineering managers reserve a small set of pre-vetted “doable in a half day with the agent” tickets for new hires. The buddy picks one when the new hire is ready. These are not throwaway tickets — they ship to production — but they have explicit characteristics: low blast radius, well-understood file scope, no migrations, clear acceptance criteria.
Wire bootstrap, sample sessions, and buddy into the official onboarding doc.

The HR / engineering onboarding doc that every new hire reads on day 0 has three items at the top: (a) run this command, (b) watch these videos with your buddy, (c) here’s your day-1 PR. Everything else — health insurance, expense system, all-hands schedule — goes below that. The signal you’re sending is that technical productivity on day 1 is the priority.
Measure and review quarterly.

Track three metrics per new hire: (a) time-from-laptop-arrival to merged-first-PR, (b) number of buddy questions logged in week 1, (c) week-4 self-report on AI-workflow confidence. Quarterly, review the data. Where do new hires get stuck? Which sample session is most-watched? Which step of the bootstrap fails most often? The bootstrap and the sample library are living artifacts — they decay if nobody is iterating on them.
Use new hires to find rot.

A new hire is the only person on the team who experiences your tooling fresh. If something doesn’t work on day 1, it’s been broken for everyone else for weeks — they just learned to work around it. Every new-hire onboarding generates two or three PRs against the bootstrap, the sample library, or the docs. Celebrate those PRs publicly — they’re the highest-leverage maintenance work happening in the org.

Common pitfalls

No bootstrap script (everything is in a wiki). The default failure mode. The org’s setup steps are spread across a Notion page, three Slack threads, and one senior engineer’s head. Every new hire reconstructs the setup with help from their buddy, and the setup drifts a little more each time. The bootstrap script is the one artifact that prevents this drift — it forces the org to have a single, executable, version-controlled answer to “how do you set up?”

Week-long setup treated as normal. A surprising number of orgs in 2026 still budget “the first week is for setup.” This is acceptable if your engineers are early-career and the company experience is novel — but for senior engineers, it reads as a lack of seriousness. Sub-day onboarding isn’t aspirational anymore; it’s the table-stakes signal of an engineering org that knows what it’s doing.

No buddy, or a buddy with no time. Naming a buddy who is also shipping a launch this week is worse than not naming one — the new hire feels like they’re imposing every time they message. The buddy role needs to be in the buddy’s load-balancing for the week. Engineering managers explicitly carve out the time.

No day-1 deliverable. “We don’t expect anything from you in your first week.” This is meant kindly, but it backfires. The new hire wants to ship something. The day-1 PR is how they prove to themselves the tooling works and they can be productive here. Skipping it means week one ends with no concrete artifact of their own — and week two starts with anxiety.

Generic sample sessions instead of company-specific ones. A link to a generic Claude Code tutorial on YouTube is not a sample session. The point of the sample session is to transmit your team’s style on your codebase. Generic videos teach the agent’s syntax — which the new hire already knows — instead of teaching the team’s conventions, which is the actual missing knowledge.

Bootstrap script that isn’t idempotent. A bootstrap that breaks if you run it twice is a bootstrap that fails the first time the buddy tries to fix something. Idempotency is the difference between “the script is a tool” and “the script is a ritual.” Test by running it five times in a row on the same laptop.

No verification step in the bootstrap. The script claims success but doesn’t actually confirm the agent works. A verification step that runs /skills, /mcp, and a small tool call — and refuses to print “done” if any of them fails — is the difference between a bootstrap and an aspirational shell script. Add the verification.

MCP secrets prompted out of band. If the bootstrap installs the MCP catalog but leaves secret-setup to “ping #infra,” the new hire is blocked for half a day waiting on an IT response. Either prompt for the secrets inline (with clear instructions on which token from which dashboard) or wire the bootstrap into your secret manager (1Password CLI, Doppler, AWS Secrets Manager) so the bootstrap pulls them automatically once the new hire’s vault access is provisioned.

Treating the onboarding artifacts as static. The bootstrap, the sample sessions, and the buddy notes decay. A skill renamed, an MCP deprecated, a CLAUDE.md convention updated — and the onboarding starts silently failing. Schedule a quarterly review explicitly to refresh.