How to Onboard Software Engineers with an AI Company Brain

Can a company brain shorten onboarding on a large, unfamiliar codebase? Yes, if it does not try to explain the codebase. We recommend a brain that holds what the repository cannot say (owners, rationale, runbooks, lessons from past incidents), a repeatable development environment, and a first change that goes through the pull request your team already requires, so that introducing it changes neither your GitHub nor your Slack workflow. Without those limits, a chatbot combines an obsolete design note with a current runbook, summarizes a restricted incident, or answers without naming the service owner.

Index what the repository cannot tell you

We recommend leaving the code itself out of the company brain. The engineer's editor and code search already read the repository, and a second copy goes stale and has to match repository permissions. Put in what code cannot say: who owns each service, why the design is the way it is, how to deploy and roll back, and what past incidents taught. Link from those pages to the files. On a large codebase the brain's job is to point to the right two files and the person who knows them, not to narrate the repository.

Engineering knowledge lives in code, build configuration, architecture decisions, runbooks, postmortems, dashboards, trackers and people's memory. These sources change at different speeds and carry different authority. A merged configuration file describes current behavior more reliably than a two-year-old diagram, while a current security standard may govern a change before the code enforces it. A generic onboarding checklist hides that difference: it records that the engineer opened a page, not that they can trace a request, find the owner or roll back a change. Give every indexed source metadata that supports a decision:

source_id: checkout-service-rollback
source_type: runbook
repository: commerce-platform
service: checkout
owner: checkout-maintainers
status: approved
effective_from: 2026-08-01
review_by: 2026-11-01
audiences:
  - checkout-engineer
allowed_uses:
  - explain
  - practice
  - operate-with-supervision
supersedes: checkout-rollback-v2

That lets retrieval reject a draft, a historical note, the wrong service, an expired runbook, or a source outside the employee's permissions. For conflicts, use a simple order: enforced repository configuration and approved security policy; current owner-approved runbooks and architecture decisions; maintained service documentation; reviewed postmortems and issue history for context; chat and personal notes as discovery leads only. When two authoritative sources disagree, withhold the instruction and route the conflict to the named owners. The assistant should not invent a compromise between incompatible deployment procedures.

AWS calls retrieval augmented generation a more cost-effective approach to introducing new data to a model, and lists providing the latest information among its benefits. That only helps if someone owns the page, which is why each source above has an owner and a review date. For permissions, Microsoft's document-level access guidance advises group access over individual user access for ACL-secured content, for ease of management. In an engineering company that means filtering on team membership and not on individual usernames. Authenticate the engineer, authorize the source set, retrieve permitted passages, and only then ask the model to answer.

Define readiness before configuring AI

Start with the responsibilities the new hire will receive for one service. Before access expands, the engineer should be able to:

• start a development environment from repository-controlled configuration;
• trace one representative request across the service boundary;
• identify the current owner, upstream dependencies and downstream consumers;
• find the secure-development rules that apply to the planned change;
• make a bounded change and pass the required automated checks;
• explain the rollout, monitoring and rollback plan in review;
• diagnose a realistic failure in a safe environment;
• name the escalation path when evidence conflicts or access is missing.

Each item needs observable evidence. "Read the architecture guide" is not evidence. "Draw the request path, cite the current sources and have the service maintainer correct it" is. NIST's Secure Software Development Framework asks for the same discipline in practice PO.2.2: role-based training for everyone with secure-development responsibilities, with proficiency reviewed periodically, and its examples start by documenting the desired outcomes of training for each role. The list above is that documented outcome for one role.

Google's SRE book names the failure it wants to avoid trial by fire: handing a new engineer tickets and expecting understanding to arrive. Among its anti-patterns are deluging students with menial work and pushing them into primary on-call before they understand their service holistically. Its alternative is an ordered learning path with hands-on work early. That gives the company brain a clear job, which is to assemble and verify the evidence for the path. The maintainers who decide readiness stay in charge of the decision.

One service, one first change, one environment

Limit the first release to a service with clear ownership, a working test path and a small change that reaches the normal review and release process. Indexing the whole engineering estate first adds sources without proving that the workflow works. The first change should be useful but reversible: an improved error message, an observable metric, a tightened input check, or a corrected runbook alongside code. Avoid menial work that teaches nothing about the system boundary.

If a new engineer spends the first week rebuilding a senior developer's laptop, the environment is part of the onboarding failure. Commit the toolchain, dependencies, startup commands and safe sample data to versioned configuration. The GitHub Codespaces overview says that committing configuration files to the repository gives every user of the project the same codespace configuration, and that you can choose virtual machine types from 2 cores and 8 GB of RAM up to 32 cores and 128 GB of RAM. Size the machine to the service's build, and test on the smallest type a new hire will get. A local container or another managed environment satisfies the same contract. Verify it with a real task: open the repository, build it, run tests, start the service and make one request. A green setup script that leaves the service unusable is not success. Test from a clean identity with no cached packages, private dotfiles or inherited credentials, record each manual fix, and move the repeatable ones into versioned configuration.

The service context pack

Create a small source set for the selected service: a current system map, the repository and build entry points, ownership and escalation records, current coding and security requirements, deployment, monitoring and rollback runbooks, two or three teachable postmortems, known local-development differences, and the review checklist for the first change. Assign an owner and a review date to each item. Kipwise's employee onboarding workflow connects assigned reading with searchable company knowledge. For engineering, extend that pattern by tying each assigned source to a task and a maintainer who can verify understanding.

Map the employee's current team, repository access, service role, environment and training stage to retrieval filters, so the brain returns only evidence the engineer can open directly. Keep production secrets, customer data, restricted incident details and unrelated repositories out of the onboarding index unless there is a current business need. A denied result reveals neither the restricted passage nor a sensitive summary. It returns the access process or the responsible owner. Test the negative cases: ask about another team's private incident, a production credential and a service outside the role, and confirm that semantic similarity cannot bypass source permissions.

Turn the first change into a source-linked path

Break the change into decisions and not into pages to read, and attach the governing evidence and expected reviewer to each decision. A change path for input validation asks the engineer to identify the API contract, find the validation boundary, inspect the related tests, check the secure-development requirement, propose the smallest change and write a rollback note. Security belongs in that path and not in a separate orientation video. The assistant can explain source passages, compare current files and identify missing evidence. The assigned reviewer approves the design and decides whether to merge.

A worked example: a new engineer is asked to add a metric for checkout timeouts. A weak assistant finds an old dashboard note and tells them to modify a retired monitoring library. A safer workflow:

1. Filter retrieval to the checkout service and approved shared platform sources.
2. Retrieve the current observability standard, ownership record, build configuration and relevant postmortem passages.
3. Show that the old dashboard note is superseded and exclude it from instructions.
4. Ask the engineer to trace where the timeout is created and how existing metrics are named.
5. Link the proposed metric to a small test and a review owner.
6. Require the pull request to explain rollout, expected signal and rollback.
7. Run a staging timeout scenario and confirm the metric appears without exposing sensitive labels.

One bounded change then tests environment use, source judgment, service tracing, secure implementation, observability and escalation together.

Rehearse failure with a closed postmortem

Build the failure exercise from a closed postmortem. A sanitized postmortem already holds the symptoms, the dead ends and the fix, so you do not have to invent a scenario. Let the assistant release evidence only when the engineer asks for it, such as the error-rate graph for the ten minutes after a deploy, so that choosing what to look at is part of what the maintainer assesses. Remove customer data and credentials first, and keep the unsanitized postmortem out of the index.

The SRE book describes a weekly "Wheel of Misfortune" that replays real or hypothetical incidents: a game master picks a primary and a secondary on-call, supplies context as the scenario unfolds, plays any team they escalate to, and the on-callers say what they would do to mitigate and investigate over the next 30 to 60 minutes.

Ask the engineer to state a theory, choose evidence, describe a safe diagnostic step and name the rollback or handoff point. Completing the exercise does not grant production mutation access. The book's reverse shadowing is the model for the next step: the new engineer is primary while an experienced on-caller diagnoses independently without changing any state.

Let the pull request carry the release decision

A separate review pack and approval form is one more workflow to maintain and remember. Most of the pack already exists: the pull request holds the change, the review and the rollout note, CI holds the environment verification, and a documentation PR holds the corrected system map. We recommend adding two lines to the PR template, the sources consulted and the rollback note, and treating the maintainer's approval on that PR as the recorded decision for this capability. Put the failure exercise notes, the failed company-brain queries and the requested next access level in one comment on the PR.

The maintainer can approve a limited next step, request remediation or hold access. An engineer may be cleared to deploy under supervision while on-call stays out of scope.

Verify the path before a new hire uses it

Run a fixed acceptance set with a valid architecture question, a superseded runbook, a restricted incident, an unknown owner, a clean environment build, a failing test and an ambiguous operational decision. Check that identity and source filters run before retrieval, that the engineer can open every cited passage (otherwise treat it as a failed answer), that current sources outrank historical context, that unsupported instructions are withheld, that the clean environment completes a real service request, that missing evidence reaches a named owner, that a corrected source changes the next answer, and that access expands only after a recorded maintainer decision. Keep a small regression set for every change to a source, permission, environment or model, because a company brain that passed last month can fail after an index update or a group change. Do not let readiness become a completion percentage: a page-open event does not prove engineering judgment.

First service, first change

Choose one incoming engineer, one maintained service and one bounded first change. Build the repeatable environment, approve the context pack, apply source permissions, and run the change through review and a safe failure exercise, with the maintainer recording a specific release decision. Expand only when the engineer can inspect the evidence behind every material instruction, restricted sources stay hidden and stale guidance is rejected. If a step fails, fix the source, permission, environment or review step before adding another team.