Understand an existing project

Goal

Without changing the project, have the Agent explain its purpose, main directories, startup entry points, core data flows, and validation methods, and identify what remains uncertain.

Before you begin

• Prepare a local project directory that you are authorized to read.
• Confirm that at least one model is enabled under Settings → Configuration.
• If the project contains sensitive code, first review the privacy and data-processing policies of the configured model service. File content read by the Agent and used in its answer might be sent to that service with model requests.

If you want a stronger read-only boundary, enable Custom permissions under Settings → General and set writes to Deny. Alternatively, use Default permissions and reject any unexpected write approval.

Steps

1. Add the project

Select New project in the project picker of a new conversation, or go to Settings → Environments and select Add project, then choose the project root directory. Captain Who records this workspace entry point; adding the project does not automatically modify any files in it.

2. Create a project conversation

Start a new conversation from the project section in the left sidebar and confirm that the input box shows the intended project. Select a model suited to understanding code.

3. Ask for a map first

Send a task with explicit boundaries, for example:

Analyze this project in read-only mode. Do not modify files or install dependencies.

First inspect the repository entry points, dependency manifests, main source directories, and test configuration. Then answer:
1. What problem does this project solve?
2. What is each main module responsible for?
3. Which modules does a typical request pass through?
4. Which commands are normally used to run and validate the project locally?
5. Which conclusions have file evidence, and which still need confirmation?

Cite relative paths to key files. Do not list every file.

The Agent lists files, searches code, and reads a small number of key files as needed. Do not begin by asking it to “read every file.” Building a structure first and then investigating important paths is usually faster and more reliable.

4. Follow one path in depth

Choose the feature you care about most and continue, for example:

Continue along the “user submits a task” path. Start at the interface entry point and trace it through backend execution and result persistence. Give the call sequence, each layer's responsibility, and the corresponding files, and state what you did not verify.

5. Verify the conclusions

Open the key files cited by the Agent and spot-check entry points, configuration, and tests. If the answer presents speculation as fact, ask the Agent to distinguish again among “proven by code,” “covered by tests,” and “inferred from naming.”

Expected result

You receive a layered project map rather than a restatement of the directory tree. At minimum, it includes the project objective, module boundaries, key entry points, data flows, common validation commands, and open questions, all traceable to specific files.

Troubleshooting

• Files cannot be found: Confirm that the conversation is bound to the correct project. If the project moved, add it again under Settings → Environments.
• The analysis scope is too large: Narrow the task to one entry point, request path, or directory.
• The Agent tries to modify a file: Reject the approval and restate “read-only analysis,” or use Custom permissions with writes denied.
• A command requires approval: Understanding a project usually does not require high-impact commands. Approve only after confirming that the command is genuinely a read-only check.
• A conclusion contradicts the code: Provide the counterexample file and ask the Agent to correct the answer using evidence instead of adding more speculation.

Next, continue to Implement a small feature, or first read Manage large projects.