DEV Community: Syed Asif

Building Hybrid Network Labs with netlab: Combining Containerlab and Vagrant

Syed Asif — Mon, 06 Jul 2026 03:42:50 +0000

Not every network operating system ships in the same format. Cisco IOSv
and IOSvL2 are distributed as virtual machine images and require KVM —
there are no container images for them. On the other end of the spectrum,
Cisco IOL and Alpine Linux run natively in containers, needing only a
few megabytes of overhead.

A hybrid lab lets you run each device in its native environment: virtual
machines for the NOSes that need them, containers for everything else.
netlab orchestrates both backends from a single topology file, so you
don't have to manage Vagrant and Containerlab separately.

By the end of this guide you'll have built a working campus topology
that mixes both providers:

Role	Nodes	Device	Provider
Core router	R1	IOSv	libvirt
Distribution	D1, D2	IOSvL2	libvirt
Access	S1, S2	IOL-L2	clab
Hosts	H1, H2, H3, H4	Linux	clab

All nine nodes are defined in one topology.yml and deployed with a
single netlab up command — netlab handles the cross-provider wiring,
bridge discovery, and configuration deployment automatically.

2. Why Build a Hybrid Lab?

Cisco distributes its network operating systems in different formats:

IOSv and IOSvL2 are QEMU/KVM virtual machine images. There are no native container images for them — they require a full VM, consuming around 1 GB of RAM each.
IOL (IOS On Linux) is a binary that runs directly on the Linux kernel. It doesn't need a hypervisor, so it uses less CPU and memory than the equivalent IOSv VM. Cisco's documentation notes that IOL nodes "consume much less CPU and memory than an equivalent IOSv or CSR 1000v node in your lab."
Alpine Linux is a few megabytes as a container image, yet netlab would allocate 1 GB of RAM to it if you ran it as a VM — just for ping and bash.

Building a lab with a single provider forces you to pick the least common
denominator: run everything as VMs (wasting resources on lightweight
nodes) or run everything as containers (excluding devices that have no
container image). A hybrid lab avoids both tradeoffs.

Device	Best Backend	Why
IOSv	Vagrant/libvirt	No native container image
IOSvL2	Vagrant/libvirt	No native container image
Cisco IOL	Containerlab	Runs as a native Linux binary
Linux	Containerlab	Runs as a native Alpine image

Run every device in its native environment.

3. Prerequisites

You need a Linux server (Ubuntu recommended) with the following toolchain
installed. Verify each component before proceeding:

# KVM hardware support
kvm-ok

# libvirt
virsh list --all

# Vagrant + vagrant-libvirt plugin
vagrant --version
vagrant plugin list

# Docker + Containerlab
docker --version
containerlab version

# netlab
pip3 show networklab | grep Version

# User group membership — must include libvirt, vagrant, docker
groups

If any check fails, see the netlab Ubuntu installation guide for setup steps.

4. Understanding netlab Providers

A virtualization provider is the backend that runs your lab devices. netlab supports three of them:

Provider	Backend	Use case
libvirt	Vagrant + KVM/QEMU	VM-based NOS images
clab	Containerlab + Docker	Container-native devices
external	Physical or pre-existing devices	Hardware or unmanaged nodes

Provider Resolution

netlab decides which provider to use for each node by checking these locations in order:

Per-node provider attribute — highest precedence
Group provider attribute — applied to all group members
Topology-level provider — the default for all nodes
System default — libvirt if nothing else is set

In our topology, provider: libvirt is set at the top level. Nodes without a provider attribute (R1, D1, D2) inherit it. Nodes with provider: clab (S1, S2, H1–H4) override it.

Hybrid Mode Constraint

When mixing providers, the primary (topology-level) provider must be libvirt. clab can only be a secondary (per-node) provider. This is a hard constraint — netlab needs to orchestrate the startup sequence (Vagrant first, then Containerlab) and bridge the two environments.

Provider-Specific Images

Each device type can use different images depending on the provider. Set them in defaults.devices:

defaults:
  devices:
    iosv.libvirt.image: cisco/iosv:15.9.M3
    ioll2.clab.image: asifsyd/cisco_iol:l2-17.12.01

The .libvirt. variant is used when the node runs on libvirt; the .clab. variant is used when it runs on Containerlab.

5. Building the Topology

Here is the complete topology.yml file. It defines a campus network with a core router, two distribution switches, two access switches, and
four hosts — each running on its native provider.

---
name: campus
provider: libvirt
version: 1.0

defaults:
  devices:
    iosv.libvirt.image: cisco/iosv:15.9.M3
    iosv.warnings.paramiko: false
    iosvl2.libvirt.image: cisco/iosvl2:15.2
    iosvl2.warnings.paramiko: false
    ioll2.clab.image: asifsyd/cisco_iol:l2-17.12.01
    linux.clab.image: alpine:latest

nodes:
  R1:
    device: iosv
    module: [ospf]
  D1:
    device: iosvl2
  D2:
    device: iosvl2
  S1:
    device: ioll2
    provider: clab
  S2:
    device: ioll2
    provider: clab
  H1:
    device: linux
    provider: clab
  H2:
    device: linux
    provider: clab
  H3:
    device: linux
    provider: clab
  H4:
    device: linux
    provider: clab

vlans:
  VLAN_10:
    id: 10
    links: [H1-S1, H4-S2]
  VLAN_20:
    id: 20
    links: [H2-S2, H3-S1]

groups:
  DISTRIBUTION:
    members: [D1, D2]
    module: [vlan, ospf]
    config: [template]
    vlan:
      mode: irb
  ACCESS:
    members: [S1, S2]
    module: [vlan]
    vlan:
      mode: bridge
  VLAN_10:
    members: [H1, H4]
    device: linux
    module: [routing]
    role: host
    routing.static:
      - ipv4: 0.0.0.0/0
        nexthop.ipv4: 172.16.0.254
  VLAN_20:
    members: [H2, H3]
    device: linux
    module: [routing]
    role: host
    routing.static:
      - ipv4: 0.0.0.0/0
        nexthop.ipv4: 172.16.1.254

links:
  - R1-D1
  - R1-D2
  - group: access_trunk
    vlan.trunk: [VLAN_10, VLAN_20]
    members: [D1-S1, D1-S2, D2-S1, D2-S2]

Top-Level Attributes

name: campus — used by netlab to name Linux bridges and container prefixes. Containers will be created as clab-campus-<node>.
provider: libvirt — the primary virtualization provider. Nodes without their own provider attribute inherit this.
version: 1.0 — the minimum netlab version required. If an older version tries to load this file, netlab will refuse.

defaults.devices

This block sets provider-specific container images and device-level settings. The syntax is device.<type>.<provider>.attribute:

iosv.libvirt.image: cisco/iosv:15.9.M3
iosv.warnings.paramiko: false

The .libvirt. variant tells netlab which Vagrant box to use when the node runs on libvirt. The .clab. variant tells it which Docker image to use when the node runs on containerlab.

The warnings.paramiko: false lines suppress Ansible paramiko warnings that Cisco IOS devices trigger during configuration deployment.

nodes

All nine lab devices are defined as a dictionary. Each node has a device type and an optional list of configuration modules.
Nodes running on the secondary provider must include provider: clab:

Node	Device	Provider	Module
R1	iosv	libvirt	ospf
D1	iosvl2	libvirt	(from group)
D2	iosvl2	libvirt	(from group)
S1	ioll2	clab	(from group)
S2	ioll2	clab	(from group)
H1	linux	clab	(from group)
H2	linux	clab	(from group)
H3	linux	clab	(from group)
H4	linux	clab	(from group)

vlans

Two VLANs are defined globally. The links attribute within each VLAN is a shortcut — it tells netlab which switch ports are access members of that VLAN, saving you from writing out vlan.access on each link:

VLAN 10 — Hosts H1 and H4 connected to switches S1 and S2. IP subnet is auto-assigned from the default LAN pool.
VLAN 20 — Hosts H2 and H3 connected to switches S2 and S1.

groups

Groups apply shared settings to multiple nodes at once:

DISTRIBUTION — D1 and D2 run the vlan and ospf modules, use IRB mode (integrated routing and bridging), and pull custom configuration from the template/ directory (Jinja2 files for VRRP configuration).
ACCESS — S1 and S2 run the vlan module in pure bridging mode. They forward traffic without routing.
VLAN_10 and VLAN_20 — Host groups that set device: linux, add a static default route pointing at the VRRP virtual IP, and mark the nodes as role: host (no loopback address).

links

Two point-to-point links connect the core router to the distribution switches:

- R1-D1
- R1-D2

A link group applies trunk attributes to all four distribution-to-access links at once:

- group: access_trunk
  vlan.trunk: [VLAN_10, VLAN_20]
  members: [D1-S1, D1-S2, D2-S1, D2-S2]

This is equivalent to writing four separate link definitions with vlan.trunk on each one.

6. Assigning Providers

Every node in the topology uses the provider that best matches its operating system's distribution format.

Provider per Node

