Explore a repository without getting lost

Ask before changing

In an unfamiliar repository, the first task should reduce uncertainty. Ask for concrete paths, symbols, and commands so every claim can be checked.

Analyze this repository without editing files. Identify:
1. entry point
2. main modules
3. one request flow
4. tests and validation commands
5. three technical risks
Cite files and lines.

Trace real behavior

A folder list does not explain a system. Pick visible behavior and ask Codex to trace it from the UI or endpoint through data, side effects, and tests.

• Where is input validated?
• Which contract connects the modules?
• Where is data transformed or persisted?
• Which test would fail if this behavior changed?

Large repositories, monorepos, and multi-repo work

In a monorepo, do not ask “understand everything.” First request the map of workspaces, packages, commands, and internal dependencies. Then narrow to one path and require Codex to say what it did not inspect.

Analyze this monorepo without editing. Return:
- detected workspaces or packages
- install and test command for each relevant package
- internal dependencies of the package I will touch
- boundaries of what you did not read
Then focus only on packages/web.

If work crosses several repositories, work through contracts: API, events, schema, published package, or versioned documentation. Do not let Codex patch two repos at once without independent verification in each.

Require evidence

Ask Codex to separate observed facts from inferences and to state when evidence is missing. This reduces plausible but incorrect answers.

Exercise

Choose one small feature, obtain its map, and manually verify two references. Keep the summary in your notes unless the team explicitly wants new repository documentation.