Claude Code AI Agent Hands-On Tutorial: Make It Run Tasks, Not Just Answer Questions

What This Guide Will Help You Accomplish

Claude Code is an entirely different beast from opening Claude in your browser. It's a CLI tool Anthropic launched in early 2026, designed specifically to let Claude operate as an agent within your local environment — reading your code, running commands, modifying files, and integrating with tools, rather than simply outputting text for you to copy and paste manually.

The goal of this guide is straightforward: once you've worked through it, you'll have a Claude Code Agent environment capable of executing multi-step tasks. You'll understand how to design task prompts, how to let it use tools, and how to control what it can and cannot touch.

If you've previously read Running Automated Tasks with Claude AI Agent: A Hands-On Tutorial from Scratch, that piece covers concepts and browser-side operations. This guide is the Claude Code CLI counterpart, oriented toward development workflows.

---

Prerequisites: What You'll Need

• Node.js 18+ (verify with node -v)
• Anthropic API Key (grab one from console.anthropic.com — there's a free tier for testing)
• A terminal (native on macOS/Linux; WSL2 is the path of least resistance on Windows)
• Basic CLI familiarity — no need to be a Bash expert

Installation is straightforward:

npm install -g @anthropic-ai/claude-code

Once installed, configure your API key:

export ANTHROPIC_API_KEY="sk-ant-..."

It's worth adding this to your ~/.zshrc or ~/.bashrc — otherwise you'll be resetting it every time you open a new terminal session.

---

Step 1: Run Your First Hello World to Confirm the Environment Is Working

claude "List all .py files in this directory and describe what each one does"

If you see Claude actually read your directory and return descriptions, congratulations — your base environment is good to go.

In plain terms: Claude Code comes with several tools by default — file reading, file writing, shell command execution, and code search. The sentence you typed is the prompt; Claude decides on its own which tools to use, how many times, and how to combine the results. That's the fundamental difference between an agent and a standard Q&A interaction.

---

Step 2: Design an Agent Task That's Actually Useful

Agents shine in scenarios involving multi-step work, file read/write operations, or tasks where you need to run commands and verify results. Some concrete examples:

• "Scan all TODO comments across this repo and compile them into a markdown list saved to TODO.md"
• "Read requirements.txt, identify packages with known security vulnerabilities (cross-referencing pip audit output), and update affected version numbers to the latest stable releases"
• "Run the test suite; for any failures, locate the corresponding functions, attempt a fix, then run the tests again to confirm they pass"

What these tasks share: a clear starting point, decision-making steps in the middle, and a verifiable endpoint. Think of it as writing a work brief for a junior engineer — the clearer and more bounded it is, the more predictable the outcome.

---

Step 3: Use --allowedTools to Control What the Agent Can Access

Claude Code's default toolset is broad, including file writing and shell execution. In production environments or situations where you want to reduce risk, you can restrict this:

claude --allowedTools "Read,Grep,Bash" "Analyze whether function naming in src/ conforms to PEP8"

This limits the agent to reading, searching, and running Bash — it cannot directly modify your files. This is ideal for "analyze but don't touch my code" scenarios.

For the complete list of tool names, check the official documentation. Commonly used ones include: Read, Write, Edit, Bash, Grep, and WebSearch.

---

Step 4: Use CLAUDE.md to Give the Agent Persistent Instructions

This is a feature many people miss when they first start using Claude Code. Place a CLAUDE.md file in your project's root directory, write your repo conventions and context inside it, and Claude Code will read it every time it starts.

Example content:

# Rules for This Repo

- Language: Python 3.11+
- Test framework: pytest; run tests with `pytest tests/`
- Do not modify `config/prod.yaml`
- Commit message format: prefix with `feat:` / `fix:` / `chore:`
- All new functions must include type hints

With this in place, you won't need to re-explain the context every time you issue a task — the agent will follow these rules on its own. Think of it as an onboarding document for your new hire.

---

Step 5: Chain Multi-Step Tasks (Non-Interactive Mode)

If you want to integrate Claude Code into a CI pipeline or script, use the --print flag to output results directly without entering interactive mode:

claude --print "Check src/ for any modules that are never imported and list the filenames" > unused_modules.txt

This output can be piped directly to other tools or saved to a file for use in subsequent steps. How to Use Claude AI Agent: A Hands-On Guide from Chat Mode to Automated Task Execution covers the architectural thinking behind agent mode in more depth — worth reading alongside this guide.

---

Common Mistakes and How to Avoid Them

1. Vague prompts that cause the agent to go off-track A prompt like "help me optimize this repo" is effectively meaningless to an agent. Be specific: "Identify functions in api/ with response times exceeding 200ms and add a caching decorator."

2. Skipping CLAUDE.md and then blaming the agent for not knowing your conventions Agents aren't mind readers. Your code style rules need to be written down explicitly.

3. Running directly in a directory with production data Always test in a staging environment or on a git branch first. Confirm the behavior is what you expect before moving to production. Claude Code's Edit and Write tools make real changes to your files — there is no undo button.

4. Not watching API costs A single agent task can involve many rounds of tool calls, consuming significantly more tokens than a one-shot conversation. It's worth testing your workflow with the Haiku model first (--model claude-haiku-4-5), then switching to Sonnet or Opus once the logic is confirmed.

---

Advanced Technique: Custom Tools

Claude Code supports defining your own tools, enabling the agent to call your internal APIs or scripts. Describe the tool's behavior in CLAUDE.md, then handle the corresponding tool calls in your script.

This enters the territory of MCP (Model Context Protocol) — in plain terms, a standard way to tell Claude "I can call this function, and it will return data in XX format." Anthropic standardized MCP in 2026, and there are now a good number of pre-built MCP servers available (GitHub, Notion, and Slack all have them), so you don't have to build everything from scratch.

---

After You're Done: Confirming Everything Is Actually Running

A quick checklist:

• claude --version outputs a version number
• Ran a read-only task to confirm the agent uses tools correctly
• CLAUDE.md exists in the project root
• Tested --allowedTools to restrict the tool scope
• Completed at least one real multi-step task

From here, consider integrating Claude Code into your CI pipeline or experimenting with MCP servers to expand the data sources it can interact with. The genuinely interesting part of the agent paradigm isn't how complex a task you can throw at it — it's your ability to design clear task boundaries. That's what ultimately determines whether the results are any good.

Frequently Asked Questions

What's the difference between Claude Code and using Claude on the web?

Claude Code is a CLI tool that runs on your local machine. It can directly read and write your files and execute shell commands — it's a true agent. The web version of Claude is conversational only; you still have to copy its output and execute it yourself. The two are suited to entirely different use cases.

Does Claude Code consume a lot of API credits?

Agent mode does consume more tokens than single-turn conversations, since it may run many rounds of tool calls. The recommended approach is to test your task flow with the claude-haiku model first to confirm the logic is correct, then switch to Sonnet or Opus for production work. This keeps costs meaningfully lower.

Is CLAUDE.md mandatory?

Not required, but strongly recommended. Without it, you'll find yourself re-explaining your code style, off-limits files, test commands, and other context every single time you issue a task. With it, Claude Code reads all of that automatically on startup — effectively a persistent project brief for your agent.

Can Claude Code run on Windows?

Yes, but running it through WSL2 (Windows Subsystem for Linux) is recommended. Bash tooling and path handling will both behave more predictably that way. Technically it can run in native Windows CMD or PowerShell, but the likelihood of running into odd edge cases is higher.

How do I prevent Claude Code from touching important files?

Two approaches: first, explicitly state in CLAUDE.md that certain files — like config/prod.yaml — must not be modified; second, use --allowedTools to exclude the Write and Edit tools entirely, leaving the agent in a read-only state. You can combine both approaches for stronger guarantees.