Claude Code: Run an AI Coding Agent from Your Terminal to Automate Development and Refactor Large Projects

AI tutorial - IT technology blog
AI tutorial - IT technology blog

The Problem with AI Coding Tools Today

Most AI coding assistants live inside your IDE as a sidebar chat. You paste code in, read the suggestion, copy it back. That back-and-forth is fine for a 20-line function, but it completely falls apart when you need to refactor a 40-file Python package, migrate a legacy API, or write tests for code that was never designed with testing in mind.

The root cause is that these tools assist — they don’t act. They give you text, and you do the rest.

Claude Code is different. It runs in your terminal, reads your actual files, executes shell commands, and iterates on its own work until the task is done.

In my real-world experience, this is one of the essential skills to master if you want to get serious leverage from AI in software development. Once you’ve used an agentic tool that can read a 10,000-line codebase and make targeted edits across dozens of files, going back to a sidebar chat feels like using a calculator when you need a spreadsheet.

Quick Start: Up and Running in 5 Minutes

Claude Code requires Node.js 18+ and an Anthropic account. Install it globally via npm:

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

Once installed, navigate to any project directory and start a session:

cd ~/my-project
claude

On first run, it asks for your Anthropic API key (or you can authenticate with your Claude.ai Max subscription via OAuth). After that, you get an interactive prompt inside your project:

✓ Connected to Claude (claude-sonnet-4-6)
~/my-project $ 

Try a simple task immediately to verify everything works:

> Explain what this project does and list the main modules

Claude Code reads your files — README.md, package.json, pyproject.toml, or whatever it finds — and gives you a structured summary. No copy-pasting needed. That alone saves several minutes on any unfamiliar codebase.

To run a one-off task without entering interactive mode, use the -p flag:

claude -p "List all TODO comments in the src/ directory"

Deep Dive: How Claude Code Actually Works

It Has Tools, Not Just Text

Unlike a chat interface, Claude Code has access to a set of tools it can call autonomously:

  • Read — read any file in your project
  • Edit / Write — make precise string replacements or write new files
  • Bash — execute shell commands (grep, pytest, git diff, etc.)
  • Glob — search files by pattern
  • Grep — search file contents by regex

When you give it a task, it plans which tools to call, executes them, reads the output, and decides what to do next — all in a loop until the task is complete or it needs your input.

The Permission Model

By default, Claude Code asks your permission before running shell commands or writing to files. This is intentional — you stay in control of what actually gets executed. You can run with --dangerously-skip-permissions if you want fully autonomous operation on a task you trust, but I’d recommend keeping the default for anything touching production code.

# Default: asks permission for each write/bash call
claude

# Autonomous mode (use carefully)
claude --dangerously-skip-permissions -p "Add docstrings to all public functions in src/"

Context and Memory

Claude Code reads a CLAUDE.md file from your project root if one exists. This is your persistent instruction layer — project-specific rules, coding conventions, file structure notes, anything you want Claude Code to remember across sessions.

# Generate a CLAUDE.md automatically
claude /init

Running /init prompts Claude Code to explore your project and write a CLAUDE.md that summarizes the architecture, key files, and conventions it observed. Edit it after to add your own rules.

Advanced Usage: Refactoring Large Projects

Renaming and Restructuring Across Multiple Files

This is where Claude Code earns its keep. Suppose you need to rename a function that’s called in 25 different files, and several of those call sites need slightly different adjustments due to changed argument order. Manual search-and-replace breaks things. Claude Code handles it:

> Rename `process_data()` to `transform_records()`. The new signature takes `(records, schema, strict=False)` instead of `(data, schema)`. Update all call sites accordingly and run the tests to verify nothing broke.

It will grep for all call sites, make targeted edits, then run your test suite — and if tests fail, it reads the error output and tries to fix the remaining issues.

Writing Tests for Untested Code

> Look at src/billing/invoice.py. Write pytest unit tests for every public method. Use mocks for the database calls. Place the tests in tests/billing/test_invoice.py and make sure they all pass.

Claude Code reads the source file, identifies the methods, writes the test file, runs pytest, reads the failures, and iterates. For a 300-line module, this takes under two minutes.

Migrating Dependencies

Upgrading a major dependency (say, moving from requests to httpx for async support) used to mean an afternoon of search-and-replace followed by debugging subtle behavioral differences. With Claude Code:

> Migrate all HTTP calls in this project from `requests` to `httpx`. Use async/await where the calling function is already async, and sync calls elsewhere. Update requirements.txt. Run the tests after.

Git Integration

Claude Code can read git history, check diffs, and create commits. This is useful for generating commit messages that actually describe the change:

> Look at the staged changes and write a commit message in conventional commit format

Or for understanding a codebase you just cloned:

> Look at the last 20 commits and summarize what the team has been working on

Practical Tips That Actually Matter

Be Specific About Scope

Vague tasks produce vague results. Instead of “improve the code quality”, say “find functions longer than 50 lines in src/api/ and break them into smaller functions. Keep existing behavior, don’t change the public API.” The more constraints you give, the more precise the output.

Use CLAUDE.md Aggressively

Add your project’s conventions to CLAUDE.md early. Things like:

  • Which test runner to use and how to run it
  • Coding style rules that aren’t obvious from the code itself
  • Files or directories that should never be touched
  • Deployment notes

Every session inherits these rules automatically. This saves you from re-explaining context every time.

Break Large Tasks Into Phases

For anything that touches more than ~20 files, break it into chunks. Claude Code has a context window, and very large tasks can lose coherence near the end. Something like:

  1. First pass: “Add type hints to all functions in src/models/”
  2. Second pass: “Now do src/services/”
  3. Third pass: “Run mypy and fix the type errors”

Review Before You Accept

When Claude Code writes to a file, it shows you exactly what changed. Read it. AI tools make confident mistakes — a renamed variable might be correct in 24 out of 25 places and wrong in the 25th. The permission prompt exists for a reason: use it to actually check the diff before approving.

Combine with CI for Even More Leverage

You can call Claude Code non-interactively in scripts, which opens up automation possibilities:

# In a Makefile or shell script
claude --dangerously-skip-permissions -p \
  "Check if there are any obvious bugs in the files changed in the last commit. Output a JSON list of findings." \
  --output-format json

Pipe the output to a linter, a notification system, or a pre-commit hook. It won’t replace your CI pipeline, but it adds a layer of AI review that catches things static analysis misses.

Pricing and What You Actually Need

Claude Code uses the Anthropic API, which means you pay per token. A typical interactive session for a medium-sized refactoring task costs roughly $0.50–$2.00 depending on codebase size and how many iterations are needed. Heavy daily use adds up, so it’s worth checking your Anthropic dashboard occasionally.

If you have a Claude.ai Max subscription ($100/month), you can authenticate with OAuth and use Claude Code with higher rate limits included in your plan — no separate API billing. For teams doing large-scale use, this is usually the more cost-effective path.

The practical threshold: if you’re spending more than an hour a day on mechanical coding tasks — search-and-replace refactors, writing boilerplate tests, documenting existing code — Claude Code pays for itself quickly.

Share: