AI onboarding for engineers: a clear first week plan

Why the first week often goes wrong

Teams often assume a strong engineer will figure things out quickly. In a small repo, that can work. In a real product, it usually does not.

A new hire joins, gets a ticket, opens the codebase, and starts guessing. They do not know where the business logic lives, which folder is legacy, or which package the team still trusts. So they search by keyword, follow a random import, and copy the first pattern that looks close enough.

AI makes that easier to do and easier to get wrong. If nobody explains the shape of the repo early, a new hire asks broad questions and gets broad answers back. The model might point to the wrong directory, an older abstraction, or a pattern that belongs to another service.

Prompts create a second problem. Engineers often reuse whatever they find in old chats, team notes, or screenshots. Those prompts may come from a different task, a different stack, or a version of the repo that no longer exists. The output can look clean and still miss the point.

Pull requests drift for the same reason. Review rules often live in people's heads instead of onboarding docs. A new hire opens a PR with the wrong title, no test notes, extra generated changes, or a style the team stopped using months ago. Review turns into cleanup instead of feedback.

The damage usually shows up in small misses. Someone adds a field to an API response but forgets the worker that fills it, the fixture that snapshots it, and the review note that asks for a migration comment. Nothing breaks in an obvious way. The team still loses hours.

Those small differences pile up fast. One engineer puts logic in handlers, another in services, and a third lets an AI tool invent a fourth pattern. After a week or two, the team has drift. Drift slows reviews, confuses ownership, and teaches the next new hire the wrong habits.

What to give on day one

A new engineer does not need a tour of every tool in the company. They need a small starter pack that shows how work actually moves through the team.

That pack should have four things.

First, give them a repo map. Keep it to one page and make it practical: the major folders, what each area does, and who owns the risky parts. A note like "billing lives here" or "ask Dana before changing auth" helps more than a long architecture document.

Second, give them a short page of review rules on the same day. Keep it plain. Show what belongs in a pull request, what tests they should run, when to ask for a second reviewer, and which changes need extra care. New hires should not guess whether a generated diff is acceptable.

Third, share a few approved prompt patterns. Most teams only need three at the start: one for reading code, one for planning a small change, and one for checking a diff before review. If you leave this open, people invent their own prompts, skip context, and get uneven results.

Fourth, show one sample task from start to finish. Pick a safe, real change and show the whole path: where the code lives, which prompt to use first, how to test it, what the PR should look like, and what kind of reviewer comments are normal. Keep it small enough to read in 10 minutes.

The last piece is not a document. It is a person. Name one human the new hire can ask when the docs feel thin or contradictory. That single point of contact cuts hesitation fast, especially in the first few days when people are still learning what is written down and what only exists as team habit.

Teams that do this well keep everything in one place and keep it short. If the pack takes an hour to read, it is too big. If someone can open it in the morning and start a safe task before lunch, it is doing its job.

How to explain the repo map

A repo map should follow the product, not the folder tree. New hires think in features first: signup, billing, search, admin, notifications. If you start with "apps/", "packages/", and "libs/", they may memorize names and still have no idea how the product works.

For each product area, point to the files where the real decisions live. Routes and UI files matter, but people also need to see where pricing rules, permission checks, retries, and state changes happen. If "cancel subscription" touches five services, write that path down once so nobody has to guess.

A good map fits on one page. For each area, include the feature in plain words, the few files someone should read first, where the tests live, which scripts or config files matter, and who owns that part of the system.

It also helps to mark the files a new hire should avoid for the first few days. Generated code, deployment settings, shared build rules, database migrations, and old compatibility layers can eat hours for no good reason. People feel pressure to move quickly, and that is exactly when they edit the scariest file in the repo by accident.

Owner labels matter more than many teams admit. Use a real name or a small group, not "engineering" or "backend." If someone has a question about auth tokens, they should know who can answer in two minutes.

A small example

If a bug shows up in checkout, the map should tell a new engineer where to start: the checkout page, the service that applies discount rules, the webhook handler that confirms payment, the tests for failed charges, and the runbook for local setup. It should also warn them not to touch shared billing config on day two.

If a new hire can answer "where does the rule live, how do I test it, and who owns it?" after 10 minutes with the map, the map works.

Teach review rules before the first pull request

Most new hires do not struggle with Git. They struggle with team habits that nobody wrote down. If you wait until the first review comment to explain those habits, people start guessing.

A good pull request is easy to review in one sitting. Show one real example from your team if you can. The best ones do one job, explain why the change exists, and make the risky part obvious.

Size matters. A reviewer can judge a small change in 10 to 15 minutes. Once a PR mixes a bug fix, cleanup, naming changes, and a refactor, review quality drops fast. Ask new engineers to split work by purpose, not by file.

