What does this solve?
Working with the model in the browser depends on transfer. The model does not see the repository: a person copies fragments of files into the chat window, receives a response, pastes it back, and manually combines imports and indents. Each iteration costs several minutes of fiddling, and on a project with hundreds of files, such a cycle is inferior to conventional manual editing.
Claude Code removes the carryover. The agent is launched in the terminal from the root of the working copy, searches for files by content, reads them, makes edits, runs tests and a linter, and displays diff. A person is busy making decisions: what to do, what to accept, what to release.
The class of tasks “to go through the entire project” is closed separately: rename a field in forty places, clean out unused imports, add tests to the module, unwind the stack trace from the log line to the reason. The work is voluminous and boring, a mistake in it is cheap, it can be checked in a minute by running tests - a suitable load for an agent.
Third - entering unfamiliar code. The question “where is this API response generated” is answered by searching the repository in ten seconds instead of half an hour of reading.
How it works
Cycle
One cycle revolves inside: the model receives the task and the current context, selects a tool, the tool is executed, the result is returned to the context, the model selects the next step. The cycle continues until the task is completed or until the person stops. Everything else is tied around this cycle.
Tools
Basic set: reading a file, writing a file, spot editing by string match, searching by content (grep), searching by name mask (glob), running shell commands, retrieving web pages. A separate tool for git no - git goes through the shell using regular commands, so the agent can do exactly the same thing that the user can do in this terminal.
Spot editing works on the principle of “find a unique fragment and replace.” Hence the typical mistake of a newbie: asking to “rewrite the entire file” instead of making targeted edits—this way, pieces of code that are not included in the context are lost.
Search instead of index
There is no pre-built vector repository index here. Files are searched on the fly: grep by substring, glob by path, reading the necessary pieces. Pros - the index does not rot, the private code does not go to someone else’s embedding storage, it works immediately after git clone, the branch has been switched - no need to rebuild anything. Disadvantages - each search wastes tokens and time, and on a very large monorep the search takes longer than using a ready-made index.
Permissions
The agent reads files silently. Writing, editing, and any shell command goes through confirmation. The rules add up to .claude/settings.json (project, committed to the repository) and to the user config: list of allowed command templates, list of prohibited ones. Smart start - allow git status, git diff, running tests and linter; ban everything that is written to the network, to products and to the database.
There is a planning mode: the agent examines the code and produces a plan, but does not change anything until the plan is accepted. On an unfamiliar project, this is cheaper than rolling back edits.
Project memory
File CLAUDE.md is read at the root at the beginning of the session. They put there things that the agent won’t display on its own: how the test run is launched, what package manager it is, where you can’t write, what branches are protected, what template to use to name the branches, where the base diagram is. Team /init collects the first version from the repository, then the file is moved manually. The same file in a subfolder affects its part of the tree.
The rule for this file is to write prohibitions and precise commands, not wishes. "Tests: make test" works, "write quality code" does not work.
Context
The context window is finite, and a long session clogs it up: read files, command outputs, stack traces. As the content is filled, the quality drops - the agent begins to forget early agreements and contradict himself. Management Tools: /clear —start from scratch, /compact —condense the story into a summary and continue. The practice is simple: one task - one session. --continue returns the last session, --resume allows you to select from a list.
Extensions
- Slash commands: files in
.claude/commands/—prepared prompt with parameters, called as/имя. Suitable for repetitive routines: analyzing a failed pipeline, preparing a description of a merge request. - Subagents: descriptions in
.claude/agents/. A separate run with its own context and its own set of tools returns only a summary to the main session. Hard research doesn't overwhelm the underlying context. - Hooks: command tied to an event - before calling the tool, after editing the file, at the end of the response. The hook is used to add a formatter after each entry or block dangerous commands. The hook is performed by the shell, not the model, so it cannot be bypassed by persuasion in the prompt.
- MCP servers: connecting external systems - tracker, database, CI, mail.
Non-interactive mode
claude -p "текст задачи" Executes the task and prints the result to stdout, without dialog. Scripts and CI steps grow from here: parsing night run logs, draft release description, checking internal rules on changed files.
Useful scripts
- Localization of a bug using a stack trace: the agent reads the log, finds the file and line, moves the chain of calls up, suggests editing and testing for reproduction.
- Mass change of signature or renaming of a field: editing for all call places with running tests after each step.
- Analysis of an unfamiliar module: “show in order of call how the discount is calculated here, and name the files.”
- Addition of tests to the uncovered area with running on site and repairing what has fallen.
- Routine around git: a branch from the desired base, commits in meaningful chunks, a draft description of the merge request by diff.
- Step into CI via
-p: synopsis of a crashed pipeline in the team chat or checking compliance with internal agreements on modified files.
Limitations
Plausible invalid code. The agent confidently writes something that does not exist: a non-existent library method, a field that is not in the schema, a flag that the utility does not have. The tone of the answer has nothing to do with correctness; reading the diff is mandatory.
Real system at hand. The tool executes commands in a real shell with user rights. Forgotten permissive level template psql * or docker * will one day fly to a live base. Permissions are set before the first long session, and not after analyzing the consequences.
Secrets. File .env for the agent is a regular text file: he will read it and can quote it in the response. The prohibition on reading is explicitly written into the prohibit list.
Money and time. The cost consists of read and written tokens. The request “look at the entire project” on a large code base eats up the limit in one go. It’s cheaper to give an entry point: file, folder, function name, log line.
Long sessions. After several dozen steps, the agent begins to contradict its own earlier decisions. It can be treated by resetting the context and transferring agreements to CLAUDE.md.
Visual tasks. The terminal does not show the page. The agent edits the layout and animation blindly until he is given a screenshot or a browser control tool.
Internal libraries. Private framework of the model company is unknown. Without examples and descriptions in CLAUDE.md she writes based on popular public analogues - syntactically pure and functionally irrelevant.
How to check the result
View git diff after each task, not after five. No one reads Diff for forty files, and that’s where the extra edits go.
Require proof instead of statement. “Tests passed” is checked in the session log: the command itself, the return code, the tail of the output. The second level is to run the same tests manually in a clean shell.
Perform a control test before editing. Before fixing a bug, a test that fails. After that the same test is green. Without this, “fixed” is indistinguishable from “rewritten so that the error no longer appears.”
Check permissions with command /permissions and eyes on .claude/settings.json. The project config should not contain wide asterisks on commands that write to the system.
Check relevance CLAUDE.md. An outdated test run command forces the agent to invent its own and break the environment. A quick check is to ask them to retell the project rules in your own words and check them against the file.
Monitor the session length. As soon as the agent asks again what has already been decided or returns the rolled-out option - /clear and again with a short description of the condition.
Rule: the agent is given the execution, the diff and test run are left to themselves.