How to use an AI coding tool in a project that already exists without making it harder to understand.
Many demos begin in an empty directory, but many real sessions do not. The project already exists. The files were written by someone else, or by several people, or by you six months ago. You do not yet know which files in the repository are intentional, fragile, obsolete, generated, or relied on by somebody else.
That changes the opening move. You have to read the project before you change it. Read broadly first and narrow as you go, paying explicit attention to local conventions that may not be documented anywhere. If you skip the reading, the tool will rewrite files it does not understand.
With inherited code, the agent's first job is to discover structure. Yours is to confirm or correct that picture before anything gets rewritten.
An agent can sketch a project map quickly, but it will also invent certainty where the project is least known. That tendency is visible early, usually as overconfident claims about entry points (the files that launch or serve the project) or conventions that have not yet been checked. The agent draws the map. You confirm or correct it.
CLAUDE.mdThe first prompts should ask questions. What does the project appear to be? Which files look like entry points? How are the directories organized? Which scripts or test commands are visible, and which assumptions still need to be checked manually? The tool scans quickly across many files. This broad-survey phase is where it is most useful.
"Refactor this project to make it cleaner and more modern."
"Inspect this repository and give me a project map: likely entry points, important directories, build or test commands, configuration files, and anything that looks generated. Do not edit anything yet. Tell me what still needs manual confirmation."
A good inspection phase ends with a clearer description of the project, a shorter list of unknowns, and at least one thing the tool flagged as uncertain. If the inspection ends without any open questions, it was probably too shallow.
Once you have a first impression from the inspection phase, ask the tool to organize what it found into a structured summary: entry points, important directories, how information moves through the project, configuration files, generated folders, and any test or build scripts that look active. The map should include the spots where it is uncertain. The tool produces clean-looking summaries even when the project is messy. You have to ask it to flag uncertainty explicitly.
An answer like that is useful because it supplies a draft picture and points to what still needs checking. A coherent-sounding summary is easy to accept without question. If you do, you may end up with edits that follow the tool's generic defaults instead of the conventions specific to this project.
The tool already knows general programming patterns. It lacks local knowledge. It does not know which library (a reusable package of code) this project already uses for a given task, how files are organized, whether styles live in one place or many, whether generated files are committed, or which naming habits the repository has already settled on. Those local rules often hold an inherited project together. They may not be documented anywhere.
If a tool introduces a second library for making web requests, or a different naming scheme, the new code may run fine but the project will be harder to maintain. If the existing site uses one approach to handle form submissions and the tool adds a second, the next person to work on the project has to understand both. Before introducing a new pattern, ask the tool to look for the existing one.
"Before suggesting changes, inspect how forms are handled elsewhere in the project and match that pattern. Do not introduce new libraries unless the existing approach clearly cannot support the change."
Once the project map is reasonably accurate, ask the tool to write it down in a short project file so the next session does not start from scratch. If you are using Claude Code, that file is CLAUDE.md. You can generate a starting version by typing /init at the Claude Code prompt (the same terminal where you type your instructions to the agent), which scans the repository and drafts a CLAUDE.md with project-level instructions, commands, conventions, architecture notes, and warnings. Edit the file afterward to correct anything the scan got wrong. Otherwise the next session will have to rediscover everything you already learned.
Record the project purpose, important commands, naming conventions, folders that should not be edited directly, verification routines, and any local terminology the tool kept getting wrong.
Before making any edits, commit the current state of the project in version control, or confirm that it is already committed. You want a clean snapshot to return to if something goes wrong. The first edit itself should be small. With a small change, you can tell whether your project map is accurate. A text correction, a bounded styling fix, or one narrow bug fix can show whether the map holds up. A broad refactor (restructuring code without changing what it does) is less helpful as a test, because by the time you notice something wrong, the tool has already touched too many files to follow easily.
"Propose the smallest reasonable change first. Tell me which files you expect to edit before making the change. After editing, summarize the diff in plain language and tell me whether the change revealed anything incorrect about your earlier project map."
A faculty or departmental site has been inherited from a previous maintainer. The root contains several HTML files, one shared stylesheet, a JavaScript theme toggle, a few one-off styles embedded in the pages, and a deployment folder that may or may not be generated. The immediate request is small: add a missing guide to the navigation and fix two chapter blurbs. The session is still risky because the project structure has not been established yet.
CLAUDE.md.That sequence is slower than "just fix the site." Skip it, and the tool may create a new version of a file that already existed. The project ends up with two copies that diverge over time. I have seen this happen more than once.
The tool can produce a persuasive-sounding summary that still misses important dependencies between files or names the wrong entry point. The most common sign of a weak map is proposed changes being directed to the wrong part of the project. Generated files get treated as source, the tool edits a configuration it did not realize was shared, or local scripts contradict the earlier summary.
When that happens, reopen inspection. Ask narrower questions and inspect the specific file or command in dispute. Update the map before more edits go in. Wherever the map turned out to be wrong, you have probably hit a complicated part of the project. Record those in the project file for next time.
the entry point appears wrong, the change reaches farther than expected, generated files are being edited as source, or the project commands do not do what the earlier summary claimed they would do.
Once you have a project map, a small set of commands, and a first-pass project file, the session can move into other parts of the series. How to Talk to the Tool covers tighter task specification. When the Vibes Go Wrong addresses verification and failure patterns. If you are using Claude Code, Project Context with CLAUDE.md goes deeper into refining that memory layer once the conventions are stable.