Node	Device	Provider	Reason
R1	iosv	libvirt	IOSv is a KVM image — no container exists
D1	iosvl2	libvirt	Same as above
D2	iosvl2	libvirt	Same as above
S1	ioll2	clab	IOL is a Linux binary packaged as a container
S2	ioll2	clab	Same as above
H1	linux	clab	Alpine runs natively as a Docker container
H2	linux	clab	Same as above
H3	linux	clab	Same as above
H4	linux	clab	Same as above

R1, D1, and D2 have no provider attribute — they inherit provider: libvirt from the topology level. S1, S2, and H1–H4 override with provider: clab.

Cross-Provider Links

When a link connects two libvirt nodes (e.g., R1–D1), netlab uses a UDP point-to-point tunnel — fast and transparent. When a link connects a libvirt node to a clab node (e.g., D1–S1), netlab automatically detects the mismatch and replaces the tunnel with a Linux bridge. Containerlab can then attach the container's vEth pair to that bridge. This happens transparently — you just define the link as D1-S1 and netlab does the rest.

Deployment Sequence

Because cross-provider links require bridge name coordination, the startup order is critical:

vagrant up — boots the libvirt VMs (R1, D1, D2)
netlab inspects the libvirt networks to discover Linux bridge names
containerlab deploy — boots the containers (S1, S2, H1–H4), wiring them to the same bridges the VMs are connected to

This is why you must use netlab up and netlab down for hybrid labs. Running vagrant up or containerlab deploy alone would leave the lab half-connected and hard to clean up.

7. Deploying the Lab

With the topology file ready, one command creates, starts, and configures the entire lab:

netlab up

What Happens Step by Step

1. Topology Validation and Configuration Generation

netlab up calls netlab create to read topology.yml, merge it with system defaults, and validate the data model. It then generates:

Vagrantfile — describes the libvirt VMs (R1, D1, D2) with their box images, memory, and network interfaces
clab.yml — describes the containerlab topology (S1, S2, H1–H4) with their Docker images and links
hosts.yml + ansible.cfg — Ansible inventory and configuration for initial device configuration
netlab.snapshot.pickle — the transformed topology snapshot used by all subsequent netlab commands

2. VM Deployment

netlab runs vagrant up to boot the libvirt nodes. Vagrant:

Downloads the Vagrant boxes (cisco/iosv, cisco/iosvl2) if needed
Creates KVM domains for R1, D1, and D2
Creates the management network (vagrant-libvirt) and data-plane bridges
Powers on the VMs

3. Bridge Discovery

With the VMs running, netlab inspects the libvirt networks and discovers the Linux bridge names for each data-plane link. These bridge names are then injected into the containerlab configuration — this is the key step that makes cross-provider links work.

4. Container Deployment

netlab runs sudo containerlab deploy -t clab.yml to start the container nodes. Containerlab:

Pulls the Docker images (asifsyd/cisco_iol, alpine:latest) if needed
Creates containers for S1, S2, and H1–H4
Attaches each container's vEth interfaces to the same Linux bridges that the VM interfaces are connected to
Creates the containerlab management network (clab)

5. Initial Configuration

Finally, netlab runs netlab initial to deploy device configurations via Ansible. This is a five-step process:

Wait for readiness — netlab polls SSH ports until all devices accept connections
Initial config — hostname, interface IP addresses, descriptions, LLDP, and basic system settings
Normalize — device-specific cleanup (e.g., removing default VLANs from IOSvL2)
Module config — OSPF, VLANs, VRRP, and static routes as defined in the topology
Custom templates — any templates specified in config: group attributes (for example, VRRP configuration from the template/ directory)

After Deployment

Once netlab up finishes, all nine devices are running, wired, and configured. The topology is ready for traffic — hosts can ping the router, OSPF adjacencies are established, and VRRP provides gateway redundancy.

8. Verifying the Hybrid Lab

Once netlab up finishes, confirm that all VMs and containers are running and the network functions correctly.

Check the VMs

virsh list

The libvirt domain names use the lab name (campus) as a prefix:

 Id   Name         State
---------------------------
 3    campus_R1    running
 6    campus_D1    running
 7    campus_D2    running

Check the Containers

docker ps --format "table {{.Names}}"

Containerlab uses the clab-<labname>-<nodename> convention:

Names
clab-campus-S1
clab-campus-S2
clab-campus-H1
clab-campus-H2
clab-campus-H3
clab-campus-H4

Check Everything with netlab

netlab status

This shows all nine devices in one table:

Lab default in /path/to/lab-02
  status: started
  provider(s): libvirt, clab
┏━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓
┃ node ┃ device ┃ image          ┃ mgmt IPv4       ┃ provider ┃ status    ┃
┡━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━┩
│ R1   │ iosv   │ cisco/iosv     │ 192.168.121.101 │ libvirt  │ Up 5 min  │
│ D1   │ iosvl2 │ cisco/iosvl2   │ 192.168.121.102 │ libvirt  │ Up 5 min  │
│ D2   │ iosvl2 │ cisco/iosvl2   │ 192.168.121.103 │ libvirt  │ Up 5 min  │
│ S1   │ ioll2  │ cisco_iol      │ 192.168.121.104 │ clab     │ Up 5 min  │
│ S2   │ ioll2  │ cisco_iol      │ 192.168.121.105 │ clab     │ Up 5 min  │
│ H1   │ linux  │ alpine:latest  │ 192.168.121.106 │ clab     │ Up 5 min  │
│ H2   │ linux  │ alpine:latest  │ 192.168.121.107 │ clab     │ Up 5 min  │
│ H3   │ linux  │ alpine:latest  │ 192.168.121.108 │ clab     │ Up 5 min  │
│ H4   │ linux  │ alpine:latest  │ 192.168.121.109 │ clab     │ Up 5 min  │
└──────┴────────┴────────────────┴─────────────────┴──────────┴───────────┘

Verify Connectivity

From the core router, check OSPF adjacencies:

netlab connect R1
R1# show ip ospf neighbor

From a distribution switch, verify VLANs and VRRP:

netlab connect D1
D1# show vlan brief
D1# show vrrp brief

From a host, confirm reachability across the campus. For example,
ping H2 (VLAN 20) from H1 (VLAN 10):

docker exec -it clab-campus-H1 ping -c 3 172.16.1.7

A successful reply means the Linux bridges, VLAN trunks, OSPF routing,
and VRRP gateway are all working correctly across both providers.

9. Connecting to Devices

netlab provides a single command to connect to any lab device,
regardless of provider.

netlab connect

netlab connect R1       # IOSv router — SSH
netlab connect D1       # IOSvL2 distribution switch — SSH
netlab connect S1       # IOL-L2 access switch — SSH
netlab connect H1       # Alpine host — docker exec

netlab connect reads the lab snapshot to determine the correct
connection method. For network devices (R1, D1, D2, S1, S2) it
opens an SSH session to the management IP. For Linux containers
(H1–H4) it uses docker exec.

You can also execute a single command:

netlab connect R1 --show "show ip route"
netlab connect H1 --show "ifconfig"

Direct docker exec

Linux containers can be reached directly with Docker:

docker exec -it clab-campus-H1 /bin/sh

For IOL containers (S1, S2), docker exec gives you a Linux shell inside the container — not the IOS CLI. Use netlab connect S1
for the standard IOS command-line experience.

Manual SSH

For VM-based nodes, SSH directly to the management IP:

ssh cisco@192.168.121.101

Management IPs are shown by netlab status. Default credentials are defined by the Vagrant box — typically cisco/cisco for
IOSv boxes.

10. Best Practices

Use libvirt as the primary provider in hybrid labs. clab can only be a secondary provider — this is a hard netlab constraint.
Use Containerlab only for container-native NOSes. IOL, Alpine Linux, FRR, and cEOS have native container images that run efficiently under Docker. IOSv and IOSvL2 do not — they must run as VMs.
Always use netlab up and netlab down for hybrid labs. Running vagrant up or containerlab deploy alone will leave bridges disconnected and be difficult to clean up.
Set provider-specific images explicitly in defaults.devices. This makes the topology portable and documents exactly which image each device expects.
Use groups to reduce duplication. The DISTRIBUTION and ACCESS groups in this topology apply VLAN mode, configuration modules, and custom templates to multiple nodes with a single block of YAML.
Keep topology files in version control. A declarative topology file coupled with netlab's automation means anyone can reproduce the exact same lab from source.
Use custom templates for complex configurations. The config: [template] group attribute pulls Jinja2 files from the template/ directory — useful for VRRP, interface descriptions, or any vendor-specific feature netlab does not generate natively.

11. Conclusion

You've built a working hybrid campus lab that mixes Cisco IOSv VMs, IOSvL2 VMs, IOL-L2 containers, and Alpine Linux containers — all
defined in a single topology.yml and deployed with one command.

The key takeaway is simple: run every device in its native environment. Virtual machines for the NOSes that need them, containers for everything else, and let netlab handle the wiring between the two.

This foundation can be extended in many directions: add more vendors (Juniper vSRX, Arista cEOS, Nokia SR Linux), introduce EVPN/VXLAN fabric modules, or connect the lab to external networks. Whatever path you take, the hybrid approach ensures you get the best mix of performance, resource efficiency, and device fidelity.

Meet the Web Search MCP Server

Syed Asif — Wed, 24 Jun 2026 12:28:01 +0000

