TL;DR
An existing codebase has working features and unwritten conventions, and a coding agent meets all of them at once. Start the agent in a mode that cannot edit, have it trace one real flow and say what it would read before changing anything, and record a baseline of the project's own checks on a clean branch. Then give it one small task those checks can verify, compare the result with the baseline, and add its mistakes to the instruction file before widening the work.
Legacy code, and an agent that acts before it understands
In April 2026 a developer with more than twenty years of experience asked on Hacker News how others were using AI code assistants on large, messy legacy codebases. Their company's code was over twenty years old, written by many developers in different styles, and without someone who already knew the system steering it, the agent added bloat; rereading large parts of the code also used up their usage limits.
In March 2025, a Cursor user asked on the Cursor forum how to keep the agent under control in large, unfamiliar code. They had written rules asking it to propose one change at a time, explain it and wait for approval, yet it sometimes wrote and ran code without waiting. They asked whether anyone had found a better way to get a careful, step-by-step workflow.
In both, the agent did not know the system, and the tools let it act before anyone knew whether it did.
Start in a mode that cannot edit your code
The first session should be read-only, and on current versions that is not the default. Claude Code starts interactive sessions in auto mode from version 2.1.283 where auto mode is available, which approves most actions without asking; its permission modes documentation recommends plan mode for exploring a codebase before changing it and Manual mode for unfamiliar code. Codex recommends its automatic preset for version-controlled folders and documents switching to read-only with /permissions when you want to plan without changes (Codex approvals and security). Cursor's Ask mode is read-only (Cursor Ask mode).
So the first command is explicit: claude --permission-mode plan, Codex with --sandbox read-only, or Cursor in Ask mode. None of this depends on the agent remembering to wait, though Claude Code's plan mode, which blocks file edits until you approve a plan, can still run shell commands to explore.
Ask what it would need to know before touching anything
Use the read-only session the way you would onboard a senior engineer, which is how Claude Code's best practices describe it. Ask for an overview, the entry points, how one important flow works from request to storage, where tests live and how to run them, and which conventions the code follows. Cursor's quickstart adds a useful question: what the agent would read before making a change.
Two habits make this session worth more than a tour:
- Make it trace, not summarize. Ask it to follow one real path through the code and name the files and functions involved. A trace can be checked against the code; a summary can only be believed.
- Check a few claims yourself. Pick two statements it made about how something works and open the files. If they are wrong, you have learned what it misreads before it acts on it.
You do not need to send it the whole repository. Claude Code's monorepo guidance covers starting in the relevant directory, keeping per-directory instruction files and blocking reads of generated or vendored code. In Cursor, search is now local grep-based retrieval rather than an embeddings index, which Cursor staff described as being retired in mid-2026, so do not assume a semantic index is doing the finding for you.
Record a baseline before the first edit
Before the agent edits anything, create a branch and make sure git status is clean, which Codex's documentation recommends before delegating work. Then run the project's own checks, tests, type checks, lint and build, and write down what passes and what already fails.
This baseline is a recommendation of this article rather than a vendor instruction: the vendors say to run the project's checks after a change, and Cursor's quickstart is explicit about running the checks the project already uses. Without the before picture, a failing test after the change could be the agent's doing or a failure that was already there, and you cannot tell which.
Checkpoints are not a substitute. Claude Code's checkpoints do not track files changed by shell commands and are not a replacement for Git, Cursor's checkpoints are local and separate from Git, and the Codex CLI has no rewind command. A commit before the first edit is the rollback that covers every route.
Pick a first task with limited impact
Cursor's quickstart suggests low-risk first tasks, such as improving copy or fixing a small interface issue, and asking the agent for a few small, safe improvements to choose from. The useful test is whether the project's existing checks can tell you the task was done right:
Comparison
| Good first task | Why it works | Wait for later |
|---|---|---|
| Add a test for behavior that has none | Verifiable by running it; changes no production code | Refactoring across modules |
| Fix a small bug with a reproducible symptom | The symptom is the done condition | Dependency or framework upgrades |
| Tidy one function the team already flagged | Contained, reviewable in one diff | Database migrations |
| Correct a documentation page against the code | Easy to check by reading | Anything in authentication or payments |
Give the task a written scope: the files it may change, what done looks like, and an instruction to report anything else it finds rather than fix it. For the mechanics of holding that scope, including a diff check against the files you declared, see the article on stopping a coding agent changing unrelated code.
Review the result before you widen the work
Review the first change against the baseline, not just on its own:
- Rerun the same checks and compare them with the baseline. New failures belong to this change; old ones do not.
- Read the diff for scope: did it touch only the files the task needed?
- Check any new test: would it fail if the fix were removed?
- Note what it did not know, such as a helper it duplicated or a convention it missed.
- Put those points into the project's instruction file. Claude Code's
/initand Codex's/initcan scaffoldCLAUDE.mdorAGENTS.md, and Codex's guide advises keeping the file short and adding rules after repeated mistakes.
Only then give it a slightly larger task, and repeat. Each round should leave the instruction file a little more accurate and the review a little faster.
Paqad turns the same sequence into a workflow. Its onboarding detects the stack and prepares project context and instructions, though detected support is not a guarantee that the application is correct. Each request is then sized into a lane, a change to a module the project marks as sensitive is forced into the heaviest lane, and each change keeps a record of its plan and checks. Its quick start shows what onboarding writes into your repository, so you can see what Paqad would set up before choosing a first task. As the agent takes on more of the work, the article on using AI coding agents without losing understanding of the codebase suggests routines that keep that knowledge with the team.
Frequently Asked Questions
How do I start using a coding agent on an existing codebase without breaking working features?
Keep the agent unable to edit until you have a baseline, then let the project's own checks judge its first change. The baseline is what makes a failing test after the change interpretable: without it you cannot tell a new failure from one that was already there.
What should the agent inspect before proposing its first change?
The files on the path the change will pass through, the tests that cover them and the commands that run them. Ask it to list those files before it reads them; a list that misses the obvious test file or the module's entry point tells you its picture of the code is incomplete.
How do I expose hidden dependencies and local conventions without sending the whole repository?
Ask directly about conventions in the area you will change, such as error handling, naming and where helpers live, and have it cite the file each answer came from. An agent that has not been told will usually infer conventions from whatever file it opened first, so a cited answer is easier to correct.
What small first task would test its understanding with a limited impact if it goes wrong?
One whose success the existing checks can show without your judgment: a missing test, a bug with a reproducible symptom, a documentation fix against the code. If no such task exists in the area, write the test first yourself; that is useful work regardless of the agent.
What should I review after that task before letting it handle a more important change?
Whether the first change needed hidden cleanup. If you had to fix a duplicated helper, a missed convention or an unrelated edit, record it in the instruction file and repeat a task of similar size. Move up only after a task that needed none.