Claude Code Usage: An AI Coding Agent in the Terminal
In the previous lesson you got Claude Code installed to a "usable" state; in this 15-minute lesson, you'll get it to "second nature": starting sessions, assigning tasks with a single sentence, referencing files with @, enabling plan mode, and reviewing changes before committing. This Claude Code tutorial focuses on the terminal CLI as the main form—it is the most feature-complete form in the official documentation, while other forms (IDE plugins, desktop app, web version) share the same engine and will be walked through together later. (Fact-checked 2026-11-04; commands and features change with versions, so refer to the official documentation.)
What you'll be able to do after this lesson
- Start Claude Code in any project directory and understand the version, model, and working directory shown above the prompt
- Use one specific natural-language sentence to have it edit code, fix bugs, and write tests—it reads files and runs commands on its own
- Use
@to "feed" specific files into the conversation, use/shortcut commands, and!to run shell commands directly - For big changes, enable plan mode first, review the plan, and only then let it act
- Use
/diffto check changes, then have it write commit messages and create PRs, and at the end of a session be able to interrupt, clear, and resume
Your current struggles
- It's installed, but when you open the terminal you don't know "what to say": you type one sentence, it changes things in a different direction than you intended, and you go back and forth
- The Claude Code Chinese tutorials online either only cover installation or jump straight to advanced stuff like MCP and subagents, while the everyday moves nobody explains clearly
- It modified a bunch of files and you don't know what changed or how to check, so you don't dare commit; the session gets longer and longer and feels slow and expensive
When to use this approach
When you need to:
- Have AI directly read your project, edit files, run commands, and commit code in the terminal—instead of copying and pasting into a web chat box
- Hand off everyday dev work like fixing bugs, writing tests, refactoring, and generating commit messages with a single sentence
- Keep changes under control: see the plan first, then let it code, review after the changes, and roll back if unsatisfied
And you don't want to:
- Reopen a new tool and re-explain the project background every time you switch tasks
- Have AI quietly modify files without you knowing
- Get scared off before even trying the advanced features (MCP, Skills, subagents)—those will be covered in the advanced handbook
🎒 Preparation before starting
- Completed the previous lesson Installing Claude Code:
claude --versioncan print the version number, and you've completed the first login (choose either a subscription or a Console account; if installation failed, first go to What to do if installation fails) - A Claude subscription (Pro / Max / Ultra / Team / Enterprise) or a Console account—what the official requirements are for most forms; for prices of each tier see Pricing Comparison, and for regional policy facts see the callout in the installation lesson
- A practice project in a git repository (Step 5 of this lesson involves committing code; if you don't have a project yet, that's fine—Claude can help you build one from scratch)
- 15 minutes of uninterrupted time
💡 Haven't used the terminal much?
The official docs include a beginner's guide to the terminal, whose opening line is "Even if you've never used the terminal before, you can use Claude Code." The terminal is just a window where you "type → press Enter → execute"; every command in this lesson can be copied and pasted directly.
Core idea
Claude Code is the agentic coding tool in Anthropic's official documentation: it reads your codebase, edits files, runs commands, and plugs into your dev tools—not a chat box where "you paste code and it gives answers," but an agent where "you assign the work and it gets it done."
The fundamental difference from web-based AI chat:
| Web chat AI | Claude Code (terminal) | |
|---|---|---|
| Code into context | You manually copy and paste | It reads project files itself |
| Editing code | Gives you snippets, you paste them yourself | Edits files directly, viewable with /diff |
| Verification | You run commands yourself | It can run tests, read errors, and fix them itself |
| Committing | You write the commit yourself | One sentence has it write the commit message and open a PR |
Four forms, one engine. Claude Code comes in more than just the terminal form, and every form connects to the same underlying engine—your project's CLAUDE.md, settings, and MCP servers work across all forms:
| Form | One-line positioning |
|---|---|
| Terminal CLI (this lesson's main thread) | The most feature-complete main form: edit files, run commands, manage the whole project |
| VS Code / JetBrains plugins | Use it inside the editor: inline diffs, @ references, plan review, session history (the JetBrains plugin requires installing the CLI separately) |
| Desktop app | A standalone app beyond the IDE and terminal: visual diffs, multiple sessions side by side, scheduled tasks |
| Web version | Open claude.ai/code in a browser, no local install needed: run long tasks, parallel multitask |
There is just one principle for everyday use: you state clearly "what to do, where to do it, and what the result should look like," and Claude handles reading, editing, running, and verifying. If it goes off track, press Esc to interrupt; if it makes a wrong change, roll back; once a task is done, use /clear to clear the slate—this loop is the six steps of this lesson.
Follow along with me
Step 1: Enter the project directory and start a Claude Code session
Why: Claude Code works in the directory where you launch it—cd into the project first, and the files it reads will be this project's files.
cd /path/to/your/project
claudeYou should see: the prompt appears, with three pieces of information shown above it: version number, current model, and working directory. A newly opened terminal session starts in auto mode by default (routine operations execute directly, while risky actions go through a safety check first and anything that should be blocked gets blocked), and the default model on most subscriptions is Claude Opus 5.5.
An immediately useful entry point:
/helpYou should see: a list of available commands. Typing / brings up the command menu, and typing / plus a few letters filters it.
- Quick check: I can see the version number, model, and working directory above the prompt, and
/helplists the commands
Step 2: Claude Code core of this tutorial: how do you use it? Describe one task clearly, like assigning work
Why: the more specific your prompt, the fewer rounds of rework. The official best practices give a contrasting example—vaguely saying "fix the login bug" leaves Claude guessing; state the file, the symptom, and the criteria for "fixed", and it hits the target in one shot.
❌ Vague assignment:
fix the login bug✅ Specific assignment (verbatim from the official example):
users report login fails after the session times out. look at token refresh in src/auth/, write a failing test that reproduces it, then fix itHow to phrase a few common kinds of tasks (all from the official workflow guide):
| Task | What you say |
|---|---|
| Fix a bug | I'm seeing an error when I run npm test (paste the error message to it verbatim) |
| Write tests | write tests for the auth module, run them, and fix any failures |
| Understand the code | give me an overview of this codebase |
| Find code | find the files that handle user authentication |
You should see: Claude reads the files itself, lists the places to change, and then starts editing; when a command needs to be run for verification, it runs it on its own (for example, running that failing test from earlier to see it turn green).
💡 If you want the "full version," say so explicitly
The official best practices mention a phrase that still works well: be ambitious. Claude tends to produce the minimal version that "just barely meets the requirements"—if you want the full version that also handles edge cases and wires up the save flow properly, add this phrase to your prompt.
- Quick check: I assigned a specific task and watched Claude read files, edit files, and run commands on its own
Step 3: Use @ to feed files and directories into the conversation
Why: waiting for Claude to find files on its own takes time; @ references bring the contents of a specified file directly into the conversation, so it can work on that file right away.
Reference a single file (official example):
Explain the logic in @src/utils/auth.jsReference an entire directory (what you get is a file list, not the full contents):
What's the structure of @src/components?You should see: a path suggestion menu pops up when you type @; press Tab or Enter to accept the highlighted path, then press Enter to send; after sending, the file's contents enter the conversation and Claude's answer centers on that file.
Two limits to know (numbers from the official docs verbatim): a single file's contents enter the conversation with a default maximum of 25,000 tokens; text files larger than 256KB are not brought in automatically.
- Quick check: I referenced a file with
@and Claude's answer was clearly based on its contents
Step 4: For big changes, switch to plan mode first and review the plan before letting it act
Why: for some changes you want to see the plan before anything is written to disk. In plan mode, Claude only reads files and gives a plan, without modifying any files—until you approve.
Two ways to turn it on, pick either:
claude --permission-mode planOr press Shift+Tab during a session to cycle through permission modes.
You should see: ⏸ plan mode on appears in the status bar. Claude reads files and proposes a change plan, waiting for your review; it only starts editing after you approve.
Also remember the row of modes you cycle through with Shift+Tab: Manual (every step needs your sign-off) → acceptEdits (auto-accept edits) → plan (plan only, no action)—start with the default auto mode for everyday work, and switch to plan for big changes you're unsure about. The "plan first, then act" discipline applies to all AI coding tools; for more, see Plan First: Turning a One-Line Idea into a Requirements List.
- Quick check: I can recognize
⏸ plan mode onin the status bar and know that Claude won't modify files at this point
Step 5: Review changes with /diff, then have it commit or open a PR
Why: AI-written code should be reviewed before it goes into the repo. /diff lets you see all changes in your working tree without leaving the terminal—including what Claude just changed and your own uncommitted work.
Type in the session:
/diffYou should see: a list of changed files, each labeled with added/deleted line counts, followed by the actual diff. In the full-screen renderer it's a persistent panel (auto-refreshing each time Claude modifies a file); in the legacy renderer it's a dialog you close with Esc after viewing.
Once the review looks good, have it commit (official example):
commit my changes with a descriptive messageTo open a PR, follow up with:
create a prYou should see: Claude operates git directly—staging changes, writing the commit message, creating a branch, opening a PR; once the PR is open it gives you the link. It integrates with git natively, so you don't need to type a single git command for these steps.
- Quick check: I reviewed the changes with
/diffand had Claude complete a commit or a PR
Step 6: Wrapping up a session—interrupt, clear, resume
Why: session management determines whether you'll "want to open it again the next day." Four actions cover the most common wrap-up scenarios:
| Scenario | Action | Effect |
|---|---|---|
| Claude goes off track | Press Esc | Interrupt immediately, keep the completed work, and redirect it yourself |
| Want to roll back a few steps | Press Esc twice with empty input | Open the rewind menu to restore the code, the conversation, or both to an earlier point |
| Switch to an unrelated task | /clear | Clear the context and start fresh—official advice: if correcting the same thing twice still doesn't work, /clear and rewrite your prompt instead of a third attempt |
| Pick it up again tomorrow | Run claude --continue after exiting | Resumes the most recent session in the current directory; claude --resume to pick from a list |
You should see: claude --continue comes back with the previous conversation context intact (if there's no session in the current directory yet, it prints No conversation found to continue and exits—in that case, just use claude to start a new session).
💡 Give long tasks a named session
Run /rename <名字> in the session (the official example uses /rename oauth-migration); afterwards you can find it precisely from the terminal with claude --resume <名字>, and the rewind points are preserved too.
- Quick check: I have interrupted Claude once with
Escand successfully resumed a session withclaude --continue
Checkpoint ✅
- I can launch Claude Code in a project directory and recognize the version, model, and working directory shown above the prompt
- I assign specific tasks: stating the file, the symptom, and the criteria for "fixed," rather than just saying "help me fix a bug"
- I use
@to reference files,/to open the command menu, and!to run shell commands directly (e.g.,! npm test; the output goes into the conversation and Claude responds automatically) - For big changes, I turn on plan mode before starting (
claude --permission-mode planorShift+Tab), and only relax once I see⏸ plan mode on - I review changes with
/diffbefore letting it commit; for sessions I useEscto interrupt,/clearto clear, andclaude --continueto continue
Pitfall reminders
❌ A one-liner is too vague—ten rounds of back-and-forth and still off target
Task assignments like "optimize this project" or "fix this bug" leave Claude guessing. The official best practice puts it this way: replace "fix the login bug" with "Users report login fails after a session timeout; look at token refresh in src/auth/, first write a failing test that reproduces it, then fix it"—with the file, the symptom, and the acceptance criteria all provided, it usually hits the mark in one round.
❌ I have no idea what it changed, and it committed right away
An AI change is not the same as a correct change. The right order: /diff review → only let it commit once you're satisfied. Two extra safeguards: first, manage your project with git—the official docs state plainly that rollback points (checkpoints) only cover files Claude modified with file tools, and files touched only via Bash commands are outside the restore scope, so git is the safety net; second, turn on plan mode for big changes and review the plan before anything is written to disk.
❌ Piling three unrelated tasks into one session makes it slower and more expensive as the conversation grows
The official cost guide explains it: every request is sent with the entire conversation—you're sending the history of all three tasks into the fourth round. The right approach: when switching tasks, use /clear, which costs nothing; when a long session needs key points preserved, use /compact with a one-line note of what to focus on (e.g., /compact keep the API changes and the test commands).
❌ Idly waiting while Claude works, or repeatedly hitting Enter to interrupt it
While it's working, you can keep typing your next message directly—Claude Code queues the message and processes it in order after the current turn finishes (press Ctrl+Enter to send the queue immediately). Only use Esc to interrupt when you need to change direction; interrupting doesn't lose work—everything already completed is preserved.
Advanced tips (optional)
Leave a "manual" for your project. Put a CLAUDE.md in the project root with your verification commands, conventions, and pitfalls—Claude Code reads it at the start of every session. Running /init in a session generates a first draft from the codebase, and /context confirms whether it's loaded. For a detailed guide on how to write it, see AGENTS.md and CLAUDE.md: leaving a project manual for AI.
Hand tasks that are too slow for it to investigate itself to subagents. Exploring a large codebase fills up the main conversation's context, and the official recommendation is to delegate investigative work:
use a subagent to investigate how our auth system handles token refreshSubagents read files in their own context window and bring back only the conclusions.
Run two sessions in parallel without stepping on each other. Use git worktree to give each session its own checkout:
claude --worktree feature-authRun it again in a second terminal with a different name, and you have isolated parallel sessions (the repository needs at least one commit).
Treat Claude Code as a Unix tool. Pipe in and out—great for batch processing and CI:
git log --oneline -20 | claude -p "summarize these recent commits"Watch usage, tune effort. Use /usage in a session to see where usage went—subscription plans (Pro/Max/Ultra/Team/Enterprise) break it down by skills, subagents, plugins, and MCP servers; /effort high makes it think harder (tricky bugs), /effort low makes it produce drafts faster (while you review step by step alongside).
Pasting images works too. Paste a screenshot of an error directly with Ctrl+V (use Alt+V on Windows/WSL), or drag it into the window, then ask Here's a screenshot of the error. What's causing it?.
Lesson summary
✅ Claude Code tutorial's daily workflow = cd into the directory and launch → assign specific tasks → @ feed files → plan mode for big changes → /diff review then commit → Esc//clear/--continue wrap up. Once these six steps are turning, it's an on-demand coding agent in your terminal.
✅ It's an agent, not a chat box: it reads the codebase, edits files, runs commands, and operates git itself—you're responsible for stating clearly "what to do, where, and to what standard."
✅ Four forms, one engine: terminal CLI (this lesson), VS Code/JetBrains extensions, desktop app, and web version claude.ai/code; CLAUDE.md, settings, and MCP work across all forms.
✅ A three-part controllability kit: auto mode intercepts risky operations, plan mode reviews the plan first, and /diff + git as the fallback for rollback.
✅ Prompt essentials: file + symptom + acceptance criteria; add be ambitious for the full version; if two corrections don't work, /clear and rewrite.
Key operations recap:
| Operation | How | Notes |
|---|---|---|
| Start a session | cd 项目目录 then run claude | Version/model/working directory shown above the prompt |
| Assign a task | Just type the task description | State the file, symptom, and acceptance criteria |
| Feed a file | @src/utils/auth.js | Single files ≤25,000 tokens by default enter the conversation |
| Run a command | ! npm test | Output goes into the conversation; Claude responds automatically |
| Turn on plan mode | claude --permission-mode plan or Shift+Tab | Status bar shows ⏸ plan mode on |
| Review changes | /diff | Lists changed files and added/removed lines |
| Commit/open a PR | commit my changes with a descriptive message / create a pr | It operates git directly |
| Resume a session | claude --continue (most recent) / claude --resume (pick one) | Prints No conversation found to continue when there's no session |
Next lesson preview
Once you're comfortable with Claude Code, the next lesson covers the OpenAI camp's counterpart tool: Codex usage: OpenAI's local coding agent.
You will learn:
- What Codex is: its official positioning as "a coding agent that runs locally on your computer," and how its agent approach compares to Claude Code's
- The process of signing in to the Codex CLI with a ChatGPT account (after
codex, choose Sign in with ChatGPT) - Codex in four forms: CLI, IDE extension, desktop
codex app, and web version - How to choose between the two tools and how to use them together — see the full pricing table at price comparison