An AI agent does not arrive with a perfect mental map of your project. It has to build that map from the folder, the files, the instructions, and the evidence it can inspect.

That is not a weakness. It is the reason a well-organized project becomes more valuable every time you return to it. The project can explain itself.

Start with location

Every file has an address called a path. On a Mac, a complete path might look like this:

/Users/darinoliver/Desktop/Byebuy/articles/05-03-how-ai-understands-a-project.md

On Windows, it might look like this:

C:\Users\Darin\Documents\my-project\README.md

You do not need to type long paths all day. But you need to understand the basic idea: an AI cannot reliably work on the right files if you cannot tell it where the project begins.

An absolute path gives the complete address from the computer's root. A relative path gives the address from the folder you are currently in. When you run an agent from the project root, short relative paths become meaningful:

src/pages/index.tsx
public/images/logo.png
README.md

The orientation sequence

Before an agent changes a project, it should follow a short orientation sequence.

Find project rootRead instructionsMap folders and dependenciesAsk or state the planMake a focused change

This is not bureaucracy. It prevents the classic AI mistake: editing the first plausible file without understanding how the product is assembled.

Give an agent a request like this:

That request teaches the agent how you want it to work. More importantly, it teaches you how to inspect its reasoning before it edits your project.

The files that give an AI a map

Different projects use different names, but the roles are consistent.

You do not need all of these on the first day. Start with a strong README.md and one context or handoff file. Add the others when the project becomes complex enough to need them.

Context is selective, not infinite

An agent can inspect many files, but it still has a limited working context. Give it a clean path into the project rather than expecting it to read every file blindly.

Good instructions say:

Read README.md, CONTEXT.md, and docs/architecture.md first.
For this task, work only in apps/web and do not modify the database schema.
Run pnpm verify before you say the task is complete.
Record the result in HANDOFF.md.

That is better than “fix the app.” The first request names the goal, the starting context, the scope boundary, the verification step, and the handoff. It gives the AI enough room to work while protecting the rest of the system.

A project tree is not just organization

Folder structure communicates meaning.

sonariq/
  README.md
  AGENTS.md
  apps/
    web/
  packages/
    research-engine/
  docs/
    architecture.md
  research/
    prompts/
    handoffs/
  tests/

From this tree, a new agent can make reasonable first inferences: this has a web application, reusable packages, documentation, research artifacts, and tests. It still needs to read the files before acting, but the structure gives it an intelligent place to start.

This is why dumping unrelated files into a desktop folder creates friction. A random folder has no obvious scope, ownership, or instructions. A project workspace has a center of gravity.

Branches: a safe second version of the project

A branch is a separate line of work inside the same Git project. Think of it as a safe copy of the project's history where you can try one focused change without immediately changing the main version.

main: working versionfeature branch: one focused changeReview and testmerge into main

This is especially useful with AI. You can ask an agent to work on a feature branch called add-search or improve-homepage, test the result, inspect the changed files, and merge it only when you are satisfied. If the experiment is wrong, the main branch remains intact.

Do not treat a branch as a license to stop reviewing. It is a safety boundary, not a quality guarantee. The agent still needs clear instructions, a limited scope, tests, and your approval before a change becomes the shared version.

GitHub makes branches visible to other people. A pull request is the review page where a branch's changes can be discussed and compared before merging. You do not need a team to benefit from this. A pull request can be your own calm review screen before publishing an AI-made change.

Sonariq: the workflow map lives with the work

Sonariq is a strong example. Its research workflow does not depend on the next agent remembering a previous conversation. It uses a README.md to explain the overall process, Shared_Standards.md for evidence rules, Data_Contracts.md for structured outputs, stage-specific PROMPT.md files for bounded assignments, and a HANDOFF.md at the end of each stage.

When a new agent starts, it can find the workflow, see the current stage, inspect the accepted inputs, and continue from a durable record. That is project orientation in practice.

Practical exercise: create an agent entry point

In one project folder, create a short AGENTS.md or add an “AI working rules” section to README.md.

Include:

1. What the project does. 2. Which files an agent must read first. 3. The command that checks whether the project works. 4. What the agent must not touch without approval. 5. Where it should record the result when it finishes.

Add one more rule if the project is important: “Do focused work in a branch. Do not merge it into main until the requested checks pass and I approve.”

Then ask an AI to read the file and repeat its assignment back to you before doing any work. If its explanation is vague, improve the file—not merely the chat prompt.

Check your understanding

1. What is the project root? 2. Why is an absolute path sometimes useful? 3. Which file would tell an agent how to verify its work? 4. What should an agent do before making a change in an unfamiliar project? 5. Why is a branch useful when an AI is making a focused change?