TL;DR

A single AI agent handles tasks one at a time.

An agent team runs multiple agents simultaneously, each owning a lane, then merges their outputs.

I built one for a reader who spends about 45 minutes every day compiling timesheets from emails and work files.

Three agents. Twenty-nine seconds. Zero minutes of their time.

Here’s exactly how it works and how to set it up yourself.

PS: If you missed Part 1 and Part 2 of this Claude Code series, you can read No-BS Claude Code - Part 1: Tokens, Context Management & CLAUDE.md and No-BS Claude Code - Part 2: Subagents Explained

Merhaba👋🏻

I am a Software Engineer with 10+ years of experience. My goal is to close the gap between the technical and the non-technical, making AI accessible to everyone, regardless of their background.

Subscribe now

One of my subscribers emailed me earlier:

When I read this email, I immediately thought that this would be a perfect use case for my Claude Code Agent Teams article!

Not because it’s complex. Because it’s parallel. Their emails and their work notes have nothing to do with each other. They’re two completely independent sources of truth that need to be read, summarized, and merged into one output. There’s no reason to process one before the other.

And that distinction; sequential vs. parallel, is the whole point of this article.

Claude Code Subagents vs Agent Teams: The Key Difference

If you’ve read Part 2 of this series, you already know subagents.

A subagent is a single AI agent that handles one task at a time. You can create many subagents with different set of skill set, and they report back to the main agent.

However, in Agent Teams, all of the agents can share a task list, work in dependently, and communicate with each other.

