Claude Code: how to start with a real project
Original publication: · Sergey Zhadov
This is a translated archive article. The date and pricing discussion refer to the original publication, not a new announcement today.
Claude Code works from a project directory. It can inspect structure, follow relationships between files, edit code and run commands. A sensible first session starts with repository discovery, continues with one small plan and ends with a reviewed diff and tests. Telling it to fix everything is how a useful tool turns into a mess.
Install it without unnecessary wizardry
Anthropic currently recommends the native installer. Windows users can use PowerShell, CMD or WinGet, while macOS and Linux have their own documented routes. npm still exists, but it is no longer the only obvious answer and its Node.js requirements can change.
Run claude --version after installation. If something looks wrong, claude doctor performs read-only diagnostics. The tool needs an internet connection and an eligible account. Do not assume that the free Claude.ai plan includes Claude Code access.
Start from the repository root
Open the terminal in the project directory and run claude. This gives the agent a codebase to understand instead of one lonely file stripped of context. Check git status first and protect important uncommitted work. That boring step matters when an edit goes sideways.
Make the first request an inspection: explain the project's purpose, identify entry points, list the main modules and find the existing test and build commands, without changing anything. You quickly learn whether the agent understands the repository or is already producing confident rubbish.
Give it one testable task
Do not begin with improve the app. Describe the symptom, expected behaviour, file boundaries and verification method. For example: the checkout form submits twice after a double click; find the cause, propose the smallest fix, keep the API unchanged and show a plan before editing.
A decent task has a finish line. The test passes, types remain valid, unrelated files stay untouched and the bug can no longer be reproduced. Without those conditions, the agent may write a heroic amount of code and achieve almost nothing.
Review the plan before the patch
Ask for the likely cause, files to change and checks to run. Compare that plan with the actual architecture. If a tiny defect somehow requires half the project to be rebuilt, stop the circus and narrow the scope.
Allow changes in small chunks and inspect each diff. Pay extra attention to configuration, migrations, dependencies, authentication and payments. A confident explanation does not turn a risky patch into a good one.
Verify with commands, not faith
Ask Claude Code to run the project's established tests, linter, type check and build. Then repeat the critical checks yourself. If the project has no tests, reproduce the original failure and exercise a neighbouring path that the fix could have broken.
Read git diff before committing. Remove stray comments, accidental formatting and unrelated changes. A commit should describe one completed fix, not a sack full of random debris.
Do not hand over the keys to the shed
Do not paste passwords, API keys, customer records or production configuration into a prompt. Check .gitignore and the changed file list before publishing anything. Keep confirmation for risky commands and constrain tools when the selected permission mode supports it.
Do not skip permissions merely to save a few clicks. That shortcut can end with deleted files, damaged data or an unexpected network action. Create a recoverable point first, then let the tool act.
Verdict: map first, scalpel second
Claude Code becomes useful on project work because it can follow context across files. The reliable workflow is not a magic sentence. It is discovery, a narrow plan, a small diff, automated checks and manual review.
Start with one defect you can reproduce. Expand the scope only after the agent understands the structure and passes the checks. If it charges off to rewrite everything after the first prompt, put the brakes on that nonsense.
Translation reviewed:
