Claude Code
The agentic terminal tool — the loop it runs, how to start it, and the workflow that gets the best results.
What it is
Claude Code is Anthropic’s command-line agent. It runs in your terminal, reads your repository, and can propose edits, run commands, and iterate against test output. It is the surface most of this guide is built around.
Starting a session
You typically run the agent from the root of your repository so it has the full project context. The exact install and launch commands change over time — check the official docs for the current one rather than copying from memory.
The agent loop
Once running, the agent works in a loop:
- You describe a task in natural language.
- The agent reads files, runs searches, and proposes tool calls.
- Tool calls that modify state (file edits, shell commands) are gated behind your approval unless you have configured a permission rule.
- The agent reports what it did and waits for your next instruction.
When to use it
- Well-scoped changes. “Add a field to the form and its validation” — the agent can hold the whole change in one pass.
- Exploration. “Where is the auth middleware applied?” — faster than grepping cold.
- Repetitive edits. Generating test cases, migration boilerplate, or config from a pattern you can describe.
Two generic examples
Example A — explain a module. Ask: “Read src/auth and explain how a request is authenticated, with file:line references.” Use the answer as a map, not as truth — open the cited lines yourself.
Example B — make a contained change.
Ask: “Add a created_by field to the Order model, the migration, and the factory. Do
not touch the controllers.” The scope cap (“do not touch the controllers”) keeps the
diff reviewable.
Pitfalls
- Unbounded tasks. “Refactor the whole auth system” produces a huge diff you cannot review safely. Break it into steps and review each.
- Approving without reading. The approval prompt is the safety mechanism. If you rubber-stamp every tool call you have removed the only gate between the agent and your code. See Security.
- Letting it run long commands blind. Long-running or destructive shell calls should be scoped in your permission config, not approved ad hoc every time.