Codebase Onboarding skill for Codex

Onboarding is done when you can answer five questions with file paths, and each answer was checked by running or tracing something rather than guessed from names:

1. How do I build, run and test it? (exact commands that worked)
2. Where does execution start? (entry points per deployable)
3. How does one real request or job flow through the layers?
4. Where are the boundaries? (modules, packages, services, what may import what)
5. What conventions must a change follow? (style, errors, tests, naming, review rules)

Order of reading

Read in this order; each step narrows the next. Do not open source files at random.

Step	Read	You learn
1	AGENTS.md (and nested ones), README.md, CONTRIBUTING.md	Stated commands, rules, boundaries
2	Manifests: package.json scripts, pyproject.toml, go.mod, Cargo.toml, Makefile, justfile	Real commands, dependencies, workspaces
3	CI config (.github/workflows/*.yml, .gitlab-ci.yml)	The commands that actually gate merges, versions of tools
4	Deploy config (Dockerfile, compose, k8s, fly.toml, vercel.json)	Deployables and what each one runs
5	Entry points and routing tables	Where execution begins
6	One end-to-end trace	How the layers actually connect
7	Git history and ownership	Where change happens, who knows what

CI beats README when they disagree: README commands rot, CI commands run every day.

Get a fast inventory first:

python3 scripts/repo_map.py .            # languages, manifests, entry points, tests, CI, churn
git ls-files | wc -l                     # tracked files only, skips build output
git ls-files | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -25   # busiest dirs

repo_map.py is read-only and uses only the standard library; it reports git churn when the folder is a git checkout.

Workflow

- [ ] 1. Read AGENTS.md, README, CONTRIBUTING; note every command they claim
- [ ] 2. Run repo_map.py; list deployables (services, CLIs, libraries, jobs)
- [ ] 3. Reproduce build + test locally; record what actually worked
- [ ] 4. Find entry points for each deployable
- [ ] 5. Trace one real flow end to end, writing file:line hops
- [ ] 6. Draw the dependency direction between top-level modules
- [ ] 7. Extract conventions from code, not just docs
- [ ] 8. Identify hot spots and owners from git history
- [ ] 9. Write the orientation note (template below)

Step 3: prove the commands

Run the cheapest checks first: install, typecheck or compile, unit tests. In a Codex sandbox, dependency installs usually need network; if network is off, say so and check for a populated lockfile cache or vendored deps instead of failing silently. Record the exact command, its duration, and any env var it needed. Never run migrations, seeders or deploy scripts against shared environments while exploring; read them instead.

Step 4: find entry points

Stack	Look for
Node/TS	main, bin, exports in package.json; scripts.start; src/index.ts, server.ts
Next.js / Remix / SvelteKit	app/ or src/routes/ file-system routes; middleware.ts
Python	[project.scripts] in pyproject.toml; __main__.py; manage.py, urls.py; app = FastAPI()
Go	cmd/*/main.go; every package main
Rust	src/main.rs, src/bin/*.rs, [[bin]] in Cargo.toml
Java/Kotlin	@SpringBootApplication, public static void main
Workers and jobs	queue consumers, cron definitions, celery, sidekiq, bullmq registrations

rg -n "package main$" --type go -l
rg -n "if __name__ == .__main__.:" --type py -l
rg -n "@(app|router)\.(get|post|put|delete|patch)\(" --type py | head -40
rg -n "\.(get|post|put|delete|patch)\(['\"]/" --type ts | head -40

Step 5: trace one real flow

Pick the most business-critical path (checkout, login, ingest), not the simplest. Follow it from the outside in and write each hop down:

POST /orders
  -> src/api/routes/orders.ts:41        validates body with OrderSchema
  -> src/services/orders.ts:88          createOrder(): opens transaction
  -> src/repos/orderRepo.ts:22          INSERT orders, order_items
  -> src/events/publish.ts:15           emits order.created (outbox table)
  -> workers/fulfilment/index.ts:30     consumes order.created

Confirm the trace dynamically when it is cheap: run the relevant test, add a temporary log line or breakpoint, or call the endpoint locally. Remove temporary instrumentation before finishing. A trace you only read is a hypothesis.

Step 6: boundaries and dependency direction

rg -n "^(import|from) " --type py | awk -F: '{print $1, $3}' | head -50
rg -n "from ['\"](\.\./)+" --type ts | head -30     # deep relative imports cross boundaries

Write the allowed direction as a one-line rule (api -> services -> repos -> db; domain imports nothing internal). Note every violation you see; they are where changes surprise people. If the repo already enforces this (eslint-plugin-boundaries, import-linter, internal/ packages in Go, Nx tags), cite the config.

Step 7: conventions from code

Docs describe intentions; code shows practice. Sample three recent, reviewed files in the area you will touch and note:

• Error style (exceptions vs result types, custom error classes, where they are mapped to HTTP)
• Logging (library, structured fields, request IDs)
• Test style (framework, fixture/factory helpers, naming, where tests live)
• Config and secrets (env loading, typed settings object, feature flags)
• Formatting and lint configs (.editorconfig, ruff.toml, eslint.config.js, biome.json)

Step 8: hot spots and owners

git log --since=6.months --name-only --format= | sort | uniq -c | sort -rn | head -20
git shortlog -sn --since=1.year -- src/billing/      # who knows this area
git log --oneline -15 -- src/billing/                 # recent intent, in commit messages

High churn plus high size marks the files where bugs and merge conflicts concentrate. For why a specific odd line exists, hand off to code-archaeology techniques (git log -S).

Gotchas

• Generated code (protobuf stubs, ORM clients, OpenAPI clients) looks like source. Check for headers like DO NOT EDIT and for generator config before reading it closely.
• Monorepos have several entry points and several test commands; one root npm test may run only a subset. Read the workspace config (pnpm-workspace.yaml, go.work, Nx/Turbo).
• Dependency injection and decorators hide call edges. Search for the registration site (container.register, @Injectable, providers:), not only the call site.
• Feature flags and env-based branches mean the code path you read may be off in production. Note every flag on the traced path.
• Dead directories survive for years. Before learning a module deeply, check that it is imported and has recent commits.

Output: orientation note

Keep it under one screen per section; link paths instead of pasting code. Offer to save it as docs/onboarding.md or to fold the commands into AGENTS.md, but ask first.

# <repo> orientation (verified <date>, commit <short sha>)

## Commands (all run successfully)
- Install: `pnpm install` (needs network)
- Test: `pnpm test` (~40 s); single file: `pnpm vitest run path`
- Run locally: `pnpm dev` + `docker compose up db`

## Deployables
| Name | Entry point | Runs as |
|---|---|---|

## One request, end to end
<hop list with file:line>

## Module map and dependency rule
<5-10 lines; the allowed direction; known violations>

## Conventions to follow
<errors, logging, tests, naming - each with an example path>

## Hot spots and owners
<top churn files, who to ask>

## Open questions / not verified
<anything read but not run>

Verification

• Every command in the note was executed in this session; anything not executed is listed under “not verified”.
• The traced flow was confirmed by a test, a log line or a local request.
• A teammate (or a fresh agent) could make a one-line change and run its test using only the note.