ai Codebase Onboarding Architect

The Problem

You join a new team and inherit a 200K-line monorepo. The README is from 2021. The "quick start" instructions reference a script that no longer exists. You ask an AI agent to "explain the codebase" and it confidently describes a perfect architecture — mixing up generated code with source code, recommending commands that fail, and identifying patterns that don't exist. You spend three days just getting the tests to run locally. Your first PR touches the wrong module and breaks a deployment boundary nobody documented.

What You Get

• Verified architecture map built from actual files, manifests, and entry points — with every claim tagged as Verified, Observed, Inferred, or Unknown, so you know exactly which conclusions to trust
• Repository map across five layers — Runtime (apps, workers, jobs), Boundary (routes, queues, APIs), Domain (business logic), Verification (tests, linting), and Operations (CI, containers, migrations) — each with concrete file paths
• Local developer checklist with exact commands verified against package scripts and CI configuration, including expected output, likely failure symptoms, and recovery guidance
• Risk register identifying hidden coupling, generated code boundaries, undocumented deployment requirements, authentication boundaries, and feature flags — each with severity (High/Medium/Low) and a concrete next verification step
• First-task plan recommending one small, high-information contribution that touches a narrow boundary, has an observable acceptance test, and teaches the repository's normal workflow — with files likely to change, files that must not change, and questions for the maintainer
• Machine-readable evidence JSON (onboarding-evidence.json) capturing all claims, sources, statuses, and verification checks — so downstream tools or agents can validate the package

Why This Beats Prompting It Yourself

When you ask an agent to "explain this codebase," it produces a polished document with zero provenance. It describes the README's version of the architecture instead of the actual file structure. It recommends commands from package.json scripts that have been renamed. It identifies a src/ directory as the main application when it's actually a shared library. This skill forces evidence-based exploration: every claim must cite a file path or command output, and unknowns stay explicitly labeled rather than filled in with plausible-sounding guesses.

Example Session

You: "Onboard me onto this monorepo — apps/web, apps/api, packages/ui, workers/email."

Agent output:

ONBOARDING PACKAGE — 2026-09-21
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SYSTEM MAP (Verified):
├── apps/web — Next.js 14 frontend [Verified: package.json + next.config.js]
├── apps/api — Fastify REST backend [Verified: package.json + src/index.ts]
├── packages/ui — Shared component library [Verified: tsconfig.json + src/]
└── workers/email — Async email processor [Verified: Dockerfile + src/worker.ts]

BOUNDARY: Request flows web → api (HTTP) → email worker (BullMQ queue)

LOCAL DEV CHECKLIST:
  1. cd apps/api && npm install [Verified: package-lock.json exists]
  2. cp .env.example .env [Blocked: requires DATABASE_URL from team]
  3. npm test [Verified: jest.config.js exists, test script in package.json]

RISK REGISTER:
  [HIGH] DATABASE_URL not in .env.example — new devs will be blocked
         → Ask team lead for .env.local or database setup instructions
  [MEDIUM] Email worker reads from Redis queue — requires Redis running
         → docker compose up redis (verified: docker-compose.yml line 12)

FIRST TASK: Add a health check endpoint to apps/api
  Files to change: src/routes/health.ts (new), src/index.ts (add route)
  Files NOT to change: packages/ui/*, workers/email/*
  Acceptance: curl localhost:3000/health returns {"status":"ok"}

Use Cases

• Onboarding a new developer onto a production codebase in under one day
• Preparing a handover document before a team lead leaves the project
• Assessing codebase readiness before an AI agent performs multi-file refactoring
• Creating a repeatable onboarding package for acquired or inherited projects
• Scoping a consulting engagement — understand the system before proposing changes

Known Limitations

The package is bounded by repository access: if files are missing, locked, or behind authentication, those sections are marked as Blocked rather than fabricated. It does not replace a formal security or compliance review. Runtime verification (actually running the application) requires available credentials and dependencies, which may not be possible in every environment.