Mastering Claude Code: A Developer’s Guide

In the last few months, I’ve tried a bunch of coding assistants. As a big JetBrains IDE’s fan, I started with Junie. It did the job, but man, it was slow. I had time for way too many coffee breaks.
Next, I tried Cursor, since everyone at the office wouldn’t stop talking about it. It’s a solid tool, but as someone who grew up on PyCharm and WebStorm, I couldn’t make peace with VS Code.

Then a friend recommended Claude Code, an IDE-agnostic assistant that works anywhere. Since that day, it’s been part of my daily workflow. In this post, I’ll share what makes it stand out and a few things I’ve learned along the way.

But before diving into the details, let’s clarify what Claude Code actually is.
Claude Code is a coding assistant agent, an AI agent designed with the right tools to help you code faster, smarter, and with less friction.

How Coding Assistants Work

Most coding assistants work around 4 main components, often called the Context → Thought → Action → Observation cycle:

1. Context: The agent identifies which part of the codebase is relevant and which files should be included in the request.
2. Thought: The LLM decides what to do next - whether to edit an existing file, write new code, or generate an entirely new component.
3. Action: The agent gets to work, calling the right tools with the right arguments. This is where the actual code is written or modified.
4. Observation: The model looks at the results from the action, reflects on them, and decides if it needs more info or if it’s ready to give the final output.

All of this happens in a continuous loop, so the agent keeps improving its answer as it goes.

Context → Thought → Action → Observation cycle

Why Use Claude Code

Unlike web-based tools, Claude Code can handle large files and complex codebases without all the copy-pasting or constant context switching.
It can also run bash commands autonomously, letting it test your code, check logs, or execute build scripts on its own. You can even define custom commands to automate repetitive tasks, keeping your workflow smooth and efficient. Plus, it integrates with VS Code and JetBrains IDEs, so you can stick with your favorite editor without changing your setup.

Whether you’re debugging an issue or adding a new feature, Claude Code takes care of the heavy lifting and helps you stay focused and in flow.

My Top Features of Claude Code

1. Managing Code Context

Context is everything with Claude Code.
Claude Code works best when it focuses on the right files, not your entire codebase. Feeding it too much irrelevant code doesn’t make it smarter; it can actually slow it down and confuse it. Think of it like trying to explain a single bug to someone while showing them your entire repository; it's overwhelming and counterproductive.

/init Command

The first thing to do when starting a project is to run /init. Think of this command as giving Claude a map of your codebase. It scans your files, learns the architecture, and identifies the key components of your project. Once the scan is complete, Claude generates a CLAUDE.md file that summarizes the most important files, recurring coding patterns, and useful commands. Essentially, you’re creating a cheat sheet that Claude can refer to throughout the project, making it much faster and smarter as you work.

CLAUDE.md Files

The CLAUDE.md file acts as a persistent system prompt, a set of instructions that Claude remembers for your project. There are three types you should know about:

• CLAUDE.md → The team version. Commit it to source control so everyone on the project has the same context and guidance.
• CLAUDE.local.md → Your personal instructions. These aren’t shared with the team and can include notes or preferences unique to your workflow.
• ~/.claude/CLAUDE.md → Global instructions. These rules and guidelines apply across all projects, like coding style preferences or default testing strategies.

By managing these files properly, you ensure Claude is always working with the right context, making its suggestions far more accurate and relevant.

2. Making Changes Effectively

Once your project context is properly set up, Claude Code becomes far more than a code suggester. It transforms into a true coding partner. The next step is learning how to guide it when making changes. Claude provides several interactive modes that let you control how deeply it reasons and how it approaches edits.

Planning Mode

For complex changes that touch multiple files — like refactoring a shared module or adding a new feature — Planning Mode is your best friend. Activate it by pressing shift+tab twice

In this mode, Claude:

• Explores more of your project to understand dependencies.
• Drafts a full implementation plan so you can review its approach.
• Waits for your confirmation before making any edits.

This approach prevents messy, half-complete changes across the codebase. Instead, you and Claude plan the change together.

Thinking Modes

Claude also offers several thinking levels, which control how deeply it reasons about your request, essential for logic-heavy tasks or tricky debugging.

• Think → perfect for small edits or simple questions.
• Think more → ideal for moderately complex fixes.
• Think a lot → useful when multiple files or logic paths are involved.
• Think longer → great for big-picture understanding.
• Ultrathink → for analyzing an entire system or complex algorithm.

When to Use Each

• Planning Mode → Ideal for changes that involve multiple files, dependencies, or architectural shifts.
• Thinking Modes → Best when debugging tricky logic or when you want to understand why something is breaking before fixing it.

Together, these tools make Claude Code feel like pair programming with a thoughtful senior engineer who plans carefully, explains clearly, and only moves forward once you’re confident in the approach.

3. Automating Tasks with Custom Commands

One of Claude Code’s most underrated superpowers is custom commands. While Claude comes with several built-in commands, its real strength shows when you start creating your own. Custom commands let you automate repetitive parts of your workflow, anything from running tests and checking dependencies to generating documentation.

If you find yourself typing the same requests over and over, this feature can save you a ton of time and keep your workflow smooth and efficient.

Setting Up Custom Commands

Creating your own commands is surprisingly simple:

1. Find the .claude folder in your project (it’s usually in the root directory).
2. Inside it, create a folder called commands.
3. Add a markdown file with your command name. For example, creating a file called pre-commit.md will automatically create a /pre-commit command.

Each markdown file acts as a mini instruction set. You can describe what the command should do, include examples, or even define step-by-step workflows.

Here’s a simple example of what pre-commit.md might look like:

# Run Pre-commit Hooks

Run the pre-commit hooks defined in `.pre-commit-config.yaml` only on files that were changed.

Hooks included:
* **pre-commit-hooks** (v4.6.0)
  - trailing-whitespace
  - end-of-file-fixer
  - check-added-large-files
  - requirements-txt-fixer
* **gitleaks** (v8.18.4)
  - gitleaks (detect secrets and sensitive info)
* **isort** (v5.13.2)
  - Apply import sorting with `--profile black`
* **black** (24.4.2)
  - Format code with `python3.11`
* **flake8** (7.0.0)
  - Run linting with:
    - `--max-line-length=120`
    - `--ignore=E203,E501,W503`
    - additional dependency: `flake8-simplify`

## Conventions
* Always ensure `.pre-commit-config.yaml` is up to date.
* Run `pre-commit install` if not already installed.
* Execute `pre-commit run --all-files` to validate the full repo.
* If hooks fail, apply the suggested fixes and re-run until clean.

## Goal
Guarantee code quality, security, and consistency across the repo before commits.

4. Leveraging Subagents for Specialized Tasks

One of the most powerful and, personally, my favorite features of Claude Code is the ability to create custom subagents, smaller, specialized AI assistants built for specific tasks.

What Are Subagents?

Think of subagents as pre-configured AI teammates. Each one is built for a certain purpose, for example, code reviewing, debugging, testing, or analyzing data.
When Claude encounters a task that fits a subagent’s skill set, it can automatically delegate the work to that subagent, which runs in isolation and returns the results when done.

Each subagent has:

• A dedicated purpose and area of expertise.
• Its own context window, separate from the main conversation.
• Custom tool permissions.
• A unique system prompt that defines its “personality” and workflow.

This separation of duties keeps your main Claude session clean while giving complex tasks their own dedicated environment.

How Subagents Are Stored

Subagents are saved as Markdown files, in one of two places:

• Project subagents → .claude/agents/ (available only in the current project)
• User subagents → ~/.claude/agents/ (available across all projects)

Each file defines the subagent’s metadata, system prompt, and tool permissions, making it easy to tweak or version-control them.

Using Subagents in Practice

You can work with subagents in two main ways:

• Automatic Delegation: Claude decides when to hand off a task to a relevant subagent.
• Explicit Invocation: You can directly tell Claude which subagent to use:

> Use the review-pr subagent to review my PR

Common examples include:

• Code Reviewer: Scans diffs for quality, clarity, and standards.
• Debugger: Digs into stack traces and root causes.
• Architecture: Helps you make an architectural decision.

When used right, subagents turn Claude Code into a full AI team, each member with a different skillset, all working together to make your development process faster, cleaner, and smarter.

5. Extending Claude with MCP Servers

One of Claude Code’s most transformative capabilities is its ability to extend itself using MCP servers. These servers act like plugins that give Claude new powers from accessing external systems and APIs to automating complex development workflows. With MCP, Claude isn’t limited to your local codebase; it can now interact with tools like Jira, GitHub, Databases, and more.
MCP servers can run locally or remotely, and they serve as an integration layer between Claude’s reasoning engine and your team’s real-world environment.

Installation and Setup

Setting up the Jira MCP server is straightforward. In your terminal, run:

claude mcp add jira npx @jira/mcp@latest

This installs the MCP server locally and registers it as jira. From that point on, Claude can access your Jira instance through your configured API credentials or OAuth connection. It can then interact with your issues, sprints, epics, and users, just like a teammate.

Managing Permissions

To maintain security and control, Claude always asks for permission before accessing external MCP tools. But if you trust the integration and use it regularly, you can pre-approve Jira in your .claude/settings.local.json file:

{
  "permissions": {
    "allow": ["mcp__jira"],
    "deny": []
  }
}

This way, Claude can interact with your Jira workspace freely without asking every time while still maintaining clear visibility into what it’s allowed to do.

6. Adapting with Output Styles

The final feature of Claude Code is its adaptive output styles, which let you shape how Claude responds based on the kind of support you need. Whether you’re deep in the middle of coding or exploring a new design pattern, Claude can instantly adjust its tone, depth, and level of detail to match your workflow.

Default Mode: Fast and Focused

When you’re in execution mode - shipping features, fixing bugs, or iterating quickly, Default is all you need.
Claude gives short, direct answers focused purely on getting things done. No fluff, no overthinking, just clean, actionable output. This mode keeps you in flow, especially during high-speed development sessions or pair programming.

Explanatory Mode: Learn While You Code

Switch to Explanatory mode when you’re exploring a new codebase or want to know why a solution works. Claude will still complete the task, but it also walks you through the reasoning, trade-offs, and architectural patterns behind the decision. When I’m onboarding into a new project, this is my go-to, it explains the project in depth and highlights the specific areas you need to focus on.

Learning Mode: A Collaborative Coding Partner

We all love to code, and we don’t want to get rusty while Claude Code does all the fun work. That’s when you switch to this mode.
Interactive Mode is designed for when you want to stay hands-on.
Claude still guides the process, but it leaves TODO(human) markers in the code, inviting you to fill in the missing pieces yourself. It’s the perfect balance between automation and active learning.

Example:
“Write a FastAPI endpoint that creates a new user and saves it to the database.”

from fastapi import APIRouter, HTTPException
from pydantic import BaseModel

router = APIRouter()

class User(BaseModel):
    id: int
    name: str
    email: str

@router.post("/users")
async def create_user(user: User):
    # TODO(human): Add your database connection logic here
    
    # TODO(human): Check if user already exists in the database
    
    # For now, just simulate a successful creation
    return {"message": f"User {user.name} created successfully!"}

Beyond the Built-ins

While these three modes cover most workflows, Claude Code’s flexibility doesn’t stop there. You can go even further by defining custom commands and creating your own output patterns tailored to your specific needs.

For example:

• /review-output — Have Claude perform a detailed code review, highlighting potential bugs, style issues, and optimizations.
• /refactor-output — Automatically restructure code for readability or performance while preserving functionality.
• /explain-tests-output — Generate explanations for test cases, describing what each one validates and why it matters.

These custom commands let you shape Claude into a personalized coding partner that adapts to your workflow.

Claude Code isn’t just another AI tool; it’s like having a smart coding partner who adapts to how you work. From managing context, planning complex changes, automating tasks, and using specialized subagents, customizing output styles, it brings intelligence right into your workflow. Whether you’re trying to ship features faster, learn a new codebase, or just reduce repetitive work, Claude Code helps you stay focused, productive, and in control. If you haven’t tried it yet, give it a try.
Once you see how it fits into your day-to-day development, it’s hard to go back.