use-cases/codebase-onboarding.md +21 −50
11# Understand large codebases | Codex use cases---
22 name: Understand large codebases
33[← All use cases](https://developers.openai.com/codex/use-cases)tagline: Trace request flows, map unfamiliar modules, and find the right files fast.
44 summary: Use Codex to map unfamiliar codebases, explain different modules and
55Copy page [Export as PDF](https://developers.openai.com/codex/use-cases/codebase-onboarding/?export=pdf) data flow, and point you to the next files worth reading before you edit.
66 bestFor:
7Use Codex to map unfamiliar codebases, explain different modules and data flow, and point you to the next files worth reading before you edit.
8
9Easy
10
115m
12
13Related links
14
15[Codex app](https://developers.openai.com/codex/app)
16
17## Best for
18
19 - New engineers onboarding to a new repo or service7 - New engineers onboarding to a new repo or service
20 - Anyone trying to understand how a feature works before changing it8 - Anyone trying to understand how a feature works before changing it
9starterPrompt:
10 title: Explain the System Area I Need
11 body: >-
12 Explain how the request flows through <name of the system area> in the
13 codebase.
21 14
22## Starter prompt
23 15
24Explain how the request flows through <name of the system area> in the codebase.
25 Include:16 Include:
26 - which modules own what
27 - where data is validated
28 - the top gotchas to watch for before making changes
29 End with the files I should read next.
30 17
31Explain how the request flows through <name of the system area> in the codebase.
32 Include:
33 - which modules own what18 - which modules own what
19
34 - where data is validated20 - where data is validated
21
35 - the top gotchas to watch for before making changes22 - the top gotchas to watch for before making changes
23
24
36 End with the files I should read next.25 End with the files I should read next.
26 suggestedModel: gpt-5.3-codex-spark
27 suggestedEffort: medium
28relatedLinks:
29 - label: Codex app
30 url: /codex/app
31---
37 32
38## Introduction33## Introduction
39 34
43 38
44If you're new to a project, you can simply start by asking Codex to explain the whole codebase:39If you're new to a project, you can simply start by asking Codex to explain the whole codebase:
45 40
46Explain this repo to me
47
48If you need to contribute a new feature to an existing codebase, you can ask codex to explain a specific system area. The better you scope the request, the more concrete the explanation will be:41If you need to contribute a new feature to an existing codebase, you can ask codex to explain a specific system area. The better you scope the request, the more concrete the explanation will be:
49 42
501. Give Codex the relevant files, directories, or feature area you are trying to understand.431. Give Codex the relevant files, directories, or feature area you are trying to understand.
62- Where does validation happen, and what assumptions are enforced there?55- Where does validation happen, and what assumptions are enforced there?
63- What related files or background jobs are easy to miss if I change this flow?56- What related files or background jobs are easy to miss if I change this flow?
64- Which tests or checks should I run after editing this area?57- Which tests or checks should I run after editing this area?
65
66## Related use cases
67
68[
69
70### Iterate on difficult problems
71
72Give Codex an evaluation system, such as scripts and reviewable artifacts, so it can keep...
73
74Engineering Analysis](https://developers.openai.com/codex/use-cases/iterate-on-difficult-problems)[
75
76### Create browser-based games
77
78Use Codex to turn a game brief into first a well-defined plan, and then a real browser-based...
79
80Engineering Code](https://developers.openai.com/codex/use-cases/browser-games)[
81
82### Learn a new concept
83
84Use Codex to study material such as research papers or courses, split the reading across...
85
86Knowledge Work Data](https://developers.openai.com/codex/use-cases/learn-a-new-concept)