Some changes need feedback before code lands. If a task changes an API shape, database schema, auth flow, billing rule, or deployment behavior, ask for a short design check first. Ten minutes of early feedback can save a day of rework.

Naming rules should feel boring. That is a good sign. New engineers should match the code that already exists instead of importing their own style from the last company. The same goes for tests. If code changes behavior, add or update tests. If a test is missing for a real reason, say that clearly in the PR.

Rollback rules matter even on small teams. If a change touches migrations, background jobs, or production config, the author should explain how to undo it. AI can produce code quickly, but it can still hide deployment risk.

A PR description should answer the reviewer before they ask: what problem this fixes, which approach the author chose, what the reviewer should check first, how the change was tested, and how to roll it back if needed.

One more rule helps a lot: the author owns the context. Reviewers should not dig through commit history or chat logs to understand the change. If an AI tool helped write the code, the engineer still needs to explain the reasoning in plain language.

Prompt patterns that match daily work

New hires get better results from AI when prompts look like real tasks instead of generic chat. Keep them concrete: read this file, draft tests for this function, suggest a safe refactor in this module.

A small shared set cuts down random habits. It also makes reviews easier because people start from the same frame and ask the model for the same kind of output.

Three starter prompts

Use one prompt for code reading. It should force the model to stay close to the file in front of it.

Explain this file to a new engineer in plain English.
File: [path]
Focus on what it does, what calls it, what inputs and outputs matter, and what might break if I change it.
Use names from the code.
If something is unclear from this file, say "unclear from this file".
Do not guess about files or behavior you cannot see.

Use another prompt for tests. The safest version asks the model to copy the repo's testing style instead of inventing one.

Draft tests for [function or class].
Use the style and structure from [existing test file].
Cover only behavior you can prove from the code I shared.
Do not invent new features.
Do not change production code.
Return the test code and a short note if context is missing.

For small refactors, keep the request narrow. That stops the model from turning a tidy cleanup into a rewrite.

Suggest a small refactor for [path] that improves clarity without changing behavior.
Keep public interfaces, data shapes, logging, and error handling the same unless I ask otherwise.
Stay in this file if possible.
If the change is risky, say so and stop.
Show the proposed code and the tests I should run after it.

The most useful line in any prompt is the constraint. Tell people to state what the model must not change every time. Common limits are API contracts, database schema, auth checks, feature flags, and test style.

Keep these examples next to the codebase docs, not in a slide deck nobody opens again. Put them near the repo map and review rules so a new hire can copy one, paste in a file path, and get a useful answer in two minutes.

A simple first week plan

The first week works best when each day has one clear job. New hires do not need a grand tour. They need a short path that helps them read the code, use the team's tools, and make one safe change before the week ends.

A practical first week can look like this:

• Day one: walk through the repo with a real person. Show the main folders, where tests live, how to run the app, how to use local tooling, and where the team keeps review rules. End the day with a simple task: start the app and explain one request path back to the mentor.
• Day two: trace one small bug or feature from report to code. The point is not speed. The point is to learn how the team follows a thread through logs, files, services, and tests without guessing.
• Day three: write prompts with a mentor nearby. Use real work, not toy examples. Ask the new hire to draft prompts for code search, test ideas, and a small refactor, then compare the results with the team's shared prompt patterns.
• Day four: ship a tiny change under review. Keep the scope tight: a copy fix, a small test, a guard clause, or a minor bug. This gives the new hire one full pass through branch naming, PR notes, review comments, and follow-up edits.
• Day five: clean up docs and collect open questions. If a setup step was unclear or the repo map caused confusion, fix it while the memory is fresh.

This order matters. The new hire first learns where things are, then how the team thinks, then how the team uses AI, and only then pushes code.

Skip that order and people build a private workflow. It may look fast for a week. It usually stays messy for a month.

A realistic example

Maya joins a backend team on Tuesday, with an active sprint already under way. Her first task looks small: change one validation rule so a signup form accepts a new company ID format. Small tasks are exactly where new hires drift, because they guess where the logic lives and start editing the wrong files.

The repo map stops that early. Instead of searching the whole codebase, Maya opens the map and sees the request validation path, the service that owns signup checks, and the test folder that covers edge cases. In about 10 minutes, she knows which service to open and which modules to ignore.

That saves more time than most teams expect. Without a map, a new engineer might change a shared helper, break another flow, and spend half a day untangling it. With a clear map, Maya makes one focused edit in the right service and leaves the rest of the system alone.

The review rules shape the PR before she writes much code. The team asks for one change per pull request, a short summary, and tests that match the edited behavior. So Maya does not mix cleanup, refactors, and naming opinions into the same branch.

She also uses a saved prompt from onboarding. It is not magic. It just gives the AI enough context to sound like the team: "Write tests for this validation change. Use our existing test style, keep names short, cover one valid case and two invalid cases, and do not add new helpers unless the current file already uses them."

Now the output looks close to what the team already writes. Maya still checks it line by line, but she does not start from a blank page. That is the point. You are not teaching people to ask better random questions. You are teaching them how your team works so their first week produces clean changes instead of avoidable noise.

Mistakes that create drift

Drift rarely starts with a big failure. It starts when a new engineer gets too much to read, no clear order, and no obvious place to begin. Ten documents can feel thorough, but they usually push people to skim, guess, and copy whatever looks recent.

The problem gets worse when each mentor teaches a slightly different process. One person says to ask AI for tests first. Another says to write the fix first and prompt later. A third wants small pull requests, while someone else accepts a giant diff if it moves fast. By the end of week one, the new hire has learned that the team has no real standard.

Prompt habits drift the same way. If teams treat prompts like private tricks instead of shared methods, every engineer builds a personal style, stores it in notes or chat history, and gets different output for the same task. That is not creativity. It is noise.

Review habits fail in similar ways. If the team only shows polished pull requests, new hires never learn what to avoid. They need to see weak examples too: a vague title, no testing notes, no reason for the change, a diff that mixes refactoring with a bug fix, or an AI-written summary that says a lot and explains nothing.

Rules also stop being rules when teams bury them in old comments, scattered chat messages, or tribal memory. A rule hidden in a three-month-old thread is just trivia.

Picture two new engineers joining on Monday. One gets a clean starter pack with the repo map, review checklist, and shared prompt patterns. The other gets a folder full of old docs and three conflicting opinions in chat. On Friday, their pull requests look like they came from different companies.

If you want less drift, make the path boring and clear. Give one starter pack. Teach one process. Share prompt patterns openly. Show weak pull requests before someone opens one.

Quick checks before week one ends

By the end of week one, a new engineer should do more than finish setup. They should show that they can work inside the team's way of building software instead of inventing a private method that nobody else follows.

These checks work best as short, practical exercises. A manager or tech lead can run them in 20 minutes and spot confusion early.

Ask the new hire to explain the repo in plain words. They do not need perfect detail, but they should be able to say where the main app starts, where shared logic lives, and where tests usually go.

Give them a small area of the codebase and ask who owns it. They should know how to find that answer in team docs, CODEOWNERS, or the right chat channel instead of guessing.

Have them open a small pull request. Check the basics: the right branch, a clear title, tight scope, notes for reviewers, and any tests or screenshots the team expects.

Ask them to use one approved prompt template for a real task. It might summarize a file, draft test cases, or review a diff. The point is simple: use the team's prompt, not a random one written on the spot.

Then ask when they would stop and ask for help. Good answers are specific: when two folders seem to solve the same problem, when a change touches billing or auth, or when they have been blocked for 30 minutes and are starting to guess.

A simple scenario makes this easy to test. If they get a bug in an API handler, they should be able to name the likely folder, find the owner, write a small fix, open a PR that matches team rules, and use the approved review prompt before asking for feedback.

If one of these steps feels shaky, fix it that same week. Shared habits matter more than speed at this stage.

What to do next

Most onboarding docs go stale unless someone owns them. Treat the repo map, review rules, and prompt patterns like working parts of the codebase, not side notes.

When the team changes the structure of the repo, update the map right away. If a service moves, a folder gets renamed, or a new boundary appears between apps, the map should change too. New hires trust what they see first.

Do the same with repeated AI advice. If senior engineers keep typing the same guidance into chat, turn that guidance into a shared prompt pattern. Keep it short, tied to a real task, and easy to reuse.

A light upkeep routine is enough:

• update the repo map after structural changes
• save repeated chat guidance as team prompt patterns
• review onboarding notes after every new hire
• fix any rule people misunderstand in the first week

That last step matters. After each new hire, read their notes and look for the spots where they guessed. Maybe they asked AI to edit files in the wrong area, opened a pull request without the expected checks, or used a prompt that produced noisy code. Those moments show where the process still has gaps.

This is how first-week onboarding stays consistent over time. The goal is not more documentation. The goal is fewer private habits.

A small startup can do this in under an hour after each hire. One person updates the map, one person cleans up the prompts, and the team agrees on any review rule that caused friction. That habit prevents drift better than a long handbook nobody reads.

If a startup needs help setting up repo maps, review rules, or practical AI-assisted engineering habits, Oleg Sotnikov at oleg.is works on exactly that kind of early process design as a fractional CTO and startup advisor. That kind of outside help is often most useful before the team builds months of messy habits around guesswork.