You just joined a new repo. You have no idea where anything lives. That is normal.
Most onboarding advice says "read the codebase." That is a trap. A big repo takes weeks to read.
You need three safe routes instead: understand, contribute, recover. This drill takes one focused session. It gets you from clone to first PR to first rollback.
It works with any stack. It costs nothing. You leave with a map, a PR, and a recovery skill.
Why onboarding fails
New engineers fail in three ways. They read too much and ship nothing. They ship too fast and break something.
They panic when a rollback is needed. The fix is a time-boxed drill. Each phase has a hard stop.
Each phase produces a concrete artifact. The whole session fits in an afternoon.
Phase 1: First hour — map the repo
You do not need the whole map. You need the entry point, the config, and the test command. Find those three things. Then stop.
Run this script in the repo root:
# map.sh — first-hour repo map
echo "== entry points =="
grep -rE "func main|app.listen|createServer|def main" \
--include="*.go" --include="*.ts" --include="*.py" . | head -20
echo "== config files =="
find . -maxdepth 2 -iname "*config*" \
-not -path "*/node_modules/*" \
-not -path "*/.git/*" | head -20
echo "== test command =="
cat package.json 2>/dev/null | grep -A5 '"scripts"' || true
Then follow four steps:
- Save the output as
repo-map.md. That is your reference file. - Trace one request end to end. Pick the simplest feature you can find.
- Follow it from the route to the database. Write down the file names.
- Do not memorize them. Just know where to look.
A free AI server can speed this up. MonkeyCode's free model access and free server option are enough for this Q&A work.
Disclosure: This article was prepared as part of MonkeyCode's product outreach.
Paste a file and ask "what does this function do?" Ask "where is this config loaded?" Verify every answer against the code.
The AI is a map reader, not a guide. You are still the navigator.
Phase 2: First PR — the safe contribution
Your first PR should be small. Keep it under 200 lines. One concern, no refactoring.
- Find the contributing guide. Read it. Follow it.
- Pick a bug or a doc fix. Nothing architectural.
- Run the full test suite before you change anything.
- Write a test that fails on the old code.
- Make the test pass. Keep the diff tight.
- Update the relevant docs. Yes, even the small PR.
Use this checklist before you open the PR:
- [ ] Contributing guide read
- [ ] Full test suite passed before changes
- [ ] Failing test written first
- [ ] Diff under 200 lines
- [ ] Docs updated
- [ ] PR description explains the why
A good PR description states the problem, the fix, and the test. Write it before the code review. Future you will thank you.
Use the AI for the boring parts. Ask it to explain the test harness. Ask it to summarize the stack trace.
Do not ask it to write the whole PR. You need to understand every line you ship. The review is still yours.
Phase 3: First rollback — practice recovery
This is the phase everyone skips. Rollbacks are rare. So nobody practices them.
Then production breaks and panic wins. Practice on a throwaway branch instead. Commit a deliberate break, then revert it.
# rollback-drill.sh — practice recovery on a throwaway branch
git checkout -b drill/rollback-practice
# introduce a deliberate break
echo "export const FEATURE_FLAG = false;" > src/flag.ts
git add src/flag.ts
git commit -m "drill: break feature flag"
# practice the rollback
git log --oneline -5
git revert HEAD --no-edit
git log --oneline -3
Read the drill as four steps:
- Create a throwaway branch.
- Commit a deliberate break.
- Revert the break with
git revert HEAD. - Confirm the log shows both commits.
git revert creates a new commit. It does not rewrite history. That makes it safe for shared branches.
Practice it until it feels boring. Then practice git reflog too.
If you reset the wrong branch, reflog is your rescue. Type git reflog and find the lost commit. Then git reset --hard <sha>.
Do this once on the drill branch. Never on main.
A rollback is not a failure. It is a standard recovery path. Teams that practice recover faster.
Roll back or roll forward?
Recovery is a decision, not a reflex. Use this table when something breaks.
| Situation | Action |
|---|---|
| Breaking change in the main path | Roll back |
| Data migration already ran | Roll forward |
| Security issue | Roll back immediately |
| Small bug, low blast radius | Roll forward with monitoring |
When in doubt, roll back. You can always re-apply the fix later. Speed matters more than elegance.
Where the AI fits — and where it does not
The drill works without AI. AI just removes friction. Use the free server to explain unfamiliar commands.
Use it to turn a stack trace into plain English. Use it to generate the rollback checklist. That is the easy part.
Do not use it for the decisions. The table above is yours. The revert command is yours.
The PR review is yours too. This drill is a harness. It tests your process, not the model.
A model can score 100% and your team still breaks production. Practice the process instead.
Limitations
This drill assumes a few things. The build must finish quickly. The repo must be mappable in an hour.
The team must allow external AI tools. If any of those are false, adapt the drill.
Who should not use this? Engineers on a codebase with no tests. Teams with strict data-security rules.
Repos where a full build takes hours. In those cases, skip the AI part. Keep the rollback drill.
If your team blocks external AI, use the local docs. The map and the drill still work.
It still works without AI. Recovery practice is universal.
The takeaway
Onboarding is not reading. It is practicing. Map the repo in one hour.
Ship one small PR. Break and restore a branch on purpose. That is the whole drill.
Thirty minutes of practice beats a month of guessing. Try the drill on your next repo.
Top comments (0)