Your AI Needs Eyes on the Web

AI models are incredibly smart, but they have a blind spot. They only know what they were trained on, which means anything that happened after their training cutoff is invisible to them. Ask about last week's news, a GitHub issue from this morning, or the latest package release, and they'll either shrug or make something up.

That's where the Model Context Protocol (MCP) comes in. Think of MCP as a way to give your AI a toolbox. Each tool is a small program the AI can run when it needs fresh information. A calculator tool for math, a file system tool for reading your code, and most importantly - a search tool for looking things up on the web.

The Web Search MCP server is one of those toolboxes. It bundles search engines, social platforms, academic databases, and web page fetchers into a single server that any MCP-compatible AI client can use. Instead of guessing, your AI can go find the answer.

What the Model Context Protocol Actually Is

MCP is a standard way for AI applications to talk to tools and data sources. If you've used Claude Code, Cursor, or any AI coding assistant that can run commands or read files, you've already seen this idea in action - just through proprietary implementations.

MCP makes it universal. Any MCP client can connect to any MCP server. Your AI doesn't care whether the server is written in Python, TypeScript, or Go. As long as it speaks MCP, the tools just work.

The Web Search MCP server is written in Python using the FastMCP library, which handles all the protocol plumbing so the author could focus on the actual search logic.

A Tour of the Toolbox

The server groups its tools by what they're good at. Here's what you get out of the box.

General Web Search

Two search engines, one interface. DuckDuckGo for fast, free lookups. Exa as a fallback or primary provider when you need semantic search. You can scope results to a specific domain, filter by date, switch to news mode, or target a geographic region.

# Broad search
search_web(query="uv package manager")

# Targeted docs search
search_web(query="useEffect cleanup", domain="react.dev")

# News with region
search_web(query="elections", search_type="news", region="us-en")

# Last week only
search_web(query="Python 3.13 features", time_range="w")

Page Fetching

Search results give you snippets. Sometimes you need the full article. The fetch_page tool extracts clean text from any URL, stripping away ads, navigation, and JavaScript cruft. It supports a dozen output formats including markdown, JSON, and plain text.

fetch_page(url="https://docs.python.org/3/library/os.html")

Social and Community Intelligence

This is where the server really shines. It doesn't just search the open web - it taps into the platforms where real people discuss technology.

Reddit searches community discussions and returns top comments with scores. This is great for finding real user opinions, troubleshooting threads, and product recommendations.

Hacker News gives you access to technical discourse and startup discussions. The results include top comments and pre-extracted insights, so the AI can quickly understand the consensus without reading every reply.

GitHub lets the AI search issues and pull requests. It returns state labels, reaction counts, and top comments. This is invaluable for tracking bugs, understanding feature requests, or checking whether a breaking change has been discussed upstream.

X/Twitter provides real-time signal from breaking news and expert threads. It requires session cookies from a logged-in account, so it's not as plug-and-play as the others, but the real-time coverage is unmatched.

# Reddit
search_reddit(query="Best mechanical keyboards 2024",
              subreddits=["MechanicalKeyboards"])

# Hacker News
search_hackernews(query="MCP server architecture")

# GitHub
search_github(query="uv package manager")

# X/Twitter
search_x(query="Llama 4 release")

Academic and Reference

arXiv searches academic papers with Lucene field prefixes. You can search by author, category, title, or abstract.

Wikipedia pulls factual summaries for background research.

search_arxiv(query="transformer attention", max_results=10)
search_wikipedia(query="Model Context Protocol")

How It Actually Works Under the Hood

The server follows a clean architecture. A central server.py file creates a FastMCP instance and registers each tool with the @mcp.tool decorator. The tool's docstring becomes its description, which the AI reads to understand when to use it.

The actual logic lives in separate modules:

search/ handles DuckDuckGo and Exa integration
social/ handles Reddit, Hacker News, GitHub, and X
tools/ handles arXiv and Wikipedia
_http/ provides a centralized HTTP client with consistent timeouts and error handling
_config/ manages rate limits and environment variables
_models/ defines Pydantic models for type-safe requests and responses

The X/Twitter integration is the most interesting piece. Instead of using the official API (which requires expensive enterprise access), the server vendors a stripped-down version of the Bird CLI, a third-party tool that reverse-engineers Twitter's internal GraphQL API. This is why it needs browser session cookies rather than an API key.

The server also implements a rate limiter to prevent abuse. Each social tool has three depth tiers - quick, default, and deep - that control how many results and comments to fetch. This lets the AI request a quick skim or a deep dive without overwhelming the source platforms.

Setting It Up in Five Minutes

You need Python 3.11 or newer and the uv package manager.

uv tool install git+https://github.com/sydasif/web-search-mcp.git

Then add it to your MCP client configuration:

{
  "mcpServers": {
    "web-search": {
      "command": "web-search-mcp"
    }
  }
}

That's it for basic usage. All the search tools work without any API keys or authentication.

Optionally, you can set environment variables for additional features:

GITHUB_TOKEN or the gh CLI for authenticated GitHub searches
AUTH_TOKEN and CT0 (browser cookies from x.com) for X/Twitter search
EXA_API_KEY for Exa as an alternative search provider

A Real Research Workflow in Action

The repository includes a research skill that shows how these tools chain together.

A deep research session goes through three phases:

Broad discovery starts with search_web to map the landscape, then uses fetch_page to read the most promising articles in full.
Community mining fans out across Reddit, Hacker News, GitHub, and X using the platform-specific tools. Each platform reveals a different angle - HN for technical critique, Reddit for user experiences, GitHub for development signals, X for real-time reaction.
Synthesis combines everything into a structured report with source citations, confidence levels, and identified gaps.

The skill uses a source weighting system: official docs are highest confidence, community discussions are medium, and social media is treated as real-time signal that needs cross-referencing.

Best Practices

Let the fallback work for you. The default provider is auto, which tries DuckDuckGo first and falls back to Exa if the results are empty. This handles most cases without configuration.

Match result depth to your need. Use quick depth for simple answers (5 results). Use deep for comprehensive research (up to 60 results). The rate limiter will thank you.

Use JSON output for programmatic use. The default markdown output is great for human reading, but if you're building a pipeline, set response_format="json" and work with the structured data.

Cross-reference before trusting. No single platform gives you the full picture. If a claim appears on Reddit, Hacker News, and a blog post, that's stronger evidence than any one source.

What You Can Build With This

The Web Search MCP server turns your AI from a static knowledge base into an active researcher. You can ask it to investigate a bug by searching GitHub issues, check community sentiment on Reddit, read the relevant documentation, and summarize everything - all in one conversation.

The best next step is to install it and try a multi-source search. Ask your AI to research a topic using search_web for background, search_hackernews for technical discussion, and search_github for current development status. You'll quickly see the difference between an AI that guesses and an AI that finds out.

Acknowledgment: This blog is inspired by publicly available materials, standards, and community research or similar work. See full configuration at https://github.com/sydasif/web-search-mcp/wiki.

Refactoring and Optimization Workflows: Turning Messy Code into Clean, Fast Systems

Syed Asif — Sat, 30 May 2026 06:35:12 +0000

Introduction

You have working code that you dread touching. Variable names make no sense. The same logic appears in three places. It's slow on large inputs, and adding a new feature feels fragile.

Refactoring fixes that — and Claude Code makes it faster. This guide covers how to clean up, restructure, and optimize code without breaking what already works: spotting design patterns in spaghetti logic, improving performance, balancing simplicity against efficiency, and applying all of it to a real-world web scraper.

Principles of Clean Refactoring

Refactoring improves existing code without changing its external behavior. Not rewriting from scratch — making the code cleaner, more readable, and easier to maintain while keeping exactly what it does.

Three rules to hold throughout any refactor:

Maintain functional parity. Output before and after must be identical for the same input.
Simplify structure. Replace complex or duplicated logic with simpler, reusable functions.
Increase clarity. The new version should be more readable and aligned with your coding standards.

Example: Refactoring an Order Calculator

Original (works, but messy):

def calculate_order_total(items, discount_rate, tax_rate):
    total = 0
    for item in items:
        price = item['price']
        quantity = item['quantity']
        total += price * quantity
    discount = total * discount_rate
    total = total - discount
    tax = total * tax_rate
    total = total + tax
    return round(total, 2)

Problems: repeated variable reassignment, all logic in one function, no docstrings, hard to unit-test.

Prompt:

"Refactor this order total function for clarity and maintainability. Break it into smaller, reusable functions. Preserve the exact same behavior."

Claude's refactored version:

def calculate_order_total(items, discount_rate=0.0, tax_rate=0.0):
    """Calculate the total order price with discount and tax applied."""
    subtotal = _calculate_subtotal(items)
    discounted = _apply_discount(subtotal, discount_rate)
    total = _apply_tax(discounted, tax_rate)
    return round(total, 2)

def _calculate_subtotal(items):
    """Compute subtotal based on item prices and quantities."""
    return sum(item['price'] * item['quantity'] for item in items)

def _apply_discount(subtotal, discount_rate):
    """Apply discount to subtotal."""
    return subtotal * (1 - discount_rate)

def _apply_tax(amount, tax_rate):
    """Apply tax to the discounted amount."""
    return amount * (1 + tax_rate)