What Are Claude Code Agent Teams (And Why They're Faster)

Agent teams are multiple AI agents working in parallel, each owning a specific task, whose outputs are combined by an orchestrator to produce a result none of them could produce alone.

They are useful when a single AI isn’t enough; not because it lacks intelligence, but because it lacks time. Instead of one agent doing everything sequentially, a team of specialized agents works simultaneously. Each owns a lane. An orchestrator waits for all of them, then hands their combined output to the next stage. The magic isn’t in any individual agent. It’s in the handoff.

💡 Use subagents when you need to complete individual tasks, and use agent teams when you need your agents interact with other. Be aware that token costs are higher with agent teams, which means they are more expensive than subagents.

Share

How to Enable Claude Code Agent Teams (Experimental Setup)

Agent teams are experimental feature and they are disabled by default. You need to enable them by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in ~/.claude/settings.json file:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

💡 I won’t go into more detail on how to enable agent teams, but you can take a look at Claude’s documentation for more details.

Real Use Case: Automate Daily Timesheets with 3 Parallel AI Agents

Let me bring this back to the real problem.

My subscriber had two separate worlds of data: their Inbox and their OneDrive.

In a traditional setup, an AI would tackle these like a human does: one after the other. It’s a bottleneck. There's no reason to read one before the other. A sequential agent would scan emails first, then scan files, then write the summary. An agent team reads both at the same time.

So I built three agents:

• EmailReaderAgent

• FileReaderAgent

• WriterAgent

The two readers run in parallel. The writer only starts when both are done.

Total processing time: 29 seconds. My subscriber’s time: 0 minutes.

That’s 30–45 minutes of daily drudgery gone.

How the Three Agents Communicate and Hand Off Work

Before I show you how to set this up, let me explain how the three agents actually talk to each other. This is the part that makes agent teams different from just running three separate prompts.

The EmailReaderAgent: This agent gets one job. Scan today’s emails. Extract any mentions of tasks completed, client interactions, deliverables sent, meetings attended. Output a clean, structured list. Nothing more.

The FileReaderAgent: Same idea, different source. Scan recent files and work notes. Extract what was worked on, what was edited, what was created. Output a clean, structured list. Nothing more.

The WriterAgent: This is the “merger”. It receives the output from both readers and produces two things: a client billing summary (grouped by client, with time estimates) and an admin timesheet (lists all work entries).

Subscribe now

Step-by-Step: Build Your First Claude Code Agent Team

Step 1: Create folders and files

We will start by creating folders and files to kick off this demo.

That’s your ClaudeAgentTeams folder structure in tree format. It maps exactly to what you uploaded, just expanded with the full multi-agent setup:

• CLAUDE.md is your main orchestrator at the root of timesheet-agent/

• subagents/ contains three worker definitions

• emails/ and work_notes/ contain your emails and work related notes

• output/ is where results go

💡 You could potentially connect to emails or notes on OneDrive folder via MCP (Model Context Protocol), but I wanted to skip it to keep this article simpler.

(Optional) Install tmux

I’ve installed tmux to visualize how agent teams work in practice. It lets you see each agent running in its own pane, side by side, in real time. You can watch the EmailReader and FileReader working simultaneously while the Writer pane sits idle, waiting. Then the Writer lights up once both inputs arrive.

It’s not required. But if you want to actually see the parallelism happening, tmux makes it tangible.

If you are using MAC, you can install tmux by running this command in your terminal:

brew install tmux

Then, start a new session:

tmux new-session -s agents

If you are not familiar with tmux and its commands, Claude is your friend. Ask it how to split your terminal into 4 pane layout.

Step 2: CLAUDE.md

Here is the actual CLAUDE.md file I have used:

# Timesheet Agent — Orchestrator

You are Asli's timesheet automation assistant. Your job is to gather all work activity from emails and notes, then produce clean billing and timesheet documents.

## Workflow

### Step 1 — Parallel data collection

Spawn two agents **at the same time** using the Task tool (both in the same message, do not wait for one before starting the other):

1. **EmailReaderAgent** — reads `emails/` directory using instructions in `subagents/email-reader.md`
2. **FileReaderAgent** — reads `work_notes/` directory using instructions in `subagents/file-reader.md`

### Step 2 — Wait for both

Wait until both agents have returned their structured summaries. Do not proceed until you have output from both.

### Step 3 — Hand off to WriterAgent

Spawn **WriterAgent** using instructions in `subagents/writer.md`. Pass it the full text output from both reader agents. WriterAgent will produce:

- `output/billing.md` — grouped by client, hours, descriptions
- `output/timesheet.md` — chronological, admin-friendly

## Rules

- Always run EmailReaderAgent and FileReaderAgent in parallel, never sequentially.
- After WriterAgent completes, confirm to the user that both files have been written and print the path to each.

Step 3: Agents Team

This is where you define the team.

Your CLAUDE.md spawns EmailReaderAgent and FileReaderAgent in parallel and passes their combined output to Writer:

# Timesheet Agent Team

## Agent: EmailReader
Role: Read today's emails and extract a structured list of tasks, meetings, and client interactions.
Output format: Bullet list grouped by client, with estimated time per task.

## Agent: FileReader
Role: Read recent work files and notes, extract a structured list of deliverables worked on.
Output format: Bullet list grouped by client, with estimated time per task.

## Agent: Writer
Depends on: EmailReader, FileReader
Role: Merge the outputs from both agents. Produce two documents:
1. Client billing summary (grouped by client, with total hours)
2. Admin timesheet (formatted as [your timesheet format])
Tone: Professional, concise, ready to paste directly into billing system.

The "Depends on" line is what makes this a team instead of three separate agents. It tells Claude Code: don't start the Writer until EmailReader and FileReader have both delivered their outputs.

Step 4: Action

If you have installed tmux, you can split your terminal layout. Here is how my terminal looks like:

Top-left: Shows running Claude Code session.

Top-right: Keeps track of output folder. Currently, it is empty.

Bottom-left: Waiting for billing file to be created.

Bottom-right: Waiting for timesheet file to be created.

Four panes. Three agents standing by. Output folder is empty. This is what it looks like right before you type the prompt.

In top-left session, run this command:

run the timesheet agent team

I typed “run the timesheet agent team” and hit enter.

Look at what happened in the top-left pane immediately:

“I’ll read the subagent instruction files first, then spawn both reader agents in parallel. Spawning both reader agents in parallel now.”

The agents didn’t queue up. They didn’t take turns. They swarmed; both launched at the same instant, each heading toward their own source.

In couple of seconds, two agents woke up simultaneously. One started reading emails. The other started reading work notes. Neither waited for the other. They just worked, in parallel, like two colleagues opening different files on the same morning.

By the time you’d have opened your first email manually, both were already done.

This is the “after” state. Everything is done.

Top-left: the orchestrator’s complete log. Read it top to bottom and you get the whole story: agents launched in parallel, both finished, writer took over, both files delivered. “Churned for 29s”. Less than half a minute.

Top-right: the output folder, live. Two files just appeared: billing.md and timesheet.md. They weren’t there 29 seconds ago. Now they are.

Bottom-left: the billing summary. Grouped by client. Hours tallied. Descriptions written. Bright Agency, Nova Health, Internal/Admin. Grand total: 7.5h. Ready to send.

Bottom-right: the timesheet. Chronological, clean, professional. Morning through EOD. Every task, every hour, every client. Ready to submit.

The story this screenshot tells:

One prompt. Three agents. 29 seconds. This is how you can save 45 min a day.

Subscribe now

💡 You can generate billing or timesheet files however you like. Billing file can be .txt and timesheet file can be in excel format.

Here is how billing file looks like:

BILLING SUMMARY — May 3, 2026

BRIGHT AGENCY

2.0h  Revised landing page copy — trimmed subhead, updated CTA, flagged mobile layout issue to dev
0.5h  Q3 campaign kick-off call recap — scope: messaging framework and 3 content formats by May 20
Total: 2.5h

NOVA HEALTH

2.0h  Investigated and patched 504 errors on patient records endpoint — fixed exhausted DB connection pool
3.0h  Set up staging environment for new patient intake form — cloned schema, ran smoke tests, fixed validation issues
Total: 5.0h

INTERNAL / ADMIN

0.5h  April invoicing wrap-up — prepared and sent invoices for Bright Agency and Nova Health
Total: 0.5h

And timesheet file (generated in .xlsx format):

Build Your Own AI Agent Team in One Sitting

Here’s a simplified version you can set up in one sitting, even if your workflow is different from my subscriber’s:

1. Identify two independent sources of information you regularly combine by hand. Could be emails + notes, Slack messages + project docs, calendar + task list.

2. Enable agent teams in your Claude Code settings.json using the config block above.

3. Write a CLAUDE.md with three agents: two readers (one per source) and one writer that depends on both. Use the template above as your starting point.

4. Define the output format for each reader agent. Be specific. “Bullet list grouped by client” is better than “summarize what I worked on”.

5. Define the final output for the writer agent. What does the merged document actually look like? If you have an existing timesheet template, paste an example into the writer agent’s instructions.

6. Run it. Review the output. Tweak the agent instructions based on what’s missing or messy.

The whole setup takes maybe 20 minutes the first time. After that, it’s a single command.

Which part clicked for you? Or which part still feels fuzzy? Drop it below; your question might be the next article!

Leave a comment

PS: If you're new here and wondering why a software engineer is writing about all this - here's why I started Becoming with AI."

TL;DR

• Subagents = temporary specialists: they handle a specific job in their own context window, so your main conversation stays clean and focused

• Set them up with /agents: point them at a task and let them work independently

• Three practical use cases: researching unfamiliar code, reviewing your work, and handling design file analysis

• Model routing matters: use Haiku for simple tasks, Opus for heavy planning (your biggest lever on AI spending)

• If Part 1 taught you to keep your desk clean, Part 2 teaches you to hire someone to clean it for you

PS: If you missed Part 1, you can read No-BS Claude Code - Part 1: Tokens, Context Management & CLAUDE.md

Merhaba 👋🏻

I am a Software Engineer with 10+ years of experience. My goal is to close the gap between the technical and the non-technical, making AI accessible to everyone, regardless of their background.

Subscribe now

So, you’ve got the hang of using Claude Code like a pro. You know how to keep your workspace tidy, keep the conversation on track, and run /compact command before AI gives you vague responses or hallucinates.

That’s already a solid foundation.

In Part 2, we're going deeper into Claude Code subagents, and how they let you delegate like you've got a whole team.

But let’s be real: even the most organized desk in the world gets buried if you’re trying to do everything yourself. At some point, the secret to staying productive isn’t just better organization, it’s delegation.

That’s where subagents come in.

Think of a subagent as a temporary specialist you hire for a very specific gig. Instead of cluttering up your main workspace with side quests, you give them a job description, point them toward a task, and let them work in their own “room” (a separate context window). You can use Haiku model for simpler tasks like summarizing a file subagent or Opus model for planning subagent.

💡 Choosing the right model for the right task is one of the most important things you can do for your AI spending budget.

Why Claude Code Subagents Change the Way You Work

Think of this as the difference between a messy office space and a high-level executive suite.

When you use a standard AI, it’s like having a conversation with someone who is constantly digging through a mountain of messy paperwork right in front of you. Every time they find a scrap of info, they throw it on the desk. Eventually, the desk is so buried that you both forget what you were originally trying to do.

Here is the “smart person’s guide” to why this new way of working is a breakthrough:

1. Context Window Isolation: Protecting Your AI's Mental Bandwidth

AI has a limited “short-term memory” (meaning Context Window).

• The Old Way: If the AI has to read 50 pages of manuals to answer one question, those 50 pages stay “cluttering up” its memory. This makes the AI slower, more confused, and much more expensive to run because you’re paying for it to “remember” all that junk every time you send a new message.

• The New Way: You send a “researcher” into a separate room to read the 50 pages. They come back and give you a one-paragraph summary. Your “desk” stays clean, and the AI stays sharp.

2. Deep Dives vs. Big Picture: Delegate the Grunt Work

Imagine you are a Software Team Lead. You don’t want to spend three hours manually checking every single file for a minor bug or a missing semicolon; you want to focus on the system design and ensure your new features actually scale.

• In this setup, you stay in The Big Picture.

• You delegate the “grunt work” (researching obscure code, hunting for a specific typo, or reading dense documentation) to a Subagent.

• They do the heavy lifting in the background while you continue thinking about the next three steps of your project.

3. Token Costs: Pay for the Signal, Not the Noise

In the AI world, you pay for every word the AI processes.

• If your conversation is 100 pages long because of all the “messy research”, you are paying a premium for that 100 page history every single time you hit enter.

• By “outsourcing the chaos”, you keep your main conversation short and sweet. You’re only paying for the answers, not the hours of “thinking out loud” it took to get there.

4. The No-Distraction Workflow: Results Without the Mess

If you’ve ever been “in the zone” only to be interrupted by a technical error, you know how hard it is to get back into the flow.

• This system acts like a filter. The subagent handles the errors, the “how-to” questions, and the trial-and-error in a separate “sandbox”.

• It only brings back the “clean” result. You never have to see the sausage being made; you just get the sandwich.

The Bottom Line: It’s about leverage. Instead of you doing the work with an AI, you are now delegating tasks to a skilled workers. You are the CEO, and you finally have a Research Department that handles the mess so you can stay focused on the vision.

Subscribe now

The Built-In Subagents Claude Code Ships With

Here’s a little secret: Claude Code is already running a small team for you under the hood.

Here are the three “employees” already on your payroll:

• Explore - The Scout: This one is fast and light (it runs on Haiku). It’s strictly read-only, meaning it can look but it can’t touch. Claude sends the Scout out to map your codebase or search for files so your main session stays focused on the big picture.

• Plan - The Strategist: This is the engine behind /plan mode. When you ask for a proposal, this agent does the deep-dive research into your project’s architecture. Because it works in its own space, it can “think” through complex problems without blowing up your main context window with all that brainstorming noise.

• General purpose - The Specialist: This one has the keys to the kingdom. It has access to all the tools and can both read and edit files. Claude calls in the Specialist when a job is too messy or multi-layered for a quick fix and requires a “boots on the ground” approach.

• Claude Code Guide: You can ask anything about Claude Code to this subagent

How to Run a Subagent in Claude Code (Step by Step)

You need to start a claude session by typing claude in your terminal. Make sure you are in the right folder. After that, you can just call subagent like this:

use claude-code-guide subagent to tell me how can i create a subagent from my terminal

This is pretty much what you would get as a response:

💡 If you ever forget what you’ve built, just run /agents and hit “List”. It’s like checking your team directory to see who’s available to take a load off your plate.

How to Create Your Own Claude Code Subagent

Setting this up is surprisingly low-friction. You don’t need to be a configuration wizard; it’s all built right into the interface.

Here is the quick-start version if you want to try it today:

1. Open your terminal and fire up Claude Code by typing claude.

2. Run the /agents command.

3. Select “Create.” Claude will basically interview you. It’ll ask for a name and a quick job description for your new helper.

4. Give it a mission. Follow the prompts to tell the subagent exactly what it should (and shouldn’t) be focusing on.

We will build 2 subagents together: Researcher and Code Review Subagents. In Researcher subagent configuration, I’ll show how you can add skills as well.

Use Case 1: The Researcher Subagent

You’re preparing to write something: an article, a pitch, a product page. You have a folder full of sources: competitor newsletters you’ve saved, research PDFs, draft notes from three different conversations, a few URLs you bookmarked last month. Reading all of it manually takes an hour. Dumping it all into a Claude session burns your context before you’ve written a word.

What you actually need is someone to read the whole pile, find what matters, and come back with a briefing.

That’s this subagent.

Here is the intriguing part: It doesn't just summarize. It's configured to know who you are and what you're looking for, because it loads a skill before it starts reading.

Without the skill, it just reads your file as a generic AI agent and surface whatever it thinks is interesting.

With the skill, it reads your files knowing your audience, your niche, your content gaps, and what "a good insight" looks like for you specifically. The output changes completely.

The Skill File:

Create a file called research-context.md in a skills/ folder in your project:

# Research Context — [Your Name / Publication Name]

## Who I Write For
[2-3 sentences describing your audience. Their level of sophistication,
what they already know, what they're trying to figure out.]

## My Niche and Angle
[What makes your perspective distinct. What you cover that others don't.
What you deliberately avoid.]

## What a Good Insight Looks Like
[Concrete examples of the kinds of findings that are useful to you.
E.g.: "a pattern nobody in my space is talking about yet" or
"a contradiction between what experts say and what practitioners do"]

## What to Ignore
[Topics, sources, or types of content that aren't relevant even if
they seem related on the surface.]

That file gets loaded into the subagent's context before it reads a single source.

How to Build a Subagent Using the /agents Command

You started claude code from your terminal (type claude, hit enter). Run /agents command.

Select Create new agent.

You can choose either Project or Personal.

💡 When you choose Project, your subagent will live only for this specific folder. When you choose Personal, you can access to your subagent from other folders as well.

Here, you can choose if you want to create your subagent with Claude or manually. Let’s generate it manually:

After that, you need to add unique identifier for your agent. Type “researcher”.

Next, you need to add a system prompt:

Add this prompt (I’ll give you the full file structure later):

You are a research analyst preparing briefings for the author.

Before reading any sources, review your loaded research-context skill.
It tells you who the audience is, what the author's angle is, and what
a useful insight looks like for this specific publication.

Now, tell Claude when it should use this agent:

Use when this agent when preparing to write, building a content strategy or analyzing a topic.

Select Readonly tools because it shouldn’t modify the files.

Use the model you want:

Now, this is the fun part! Choose the color you want for your subagent:

After completing all the steps and save the subagent, you will find your researcher subagent under .claude/agents/researcher.md. Here is the full definition:

---
name: researcher
description: Competitive intelligence and research analyst. Use when 
preparing to write, building a content strategy, or mapping a topic 
before taking a position. Reads source material and returns structured 
briefings — never modifies files.
tools: Read, Grep, Glob
model: sonnet
skills:
  - research-context
---

You are a research analyst preparing briefings for the author.

Before reading any sources, review your loaded research-context skill.
It tells you who the audience is, what the author's angle is, and what
a useful insight looks like for this specific publication.

When invoked:
1. Read the research-context skill to calibrate your lens
2. Read all provided source files thoroughly
3. Return a structured briefing:

   ## The Landscape (3-5 sentences)
   What is the current state of thinking on this topic?
   
   ## What Everyone Is Saying
   The consensus view — what appears in most sources.
   
   ## What Nobody Is Saying
   The gap. The contradiction. The thing that's true but underrepresented.
   This is the most important section.
   
   ## The Angle Worth Taking
   One specific, arguable position the author could own.
   
   ## Sources That Earned Their Place
   Which files/sources were actually useful and why.

Never pad. Never summarize for the sake of summarizing.
If a source has nothing useful, say so and move on.

You can now run this subagent with this prompt:

Use the researcher subagent to read everything in /research/ai-agents-april/ and 
brief me on the competitive landscape. I'm preparing to write about autonomous AI agents.

When you run this command, researcher subagent loads your research-context skill (it already knows your audience, your niche, what you care about), reads every file in that folder, and returns a structured briefing. Your main session sees the briefing only. All the file reads stay in the subagent's context.

Share

Use Case 2: The Code Reviewer Subagent

This is one of the most useful case for subagents.

You just finished writing a code. You know it well. You made the decisions; you know why every line is there. That's exactly why you're the worst person to review it. You'll miss the thing that's obviously wrong to everyone who wasn't in the room when you built it.

Same goes for Claude Code: when Claude implements a new feature in the codebase, you shouldn’t do the code review in the same session. Since subagent create a new context window, it is better to delegate code review task to a subagent.

💡 You can follow the same steps above to create a code-reviewer subagent.

The Subagent Definition

---
name: code-reviewer
description: Expert code review specialist. Use immediately after writing 
or modifying code. Reviews for quality, security, and maintainability. 
Read-only — never modifies files.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards of quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files; don't review the entire codebase
3. Begin the review immediately — no preamble

Review checklist:
- Logic errors and edge cases the author probably didn't test
- Security issues: exposed secrets, missing input validation, unsafe operations
- Anything that contradicts the patterns in CLAUDE.md
- Missing error handling
- Anything that would confuse someone reading this cold

Return feedback organized by priority:
- 🔴 Critical (must fix before shipping)
- 🟡 Warning (should fix soon)
- 🟢 Suggestion (worth considering)

For each issue: name the file, describe the problem, show a concrete fix.
No padding. If there's nothing critical, say so clearly.

The prompt:

Use the code-reviewer subagent to review the changes I just made to the 
authentication module.

The subagent runs git diff, reads the changed files, and returns a prioritized list. Your main session sees the list. The file reads stay in the subagent’s context.

Why read-only is the right default:

Notice the tools: Read, Grep, Glob, Bash; no Edit, no Write. This is intentional. A reviewer’s job is to find problems, not fix them. You decide what to fix and in which order. If you give the reviewer edit access, you’ve hired someone who might “helpfully” change three things while fixing one, and now you’re reviewing the reviewer’s work.

Keep reviewers read-only. Bring in a separate agent to fix what the reviewer flagged.

Subscribe now

Subagent Gotchas: The Rules You Can't Ignore

Using subagents feels like a superpower, but there are some technical “laws of physics” you need to respect.

1. It’s a Shared Wallet (The Token Pool)

Subagents aren’t “free” extra processing power. They draw from the same token pool (think of this as your session’s budget) as your main chat.

• The Trade-off: Using a subagent keeps your main chat window clean and fast because the “heavy lifting” happens off-screen.

• The Reality: If you send five subagents to do massive tasks at once, you’ll hit your limits faster. Use them strategically, not constantly.

2. Summaries Lose Detail (The “TL;DR” Effect)

When a subagent finishes a task, it sends a summary back to you. Like any summary, it skips the boring stuff, but sometimes that “boring stuff” is the line number you actually needed.

• Pro Tip: If you need the nitty-gritty, tell it: “Save your full findings to review-notes.md”.

• You can then open that file separately to see the raw data without cluttering your main conversation.

3. They Are “One-Shot” Workers

Subagents are built for Task -> Result, not Back-and-Forth.

• If you say “Go look at this,” and then wait for it to come back so you can say “Okay, now look at that,” you’re doing it wrong. That’s a conversation, keep that in your main session.

• The Workaround: Chain them. Tell the first subagent to research, and the second to act on whatever the first one found.

4. No “Inception” (Subagents can’t spawn subagents)

There is a hard limit: A subagent cannot hire its own subagent.

• If your task is so complex that it needs a manager, a specialist, and a researcher all working in a hierarchy, you’re looking for Agent Teams (which we’ll cover in Part 3). For now, keep your requests direct and flat.

💡 Treat subagents like a background job. Give them a clear set of parameters, let them run while you focus on something else, and just check the output logs once they’ve finished their work.

If you want to run your own Agent Teams, check out Part 3: Claude Code Agent Teams Tutorial.

Which part clicked for you? Or which part still feels fuzzy? Drop it below; your question might be the next article!

Leave a comment

PS: If you're new here and wondering why a software engineer is writing about all this - here's why I started Becoming with AI."

TL;DR;

Claude Code is Anthropic’s terminal based (CLI) AI agent that shifts the paradigm from “AI as a consultant” to “AI as a junior engineer”. Unlike a web-based chatbot, it has “hands”; it can read your files, execute terminal commands, run tests, and commit to Git.

• The “Brain” Shift: Stop describing problems; start directing work. Claude Code lives in your local file system, not just a browser tab.

• The Secret Sauce (CLAUDE.md): Create a markdown file at your project root to act as Claude’s “onboarding manual” for persistent context and project rules.

• Essential Commands: Use /model to switch to Sonnet 4.6 (saves tokens), /compact to refresh AI memory, and /plan to vet complex tasks before execution.

• Context is Currency: Manage your “attention budget” by using /clear between unrelated tasks to prevent “AI fog” and high costs.

• Requirement: Requires a Claude Pro subscription ($17/month) and installation via terminal.

The Golden Rule: Treat Claude Code like a colleague who needs clear boundaries and permissions, not just a text box for questions.

Merhaba 👋🏻

I am a Software Engineer with 10+ years of experience. My goal is to close the gap between the technical and the non-technical, making AI accessible to everyone, regardless of their background.

Subscribe now

If you just installed Claude Code and you're not sure how to actually get it working; this is the guide I wish I had.

If you’ve been using AI in a browser, you’ve been treating it like a consultant. You describe a problem, it gives you a suggestion, and then you do the manual labor of copy-pasting, debugging, and saving files. You are the worker; the AI is the advisor.

You type. It answers. You copy the answer somewhere useful. Then you go do the work yourself.

Claude Code is not that.

Claude Code is a junior engineer who actually sits at your computer; it can open your files, edit them and run commands. You don't describe the problem to a consultant anymore; you hand the keys to a colleague and tell them what to do.

That shift in mindset is everything.

How Claude Code Works: The 3-Phase Framework

Claude executes tasks through an integrated three-phase framework: gather context, take action, and verify results. As these phases blend together, Claude actively leverages its toolset at every stage to analyze codebase files, apply changes, and validate outcomes through testing.

Before we go into more detail, I want to clarify something: You don't need to write code to use Claude Code. You need to direct work. If you have a folder of markdown notes, a half-built side project, a Substack draft workflow, research PDFs, or a spreadsheet mess, Claude Code can work on any of that. The "code" in the name is misleading. It's really an agent that lives in your file system. That said, you can always use Claude Cowork instead, which is basically an interface with a high-level coding power. You can also check out my AI News Digest with n8n article to explore a low code tool.

How to Install Claude Code (Mac & Windows)

To be able to use Claude Code, you need at least Claude Pro Subscription which is 17$ per month. If you already have a subscription, you can download claude code by following these instructions on Quickstart page from Anthropic.

💡 Prefer to download claude code with native installer from Quickstart page because this will help you to get auto updates in the background.

After you install it, run this command on terminal (or powershell) to verify installation:

claude --version

Now that you got the correct version on your terminal, you can start claude code by typing claude.

6 Claude Code Concepts Every Beginner Needs to Know

Once Claude Code is running, there's a small set of ideas that make the difference between "this is confusing" and "oh, this actually makes sense." Here they are, in rough order of importance.

1. CLAUDE.md: Claude Code's Project Memory File

This is a plain markdown file you put at the root of your project folder. Claude reads it automatically at the start of every session. Think of it as the onboarding document for a new hire: conventions, file structure, “always do X”, “never touch Y”, what tools the project uses.

Writing a good CLAUDE.md is the single highest-leverage thing a beginner can do. It’s the difference between “it keeps forgetting my setup” and “it just knows”.

A starting point (steal this):

Project: [Name of your project or workspace]

What this is: [One sentence describing what lives in this folder]

File structure:

/drafts — [what goes here]
/published — [what goes here]
/templates — [what goes here]
Rules:

* Always [your most important convention, e.g., "use markdown for all new files"]
* Never [your biggest guardrail, e.g., "delete anything in /published without asking"]
* When creating new files, [naming convention or format preference]
* Tone/Style notes: [If Claude will be writing for you, put voice guidelines here]

Tools this project uses: [List anything relevant: Git, a specific static site generator, a particular folder structure]

I skipped writing a CLAUDE.md for my first three projects because it felt like extra work. Every single one of those projects turned into sessions where I repeated the same instructions over and over. Write it first, not last.

💡 If you don’t know how to fill this file yet, it’s okay to not have it in the beginning. You might end up repeating yourself to claude for a while, but when you discovered what claude keeps forgetting, you can always tell claude to create a CLAUDE.md file and add these constraints.

Subscribe now

2. Claude Code Slash Commands: Your Essential Control Panel

Inside a Claude Code session, typing / pulls up a menu of commands. You don’t need to memorize all of them. The ones worth knowing on day one:

• /help — shows you what’s available

• /clear — wipes the conversation and starts fresh (your files stay untouched)

• /compact — summarizes the conversation to free up context space

• /model — lets you switch between models mid-session

• /effort — lets you switch between intelligence levels

• /context — shows you how much of the “attention budget” you’ve used

• /plan — puts Claude into planning mode so it thinks before it acts

• /insights — generates a report that analyzes your claude code session.

💡 When you run /insights command, Claude Code will give you tips to get most out of it by generating a nice report for you.

Among all these, one of the most important command is /model. When you first downloaded Claude Code, you probably will get the highest model: Opus 4.7.

Well, nothing wrong with Opus 4.7 model. Only problem is, your tokens will burn so fast before you finish the work. That’s why I’d suggest you to switch to Sonnet 4.6 by typing /model command.

💡 You can also set effort level by typing /effort to the terminal. Set it to medium if you are just going to do a code generation. You can also set it to Low effort for a chat or non-coding use cases.

3. Claude Code Context Window: Managing Your Token Budget

This is where most people hit their first real wall, and it’s the same concept I’ve written about before in No-BS Vibe Coding series. Claude has a limit on how much it can “hold in its head” at once. Every file it reads, every message you send, every tool result; it all goes into that budget.

When the budget fills up, two bad things happen: responses get worse, and older parts of the conversation start getting quietly dropped. You’ve seen this in ChatGPT or in Gemini too; that moment forty minutes into a conversation where the AI seems to forget everything you told it earlier.

Same thing here. But in Claude Code, the stakes are higher because the AI is actually editing your files, not just talking.

If you want to see context in action:

1. Open a Claude Code session in any project folder.

2. Run /context to see how much budget you have.

Here is how context usage looks like in one of my projects.

3. Work on one focused task for 15 to 20 minutes.

4. Run /context again to see how it’s changed.

5. Run /compact and notice how the session feels sharper afterward.

This builds your intuition for context management faster than any explanation I can write.

3.1. When to Use /compact vs. /clear in Claude Code

It is important to know when to use /compact and /clear commands. This way, you don’t accidentally lose the entire conversation in the middle of the current task, like I did before.

/clear nukes the conversation entirely. Use it when switching to something unrelated and the history has zero value for the next task.

/compact summarizes the conversation and restarts from the summary. Use it when you’re still in the same task but the session has gotten long and noisy.

💡 /clear is “burn the whiteboard”. /compact is “take notes from the whiteboard so you can erase it”.

Compact proactively; don't wait to hit the wall. After a feature is working, after a bug is fixed, after a module is complete; that's the right moment to compact, not after Claude starts forgetting what you told it three hours ago.

4. Claude Code Permissions: How to Stay in Control

Claude Code asks you before it does anything risky: editing a file, running a shell command, deleting something. You’ll see a prompt like “Claude wants to run rm -rf logs/. Allow?”

Read these. Actually read them.

Don’t build the habit of mashing “Yes” to everything. That’s how people lose work. I’ve done it; twenty minutes into a productive session, clicking “Allow” on autopilot, and then watching Claude cheerfully overwrite a file I hadn’t backed up yet. The tool warned me. I just wasn’t paying attention.

You can configure Claude Code to auto-approve safe operations later, once you’ve built trust and you know what “safe” looks like in your project. But on day one, read every permission prompt.

There’s also a Plan mode. Type /plan and Claude will think through a task and propose a plan before touching anything. Use this for anything bigger than a one-line fix. It’s like asking your junior engineer to explain what they’re going to do before they start doing it.

5. Claude Code Skills: Reusable Task Bundles

A skill is a folder with a SKILL.md file that teaches Claude how to do a specific kind of task. “How we write SEO metadata for this newsletter”. “How we format a PR description”. “How to process an invoice PDF”. Claude auto-invokes the right skill when the situation matches.

Think of skills like recipe cards in a kitchen. You write them once, and every time Claude encounters a matching situation, it already knows the steps.

You don't need skills on day one. But by day three, when you notice yourself giving the same instructions for the third time, that's when you create one.

6. Claude Code MCP: Connect to Notion, Gmail & GitHub

MCP stands for Model Context Protocol, and it’s how Claude Code plugs into other services: Gmail, Google Drive, Notion, Slack, GitHub, etc. You add an MCP server once, and Claude can now use that service on your behalf.

This is the part that makes Claude Code feel less like a coding tool and more like an assistant that actually has hands.

💡 Without MCP, Claude can only work with files on your computer. With MCP, it can pull data from your Google Drive, check your GitHub issues, or read from a Notion database.

I’d file this under “week two” for most people. Get comfortable with the basics first; the file system, the context management, the CLAUDE.md. Then start connecting external services once you’ve got the core mental model solid.

Claude Code Tips to Save Tokens and Avoid Mistakes

Each of these cost me at least one frustrating session before I figured it out. Here they are so you can skip the frustration.

• Write the CLAUDE.md first, not last. I said this already. I’m saying it again because I still catch myself skipping it when I’m excited to start a new project. Every time I skip it, I regret it within twenty minutes.

• Start every unrelated task with /clear. Context bleed between tasks is real. If you just finished reorganizing your file structure and now you want to draft a blog post, clear the session. Fresh context, fresh results.

• Use Plan mode for anything scary. If the task involves deleting, moving, or restructuring, type /plan first. Let Claude show you what it’s going to do. Then decide.

• Pick your model deliberately. You can switch models mid-session with /model. Some tasks need the most capable model; some tasks are fine with a faster, cheaper one. Don’t burn your best model on file renaming.

• Don’t run it in your home directory. If you launch claude from ~ (your home folder), Claude’s “world” is your entire home directory. That’s messy and slow. Always switch into a specific project folder first.

• Version-control your config. Your CLAUDE.md, your skills, your slash commands; these are all just files. Put them in Git. If something breaks, you can roll back. We call this “version control,” but it is just a Temporal Insurance. (If you missed that concept, it showed up in one of my earlier articles.)

Common Claude Code Mistakes (And Exactly How to Fix Them)

These are the problems I see people hit most often. Knowing them in advance saves you real hours.

• “Why won’t it log in?”

  You’re probably on a free Claude.ai account. Claude Code requires Pro, Max, Team, Enterprise, or API access. Check your account settings at claude.ai before troubleshooting anything else.

• “It feels dumber than it was an hour ago.”

  Context is full. Run /context to check, then /compact or /clear. This is not a bug; it’s the attention budget running out. It happens in every long session. The fix is always the same: clear or compact.

• “It keeps forgetting what I told it earlier.”

  Two possible causes. Either the context budget pushed your earlier messages out, or you didn’t put the important stuff in your CLAUDE.md. Anything Claude needs to remember across sessions belongs in CLAUDE.md. Anything it needs to remember within a long session might need a /compact to survive.

• “It did something I didn’t want.”

  This is almost always a permissions problem; either you auto-approved something without reading it, or you gave instructions that were too vague. Be specific. “Clean up this folder” is dangerous. “Move all .log files from /output to /archive and list what you moved” is safe.

Share this post with someone who is learning Claude Code

Share

The Mental Model That Makes Claude Code Click

Here’s what I keep coming back to with Claude Code: the tool is not the hard part. The mental model is the hard part.

If you walk in thinking “this is a fancier chatbot”, you’ll be frustrated within the hour. If you walk in thinking “this is a junior colleague who needs clear direction, an onboarding doc, and someone checking their work”, it clicks almost immediately.

I’m still calibrating this myself. I still catch myself typing long, descriptive prompts when I should be giving short, direct instructions. The difference is that now I know why it’s happening, and I can fix it in seconds instead of spending thirty minutes blaming the tool.

The junior engineer metaphor isn’t perfect. No metaphor is. But it’s the closest thing I’ve found to a mental model that actually predicts how Claude Code will behave before you hit Enter.

That’s worth a lot on day one.

If you want to try out Claude Code today, try building your own AI agent that I’ve explained in one of my articles. Just download Claude Code, use an IDE if you like (i.e. VS Code), and give instructions to Claude.

Here is the Part 2 of the Claude Code series: Claude Code: Subagents.

Which part clicked for you? Or which part still feels fuzzy? Drop it below; your question might be the next article!

Leave a comment

PS: If you're new here and wondering why a software engineer is writing about all this - here's why I started Becoming with AI."