Claude Code on an Existing Codebase: A First-Task Workflow

To use Claude Code on an existing codebase, begin with one behavior you want to understand. Ask the agent to trace its entry point, implementation, and tests before it edits files. Then give it a small change with a checkable result. The same approach works with Codex.

“Understand this entire repository and improve it” is a difficult first assignment to review. “Find where the search page builds its URL, explain how it preserves filters, and identify the relevant test” gives you something concrete to inspect.

This guide provides a reusable first-session brief. For a complete runnable exercise after exploration, use the bug-fix walkthrough.

1. Establish which copy of the project you are using

Before the agent starts, identify the working directory and branch. In a Git repository, these read-only commands provide a useful baseline:

git status --short --branchgit diff --statgit log -1 --oneline

Existing edits matter. Tell the agent which belong to the current task, and ask it to preserve everything else. If the directory is not a Git repository, make a separate copy before allowing changes.

Next, read the project's own setup instructions and dependency manifest. A lockfile and a declared package manager are better evidence for how to install dependencies than a guessed command. Ask before running scripts whose effects you do not understand; installation can execute project scripts.

2. Trace one behavior instead of requesting a repository tour

Use this brief, replacing the bracketed parts:

I am new to this repository. Investigate [one visible behavior].Do not edit files or install dependencies yet.
Read the repository instructions that apply to the relevant files.Trace the path from [UI action, route, or command] to its implementation.Find the closest existing test or example.
Return:1. Entry point and relevant files, with file references.2. The current behavior, including one important edge case.3. The smallest command that can check this behavior.4. Anything you could not verify from the repository.
Keep the investigation focused on this behavior.

For a search feature, the useful result is a chain such as “form submission → URL helper → query parsing → test.” That chain is an example of the expected output, not a claim about your repository. Require real paths before accepting it.

Check two or three references yourself. Does the handler actually call the helper? Does the test import the same implementation? A fluent architectural overview is less useful if it links to an obsolete path.

3. Distinguish project instructions from task context

Claude Code and Codex have different instruction mechanisms. Claude Code's official best practices discuss CLAUDE.md, focused context, and verification. Codex documents its discovery of AGENTS.md instructions. Do not assume that naming a file for one harness configures every other harness.

Read what is already there. Avoid creating another instruction file just to repeat the current task. A temporary request belongs in the session; a project-wide rule deserves an explicit decision by the project's maintainer.

If you switch harnesses, provide the important task constraints directly and verify that the new session has read the relevant project rules. The harness-versus-model guide explains why changing the execution tool is different from choosing a model.

4. Check the baseline before changing code

Run the relevant existing check in the correct directory when you are ready to execute project commands. Record the result before editing.

Do not ask an agent to “make all tests green” when the baseline contains unrelated failures. Name the failure it owns and retain the original output.

5. Make the first change small enough to read

Once you understand the path and baseline, use a second brief:

Implement [specific behavior] in the path you just traced.Preserve [existing behavior] and my unrelated edits.Reuse the current project conventions and dependencies.
Acceptance:- [observable outcome]- [important edge case]- [relevant existing check]
Show the changed files and actual verification output.Stop for a decision if this requires changing a public contract,deleting data, or expanding the agreed scope.

Read the diff, not only the final message. Check whether the patch changes dependencies, removes validation, weakens tests, or modifies files outside the traced path. Those may sometimes be appropriate, but they need an explanation connected to the task.

6. Continue the project without repeating discovery

At the end of the session, keep the current result, verification command, and next step together. A useful note is short: “Search preserves the existing sort parameter; the URL helper tests pass; browser behavior has not yet been checked.” It separates evidence from remaining work.

In Agent.Space, you can organize a project around saved files and supported agent sessions. Begin with the first Workspace guide, add the relevant project files, and choose an available harness and compatible model. Confirm the live product's supported combination rather than assuming every model works with every harness.

Changing sessions does not transfer private reasoning, and sharing a Workspace does not automatically isolate concurrent edits. For a solo first task, one active writer and a small reviewable change are enough. If you later change agents, follow the context handoff checklist.

This is an original workflow guide, not a measured comparison of agent performance. Official instruction references checked October 8, 2026.