Validation test:

items = [{"price": 10.0, "quantity": 2}, {"price": 5.0, "quantity": 3}]

# Original inline calculation
original = 0
for item in items:
    original += item["price"] * item["quantity"]
original -= original * 0.1
original += original * 0.07
original = round(original, 2)

# Refactored
new_total = calculate_order_total(items, discount_rate=0.1, tax_rate=0.07)
print(original == new_total)  # Expected: True

True confirms behavior is preserved, structure improved.

Aspect	Before	After
Length	Single long function	Modular functions
Responsibility	Mixed	Each function handles one task
Extensibility	Hard to modify	Easy to adjust discount or tax rules
Testability	Hard to isolate	Unit-test friendly

Design Pattern Discovery

Patterns often emerge in code before they're named. Claude can recognize them — Singleton, Factory, Observer — even when they developed unintentionally, and refactor them into explicit, robust implementations.

Example: Discovering a Singleton Pattern

Original logger:

class Logger:
    def __init__(self):
        self.logs = []

    def log(self, message):
        self.logs.append(message)
        print(f"[LOG]: {message}")

logger = Logger()
logger.log("Application started.")

This works in a single module. Import it into multiple modules and each gets its own instance, breaking log consistency.

Prompt:

"This logger creates new instances when imported in different modules. Identify the design pattern it resembles and refactor it properly."

Claude's analysis: "This should be a singleton — one shared instance across the application. The basic __new__ override is the common introduction, but it's not thread-safe. In multi-threaded environments, two threads can check _instance is None simultaneously and both create an instance."

Thread-safe Singleton:

import threading

class Logger:
    _instance = None
    _lock = threading.Lock()

    def __new__(cls):
        if cls._instance is None:
            with cls._lock:
                # Double-checked locking: re-check after acquiring the lock
                if cls._instance is None:
                    cls._instance = super(Logger, cls).__new__(cls)
                    cls._instance.logs = []
        return cls._instance

    def log(self, message):
        self.logs.append(message)
        print(f"[LOG]: {message}")

Verification:

logger1 = Logger()
logger2 = Logger()
logger1.log("Application started.")
logger2.log("Processing data...")
print(f"Same instance? {logger1 is logger2}")  # True

One important caveat Claude should flag: for async frameworks (FastAPI, aiohttp, asyncio-based servers), threading.Lock doesn't work correctly. Use asyncio.Lock() with a factory method instead — __new__ can't be awaited. For most logging scenarios, a module-level singleton (a plain module-level instance) is simpler and avoids the problem entirely.

Optional: Factory pattern

class LoggerFactory:
    _logger = None
    _lock = threading.Lock()

    @staticmethod
    def get_logger():
        if LoggerFactory._logger is None:
            with LoggerFactory._lock:
                if LoggerFactory._logger is None:
                    LoggerFactory._logger = Logger()
        return LoggerFactory._logger

Use this when you want to separate creation from usage — useful when the logger initialization takes arguments or depends on configuration.

Pattern	Symptom in Code	Benefit
Singleton	Shared-state class instantiated repeatedly	Centralized control, consistent resource access
Factory	Objects created manually in multiple places	Clean separation of creation and usage
Observer	Event-driven callbacks without structure	Decoupled, maintainable event handling

Performance Optimization

Optimize where you have a measured bottleneck. Claude helps identify inefficiencies early, explains root causes, and proposes targeted improvements.

Example: Optimizing a Word Counter

Original (O(n²)):

def count_unique_words(file_path):
    unique_words = []
    with open(file_path, "r", encoding="utf-8") as f:
        for line in f:
            words = line.strip().split()
            for word in words:
                if word not in unique_words:  # O(n) scan per word
                    unique_words.append(word)
    return len(unique_words)

Each membership check scans the entire list. On a large file this compounds quickly.

Prompt:

"This function becomes very slow with large text files. Analyze and optimize it without changing its behavior."

Claude's reasoning: "List membership checks are O(n). Replace the list with a set for O(1) average lookups. Also normalize to lowercase for consistent deduplication."

Optimized (O(n)):

def count_unique_words(file_path):
    """Count unique words in a text file using a set for O(1) lookups."""
    unique_words = set()
    with open(file_path, "r", encoding="utf-8") as f:
        for line in f:
            for word in line.strip().split():
                unique_words.add(word.lower())
    return len(unique_words)

On a 10MB file the difference is minutes vs. milliseconds.

Focus	Problem	Recommendation	Impact
Data structure	List for membership checks	Replace with set	O(n) → O(1) average
Algorithm	Nested iteration	Simplify loop logic	Better scalability
Memory	Unbounded list growth	Hash-based collection	Reduced storage
I/O	Synchronous DB calls in async framework	Async or connection pooling	Faster throughput

Simplification vs. Efficiency

Not every optimization is worth its complexity. Sometimes the simpler code is the better choice.

Example: Filtering Even Numbers

Simple, readable version:

def filter_even_numbers(numbers):
    """Return all even numbers from the list."""
    return [n for n in numbers if n % 2 == 0]

Prompt: "Can this be optimized for performance if it needs to handle millions of integers, or should I keep it simple?"

Claude's reasoning: "List comprehensions run in C and are already fast. For most cases this is optimal. If your dataset exceeds available memory, a generator reduces memory overhead by yielding one element at a time."

Memory-efficient generator:

def filter_even_numbers_stream(numbers):
    """Yield even numbers lazily for large datasets."""
    for n in numbers:
        if n % 2 == 0:
            yield n

Trade-off:

import time
nums = list(range(10_000_000))

start = time.time()
filter_even_numbers(nums)
print("List comprehension:", round(time.time() - start, 3), "s")

start = time.time()
list(filter_even_numbers_stream(nums))
print("Generator:", round(time.time() - start, 3), "s")

Approach	Performance	Memory	Best Use
List comprehension	Fast for small-medium	Stores all results	General purpose
Generator	Slightly slower iteration	Streams one at a time	Large datasets, pipelines
NumPy vectorized	Very fast for numerics	Moderate	Numerical heavy lifting

Simplify where clarity yields lasting value. Optimize only where you have a measured bottleneck.

Example Project: Optimizing a Web Scraper

A complete example: take a slow synchronous scraper and turn it into a concurrent, fault-tolerant pipeline.

Baseline (Slow but Correct)

import time
import requests
from bs4 import BeautifulSoup

HEADERS = {"User-Agent": "MasteringClaudeCode/1.0"}

def fetch(url, timeout=10):
    resp = requests.get(url, headers=HEADERS, timeout=timeout)
    resp.raise_for_status()
    return resp.text

def parse(html):
    soup = BeautifulSoup(html, "html.parser")
    title = soup.title.string.strip() if soup.title else ""
    h1 = soup.find("h1").get_text(strip=True) if soup.find("h1") else ""
    return {"title": title, "h1": h1}

def scrape(urls):
    results = []
    for url in urls:
        html = fetch(url)
        data = parse(html)
        data["url"] = url
        results.append(data)
        time.sleep(0.2)  # polite delay
    return results

Problems: synchronous (waits for each request), no retries, no concurrency, fragile error handling.

Optimized (Concurrent, Robust)

import asyncio
import aiohttp
from bs4 import BeautifulSoup
import random

HEADERS = {"User-Agent": "MasteringClaudeCode/1.0"}
MAX_CONCURRENCY = 10
REQUEST_TIMEOUT = aiohttp.ClientTimeout(total=12, connect=5)

async def fetch(session, url, attempt=1, max_attempts=3):
    try:
        async with session.get(url) as resp:
            resp.raise_for_status()  # raises ClientResponseError for 4xx/5xx
            return await resp.text()
    except (aiohttp.ClientError, asyncio.TimeoutError):
        if attempt >= max_attempts:
            raise
        backoff = (2 ** (attempt - 1)) + random.uniform(0, 0.25)
        await asyncio.sleep(backoff)
        return await fetch(session, url, attempt + 1, max_attempts)

def parse_fast(html):
    soup = BeautifulSoup(html, "lxml")  # faster C-based parser
    title = soup.title.string.strip() if soup.title else ""
    h1 = soup.find("h1").get_text(strip=True) if soup.find("h1") else ""
    return {"title": title, "h1": h1}

async def scrape_one(semaphore, session, url):
    async with semaphore:
        try:
            html = await fetch(session, url)
            data = parse_fast(html)
            data["url"] = url
            return url, data, None
        except Exception as e:
            return url, None, str(e)

async def scrape(urls):
    semaphore = asyncio.Semaphore(MAX_CONCURRENCY)
    connector = aiohttp.TCPConnector(limit=MAX_CONCURRENCY)
    async with aiohttp.ClientSession(
        headers=HEADERS,
        timeout=REQUEST_TIMEOUT,
        connector=connector
    ) as session:
        tasks = [scrape_one(semaphore, session, url) for url in urls]
        results = []
        for coro in asyncio.as_completed(tasks):
            url, data, err = await coro
            results.append({"url": url, "error": err} if err else data)
        return results

Key changes Claude explains:

