Repository guide
How to understand an AI-generated repository
·
Learn where to start in an unfamiliar repository: setup instructions, entry points, data flow and the smallest relevant change.
Start with the README and execution settings
- You do not need to read every file. Find the project purpose and setup instructions in the README, then verify commands in configuration such as package.json. Use example environment files to understand variable names; never share files containing real credentials.
Trace one screen to its entry point
- Search the repository for the affected page URL or visible text. Follow its event handler, function calls and API request. File conventions differ between frameworks, so verify a file’s role instead of inferring it from its name alone.
Map input through to storage
- Write a flow such as “form → validation → API → server → database → response → interface update.” Add the files you actually found beside each step. This exposes unknowns and helps explain why editing a UI component may not fix a server authorization failure.
Check AI explanations against the code
- Ask for the exact functions and files involved when a button is clicked, rather than a generic folder summary. Confirm that those functions exist and are called. Ask the explanation to distinguish observed facts from assumptions.
Define a narrow change
- Use a goal such as “fix navigation after the login response” rather than “improve the architecture.” Record current behavior and test in a separate branch. List the files you have checked and the behavior that remains unclear.
Separate verified facts from open questions before deciding what to change next.
Read next: Repository review checklist: what to prepare