Orient to an Existing Project

A software project can exist simultaneously as source files on your computer, commits in a Git host, a local process, a temporary preview, a packaged desktop application, and a public deployment. These are related but not interchangeable. Editing a local file changes only that checkout until a later process builds, shares, or deploys it.

Create an evidence ladder for the question you are answering. Source proof means the intended text or code exists in the named file. Local runtime proof means a process built from that source behaves correctly. Shared preview proof means another person can reach a specific version. Production proof means the public route is serving that version. Ask Claude to label each claim with the highest layer actually observed.

Start with the files written to orient humans and tools: README files, package manifests, dependency locks, build scripts, environment examples, deployment configuration, and project instruction files. They reveal the intended commands and architecture, but they may be stale. Treat documentation as a claim to verify against source and runtime, not as unquestionable truth.

Ask Claude to cite exact paths and distinguish facts from inferences. For example, `package.json` may prove that a script named `build` exists, while only running that script proves it currently succeeds. A deployment file may name a service, while a provider receipt or live response proves which release is active.

Do not try to understand every file equally. Choose one user-visible outcome and trace it through the system. For a web page, follow the route to its component, data source, server logic, integration, and deployment configuration. For a command-line tool, follow its entry command to argument parsing, domain logic, state changes, and output.

This vertical trace gives each technical term a job. The interface collects or displays information. Logic applies rules. State persists what must survive. Integrations cross system boundaries. Identity controls access. Tests encode expectations. Logs and receipts reveal what happened. Claude can search quickly, but you should require it to explain this chain in plain language.

Git tells you which files differ from the current commit, but those changes may belong to another person or another unfinished task. Ask Claude to summarize `git status` and the diff without modifying them. Do not let an orientation task clean, reset, reformat, or commit a dirty checkout merely to make the environment easier to understand.

Then inspect recent history and relevant file history to learn conventions and intent. A nearby component or a previous commit often provides a safer implementation pattern than a generic solution. History is evidence, not an instruction to restore old code blindly; the live requirement may have changed since that commit.

The output of orientation should be an artifact another person can inspect. Record the repository, important directories, entry points, commands, data stores, external services, environment variables by name, test layers, and deployment path. Mark every statement confirmed, inferred, or unknown. Never copy secret values into this map.

Keep the map narrow enough to remain useful. If it becomes a file-by-file inventory, it will be obsolete before anyone reads it. Focus on responsibility boundaries and the paths a maintainer needs to build, test, deploy, and recover the system. Later chapters will turn the durable parts into project instructions and reusable workflows.