Concurrency. Async I/O overlaps requests, hiding network latency. Wall time drops from N * latency to roughly latency.
Connection pooling. TCPConnector reuses connections, reducing handshake overhead.
Timeouts and exponential backoff. Fails fast on slow endpoints and recovers from transient errors.
Faster parser. lxml is a C-based HTML parser — significantly faster than html.parser for large pages.
Structured error handling. Partial failures are captured per-URL rather than crashing the pipeline.

Note on raise_for_status(): The optimized version calls resp.raise_for_status() to handle 4xx/5xx responses. This is the correct pattern — aiohttp.ClientResponseError requires internal request_info and history arguments and should not be constructed manually.

Run it:

URLS = ["https://example.com", "https://httpbin.org/html"]
items = asyncio.run(scrape(URLS))

Optimization	What Changed	Why It Matters
Concurrency	Single-threaded → asyncio + semaphore	Overlaps I/O, wall time ≈ one request latency
Connection reuse	New TCP per request → pooled	Reduces handshake overhead
Timeouts + backoff	None → explicit + exponential	Faster failure, automatic recovery
Parser	`html.parser` → `lxml`	C-based, measurably faster on large HTML
Error handling	Exceptions crash pipeline → captured per-URL	Pipeline survives partial failures

Cost Considerations

Token costs are real for teams running Claude at scale. A few practices keep them under control.

Current API pricing (May 2026, per million tokens):

Model	Input	Output	Best For
Haiku 4.5	$1.00	$5.00	Simple refactors, repetitive tasks
Sonnet 4.6	$3.00	$15.00	General coding — best cost/quality ratio
Opus 4.7	$5.00	$25.00	Complex architecture, deep analysis

Prompt caching cuts input costs by up to 90%. The Batch API cuts everything 50%. Combined, costs can drop by up to 95% for high-volume workloads.

A rough cost estimator:

def estimate_cost(prompt: str, response_tokens: int, model: str = "sonnet") -> float:
    """Estimate API cost for a single request (USD)."""
    pricing = {
        "haiku":  {"in": 1.00, "out": 5.00},
        "sonnet": {"in": 3.00, "out": 15.00},
        "opus":   {"in": 5.00, "out": 25.00},
    }
    # ~4 chars per token
    in_tokens = max(1, len(prompt) // 4)
    p = pricing[model]
    return round(
        (in_tokens / 1_000_000) * p["in"] + (response_tokens / 1_000_000) * p["out"],
        6
    )

prompt = "Refactor this 200-line Python class for readability."
print(f"Estimated cost: ${estimate_cost(prompt, response_tokens=500, model='sonnet')}")

Cost-control habits:

Practice	Why It Helps
Match model to task complexity	Haiku for simple refactors; Opus only for deep architecture work
Keep a 2-4 sentence project anchor	Reduces repeated context tokens across turns
Ask for only what you need	"Return only the refactored function" cuts unnecessary output
Batch similar requests	Amortizes system tokens; 50% off with the Batch API
Trim context to relevant files	Large irrelevant context dilutes focus and burns tokens

Conclusion

Refactoring and optimization are small, intentional improvements that compound over time. With Claude Code you can decompose tangled functions into clean modules, name the patterns that already exist in your code, replace O(n²) lookups with O(1) data structures, and scale a synchronous scraper into a concurrent pipeline — without breaking what already works.

Try this: Pick a messy function from your own codebase. Prompt Claude: "Refactor this for clarity and maintainability. Preserve all behavior. Break it into smaller, reusable pieces." Run the validation test. Then profile before and after on real data if performance matters.

Acknowledgment: Based on official Anthropic documentation and community research. Technical details reflect the state of Claude Code as of May 2026.

Debugging and Code Review with Claude Code

Syed Asif — Thu, 28 May 2026 13:34:42 +0000

Introduction

You've written the code. It looks right. But when you run it, something breaks. The error message is cryptic, the stack trace points everywhere, and you've been staring at the same five lines for an hour.

Debugging is time-consuming. Claude Code makes it faster — not by magically finding bugs, but by reading your code, understanding what you intended it to do, and walking you through exactly what went wrong. This chapter covers how to use Claude Code as a debugging and code review partner: identifying bugs, automating reviews, testing fixes in real time, and building an iterative loop that improves your output.

How Claude Code Approaches Debugging

Claude Code doesn't just respond to your prompt in isolation. It runs an agentic loop: gather context, take action, verify results, repeat. For debugging, that looks like this:

Context gathering — Claude reads your code, file structure, imports, and dependencies. It looks for missing definitions, misused libraries, and structural issues.
Intent comparison — Claude compares your code's actual logic against its described purpose (from your prompt, docstrings, or comments) and identifies mismatches.
Fix and verification — Claude proposes a corrected version, explains its reasoning, and generates test cases you can run immediately.

You're part of this loop. You can interrupt at any point to provide more context, redirect Claude's approach, or push back on a suggestion. Claude works autonomously but stays responsive to your input.

Example: Fixing a Flask Discount Calculator

Buggy code:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/discount", methods=["POST"])
def discount():
    data = request.get_json()
    price = data.get("price")
    discount_rate = data.get("discount")
    discounted_price = price * discount_rate
    return jsonify({"discounted_price": discounted_price})

You expect {"price": 100, "discount": 0.2} to return 80.0. It returns 20.0 — the discount amount, not the final price.

Prompt:

"This Flask endpoint should return the final price after applying a discount, but it's returning the discount value itself. Find and fix the issue. Include the corrected code and explain what was wrong."

Claude's fix:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/discount", methods=["POST"])
def discount():
    """Calculate the final price after applying a discount."""
    data = request.get_json()
    price = data.get("price")
    discount_rate = data.get("discount")

    if price is None or discount_rate is None:
        return jsonify({"error": "Missing required fields"}), 400

    if not isinstance(price, (int, float)) or not isinstance(discount_rate, (int, float)):
        return jsonify({"error": "Invalid input types"}), 400

    discounted_price = price * (1 - discount_rate)
    return jsonify({"discounted_price": round(discounted_price, 2)})

Claude's explanation: the original formula computed the discount amount (price * discount_rate) instead of the final price (price * (1 - discount_rate)). It also added input validation to handle missing or wrongly-typed fields — a common real-world failure mode the original code silently ignored.

Automated Code Review

Claude can read, analyze, and critique code in real time — flagging logic issues, security risks, and performance problems before they hit production.

The workflow is three steps:

Context ingestion — provide the relevant file or diff. Claude builds an internal model of what the code does.
Evaluation — Claude reviews logic, structure, naming, performance, and maintainability, and explains why each issue matters.
Structured feedback — Claude returns actionable output you can use directly in pull request comments.

Example: Reviewing a FastAPI Endpoint

Code under review:

from fastapi import FastAPI
import sqlite3

app = FastAPI()

@app.get("/users")
def get_users():
    conn = sqlite3.connect("database.db")
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM users")
    users = cursor.fetchall()
    conn.close()
    return {"users": users}

At first glance this works. Claude will catch four issues: it uses synchronous SQLite inside an async framework, blocking the event loop; there's no error handling; it selects all columns with SELECT * rather than explicit fields; and future parameter additions could introduce SQL injection.

Prompt:

"Review this FastAPI endpoint for code quality, security, and performance. Identify issues, explain their impact, and propose corrected code following current best practices."

Claude's suggested fix (using the current lifespan pattern — @app.on_event has been deprecated since FastAPI 0.93):

from contextlib import asynccontextmanager
from fastapi import FastAPI, HTTPException
from databases import Database

DATABASE_URL = "sqlite:///database.db"
database = Database(DATABASE_URL)

@asynccontextmanager
async def lifespan(app: FastAPI):
    await database.connect()
    yield
    await database.disconnect()

app = FastAPI(lifespan=lifespan)

@app.get("/users")
async def get_users():
    """Retrieve all users asynchronously."""
    try:
        query = "SELECT id, username, email FROM users"
        users = await database.fetch_all(query=query)
        return {"users": [dict(user) for user in users]}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

Key changes: async I/O via the databases library, explicit column selection, proper error handling, and the lifespan context manager instead of the deprecated @app.on_event decorators.

Review Focus Areas

Area	What Claude Checks	Example Feedback
Security	SQL injection, unsafe evals, hardcoded secrets	"Avoid string interpolation in SQL queries."
Performance	Blocking I/O, missing caching, inefficient queries	"Replace sync DB calls with async equivalents."
Readability	Naming, docstrings, structural clarity	"Add docstrings to API routes."
Compliance	PEP8, project conventions, CLAUDE.md rules	"Use context managers for database sessions."

Interpreting Claude's Feedback

Claude's suggestions are starting points, not commands. Two things determine whether to accept them:

Does it make sense in your environment? A "best practice" in one context is wrong in another. Claude's context is limited to what you provided. If you omitted key files or constraints, its feedback will reflect those gaps.

Does it match your intent? Claude reasons about what the code probably needs. You reason about what it actually needs. Those aren't always the same.

Example: Evaluating a Suggestion You Should Modify

Original code:

class FileReader:
    def __init__(self, file_path):
        self.file_path = file_path

    def read(self):
        file = open(self.file_path, "r")
        data = file.read()
        file.close()
        return data

Claude's feedback: "Use a context manager (with statement) to ensure the file closes automatically even if an error occurs."

Claude's suggested fix:

class FileReader:
    def __init__(self, file_path, chunk_size=8192):
        self.file_path = file_path
        self.chunk_size = chunk_size

    def read(self):
        """Read file in chunks for memory efficiency."""
        try:
            with open(self.file_path, "r", encoding="utf-8") as file:
                for chunk in iter(lambda: file.read(self.chunk_size), ""):
                    yield chunk
        except FileNotFoundError:
            raise FileNotFoundError(f"File not found: {self.file_path}")
        except Exception as e:
            raise RuntimeError(f"Error reading file: {e}")

The developer accepted the context manager suggestion but adapted the rest for their actual needs — chunked reading for large files. Claude's reasoning ("safe file handling") was the right principle; the specific implementation needed adjustment for the workload.

Feedback Types

Type	What It Means	How to Evaluate
Corrective	Fixes an error or unsafe pattern	Test in your environment before accepting
Advisory	Suggests a best practice	Check relevance to your project standards
Speculative	"You could also..." optional improvement	Evaluate the trade-off before adopting
Context-limited	Based on incomplete information	Re-prompt with the missing files or context

Testing Fixes in Real Time

The fastest path from bug to fix is an iterative loop: show Claude the problem, get a fix, test it, feed results back. Claude participates in every step.

The loop:

Show Claude the buggy code and describe what's wrong.
Claude suggests a fix with explanation.
Run the fix locally, or ask Claude to generate test cases.
Feed results back — if it still fails, Claude reasons about why and adjusts.
Repeat until resolved.

Example: Empty List Error

Buggy code:

def calculate_average(numbers):
    total = sum(numbers)
    return total / len(numbers)

Calling calculate_average([]) raises ZeroDivisionError.

Prompt:

"This function crashes on empty lists. Fix it and show how to test it."

Claude's fix:

def calculate_average(numbers):
    """Calculate the average of a list of numbers. Returns 0 for empty lists."""
    if not numbers:
        return 0
    return sum(numbers) / len(numbers)

Claude's tests:

print(calculate_average([10, 20, 30]))  # Expected: 20.0
print(calculate_average([]))            # Expected: 0
print(calculate_average([5]))           # Expected: 5.0

Developer follow-up: "Tests pass. But I'd prefer a ValueError instead of returning 0 for empty lists."

Claude's adjustment:

def calculate_average(numbers):
    """Calculate the average of a list of numbers. Raises ValueError for empty input."""
    if not numbers:
        raise ValueError("Cannot calculate average of an empty list.")
    return sum(numbers) / len(numbers)

Updated test:

try:
    print(calculate_average([10, 20, 30]))  # Expected: 20.0
    calculate_average([])                   # Expected: ValueError
except ValueError as e:
    print(f"Caught expected exception: {e}")

One follow-up message changed the behavior contract without restarting the conversation. That's the loop working as intended.

Human-in-the-Loop Debugging

Claude is most effective when you steer the reasoning rather than hand it the wheel entirely. The productive pattern is:

Phase	Your Role	Claude's Role
Framing	Define the problem, expected behavior, and environment	Build an understanding of the context
Hypothesis generation	Evaluate theories for relevance to your setup	Propose likely causes and affected areas
Validation	Run the code, confirm or disprove	Interpret results, propose next steps
Refinement	Provide feedback on each fix	Adjust the approach based on new information

Example: API Timeout Bug

Buggy code:

import requests

def fetch_data(url):
    response = requests.get(url)
    return response.json()

The function occasionally hangs when an API is slow.

Prompt: "This function sometimes gets stuck waiting for a response. The API is valid. Can you help find out why?"

Claude's diagnosis: requests.get() waits indefinitely by default. The timeout parameter controls this.

Claude's fix:

import requests

def fetch_data(url, timeout=5):
    try:
        response = requests.get(url, timeout=timeout)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.Timeout:
        print("Request timed out.")
        return None
    except requests.exceptions.RequestException as e:
        print(f"An error occurred: {e}")
        return None

Follow-up: "This works, but I still get a JSONDecodeError sometimes."

Claude: "That happens when the response isn't valid JSON — usually a server returning HTML for an error state. Check the Content-Type header before parsing."

Refined version:

import requests
import json

def fetch_data(url, timeout=5):
    try:
        response = requests.get(url, timeout=timeout)
        response.raise_for_status()

        if "application/json" not in response.headers.get("Content-Type", ""):
            print("Response is not JSON.")
            return None

        return response.json()

    except json.JSONDecodeError:
        print("Invalid JSON in response.")
        return None
    except requests.exceptions.Timeout:
        print("Request timed out.")
        return None
    except requests.exceptions.RequestException as e:
        print(f"An error occurred: {e}")
        return None

Each follow-up pushed the fix one step further. Claude didn't invent the second bug — you found it through testing and brought it back.

Collaborative Debugging in Practice

Example: Email Validator

Initial code:

import re

def is_valid_email(email):
    pattern = r"^[a-zA-Z0-9]+@[a-zA-Z]+\.[a-zA-Z]+$"
    return bool(re.match(pattern, email))

This rejects valid addresses like john.doe@sub.domain.org.

Prompt: "This regex rejects some valid emails like 'john.doe@sub.domain.org'. Debug and improve it — keep the function simple and secure."

Claude's diagnosis: The pattern disallows dots and hyphens in both the local part and domain, and doesn't handle subdomains.

Claude's fix:

import re

def is_valid_email(email):
    """Validate an email address. Allows dots, hyphens, and subdomains."""
    pattern = r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
    return bool(re.match(pattern, email))

Test suite:

emails = [
    "user@example.com",
    "john.doe@sub.domain.org",
    "user-name@company.co.uk",
    "invalid@domain",
    "@missinguser.com"
]

for e in emails:
    print(f"{e}: {is_valid_email(e)}")

Expected output:

user@example.com: True
john.doe@sub.domain.org: True
user-name@company.co.uk: True
invalid@domain: False
@missinguser.com: False

Best Practices

Situation	What to Do	Why
Reporting a bug	Include the error trace and source snippet	Claude's reasoning improves with the full failure context
Generating tests	Describe expected behavior in plain English	"The function should raise ValueError if input is empty"
Code review	Ask Claude to review intent, not just syntax	Catches logic mismatches, not only typos
Testing fixes	Feed results back to Claude iteratively	Enables targeted follow-up without restarting
Trusting suggestions	Verify in your environment	Claude's context is limited to what you provided
Framework-specific code	Specify library versions	Prevents Claude from suggesting deprecated APIs

Conclusion

Claude Code works best as a reasoning partner in a loop: you frame the problem, Claude proposes a diagnosis and fix, you test it and report back, Claude adjusts. The quality of that loop depends on the quality of your framing — clear descriptions of expected behavior, actual error output, and relevant context get better results than vague bug reports.

You now have the mechanics for each part of that loop: context-aware bug identification, structured code review, iterative fix testing, and the human-in-the-loop phases that keep the process on track.

Next step: Take a buggy function from your own codebase. Paste it into Claude with the error output and a clear description of what it should do. Work through the loop — hypothesis, fix, test, refine. The time from problem to working code will surprise you.

Acknowledgment: Based on official Anthropic documentation and community research. Technical details reflect the state of Claude Code as of May 2026.

Prompting Foundations for Developers — How to Talk to Claude So It Listens

Syed Asif — Thu, 28 May 2026 05:19:52 +0000

Introduction

You've installed Claude Code. You've sent a few prompts. But when you ask for something real — "write a login system" — the output feels generic, incomplete, or misses the point entirely.

The problem is almost always the prompt. That's fixable.

This chapter covers the exact structures and habits that turn vague requests into production-ready code: what Claude needs to know before it writes anything, how to trigger its reasoning instead of its pattern-matching, how to feed it multiple files without losing context, and how to lock in project-wide standards with CLAUDE.md.

What Claude Needs Before It Writes

Before Claude produces a single line, it resolves three things from your prompt:

What to build. "A login system" could mean a simple password check, a full OAuth flow, or a JWT-based API endpoint. Claude picks one. If you didn't specify, it guessed.
How it should behave. Should it block on errors or return structured error responses? Log failures? Validate inputs? Hash passwords? Silence on these means Claude chooses defaults — often the simplest ones.
What the result should look like. A single function? A module? A class with docstrings? Raw code or code with explanation?

Leave any of these unanswered and Claude fills the gap. The output won't be wrong exactly — it just won't be what you had in mind.

A useful mental check before sending: What, How, Format. Three seconds to answer those three questions will consistently improve what comes back.

Writing Prompts That Work

Weak vs. Strong

Weak:

"Write a function to handle user authentication."

Claude produces a bare-bones username/password check. No error handling, no hashing, no structure. Technically functional, not shippable.

Strong:

"Write a Python function using FastAPI that handles user authentication with JWT tokens. Verify credentials against the database, issue tokens that expire in 15 minutes, and return structured JSON responses. Include docstrings and a comment explaining each step."

Four additions: framework (FastAPI), language (Python), expected behavior (JWT, expiration, JSON responses), output format (docstrings, comments). Claude now knows what "done" looks like.

Chain-of-Thought Prompting

Claude reasons more carefully when you ask it to reason before it codes. This is chain-of-thought prompting — and it's worth knowing how it fits alongside Claude's newer capabilities.

Without it:

"Write a FastAPI endpoint that calculates factorial."

Claude often produces a recursive function with no input validation. It works for positive integers. It breaks on negatives and very large values.

With it:

"Before coding, outline your approach for a FastAPI endpoint that accepts a number and returns its factorial. Then write the full implementation with input validation, error handling, and comments."

Claude first lists its plan — input schema, recursion vs. iteration, edge cases (negative numbers, zero, large values), JSON output — then writes code that matches it. The result is safer and easier to debug.

One important nuance: Chain-of-thought prompting was the standard approach before Claude's extended thinking feature. Extended thinking (available on Sonnet 4.6 and Opus 4.6/4.7) gives Claude a separately-budgeted reasoning pass before generating output — you can inspect that reasoning trace in the API response. For complex coding tasks, extended thinking generally produces better results than manual chain-of-thought prompting. If you're on a plan that supports it, enable it for architecture decisions, complex debugging, and multi-step refactors. Manual chain-of-thought remains useful when extended thinking isn't available or when you need the reasoning to appear inline in Claude's response.

For either approach, Anthropic's docs note one consistent finding: always have Claude output its thinking. If the reasoning doesn't appear in the response, no reasoning step ran.

Multi-File Prompts

Real projects span multiple files. Claude handles them well — if you structure the input clearly.

Bad approach: Dump five files into a prompt with no labels. Claude loses track of which code belongs to which file and what the relationship between them is.

Good approach: Label each file with a clear header and state your goal upfront.

Claude, I'll share two FastAPI files. Analyze how validation is handled
across both and refactor them to remove redundancy.

## FILE: validators.py
[code here]

## FILE: main.py
[code here]

Provide the complete corrected code for both files.

Claude reads the structure, understands the relationship between modules, and refactors across both in one pass. The 1M-token context window on Sonnet 4.6 and Opus 4.6/4.7 means you can feed in large codebases this way — many files, full documentation, test suites.

CLAUDE.md: Project-Wide Standards

The blog's original framing of "system prompts" is accurate for API usage, but in Claude Code the standard mechanism is CLAUDE.md — a file you place in your project root (or in subdirectories for local rules). Claude reads it automatically at session start.

A CLAUDE.md might contain:

# Project Standards

- Language: Python 3.12, FastAPI 0.115
- Always include docstrings on public functions
- Use Pydantic v2 models for request/response schemas
- Never use eval() or exec()
- All database queries go through the repository layer — no raw SQL in route handlers
- Secrets come from environment variables only

Claude automatically merges multiple CLAUDE.md files based on directory structure — global rules in the root, local overrides in subdirectories. This mirrors how senior engineers think: project-wide conventions plus file-specific constraints.

For API usage, system prompts work the same way — set them once, and every request in the session inherits the standards.

On security guardrails specifically: treat prompts like logs. Assume they can be inspected. Don't put secrets or credentials in prompts. Lock down tool permissions to what Claude needs for the task. For anything touching authentication or access control, keep a human in the review loop.

Best Practices

For Beginners

Run the What, How, Format check before every prompt.
Paste actual error messages when debugging. Claude diagnoses errors well when it sees the full stack trace, not a paraphrase of it.
Ask Claude to explain its reasoning: "Why did you choose an iterative approach over recursion?" The answer teaches you how it's modeling the problem.

For Experienced Developers

Commit a CLAUDE.md to every project. Keep it short and explicit — specific rules outperform long documentation.
Label files clearly in multi-file prompts. State the goal at the top, then paste the files.
Use extended thinking for complex tasks. Set effort to xhigh for coding and agentic work — Anthropic's own docs recommend this as the default for most development use cases.
For very long autonomous runs, use sub-agents: "You just wrote the payment processor. Now use a sub-agent to run a security review on that code." This keeps the main conversation focused while the review runs in a separate context.

Common Prompting Errors

Problem	Likely Cause	Fix
Generic output	Prompt missing framework, format, or behavior constraints	Add specific language, library, and output requirements
Output cuts off	Hitting max token limit	Ask for output in sections, or summarize then expand
Claude ignores part of the prompt	Too many instructions at once	Break into sequential prompts
Wrong imports or syntax	Missing version context	Specify library versions: "FastAPI 0.115, Pydantic v2"
Claude contradicts earlier decisions	Context drift	Re-anchor: "We're still using FastAPI 0.115 with PostgreSQL"

Prompts as Dialogue

The developers who get the most out of Claude treat prompting as a conversation, not a one-shot command. Start broad enough to test Claude's interpretation of the problem. Refine based on what comes back. Ask it to defend its choices.

Each iteration improves the output. Over time you develop a sense for when to be specific and when to leave room for Claude to interpret — when a tight spec produces better code and when a looser framing surfaces a better architecture. Anthropic's own best practices guide puts it plainly: sometimes a vague prompt is exactly right, because you want to see how Claude interprets the problem before constraining it.

Conclusion

Prompting is a skill with a short learning curve and a long ceiling. The foundations: answer What, How, Format before you send anything; use chain-of-thought or extended thinking for tasks that require reasoning; label multi-file inputs clearly; store project standards in CLAUDE.md so you don't repeat yourself every session.

Try this: Take a piece of code you wrote recently. Write a weak prompt — just "improve this function." Then write a strong one using the three questions. Compare what Claude returns. The difference will be obvious, and you won't go back to vague prompts.

Acknowledgment: Based on official Anthropic documentation and community research. Technical details reflect the state of Claude Code as of May 2026.

How Claude Code Thinks: Inside Your AI Coding Assistant

Syed Asif — Thu, 28 May 2026 04:50:14 +0000

Introduction

You've set up Claude Code and sent your first prompt. Now the question is: how does it actually understand what you wrote?

This guide covers what happens under the hood — how Claude reads code, what tokens and context mean in practice, and why it sometimes drops details from earlier in a conversation. Understanding these mechanics will change how you prompt.

How Claude Reads Code

Claude doesn't execute your code. It processes text. Three stages build its understanding:

1. Parsing and context formation. Claude breaks your prompt into tokens and maps relationships between them — which function calls which, where a variable appears, how control flow branches. The output is a structural model of your code.

2. Reasoning and pattern matching. Claude compares that model against patterns from training. A sorting function that resembles merge sort gets treated like merge sort. That match drives what Claude predicts you need next.

3. Generation and justification. Claude writes its response token by token, checking for coherence and safety at each step. The comments you see — "This variable is unused," "This may fail on empty lists" — come from this stage, not from running the code.

Claude is probabilistic. Two similar prompts may produce different answers. That's reasoning, not a bug.

Tokens and Context Windows

A token is a small chunk of text. Claude averages 4 characters per token, or about 1.5 tokens per word in English. For code that number rises — brackets, operators, and keywords don't map cleanly to natural language tokens.

Practical scale:

print("Hello") is 3–4 tokens
A typical function is 50–200 tokens
1,000 tokens is roughly 750 words of English prose

The context window is Claude's working memory for a session. It holds your prompts, Claude's responses, uploaded files, and tool outputs — all from the same token budget. Current models as of May 2026:

Model	Context	Best For
Claude Haiku 4.5	200K	Quick fixes, low-latency tasks
Claude Sonnet 4.6	1M	General coding, refactoring, multi-file work
Claude Opus 4.6 / 4.7	1M	Deep analysis, full-stack architecture, large codebases

The 1M window on Sonnet 4.6 and Opus 4.6 went live at standard pricing in March 2026. The older Claude 3 series is deprecated. Claude 3 Haiku is fully retired — requests to it now return errors.

When a session fills up, Claude drops the oldest tokens first. Recent messages stay. That's why early details can go missing in long conversations.

One more thing worth knowing: research has documented a "lost in the middle" effect — attention quality drops for content buried in the center of a very large context. Put your most important constraints, framework choices, and goals at the top of a session.

The Request-Response Lifecycle

Four stages happen every time you send a prompt.

Stage 1 — Tokenization. Claude converts your input to token IDs. It processes your message together with conversation history, loaded files, system prompts, and any command outputs. Longer sessions accumulate tokens faster because the input compounds.

Stage 2 — Context assimilation. Claude merges the new prompt with history and runs self-attention, weighting which parts matter most. Constitutional AI constraints apply here — unsafe requests get flagged before generation starts.

Stage 3 — Generation. Claude produces output token by token. It checks coherence and safety continuously. You'll often see Claude frame its approach before writing code — that framing is the alignment step.

Stage 4 — Memory update. Claude adds the response to its in-session context. That's why "now optimize the async performance" works — Claude knows which code you mean. Close the session and that context is gone.

Memory and Conversation State

Within a Session

Claude holds everything in the active context window. As it fills, the oldest tokens drop. Re-anchoring every few turns keeps Claude oriented:

"We're still on the FastAPI e-commerce API with JWT auth and PostgreSQL. Now add order history."

Across Sessions

By default, Claude Code starts each session from scratch. Stateless architecture is simpler to reason about and easier to scale — this is intentional, not an oversight.

Anthropic rolled out auto-memory for Claude Code in early 2026. Claude now builds and maintains a MEMORY.md file during sessions, storing key decisions and context that load automatically next time. The feature is on a gradual rollout; your account may need it enabled.

The manual alternative: keep a .claude/ directory with a context.md or decisions/ folder. Claude reads these at session start.

A session_notes.txt with key decisions and code snippets also works well. Paste it in at the top of each new session if auto-memory isn't available yet.

API vs. IDE

Claude Web and IDE integrations maintain context within the open session automatically. The Claude API is stateless by default — you send conversation history with each request to maintain continuity. More work, but also more control.

Which Model to Use

Model	Context	Use When
Haiku 4.5	200K	Repetitive tasks, test generation, quick completions
Sonnet 4.6	1M	Everyday coding — best cost-to-capability ratio
Opus 4.6 / 4.7	1M	Legacy refactors, complex multi-file reasoning, long-context analysis

Use Haiku for "add a docstring to every function." Use Sonnet for most development work. Bring in Opus when you need to untangle something genuinely complex — a legacy monolith, an architecture decision with many constraints, a long document to reason over. Using Opus for a typo fix costs you money and time.

Best Practices

For Beginners

Start small. Token awareness develops naturally as you work.
If Claude loses track of earlier context, restate your goal explicitly.
The web interface handles context management for you.

For Power Users

Front-load key facts. Your framework, language, and hard constraints belong at the top of the session, not buried in message 15.
Re-anchor every few turns. "Still on the FastAPI project, PostgreSQL backend" keeps Claude from drifting as context accumulates.
Segment sessions by topic. Start a new session when you switch from backend to frontend work.
Build explicit context for the API. Send prior messages in each request, or use the MEMORY.md / .claude/ pattern to persist decisions.

Common Mistakes

Assuming Claude remembers yesterday. It doesn't by default. Save summaries or enable auto-memory.
Pasting 50,000-line files wholesale. Large undifferentiated inputs dilute attention. Start with the relevant files and expand from there.
Reaching for Opus by default. Sonnet 4.6 handles most development tasks well and costs significantly less.
Referencing retired models. Claude 3 Haiku returns errors now. Claude 3 Sonnet and Opus are deprecated. Use the 4.x series.

Conclusion

Claude Code is a reasoning engine with a finite but large working memory. You now understand how it reads code, how tokens accumulate across a session, the four stages it runs on every request, and how to manage context across sessions and model choices.

Try this: Open a fresh session and build a small API across several turns. After a few exchanges, change the subject entirely, then bring Claude back to the original task. Watching how it re-anchors — or loses the thread — makes the mechanics concrete.

Acknowledgment: Based on official Anthropic documentation and community research. Technical details reflect the state of Claude Code as of May 2026.

Getting Started with Claude Code: Your First AI Coding Partner

Syed Asif — Thu, 28 May 2026 04:44:35 +0000

Introduction

Claude Code is a pair programmer that never gets tired, explains every suggestion, and reads your entire project at once. But it's not a chat interface with a coding plugin. It's an agentic CLI that runs in your terminal, reads and writes files, manages Git, and reasons across your full codebase.

This guide covers what sets Claude Code apart, how to install it, and how to run your first prompt. By the end you'll know how to treat it as a collaborator rather than an autocomplete.

Core Concepts

What Claude Code Actually Is

Claude Code is Anthropic's official command-line interface for AI-assisted development. It runs in your terminal and can:

Read and write files directly in your project
Execute commands
Manage Git workflows — branches, commits, pull requests
Reason across up to 1 million tokens of codebase context
Connect to external services via MCP (Model Context Protocol)
Surface its reasoning in plain English before acting

It runs on Sonnet 4.6 by default for Pro users, Opus 4.6 on Max plans. Before taking any file-altering action, it asks for confirmation and shows its plan — that's the Constitutional AI framework in practice.

How Claude Code Compares

Feature	Claude Code	Typical autocomplete tools
Type	Agentic CLI	IDE plugin or chat interface
Focus	Multi-file reasoning and agentic tasks	Predicting the next line
Context	Up to 1M tokens	Current file or limited window
Actions	Reads/writes files, runs commands, manages Git	Suggests code you paste manually
Safety	Confirms before file changes	Basic filtering

Claude Code handles large-scale refactoring, cross-file bug fixes, and infrastructure tasks end to end. It's a different category from autocomplete.

Installation and Your First Prompt

Step 1 — Choose Your Access Method

Three ways to use Claude Code:

Claude Web (claude.ai) — No installation. Good for experimenting with prompts.
Claude Code CLI — The core tool. Runs from any terminal, works over SSH, scriptable in CI/CD pipelines.
IDE Extension — A VS Code extension (also works in Cursor, Windsurf, and Kiro) that surfaces inline diffs and accept/reject controls without leaving your editor.

Installing the CLI

To install Claude Code, use one of the following methods:

macOS, Linux, WSL:

curl -fsSL https://claude.ai/install.sh | bash

Or install Node.js 18+ first, then:

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

Run claude in your terminal and complete the OAuth flow to authenticate. Verify with:

claude doctor

Install with Linux package managers

For Debian and Ubuntu. To use the rolling channel, change both stable occurrences in the deb line: the URL path and the suite name.

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Verify the GPG key fingerprint before trusting it: gpg --show-keys /etc/apt/keyrings/claude-code.asc should report 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE.

To upgrade later, run sudo apt update && sudo apt upgrade claude-code.

Setting Up in VS Code

Open the Extensions view (Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on Mac), search for Claude Code, and click Install. Sign in with your Anthropic account on first launch.

The extension also installs the first time you run claude from VS Code's integrated terminal. It works identically in Cursor, Windsurf, and other VS Code forks.

Once installed, click the Spark icon in the sidebar. You get real-time inline diffs, plan review before Claude touches any files, @-mention support for specific files and line ranges, and conversation history across tabs.

Setting Up in Cursor

Run Claude Code from Cursor's integrated terminal for heavy agentic tasks. Use Cursor's Composer for interactive editing. The two tools operate at different speeds and task scales — they complement each other.

Setting Up in Zed

Since Zed 1.0, Claude Code is native to Zed's Agent Panel via ACP (Agent Client Protocol). No separate installation. Zed is built in Rust with GPU-accelerated rendering.

Pick your entry point: VS Code if you're already there. Cursor for deep project-wide IDE features alongside agentic work. Zed for raw performance.

Step 2 — Your First Prompt

Open your chosen interface and send this:

"Hello Claude! Please write a Python program that prints 'Hello, Claude!' and then explains, in a comment, what each line of the code does."

Claude responds:

# Assign the string 'Hello, Claude!' to the variable 'message'
message = 'Hello, Claude!'

# Use the print() function to display the value of 'message' in the console
print(message)

It explained each line without being asked. That's the default behavior — Claude assumes you want to understand the code, not just copy it.

Now push further:

"Rewrite it in JavaScript and explain the differences."

Claude produces a JavaScript version and explains that const replaces Python's implicit assignment and console.log() replaces print():

// Assign the string 'Hello, Claude!' to the variable 'message' using const
const message = "Hello, Claude!";

// Use console.log() to display the value in the console
console.log(message);

Step 3 — Iterate

"Update the Python version to ask for my name, greet me personally, and show the current time."

Claude adds input(), imports datetime, and returns a runnable script:

import datetime

# Ask the user for their name
name = input("What is your name? ")

# Greet the user by name
print(f"Hello, {name}!")

# Display the current system time
current_time = datetime.datetime.now().strftime("%H:%M:%S")
print(f"The current time is {current_time}.")

Each follow-up request revises Claude's reasoning and output. Treat it as a conversation, not a one-shot query.

Best Practices

For Beginners

Start with the web interface — no setup, immediate feedback.
Ask Claude to explain every decision. The reasoning is often more useful than the code.
Make small, specific requests. Vague prompts produce vague output.

For Experienced Developers

Install the CLI and IDE extension. You'll cut context switching significantly.
Use chain-of-thought prompts: ask Claude to "think step by step" before writing code on complex problems.
Put your full codebase in context. Claude reads 1M tokens — use it on large files and documentation.
Describe Git tasks in plain language. Claude Code creates branches, writes commit messages, and opens pull requests.

Common Mistakes

Vague bug reports produce vague fixes. Instead of "fix this bug," say: "The function should return X but returns Y. Here's the code and the error."
Ignoring Claude's explanations wastes the tool's main advantage. Read the reasoning.
Single-prompt expectations don't match how Claude works best. Iterate.
Using Claude Code for line completions is like using a chainsaw to slice bread. Save it for multi-file, multi-step tasks.

Conclusion

Claude Code is an agentic CLI that reads your codebase, executes commands, manages your Git workflow, and explains every decision. You now know:

What it is and how it differs from autocomplete tools
How to install the CLI and configure VS Code, Cursor, or Zed
How to run and iterate on your first prompt

Next step: Install the CLI, send that first "Hello, Claude!" prompt, then try something harder — ask it to refactor a real file, add error handling, or commit a change. The scope of what it can do autonomously becomes clear quickly.

Acknowledgment: Based on official Anthropic documentation and community research. Technical details reflect the state of Claude Code as of May 2026.