There is a particular kind of panic running through the software industry right now. It lives in Slack threads and conference hallways. It sounds like this: If AI can write code, what exactly am I for?

It is the wrong question. Not because AI cannot write code — it can, increasingly well — but because it confuses the activity with the value. A software engineer’s value was never in typing syntax. It was in deciding what to build, how the pieces fit, and what to leave out. These are acts of judgment. And judgment is the one thing AI cannot automate, because judgment requires accountability — someone who lives with the consequences.

The engineers who will thrive in the age of AI are not the ones who resist it or the ones who surrender to it. They are the ones whose architectural judgment turns AI from a parlor trick into a force multiplier.

This essay is about what that judgment looks like in practice.

1. The Judgment Gap

AI can generate a function that parses JSON. It can scaffold a REST API. It can write a passable database migration. What it cannot do is answer the question that precedes all of these: should this exist at all?

That question is architectural. It lives upstream of code. It asks: does this service need to be separate, or is it premature decomposition that will cost us three years of distributed debugging? Should this data be denormalized for read performance, or will that decision make the inevitable schema migration a nightmare? Is this the right abstraction boundary, or are we drawing lines based on our org chart rather than our domain model?

These decisions are not hard because we lack information. They are hard because they require weighing incommensurable concerns — development speed against operational complexity, team autonomy against system coherence, present convenience against future optionality. They are irreducible judgment calls.

The staff engineer is not the one who writes code quickly. It is the one who decides correctly which code should never be written.

AI collapses the cost of producing code toward zero. That sounds like it makes engineers less valuable. In fact, it makes judgment more valuable, because the cost of producing the wrong code has also collapsed toward zero — which means organizations will produce far more wrong code, far faster, unless someone is applying judgment at the architectural layer.

2. Core Architectural Decisions That AI Cannot Make

Let’s be concrete. Here are the categories of decisions where human judgment remains irreplaceable — not because AI lacks knowledge, but because these decisions require owning trade-offs that have no objectively correct answer.

System Boundaries

Where do you draw the lines between services, modules, or teams? This is simultaneously a technical decision (coupling, cohesion, data ownership) and an organizational one (Conway’s Law is real). AI can suggest microservice boundaries based on domain analysis. It cannot know that your payments team just lost two senior engineers and cannot own an independent service right now. That context is judgment.

Consistency vs. Availability

The CAP theorem is not a trivia question — it is a business decision. When the network partitions, does your system prioritize returning a correct answer (at the cost of availability) or returning some answer (at the cost of correctness)? An e-commerce cart can tolerate stale data. A financial ledger cannot. AI can explain the theorem. It cannot decide which trade-off your business can survive.

Build vs. Adopt vs. Defer

Every component in your system represents a choice: build it yourself, adopt an existing tool, or defer the decision entirely. AI biases toward building because generating code is what it does. An experienced architect knows that the best architectural decision is often not yet — keeping options open until the problem is better understood. This is negative capability, and it is one of the hardest skills to develop.

Failure Mode Design

Every system fails. The architectural question is not “how do we prevent failure” but “how does this system degrade?” Do orders queue and retry, or do they fail immediately with a clear error? Does the recommendation engine fall back to popularity-based suggestions, or does it show nothing? These are product decisions expressed as architecture, and they require understanding the business impact of each failure scenario.

Reversibility Assessment

Some decisions are two-way doors: easy to reverse if wrong. Others are one-way doors: the migration to a new database engine, the public API contract, the choice of cloud provider at scale. The judgment lies in classifying decisions correctly. Over-deliberating a two-way door wastes time. Under-deliberating a one-way door creates years of regret.

3. AI as Judgment Amplifier

Here is the shift that most commentary on AI and engineering misses: AI does not replace judgment. It amplifies it. An engineer with good judgment and access to AI is dramatically more effective than either alone. An engineer with bad judgment and access to AI is dramatically more dangerous.

Think of it as leverage. A lever does not create force — it multiplies the force you apply. If you push in the wrong direction, a longer lever just gets you further from where you want to be, faster.

What amplification looks like in practice

Good judgment + AI:

• Architect decides on event-driven decoupling → AI generates the consumer/producer boilerplate in minutes
• Engineer identifies the right abstraction boundary → AI scaffolds the interface and tests
• Team chooses eventual consistency → AI implements the saga pattern with proper compensation logic
• Architect defines failure modes → AI builds circuit breakers, retries, and fallbacks to spec

Poor judgment + AI:

• Premature microservices split → AI generates five services that should have been one module
• Wrong abstraction boundary → AI produces a beautifully tested interface nobody should call
• Unnecessary complexity adopted “because AI made it easy” → team drowns in operational burden
• No failure mode analysis → AI builds a happy-path system that shatters on first contact with reality

The pattern is consistent: AI accelerates execution, but the direction of execution is set by architectural judgment. Get the direction right, and AI gives you velocity that was previously impossible. Get it wrong, and AI helps you build the wrong thing at unprecedented speed.

4. The Judgment Stack

If judgment is a durable skill, what does it consist of? Not abstract wisdom — judgment is a stack of concrete capabilities that can be developed, practiced, and refined.

The Judgment Stack — what AI can’t substitute

Layer 4: BUSINESS CONTEXT

What does the business need? What constraints are non-negotiable? What can we sacrifice?

→ Requires organizational knowledge AI lacks

Layer 3: TRADE-OFF EVALUATION

Given N viable options, which set of costs is this organization best equipped to bear?

→ Requires value judgments, no “correct” answer

Layer 2: SYSTEM-LEVEL REASONING

How do components interact under stress? Where are the hidden couplings?

→ AI helps explore; humans must validate

Layer 1: PATTERN RECOGNITION

Which architectural patterns apply here? What worked in similar contexts?

→ AI strong here, but pattern ≠ decision

Layer 0: IMPLEMENTATION

Write the code, configure the infra

→ AI handles most of this now

AI is strong at Layers 0 and 1. It can write code and recognize patterns. It is useful but unreliable at Layer 2 — it can model system interactions but misses emergent behaviors and implicit coupling. It is weak at Layers 3 and 4, because these require reasoning about values, organizational dynamics, and consequences that extend beyond the technical system.

The engineer who invests in Layers 3 and 4 becomes more valuable as AI improves at Layers 0 and 1. The engineer who stays at Layer 0 is competing directly with a tool that works 24 hours a day and never asks for a raise.

5. How to Develop Architectural Judgment

Judgment is not innate. It is scar tissue from decisions made, consequences observed, and lessons internalized. Here is how to accelerate its development.

Study failures, not successes

Success is ambiguous — it could be good design or good luck. Failure is informative. Read post-mortems. Study systems that collapsed under scale, migrations that went sideways, abstractions that leaked. Every failure is a lesson in judgment that someone else paid for.

Make decisions, then live with them

You cannot develop judgment by observing decisions. You develop it by making them, owning the consequences, and adjusting. This means seeking responsibility for architectural choices, not avoiding it. Volunteer for the database migration. Own the API design. Choose the messaging system. When it goes wrong — and it will — you learn something that no book or AI can teach you.

Write Architecture Decision Records

Document your decisions, the alternatives you considered, and why you chose what you chose. Six months later, revisit them. Which held up? Which did you get wrong? The act of writing forces clarity; the act of revisiting builds calibration.

Argue the other side

Whatever architectural position you hold, practice arguing the opposite. If you chose Kafka, argue for RabbitMQ. If you went serverless, make the case for containers. If you cannot make a compelling case for the alternative, you do not actually understand your own decision — you just have a preference.

Use AI to stress-test your thinking

Here is where AI becomes a genuine tool for developing judgment: use it as a sparring partner. Present your architecture to an AI and ask it to find the weaknesses. Ask it to generate failure scenarios. Ask it what a critic would say. This is not AI replacing your judgment — it is AI sharpening it.

6. The New Engineering Career Trajectory

The traditional engineering career ladder — junior writes code, senior writes better code, staff writes the hardest code — is collapsing. AI compresses the lower rungs. A mid-level engineer with AI can ship features that used to require a senior. This does not eliminate levels. It redefines what each level means.

The new career trajectory is not writing harder code. It is making harder decisions with higher stakes and broader consequences.

The junior engineer’s job is no longer “learn to write code.” It is “learn to evaluate AI-generated code, understand why it works, and recognize when it doesn’t.”

The senior engineer’s job is no longer “write complex systems.” It is “design systems that are correct, make trade-offs explicit, and guide teams through ambiguity.”

The staff engineer’s job is no longer “solve the hardest technical problems.” It is “decide which problems are worth solving, align technical strategy with business strategy, and create the conditions for good judgment to flourish across the organization.”

At every level, the differentiator is judgment. The tools change. The judgment endures.

7. The Uncomfortable Corollary

If judgment is a durable skill, then engineers who never develop it are genuinely at risk. If an organization can get the same code output from fewer people, and the remaining people are differentiated by their judgment, then the engineers who only execute without deciding will find their roles compressed.

This is not a threat to wave around for dramatic effect. It is a structural change that is already happening. The response is not to panic. It is to invest in the right skills — to move up the judgment stack deliberately, to seek architectural responsibility proactively, and to treat AI as a lever that makes your judgment reach further rather than a replacement that makes your coding obsolete.

The engineers who do this will have the ability to execute at a speed and scale that was previously reserved for entire teams, directed by judgment that no model can replicate. That combination — human judgment amplified by machine capability — is not the end of the software engineer. It is the beginning of the software engineer who actually matters.

Judgment day is not the day machines replace you. It is every day you show up and make a decision that a machine cannot. The question is not whether that day is coming. It is whether you are building the judgment to survive it.

That gap is where things get interesting.

The Problem with Perfect Logic

Traditional code requires you to anticipate scenarios. You write decision trees, add conditions, build in edge cases. It works until the world throws something you didn’t predict in your planning session six months ago. I’ve been on teams that tried to solve this by adding more rules (more if-then statements, more configuration files, more attempts to encode every possible situation). You end up with something that handles known cases perfectly and fails in novel ones.

The fundamental tension exists between rigid instruction sets and environments that refuse to be predictable. This has always been true.

What Agents Actually Change

Over the past year, I’ve worked with several teams implementing agents in production. I’ve also been part of building the main agent system at Similarweb (one that takes user requests, analyzes our data, and generates whatever assets users need). I spent the first three months fairly convinced we were overcomplicating things. Why add this layer of apparent unpredictability to systems that need to be reliable?

The shift came when I stopped asking “do we need agents” and started asking “which parts of this system have the right structure for agent-based approaches.”

Consider order execution timing. You can write logic for when to execute based on price thresholds and volume. But what about breaking news that hasn’t fully propagated through the market? What about unusual options activity suggesting informed traders know something? Traditional code needs you to have predicted these exact scenarios and coded for them. An agent can observe patterns, connect information that wasn’t explicitly programmed, and adjust. It can reason about context in ways that brute-force rules can’t.

Agents handle the subset of problems where the solution space is too large to enumerate but the success criteria are clear enough to evaluate. They aren’t replacing your deterministic code.

Where This Actually Works

We had thousands of configuration files for web scraping. Giant instruction sets telling our engine which page to enter, what to click, what to look for. Clients wanted to track how their products were performing across various sites. The problem was that websites change constantly. A button moves, some text updates, and suddenly dozens of scrapers break. We’d spend days tracking down failures and updating configs.

Then we built a tool where you just specify what you’re looking for. No step-by-step instructions. The agent scouts the site until it finds what’s needed. Sites can redesign their entire layout overnight, and the next day the scraper just figures it out.

This worked because the problem had the right architecture. The success criteria were clear (find this specific data). The execution was self-contained (one site at a time). Verification was straightforward (did you get the data or not). Not every scraping problem has this structure, but the ones that do benefit dramatically from this approach.

What’s Still Hard

The biggest challenge is definitional, not technical. You can’t just say “make good decisions” and expect an agent to know what “good” means in your context. You need to be precise about priorities, edge cases that matter, when to be conservative versus aggressive.

I’ve watched agents do something technically correct based on the guidelines we gave them, and immediately known we’d explained our requirements wrong. We failed to understand what we actually wanted clearly enough. The agent just did what we asked.

The architectural questions matter more than people realize. When should you use agents versus deterministic code? When do you need multiple specialized agents instead of one general-purpose one? Where should the boundaries be? These are fundamental design decisions that determine whether the system works at all.

There’s also the reliability question. Deterministic code is testable in ways that agent-based systems aren’t. An agent might handle the same situation differently based on context you didn’t think was relevant. For many problems, that variability is the entire point. But you need to be comfortable with it, and you need monitoring and guardrails that match that reality.

The Real Shift

We’re moving from “predict every possible use case” to “explain the world clearly and define success.”

Traditional engineering is about anticipation. You think through scenarios, you code for them. Thorough, logical, and it works beautifully when the possibility space is manageable. For complex, dynamic environments (markets, user interactions, systems that change daily), the possibility space is effectively infinite.

With agents, you’re teaching instead of predicting. You explain how your world works, what the constraints are, what matters, what the tradeoffs look like. The agent navigates within that space, handling specific scenarios as they emerge in real time. It requires you to articulate things you might have just intuitively understood before. When it works, it handles situations that rigid code simply can’t.

Moving Forward

The puzzle between messy reality and deterministic code isn’t going away. We’ve never been able to predict the future, and that hasn’t changed. But we’re getting better at building systems that adapt rather than systems that try to anticipate everything.

Agents work well for a specific class of problems (ones where the solution space is too large to enumerate but success is definable enough to recognize). Understanding which problems have that structure, and how to architect systems that take advantage of it, separates production-ready agent systems from experiments that look impressive in demos.

The puzzle is still endless. But we’re learning to solve it differently. Instead of predicting every scenario, we’re building systems that can reason about the ones we didn’t predict. We’re just starting to understand what becomes possible when you stop trying to code for everything and start building systems that can figure it out.

Last month, I reviewed a pull request that made me do a double-take. The code was pristine — clean functions, comprehensive tests, clear variable names. It implemented a user notification system that worked perfectly in our staging environment.

Three weeks after production deployment, our support team was drowning in timeout errors. The elegant notification system was making 47 database calls per user action, the beautiful synchronous API was blocking threads for minutes, and the “comprehensive” error handling was silently swallowing failures that should have been escalated.

The code was AI-generated. And it was architecturally catastrophic.

This is the hidden danger of AI-assisted development: tools that write syntactically perfect code while making architectural decisions that will cripple your system at scale. Let me show you the patterns I’ve seen AI get consistently wrong — and how to guide it toward better solutions.

Pattern #1: The CRUD Trap — When AI Misses Your Domain Model

What AI Does: AI loves CRUD. Give it a feature request, and it’ll default to Create, Read, Update, Delete operations wrapped in REST endpoints. It’s simple, predictable, and works for demos.

The Problem: Your business domain isn’t CRUD operations. It’s workflows, state transitions, and business rules that evolve over time.

Real Example: I asked an AI to implement an order management system. It generated this structure:

# AI's approach - pure CRUD
class Order:
  def __init__(self, customer_id, items):
    self.status = "pending"
    self.customer_id = customer_id
    self.items = items
  
  def update_status(self, new_status):
    self.status = new_status # Any status to any status
  
  def update_items(self, new_items):
    self.items = new_items # Even after shipping!

Looks reasonable, right? But this design allows orders to jump from “shipped” back to “pending,” lets you modify items after payment, and has no concept of business rules or state validation.

What Your Domain Actually Needs:

# Domain-driven approach
class Order:
  def __init__(self, customer_id, items):
    self.customer_id = customer_id
    self.items = items
    self.status = OrderStatus.DRAFT
    self.events = []
  
  def submit_for_payment(self):
    if self.status != OrderStatus.DRAFT:
      raise InvalidTransition("Cannot submit non-draft order")
    self._transition_to(OrderStatus.PAYMENT_PENDING)
  
  def confirm_payment(self, payment_id):
    if self.status != OrderStatus.PAYMENT_PENDING:
      raise InvalidTransition("Cannot confirm payment for non-pending order")
    self._add_event(PaymentConfirmed(payment_id))
    self._transition_to(OrderStatus.CONFIRMED)
  
  def _transition_to(self, new_status):
    self.events.append(StatusChanged(self.status, new_status))
    self.status = new_status

Why AI Gets This Wrong: AI optimizes for implementation simplicity, not domain correctness. It doesn’t understand that your “order” represents a business process with rules, not just data storage.

How to Guide AI:
Instead of: “Create an order management system”
Try: “Model an order as a state machine with these valid transitions: draft→payment_pending→confirmed→shipped→delivered. Each transition should validate business rules and emit domain events.”

Pattern #2: The Synchronous Seduction — When AI Blocks Your Threads

What AI Does: AI defaults to synchronous patterns. Function calls return values directly, APIs wait for responses, operations complete before moving on. It’s easier to reason about and debug.

The Problem: Modern applications are fundamentally asynchronous. Users don’t wait for batch processes, external services have variable latency, and blocking operations kill scalability.

Real Example: I asked AI to implement a user onboarding flow:

# AI's synchronous approach
def onboard_user(user_data):
  # Create account
  user = create_user_account(user_data)
  
  # Send welcome email (blocks for 2–3 seconds)
  email_service.send_welcome_email(user.email)
  
  # Generate profile image (blocks for 5–10 seconds)
  avatar_url = image_service.generate_avatar(user.name)
  user.avatar_url = avatar_url
  user.save()

  # Sync with CRM (blocks for 3–5 seconds)
  crm_service.create_contact(user)
  
  # Setup analytics tracking (blocks for 1–2 seconds)
  analytics_service.track_signup(user.id)
  
  return user

This “works,” but the user waits 10–20 seconds for account creation while your API threads are tied up with external service calls.

What You Actually Need:

# Event-driven asynchronous approach
async def onboard_user(user_data):
  # Critical path - must complete immediately
  user = await create_user_account(user_data)
  
  # Non-critical operations - emit events for background processing
  await event_bus.publish(UserSignedUp(
    user_id=user.id,
    email=user.email,
    name=user.name
  ))
  
  return user

# Background handlers process events asynchronously
@event_handler(UserSignedUp)
async def handle_user_signup(event):
  tasks = [
    email_service.send_welcome_email(event.email),
    image_service.generate_avatar(event.name),
    crm_service.create_contact(event.user_id),
    analytics_service.track_signup(event.user_id)
  ]
  await asyncio.gather(*tasks, return_exceptions=True)

Why AI Gets This Wrong: AI optimizes for code that “just works” in isolation. It doesn’t consider concurrent users, service latency, or system-wide performance characteristics.

How to Guide AI:
Instead of: “Build a user onboarding system”
Try: “Design a user onboarding flow where account creation is synchronous but welcome emails, avatar generation, and CRM sync happen asynchronously via events. The user should see immediate feedback while background processes handle non-critical operations.”

Pattern #3: The Error Handling Mirage — When AI Optimizes for the Happy Path

What AI Does: AI writes error handling that looks comprehensive but misses the errors that actually matter in production.

The Problem: AI focuses on syntax errors and type mismatches, but real systems fail in ways that are hard to predict: network partitions, partial failures, cascading timeouts, and race conditions.

Real Example: AI-generated payment processing code:

# AI's "comprehensive" error handling
def process_payment(order_id, payment_data):
  try:
    order = get_order(order_id)
    if not order:
      return {"error": "Order not found"}
    
    payment_result = payment_gateway.charge(
      amount=order.total,
      card=payment_data['card']
    )
    
    if payment_result.success:
      order.status = "paid"
      order.save()
      return {"success": True, "transaction_id": payment_result.id}
    else:
      return {"error": payment_result.error_message}
  
  except Exception as e:
    logger.error(f"Payment processing failed: {e}")
    return {"error": "Payment processing failed"}

This handles the obvious cases but creates subtle data corruption:

1. What if the payment succeeds but saving the order fails?
2. What if the payment gateway returns success but then sends a webhook saying it failed?
3. What if this function runs twice for the same order due to a retry?

What You Actually Need:

# Robust error handling with compensation patterns
def process_payment(order_id, payment_data, idempotency_key):
  # Check if we've already processed this request
  existing_result = get_cached_result(idempotency_key)
  if existing_result:
    return existing_result
  try:
    # Start distributed transaction
    with transaction_manager() as tx:
      order = get_order_for_update(order_id)
    if order.status != "pending_payment":
      return {"error": "Order not in payable state"}
    
    # Reserve inventory before charging
    if not inventory_service.reserve_items(order.items, tx):
      return {"error": "Items no longer available"}
    
    # Process payment with compensation logic
    payment_result = payment_gateway.charge(
      amount=order.total,
      card=payment_data['card'],
      idempotency_key=idempotency_key
    )

    if payment_result.success:
      order.status = "paid"
      order.payment_id = payment_result.id
      order.save()
      
      # Schedule payment confirmation check
      schedule_payment_verification(payment_result.id, delay=300)
      result = {"success": True, "transaction_id": payment_result.id}
      cache_result(idempotency_key, result)
      return result
    
    else:
      # Release reserved inventory
      inventory_service.release_items(order.items, tx)
      return {"error": payment_result.error_message}
  
  except PaymentGatewayTimeout:
    # Payment might have succeeded - check status
    schedule_payment_status_check(order_id, idempotency_key)
    return {"error": "Payment processing - status will be confirmed shortly"}
  
  except Exception as e:
    # Ensure any partial state is cleaned up
    cleanup_partial_payment_state(order_id, idempotency_key)
    logger.error(f"Payment processing failed: {e}", extra={"order_id": order_id})
    return {"error": "Payment processing failed"}

Why AI Gets This Wrong: AI doesn’t understand distributed systems failure modes. It optimizes for code that handles expected exceptions, not systems that maintain consistency under partial failures.

How to Guide AI:
Instead of: “Add error handling to this payment processing function”
Try: “Design payment processing that handles these failure scenarios: payment succeeds but order update fails, gateway timeout with unknown payment status, duplicate payment attempts, and inventory changes between payment and confirmation. Use compensation patterns.”

Pattern #4: The Database Relationship Disaster — When AI Normalizes Everything

What AI Does: AI loves clean, normalized database schemas. Every entity gets its own table, every relationship is properly foreign-keyed, and the ERD looks like a textbook example.

The Problem: Normalized schemas optimize for write consistency but can create query performance disasters. AI doesn’t understand your read patterns, query volume, or consistency requirements.

Real Example: AI-generated e-commerce schema:

-- AI's "perfect" normalization
CREATE TABLE products (
  id INT PRIMARY KEY,
  name VARCHAR(255),
  description TEXT
);

CREATE TABLE categories (
  id INT PRIMARY KEY,
  name VARCHAR(255)
);

CREATE TABLE warehouses (
  id INT PRIMARY KEY,
  name VARCHAR(255),
  location VARCHAR(255)
);

CREATE TABLE product_categories (
  product_id INT REFERENCES products(id),
  category_id INT REFERENCES categories(id)
);

CREATE TABLE product_attributes (
  id INT PRIMARY KEY,
  product_id INT REFERENCES products(id),
  attribute_name VARCHAR(255),
  attribute_value VARCHAR(255)
);

CREATE TABLE inventory (
  id INT PRIMARY KEY,
  product_id INT REFERENCES products(id),
  warehouse_id INT REFERENCES warehouses(id),
  quantity INT
);

This schema requires 5+ joins for basic product listing queries and becomes unusable at scale.

What Your Read Patterns Actually Need:

-- Read-optimized with strategic denormalization
CREATE TABLE products (
  id INT PRIMARY KEY,
  name VARCHAR(255),
  description TEXT,
  category_names TEXT[], -- Denormalized for filtering
  attributes JSONB, -- Flexible attributes in one place
  total_inventory INT, -- Cached across warehouses
  inventory_by_warehouse JSONB, -- When you need details
  search_vector tsvector, -- Full-text search
  last_updated TIMESTAMP
);

-- Separate write-optimized tables for updates
CREATE TABLE inventory_events (
  id BIGSERIAL PRIMARY KEY,
  product_id INT,
  warehouse_id INT,
  quantity_change INT,
  event_time TIMESTAMP
);

Why AI Gets This Wrong: AI applies database normalization rules without understanding query patterns, read-write ratios, or consistency requirements specific to your domain.

How to Guide AI:
Instead of: “Design a database schema for e-commerce”
Try: “Design a schema optimized for read-heavy product catalogs where we need fast filtering by category and attributes. Write operations happen via events, and we can tolerate eventual consistency for inventory counts. Optimize for sub-100ms product listing queries.”

Pattern #5: The Testing Theater — When AI Tests Implementation, Not Behavior

What AI Does: AI generates comprehensive unit tests that achieve high coverage by testing implementation details rather than business behavior.

The Problem: Implementation-focused tests become maintenance burdens that don’t catch real bugs. They pass when your code is broken and fail when you refactor correctly.

Real Example: AI-generated tests for a shopping cart:

# AI's implementation-focused tests
def test_add_item_to_cart():
  cart = ShoppingCart()
  item = CartItem(product_id=1, quantity=2, price=10.00)
  cart.add_item(item)
  
  # Testing internal state instead of behavior
  assert len(cart._items) == 1
  assert cart._items[0].product_id == 1
  assert cart._items[0].quantity == 2
  assert cart._total == 20.00
 
def test_cart_calculates_total():
  cart = ShoppingCart()
  
  # Tests the specific calculation method
  cart._items = [
    CartItem(product_id=1, quantity=2, price=10.00),
    CartItem(product_id=2, quantity=1, price=5.00)
  ]
  
  total = cart._calculate_total()
  assert total == 25.00

These tests break when you change internal implementation and don’t verify actual user-facing behavior.

What You Actually Need:

# Behavior-focused tests
def test_user_can_add_items_and_see_correct_total():
  cart = ShoppingCart()
  
  # Test the behavior users care about
  cart.add_product(product_id=1, quantity=2, unit_price=10.00)
  cart.add_product(product_id=2, quantity=1, unit_price=5.00)
  
  # Verify observable behavior, not implementation
  assert cart.get_total() == 25.00
  assert cart.get_item_count() == 3
  assert cart.contains_product(1)
  assert cart.contains_product(2)

def test_cart_handles_inventory_constraints():
  cart = ShoppingCart()
  inventory = MockInventoryService()
  inventory.set_available_quantity(product_id=1, quantity=1)
  
  # Test business rule enforcement
  with pytest.raises(InsufficientInventoryError):
    cart.add_product(product_id=1, quantity=2, inventory_service=inventory)

def test_cart_preserves_items_across_sessions():
  # Test the behavior that matters to users
  user_id = "user123"
  
  cart1 = ShoppingCart.load_for_user(user_id)
  cart1.add_product(product_id=1, quantity=1, unit_price=10.00)
  cart1.save()
  
  cart2 = ShoppingCart.load_for_user(user_id)
  
  assert cart2.get_total() == 10.00

Why AI Gets This Wrong: AI tests the code it generated, not the behavior your users depend on. It doesn’t understand which aspects of your system are essential contracts versus implementation details.

How to Guide AI:
Instead of: “Write unit tests for this shopping cart class”
Try: “Write tests that verify these user behaviors: adding items updates the total correctly, quantity constraints are enforced, cart contents persist across sessions, and duplicate items are handled appropriately. Focus on testing the public interface, not internal methods.”

The Path Forward: Architectural AI Partnership

The solution isn’t to avoid AI — it’s to guide it toward better architectural decisions. Here’s how:

1. Lead with Constraints, Not Features Instead of describing what you want to build, describe the forces your system must handle: concurrency, consistency requirements, performance characteristics, and failure modes.

2. Specify Non-Functional Requirements AI optimizes for functional correctness. You must explicitly specify scalability, maintainability, and reliability requirements.

3. Review Generated Code for Architectural Patterns Ask yourself: Does this code make assumptions about usage patterns? How would this behave under load? What happens when external dependencies fail?

4. Use AI for Exploration, Humans for Decisions Let AI generate multiple approaches, but use human judgment to evaluate tradeoffs and select patterns that fit your specific context.

The developers who thrive with AI won’t be those who generate code fastest — they’ll be those who can spot architectural anti-patterns and guide AI toward solutions that survive contact with production reality.

Your system’s architecture is too important to delegate to a tool that optimizes for demos instead of durability. Use AI as a powerful implementation partner, but keep the architectural decisions where they belong: with engineers who understand the difference between code that works and code that lasts.

The AI Architecture Illusion: Why Generated Code Works in Demos but Dies in Production was originally published in Similarweb Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

The feature broke in production two days later.

When asked to debug it, the developer stared at the code like it was written in hieroglyphics. Because in a way, it was. They had built something they didn’t understand, solving a problem they never truly grasped.

This is the ChatGPT Trap, and it’s stealing the learning experiences that create great developers.

The Invisible Skills We’re Not Building

Here’s what I see happening across engineering teams:

The Assignment Dump: “Here’s my ticket, ChatGPT. Solve it.” No problem breakdown, no requirement analysis, no architectural thinking. Just hoping AI will figure out what they couldn’t be bothered to understand.

The Copy-Paste Cycle: Entire functions copied wholesale, variable names unchanged, patterns unrecognized. When the code inevitably needs modification, they’re back to ChatGPT for another complete rewrite.

The Question Drought: Instead of asking clarifying questions about requirements or exploring edge cases, developers let AI make those decisions. The problem? AI doesn’t know your business context, your user needs, or your system constraints.

Technology Problems Are Rarely Technology Problems

Here’s the truth that’s getting lost in the AI hype: Your biggest technical debt isn’t inefficient algorithms or outdated frameworks. It’s misunderstood requirements.

That “simple” user authentication feature? It touches session management, security policies, user experience flows, error handling, and data privacy requirements. ChatGPT can generate the code, but it can’t tell you which business rules you forgot to ask about.

The most expensive line of code is the one that solves the wrong problem. And if you don’t understand the problem deeply enough to debug, modify, or extend your solution, you’ve built technical debt with AI assistance.

AI Gives You Faster Answers, But Are You Asking the Right Questions?

AI is incredibly powerful, but it amplifies whatever approach you bring to it. Bring shallow thinking, get shallow solutions. Bring deep problem understanding, get genuinely helpful assistance.

Instead of: “Build me a REST API for user management” Try: “I’m designing user management for a multi-tenant application. What are the key architectural decisions I should consider around data isolation, authentication, and scalability? Help me think through the tradeoffs.”

Instead of: “Fix this bug” [paste entire function] Try: “This function should handle user input validation, but it’s failing on edge cases. Help me understand why this approach might be fragile and what validation patterns would be more robust.”

See the difference? One treats AI as a solution machine. The other treats it as a thinking partner.

The Questions That Make AI Your Learning Partner

Before you open ChatGPT, ask yourself:

• What problem am I really trying to solve?
• What do I already know about this domain?
• What specific part am I stuck on?
• What would success look like from a user perspective?

When working with AI, prioritize understanding:

• “Explain this concept, don’t just give me code”
• “What are the tradeoffs of this approach?”
• “What edge cases should I consider?”
• “How would you test this solution?”

After AI gives you code, dig deeper:

• “Why did you choose this pattern?”
• “What would break if the requirements changed?”
• “How would I modify this for different use cases?”

The 24-Hour Test

Here’s how to know if you’re learning or just producing:

Can you explain the code you wrote yesterday without looking at it? Can you modify it for a new requirement? Can you debug it when it breaks?

If the answer is no, you’re letting AI learn instead of you.

Building Systems That Survive Contact With Reality

The best developers I work with use AI to accelerate their learning, not replace their thinking. They understand that:

• Good architecture starts with good questions, not good code
• Your users don’t care about your stack, they care about their problems
• Every feature request is really a hypothesis that needs testing

They use AI to explore possibilities, understand tradeoffs, and generate options. But they make the decisions, understand the implications, and take responsibility for the outcomes.

The Path Forward

AI isn’t going anywhere, and neither should your curiosity. The developers who thrive in the next decade will be those who can leverage AI’s capabilities while maintaining their problem-solving skills.

Use AI as a research assistant, not a replacement brain. Let it help you explore solutions faster, but never let it do your thinking for you.

Because at the end of the day, the code that matters most isn’t the code that works once. It’s the code you can debug, extend, and evolve as your understanding of the problem deepens.

Your users are debugging your assumptions every day. Make sure you understand those assumptions well enough to fix them.

The ChatGPT Trap: Why Junior Developers Are Learning Less While Building More was originally published in Similarweb Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Drawing from my experience as both a software developer and LLM user, I’ve compiled these battle-tested practices that transform how effectively you can leverage these AI tools for coding tasks. Think of this as your practical field guide to speaking the language that gets you the code you actually need.

Understanding the “Mind” Behind the Model

Before diving into specific techniques, it helps to understand how LLMs approach coding tasks. Unlike human programmers, LLMs don’t truly “understand” code in the way we do. They recognize patterns and predict what should come next based on their training data.

This pattern-matching approach means that your prompt serves as both the problem statement and an implicit guide for how the solution should be structured. When your prompt lacks clarity or specificity, the model fills in the gaps with what it considers most probable based on similar examples in its training — which may not align with your actual needs.

Best Practice #1: Set the Context with Precision

One of the most common mistakes I see is jumping straight to requesting a specific function or feature without establishing the broader context. Just as you wouldn’t expect a new team member to write perfect code without understanding your project, LLMs need context to generate appropriate solutions.

Why this matters: Context helps the LLM understand the environment where your code will live, the constraints it must operate within, and the patterns it should follow. Without this information, the model may produce technically correct code that’s completely misaligned with your actual project needs.

Instead of this:

Write a function that validates a user's password.

Try this:

I'm working on a Node.js application using Express and MongoDB. We follow a service-oriented architecture with separate validation utilities. I need a password validation function that:
- Checks for minimum 8 characters
- Requires at least one uppercase letter, one lowercase letter, and one number
- Doesn't allow more than 3 consecutive identical characters
- Returns a detailed object with a success flag and specific validation errors

Notice how the improved prompt establishes the technical ecosystem, architectural pattern, and specific requirements. This context drastically narrows the solution space, leading to more relevant output.

Best Practice #2: Use Test Cases as Specifications

When describing what you want code to do, natural language can be surprisingly ambiguous. I’ve found that including explicit test cases in your prompt is one of the most effective ways to clarify your expectations.

Why this matters: Test cases provide concrete examples of inputs and expected outputs, which eliminates ambiguity and helps the LLM understand edge cases. This approach also naturally aligns with test-driven development practices.

Instead of this:

Write a function that formats phone numbers.

Try this:

Write a JavaScript function that formats phone numbers. The function should:
- Accept strings with 10 digits in any format
- Return a string formatted as (XXX) XXX-XXXX

Examples:
- formatPhoneNumber("1234567890") should return "(123) 456–7890"
- formatPhoneNumber("123–456–7890") should return "(123) 456–7890"
- formatPhoneNumber("(123) 456–7890") should return "(123) 456–7890"
- formatPhoneNumber("abc1234567890") should return "Invalid input"
- formatPhoneNumber("12345") should return "Invalid input"

By providing these test cases, you’ve essentially defined a specification through examples, which dramatically increases the chances of getting exactly what you need on the first try.

Best Practice #3: Establish Your Coding Standards

Each team and project has its own coding conventions and preferred patterns. By explicitly stating these preferences in your prompt, you can get code that feels like it was written by you or your team.

Why this matters: Code that follows your established patterns integrates more seamlessly with your existing codebase and requires less refactoring. This saves time and reduces the cognitive load of switching between different styles.

Instead of this:

Create a React component for a user profile.

Try this:

Create a React functional component for a user profile with the following guidelines:
- Use TypeScript with explicit interface for props
- Follow our naming convention: [ComponentName]/[ComponentName].tsx
- Use CSS modules for styling
- Use React hooks for any state management
- Include proper error handling for API data
- Add JSDoc comments for the component and its props
The component should display the user's profile image, name, email, and a list of their recent activities.

This approach guides the LLM to produce code that aligns with your team’s practices, making the output immediately more valuable and reducing the need for adjustments.

Best Practice #4: Request Error Handling and Edge Cases

In my experience, one of the biggest gaps in LLM-generated code is proper error handling. The “happy path” usually works fine, but real-world code needs to gracefully handle all sorts of unexpected inputs and conditions.

Why this matters: Production-quality code needs to be robust against invalid inputs, network failures, and other edge cases. Explicitly requesting this coverage prevents you from having to add it yourself later.

Instead of this:

Write a function to fetch user data from an API.

Try this:

Write an async JavaScript function to fetch user data from an API with the following requirements:
- Use fetch API with proper timeout (5 seconds)
- Handle network errors gracefully
- Handle 404 errors by returning null
- Handle other HTTP errors by throwing a custom error with the status code
- Include retry logic (maximum 3 attempts with exponential backoff)
- Add TypeScript typings for the return value and parameters
The function should take a userId parameter and return a promise that resolves to the user object.

By specifying your error handling expectations, you prompt the LLM to consider these critical aspects rather than focusing solely on the basic functionality.

Best Practice #5: Break Down Complex Requests

When you need complex functionality, resist the urge to request everything in a single prompt. Instead, break it down into logical components, just as you would decompose a complex programming task.

Why this matters: LLMs perform better on focused, specific tasks rather than broad, multi-faceted ones. Breaking down requests helps the model concentrate on one aspect at a time, leading to higher-quality output for each piece.

Instead of this:

Create a full authentication system with login, registration, password reset, and profile management.

Try this:

A series of separate, focused prompts:

1. "Create a user schema and model for MongoDB with fields for authentication…"

2. "Write a registration controller function that validates input and creates a new user…"

3. "Create a JWT authentication middleware function that verifies tokens…"

This sequential approach mirrors how you would actually build such a system, focusing on one component at a time and ensuring each piece is solid before moving on.

Best Practice #6: Request Explanations and Comments

When working with complex algorithms or domain-specific code, ask the LLM to explain its implementation. This not only helps you understand the generated code but often improves its quality as well.

Why this matters: The act of explaining code forces clearer thinking — a principle known as the “rubber duck debugging” effect. When an LLM includes explanations, it often catches issues in its own logic and produces better organized, more thoughtful code.

Instead of this:

Write a function to implement the Boyer-Moore string search algorithm.

Try this:

Write a function to implement the Boyer-Moore string search algorithm with the following:
- Include detailed comments explaining each step of the algorithm
- Add a brief explanation of the time and space complexity
- Include examples of how the algorithm works on specific inputs
- Add TypeScript type annotations

After the code, please explain the key insight of the Boyer-Moore algorithm and why it's often more efficient than naive string searching.

The explanations you receive serve as built-in documentation and help validate that the code is implementing what you expect.

Best Practice #7: Iterative Refinement with Context

Perhaps the most powerful technique is approaching complex tasks as a conversation rather than a one-shot request. Start with a basic implementation, then iteratively refine it while maintaining the full context.

Why this matters: This approach mimics the natural development process and allows you to build on previous work rather than starting from scratch with each refinement. It also helps the LLM maintain consistency across iterations.

A sample conversation flow:

1. Initial request: “Create a basic Redux slice for managing user authentication state…”
2. Refinement: “Great, now add action creators for handling login failure scenarios…”
3. Further refinement: “Update the reducer to handle token refresh…”

Each step builds on the previous one, with the LLM maintaining awareness of the evolving codebase.

Best Practice #8: Specify the Level of Abstraction

Different coding tasks require different levels of abstraction. Being explicit about whether you want high-level pseudocode, detailed implementation, or something in between helps set appropriate expectations.

Why this matters: Sometimes you need a detailed implementation ready to copy into your project; other times, you’re looking for a conceptual approach or architecture. Specifying this upfront helps you get exactly what you need.

Example:

I'm designing a real-time notification system for a web application. 
First, provide a high-level system architecture diagram showing the main components. 
Then, focus on the database schema for storing notification preferences and history. 
Finally, give me the detailed implementation for the notification dispatcher service in Node.js.

This multi-level approach helps you establish the big picture before diving into implementation details.

Putting It All Together: A Practical Workflow

Based on these practices, here’s a workflow I’ve found effective for using LLMs in coding tasks:

1. Start with context: Begin by explaining your project, tech stack, and coding patterns.
2. Define requirements clearly: Use test cases, examples, and explicit criteria.
3. Request a specific scope: Ask for focused functionality rather than entire systems.
4. Review and refine: Treat the first response as a starting point, then iterate with specific feedback.
5. Ask for explanations: Request the LLM to walk through complex parts of the generated code.
6. Integrate mindfully: Always review generated code for security, performance, and alignment with best practices.

Conclusion: Prompting as a Programming Skill

Effective LLM prompting for coding tasks is emerging as a distinct skill — one that bridges natural language communication and programming. By applying these techniques consistently, you’ll find that your interactions with AI coding assistants become increasingly productive, allowing you to focus more on the creative and architectural aspects of development while delegating routine coding tasks.

Remember that these models are continuously evolving. The techniques that work best today may need adjustment as capabilities advance. However, the fundamental principle remains: the more effectively you communicate your requirements and context, the better results you’ll achieve.

Treat your AI coding assistant as a junior developer with impressive capabilities but who needs clear guidance — and you’ll be amazed at how much more productive your partnership becomes.

About the author: This article was written by a software engineer with extensive experience in both software development and leveraging LLMs to enhance coding productivity.

Effective LLM Prompting: Getting the Code You Actually Need was originally published in Similarweb Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Why Architecture Matters Now More Than Ever

Imagine you’re building a house. You could focus all your energy on selecting beautiful furniture, state-of-the-art appliances, and perfect paint colors. But if the foundation is weak or the frame is unstable, those details won’t matter — the whole structure is at risk.

The same principle applies when building systems around Large Language Models (LLMs). The technology is evolving at breakneck speed, with new models, techniques, and tools emerging almost weekly. In this environment, focusing solely on today’s capabilities without considering tomorrow’s needs is a recipe for technical debt and frustration.

Good architecture isn’t just about making things work today — it’s about building systems that can adapt, scale, and evolve as the technology landscape shifts beneath our feet.

The Four Pillars of Effective LLM Architecture

Through experience and sometimes painful lessons, I’ve identified four core principles that form the foundation of effective LLM architecture:

1. Modularity: Building with LEGO, Not Concrete

When working with LLM tools, modularity is your greatest ally. Each component in your system should have clear boundaries and well-defined interfaces. This approach allows you to:

• Replace individual components as better alternatives emerge
• Experiment with new models or techniques without rebuilding the entire system
• Create specialized workflows for different teams or use cases

The LangChain ecosystem, which we’ve adopted as our foundation, embraces this modularity. It allows us to swap out embedding models, change vector stores, or update prompt templates without disrupting the entire system.

Consider this: Would you rather replace a single brick in your structure or rebuild the entire wall? Modularity gives you that flexibility.

2. Observability: You Can’t Improve What You Can’t Measure

LLMs can sometimes feel like black boxes. Without proper observability, you’re flying blind — unable to identify issues, measure improvements, or justify investments.

Effective LLM architecture must include robust mechanisms for:

• Logging inputs, outputs, and important intermediate steps
• Tracking performance metrics (latency, token usage, costs)
• Evaluating result quality against defined benchmarks
• Identifying patterns in failures or suboptimal outputs

Dedicated observability platforms provide this crucial visibility layer, much like having a dashboard in your car that shows engine temperature, fuel levels, and speed. This visibility into what’s happening at each step of your LLM pipelines becomes invaluable when debugging issues, optimizing performance, or demonstrating value to stakeholders.

3. Adaptability: Planning for Change, Not Fighting Against It

The only constant in AI development is change. New models emerge, existing models improve, best practices evolve, and organizational needs shift. Your architecture shouldn’t just accommodate change — it should embrace it.

Think of it like building a garden rather than a concrete structure. Gardens are designed to grow and evolve with the seasons. In the same way, adaptable AI architecture allows for natural growth and change.

This means:

• Avoiding tight coupling to specific models or providers (like how a good garden isn’t dependent on just one type of plant)
• Building abstraction layers that shield most of your codebase from underlying changes (similar to how mulch protects plant roots from temperature extremes)
• Creating clear extension points for new capabilities (like leaving space in your garden for new plantings)
• Designing with both backward compatibility and forward evolution in mind (ensuring new additions complement what’s already growing)

Modern workflow orchestration systems demonstrate this adaptability beautifully. By defining workflows as graphs with clear transitions and state management, you create systems that can evolve piece by piece — like replacing individual plants in your garden rather than digging everything up and starting over.

4. Governance: Balancing Innovation with Control

As LLM usage grows within an organization, so does the need for governance. Without appropriate guardrails, you risk inconsistent experiences, runaway costs, or even compliance issues.

Effective LLM architecture must include:

• Centralized policy management for prompt engineering and model selection
• Cost controls and usage monitoring
• Authentication and authorization frameworks
• Auditability for sensitive operations
• Versioning and rollback capabilities for critical components

This doesn’t mean stifling innovation — quite the opposite. Good governance creates safe spaces for experimentation while protecting production systems from unvetted changes.

Real-World Architecture Patterns That Work

Beyond these principles, several architectural patterns have proven effective when building LLM-powered systems:

The Hub-and-Spoke Model

In this pattern, a central orchestration layer manages access to LLM capabilities, while specialized adapters handle integration with various business systems. This creates a clean separation between:

• The core LLM interaction logic (prompting, chain execution, etc.)
• The business-specific knowledge and integration points
• The underlying model providers and tools

This approach allows centralized teams (like yours) to maintain the core infrastructure while enabling individual departments to build their own specialized adapters.

The Evaluation-First Pipeline

Traditional software development emphasizes testing after implementation. With LLMs, this approach falls short because the outputs are probabilistic rather than deterministic.

An evaluation-first pipeline flips this model by:

1. Defining clear evaluation metrics before building
2. Creating benchmark datasets that represent real-world usage
3. Establishing automated evaluation pipelines
4. Only then implementing and iterating on the actual solution

This approach ensures that you can measure the impact of architectural changes on actual performance.

The Feedback Loop Architecture

LLMs improve with feedback. Your architecture should embrace this by creating explicit pathways for:

• Human feedback on model outputs
• Automated detection of suboptimal responses
• Continuous fine-tuning or retrieval augmentation based on this feedback
• Performance monitoring to ensure improvements actually help

This creates a virtuous cycle where your systems get better with use, rather than degrading over time.

Common Pitfalls to Avoid

Having worked on LLM infrastructure for our organization, I’ve witnessed several architectural missteps that create long-term problems:

The Model-Centric Fallacy

It’s tempting to build your architecture around the capabilities of a specific model. This creates brittle systems that break when model APIs change or when new, better models emerge.

Instead, design around the problems you’re solving, creating abstraction layers that can accommodate different models as appropriate.

The Prompt Engineering Spaghetti

Without architectural discipline, prompt engineering quickly becomes unmanageable — with critical business logic embedded in strings scattered throughout your codebase.

Treat prompts as first-class citizens in your architecture, with appropriate versioning, testing, and abstraction.

The Integration Overload

As LLMs prove their value, teams inevitably want to integrate them with everything — from knowledge bases to CRMs to internal tools.

Without a thoughtful integration architecture, you’ll find yourself building and maintaining countless one-off connectors. Instead, create standardized integration patterns and reusable components.

The Observability Afterthought

Too often, monitoring, logging, and evaluation are added after problems arise. By then, you’re already flying blind, unable to diagnose issues or measure improvements.

Bake observability into your architecture from day one. Luckily, we have great tools today that make this job easy, but the architectural commitment must come first.

Building for an Uncertain Future

Perhaps the greatest challenge in LLM architecture is the uncertainty of the technology’s future. Will agents become more autonomous? Will multimodality become standard? Will fine-tuning give way to new adaptation techniques?

Think of your architecture like building a house with an expandable floor plan. Rather than trying to predict exactly how many children you might have someday, you create a design where adding rooms is straightforward. In technical terms, this means focusing on systems with clear extension points and abstraction layers.

This flexible foundation approach has proven successful across many AI frameworks. We’ve seen orchestration systems evolve from simple sequential workflows to sophisticated graph-based executions without requiring developers to throw away their existing code. It’s like how your smartphone can gain new capabilities through software updates without requiring you to buy an entirely new device.

Conclusion: The Architectural Mindset

As technological leaders, our job isn’t just to implement today’s solutions but to build foundations for tomorrow’s possibilities. With LLMs, this requires a particular mindset — one that values flexibility over certainty, observability over assumption, and evolution over perfection.

By embracing modular design, prioritizing observability, planning for adaptation, and implementing thoughtful governance, we create AI systems that don’t just work today but continue to deliver value as the technology landscape evolves.

The choices we make now in our LLM architecture will either empower our organizations to ride the wave of AI innovation or leave them struggling to keep up with each new development. By building on solid architectural ground, we ensure it’s the former rather than the latter.

Are your AI systems built to last, or just built to launch? The architecture you choose today will determine the answer tomorrow.

Building on Solid Ground: The Critical Importance of Good Architecture for LLM Tools was originally published in Similarweb Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Evolution of Technical Leadership

When I first stepped into the tech lead role, my focus was primarily on system design and helping with complex technical challenges. These responsibilities aligned with the traditional expectations of technical leadership — being the go-to person for difficult engineering problems and architectural decisions. However, a recent experience taught me that some of our most significant contributions might come from unexpected directions.

The conventional path of technical leadership often follows a predictable trajectory: start as a strong individual contributor, take on more complex technical challenges, and gradually assume responsibility for technical decisions affecting entire systems or teams. This progression makes sense, as it builds upon our core strengths and established expertise. However, this linear path can sometimes blind us to other equally important opportunities for impact.

The Changing Landscape of Technical Leadership

Today’s technology organizations face challenges that extend beyond pure technical excellence:

• Rapidly evolving technology stacks requiring continuous learning
• Growing teams with diverse skill levels and backgrounds
• Increased emphasis on soft skills and cross-functional collaboration
• Need for scalable knowledge sharing and standardization
• Balance between innovation and maintainable solutions

These challenges require technical leaders to expand their toolkit beyond coding and system design, embracing roles as educators, mentors, and cultural ambassadors.

Identifying the Opportunity

It began with a small-scale course I had developed to enhance our analysis team’s engineering capabilities. The positive impact of this initiative caught the attention of our CTO, who recognized the potential for a broader application. This led to a request to develop a comprehensive training program for our new graduate hires — young engineers fresh out of college whom the company was eager to invest in.

The request aligned with a pattern I had observed: while our junior engineers were technically skilled, they needed guidance in applying their knowledge within our specific business context and development practices. This gap between academic knowledge and practical application represented both a challenge and an opportunity.

The Analysis That Led to Action

The path to expanding our training program began with observing recurring patterns in our development process. Through code reviews and technical discussions, I noticed consistent knowledge gaps among our junior engineers. While they possessed strong theoretical foundations from their academic backgrounds, they often struggled to apply this knowledge effectively in our production environment. Common issues surfaced repeatedly: misconceptions about how our systems operated at scale, inconsistent approaches to coding practices, and difficulties in translating their theoretical knowledge into practical solutions. These patterns weren’t just isolated incidents — they represented a systematic gap between academic learning and real-world application.

The impact of these knowledge gaps extended beyond individual performance issues. Our teams were experiencing varying onboarding experiences, leading to inconsistent skill development across the organization. Some teams had developed their own informal training approaches, while others relied heavily on one-on-one mentoring. This inconsistency meant that new hires’ time-to-productivity varied significantly depending on their team placement. Furthermore, knowledge silos were beginning to form within teams, making it difficult to maintain consistent practices across the organization and limiting opportunities for cross-team collaboration.

Looking at these observations through a business lens revealed the broader implications of these challenges. Projects were taking longer than necessary to complete as senior engineers spent significant time reviewing and correcting common mistakes. The inconsistent practices across teams were contributing to technical debt, which would eventually require dedicated time and resources to address. More importantly, our review cycles were becoming increasingly lengthy, affecting our overall team velocity. These business impacts made it clear that a more structured approach to knowledge sharing wasn’t just desirable — it was essential for our organization’s continued growth and efficiency.

From Recognition to Action

Taking on this educational initiative was a departure from my usual technical leadership responsibilities. However, the decision to embrace this challenge was driven by several key considerations:

1. Scalable Impact: While solving technical problems has immediate value, creating educational content has the potential to impact multiple generations of engineers.
2. Knowledge Standardization: A structured course ensures consistent knowledge transfer across teams and reduces the repetitive nature of one-on-one mentoring.
3. Cultural Investment: Demonstrating the organization’s commitment to employee development helps build a culture of continuous learning and growth.

The Decision-Making Process

The journey from identifying the educational need to committing to a comprehensive solution wasn’t straightforward. My first step was conducting a thorough assessment of our available resources — evaluating the time investment required, gauging potential support from team members, and identifying the technical resources we’d need to create effective training materials. I also had to carefully consider how this initiative would impact my ongoing technical responsibilities and existing workflows. The prospect of disrupting our team’s rhythm with this new undertaking weighed heavily on my mind, as did the learning curve I’d face in creating educational content.

This careful deliberation led me to weigh the opportunity costs against potential benefits. While taking on this educational initiative meant temporarily stepping back from some technical projects, the long-term impact on team development appeared far more valuable. The possibility of creating lasting change through knowledge sharing, combined with my own growth opportunities in content creation and mentorship, ultimately tipped the scales. The decision to proceed wasn’t just about immediate team needs — it was an investment in our organization’s future, promising returns through improved code quality, faster onboarding, and a stronger engineering culture.

The Implementation Journey

Developing the course required a different skill set from my usual technical work. Here are some key lessons learned:

Content Architecture

Just as we architect software systems, educational content needs careful structuring:

• Breaking down complex concepts into digestible modules
• Creating a logical progression of topics
• Balancing theoretical knowledge with practical exercises
• Incorporating real-world examples

Curriculum Design Principles

The course structure was built on the principle of progressive complexity, carefully guiding participants from foundational concepts to advanced topics. We designed the learning journey to mirror the natural growth of a software engineer, starting with basic principles and gradually introducing more complex challenges. Regular checkpoint exercises were strategically placed throughout the curriculum, allowing participants to validate their understanding before moving forward. This stepped approach proved particularly effective as it gave new engineers the confidence to tackle increasingly sophisticated problems while maintaining a clear connection between each new concept and their existing knowledge.

The curriculum’s strength lay in its deeply practical focus and interactive nature. Rather than relying on theoretical exercises, we incorporated real-world examples, making the learning immediately applicable to daily work. Hands-on sessions became the cornerstone of our approach, featuring group discussions, and intensive workshops. System design exercises were structured as collaborative sessions where participants could explore architectural decisions together, learning not just from the instructor but from each other’s perspectives and experiences. This combination of practical application and interactive learning created an engaging environment where engineers could safely experiment with new concepts while building the confidence to apply them in their actual work.

Measuring Success

Throughout the course delivery, I took an active role in monitoring and measuring its effectiveness, personally conducting code reviews for participants to track their progress firsthand. This direct involvement gave me invaluable insights into how well the concepts were being absorbed and applied in practice. After each section of the course, I distributed detailed surveys to gather immediate feedback from participants, helping us understand which topics resonated most strongly and which areas needed reinforcement. The responses from these surveys proved instrumental in fine-tuning the content and delivery methods as we progressed, ensuring the course remained both engaging and effective.

To ensure a comprehensive view of the program’s impact, I maintained regular communication with the participants’ team leaders throughout the training period. Their feedback was consistently positive, with team leaders reporting that their new engineers were demonstrating a solid grasp of the material and showing genuine enthusiasm for the course content. While the participants hadn’t yet been granted production access, their performance in training exercises and practice scenarios showed promising signs of their readiness for real-world challenges. The team leaders’ observations, combined with the participants’ own positive feedback through surveys, validated our approach to structured learning and confirmed that we were effectively preparing these engineers for their future responsibilities. This early success suggested that our educational initiative was laying a strong foundation for these new engineers to become valuable contributors once they began working with production systems.

The Broader Impact

The impact of this educational initiative began revealing itself even during the course delivery, showing promise beyond its initial scope as a training program for new graduates. The process of creating and delivering structured educational content forced us to examine and articulate our engineering practices in unprecedented detail. As we developed the curriculum, we found ourselves documenting processes that had previously existed only as tribal knowledge, creating clear guidelines and explanations that could benefit not just course participants but potentially the entire engineering organization.

The course development process also sparked valuable discussions among our experienced engineers who contributed to the content. These conversations about best practices, common pitfalls, and effective teaching approaches led to thoughtful examinations of our own processes. We found ourselves questioning and refining our approaches to code review, development workflows, and quality assurance practices. The simple act of preparing to teach others prompted us to clarify and sometimes improve our own methods, creating a more structured and well-documented approach to our engineering practices.

The collaborative atmosphere that emerged during the course delivery was particularly encouraging. As we worked through the curriculum with participants, we observed an increasing willingness to ask questions and engage in technical discussions. The shared learning environment created a space where it was safe to explore ideas and learn from mistakes, fostering the kind of supportive culture we hoped to build in our engineering teams. While it’s too early to assess the long-term impact of this initiative, these early signs suggest that our investment in structured learning and knowledge sharing has the potential to strengthen our engineering practice in meaningful ways.

Expanding Your Impact Toolkit

For tech leads looking to expand their influence beyond code, consider these approaches:

1. Identify Knowledge Gaps

For tech leads looking to create a similar impact in their organizations, the journey should begin with a careful assessment of knowledge gaps within their teams. In my experience, this process started with paying closer attention to the daily challenges faced by team members, particularly noting recurring questions and common stumbling blocks. Through observing code review discussions, architecture planning sessions, and day-to-day problem-solving activities, patterns began to emerge. These patterns highlighted not just technical skill gaps, but also areas where theoretical knowledge from academic backgrounds wasn’t translating effectively into practical application within our specific business context.

The identification process shouldn’t stop at technical skills alone. By engaging in conversations with team members across different experience levels and roles, I discovered gaps in understanding of our broader business context and development practices. These discussions revealed opportunities for improvement in areas such as system design approaches, performance optimization strategies, and cross-team collaboration practices. Understanding these gaps required looking beyond immediate technical challenges to see how our teams’ capabilities aligned with the organization’s strategic objectives and growth plans. This broader perspective helped ensure that any educational initiative we developed would address not just immediate technical needs, but also support the long-term success of both the team and the organization.

2. Start Small

While the desire to create comprehensive educational programs might be strong, I’ve learned that starting with smaller, focused initiatives can provide valuable insights and build momentum. My journey began with a single focused workshop addressing a specific technical challenge our team was facing. This modest start allowed me to experiment with different teaching approaches and content delivery methods without the pressure of a full-scale program. The immediate feedback and lessons learned from this initial effort were invaluable in understanding what resonated with participants and what needed adjustment, providing a solid foundation for future expansion.

The key to successfully growing these educational initiatives lies in maintaining consistent feedback loops and being willing to iterate. After each workshop or training session, I made it a point to gather detailed feedback from participants and incorporate their suggestions into the next iteration. This incremental approach not only helped refine the content and delivery but also built credibility within the organization. As team members began to see the value in these focused learning sessions, support for larger initiatives naturally grew. By demonstrating success on a smaller scale first, we were able to build the trust and organizational buy-in necessary to eventually develop more comprehensive training programs.

3. Leverage Technical Expertise

Your technical expertise as a senior engineer is your greatest asset when creating educational content, but I discovered that the key lies in how you translate this knowledge into digestible learning materials. Throughout the development of our course, I found myself constantly drawing from my own experiences with production systems and architectural decisions. Rather than presenting theoretical concepts in isolation, I focused on connecting them to real scenarios we’d encountered in our work. When explaining a particular design pattern or best practice, I would accompany it with examples of how it solved actual problems we’d faced, or in some cases, how its absence had led to challenges in past projects.

The art of leveraging technical expertise for education goes beyond just sharing what you know — it’s about creating meaningful learning experiences that bridge the gap between theory and practice. I structured hands-on exercises around simplified versions of real challenges we’d encountered, allowing participants to experience the same problem-solving process we go through in our daily work. When discussing system architecture, I would walk through the evolution of our own systems, explaining the decisions we made and their consequences. This approach of grounding everything in practical experience helped participants understand not just the how of our technical practices, but also the crucial why behind our decisions, making the learning more engaging and immediately applicable to their work.

4. Build Support Networks

The success of any educational initiative relies heavily on building a strong network of support throughout the organization. In our case, this began with engaging our technical leadership team, sharing the vision for the training program and demonstrating how it aligned with our organization’s growth objectives. These early conversations proved crucial in securing not just approval, but active support for the initiative. Senior engineers across different teams began expressing interest in contributing their expertise, offering to review content or share their experiences in specific technical areas. This collaborative approach helped ensure the program’s content was well-rounded and reflected the diverse technical perspectives within our organization.

Equally important was fostering connections with the broader engineering community within our company. Regular updates about the program’s development and its potential impact helped maintain visibility and generate interest. I found that keeping communication channels open with team leaders and potential participants helped shape the program to better meet their needs. This ongoing dialogue created a sense of shared ownership in the program’s success, with various team members volunteering their time and insights to improve the content. The support network we built wasn’t just about securing resources — it became a community of people invested in the growth and development of our engineering talent.

Conclusion

As technical leaders, our value to the organization extends far beyond our ability to write code or design systems. By identifying opportunities to share knowledge and build capabilities within our teams, we can create lasting impact that scales beyond our direct technical contributions.

The journey from developing a small course to creating a comprehensive training program taught me that some of our most significant contributions might come from stepping outside our comfort zones. Whether through educational initiatives, process improvements, or cultural engineering, tech leads have unique opportunities to shape their organizations in meaningful ways.

Remember, every piece of knowledge shared, every process improved, and every junior engineer mentored contributes to the organization’s long-term success. As you progress in your technical leadership role, consider how you might expand your impact beyond code. The future of technical leadership lies not just in what we can build ourselves, but in how we can empower and elevate entire teams to build better solutions together.

Beyond Code: How Tech Leaders Can Drive Organizational Growth Through Knowledge Sharing was originally published in Similarweb Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

That’s when the idea hit us — what if we started a backend engineering guild to bring people together? A forum for “builders” across teams to connect, share ideas, and learn. We weren’t sure exactly what it would look like, but we knew we had to give it a shot.

Here’s the story of how we started “The Builders Forum”, the backend engineering guild at our company, and some tips for starting your own thriving technical guild.

Gauging Interest

First, we wanted to see if others were interested in the idea of a backend guild. We put out some feelers by having casual conversations with engineers on various teams. Whenever the topic of cross-team collaboration or knowledge sharing came up, we’d mention the idea of starting a guild. To our delight, many were enthusiastic about it. They faced the same isolation we did and craved more connection with their fellow backend devs.

These informal conversations confirmed there was significant interest and gave us the confidence to move forward. We also got a lot of great ideas from these chats that helped shape the direction of the guild.

Kick-off Meeting

We scheduled an initial kick-off meeting and invited anyone who was interested. The purpose was to introduce the concept of the guild and gauge people’s interest in participating and contributing.

To start off, we presented the idea ourselves. We wanted to set the tone that this was a collaborative effort and that everyone’s participation was welcome and valued. By presenting first, we hoped to make others feel more comfortable with the idea of presenting and sharing at future meetings.

The turnout was great and the response was very positive. Many attendees expressed excitement about the guild and volunteered to give talks or lead sessions on various backend topics they were passionate about.

We also brainstormed between ourselves about different types of events and activities the guild could host: — Talks and presentations on backend topics — Roundtable discussions — Code reviews and collaboration sessions — Workshops and tutorials — Hackathons — Social events and outings

Hosting Regular Events

With the positive response from the kick-off meeting, we started hosting regular guild events. We aimed to have at least one event per month, with a variety of formats.

Some of our most popular events have included:

- A talk on FastAPI best practices

- A comparison between serverless and monolith architecture within our organization

- A new approach for using Airflow operators

- A deep dive for our yearly Hackathon winning project

For each event, my partner and I take on the organization tasks. We create an agenda, coordinate with speakers or facilitators, book a room, order food, and invite the whole backend engineering org. It’s a lot of work, but we’re committed to making the guild a success.

We also set up a dedicated Slack channel for the guild where we announce upcoming events, share relevant articles and resources, and keep the discussion going between meetings. This keeps engagement high and makes the guild feel like an active community.

Lessons Learned

It’s been a year since we started The Builders Forum, and while it’s been very successful, we’ve also learned some lessons along the way:

1. Consistency is key. It’s easy to let the guild slide when things get busy, but having a consistent schedule of events that people can plan around keeps momentum and engagement high.

2. Embrace variety. Different people like different formats, so having a mix of talks, discussions, social events, etc. helps keep things fresh and appeals to a range of preferences.

3. Encourage participation. Encouraging others to lead sessions and share their knowledge has been crucial. It’s not just about my partner and I presenting.

4. Get leadership buy-in. Our engineering managers and CTO have been supportive of the guild, which helps a lot with things like booking rooms and justifying time spent on it. Make sure your leadership sees the value.

5. Keep it fun. At the end of the day, the guild is an opportunity to connect with fellow backend devs and geek out together. The more fun it is, the more people want to engage. Don’t take it too seriously and optimize for enjoyment.

Get Started!

Starting The Builders Forum has been incredibly rewarding. It’s broken down silos, sparked collaborations, leveled up skills across the board, and formed a thriving backend community at our company. If your engineering org could benefit from more connection and collaboration (and whose couldn’t?), I highly recommend starting your own technical guild.

Use this post as a rough guide, but make it your own! Talk to engineers on different teams to gauge interest and gather ideas. Find a co-conspirator to help with the organizing. Schedule an initial kick-off meeting to introduce the idea and see who’s interested in participating and contributing. Then pick a date for your first event and make it happen!

With some passion and consistency, you’ll have a thriving technical guild of your own in no time. Trust me, your engineering org will thank you. Now get out there and start connecting and collaborating!

The Builders Forum: How We Started a Thriving Technical Guild was originally published in Similarweb Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Three months ago, life as I knew it was upended. The onset of war in my country led to a swift and unexpected transition for many of us, including myself, from my role as software engineer to fulfilling civic duty in the reserves. This abrupt change left a profound impact, not just on me but on several of my colleagues who found themselves in similar situations, with some still serving. This blog post is a reflection on this shared experience, focusing on the unique challenges and learnings that come with such sudden transitions in my professional life.

Understanding the Process

The experience of leaving a familiar work environment for an uncertain future brought about a profound realization of the challenges faced in such transitions. The first lesson was clear: the importance of robust, adaptable processes in a tech team. When a key member steps away suddenly, the team’s ability to maintain momentum hinges on these established practices. In my case, and for many of my colleagues, the disruption highlighted the crucial role of clear communication channels and flexible workflows, which had been set up but not fully appreciated until tested by these circumstances.

The second lesson was about the resilience of our team dynamics. The absence of one or more team members can strain a team, yet it can also reveal the strength of the collective. It’s in these moments that the team’s adaptability and cohesiveness are truly tested. For us, it meant redistributing responsibilities, relying more on remote collaboration tools, and finding new ways to support each other, both professionally and emotionally.

The Essence of Good Coding Practices During Absences

In the whirlwind of our sudden departures, the underlying principles of good coding practices stood out as a beacon. These practices, often summed up as ‘clean code’, go beyond mere neatness. They encompass writing code that is not just functional but also clear, well-organized, and easily maintainable. In our absence, this approach to coding proved to be a critical asset.

The true power of these practices became apparent when we returned and seamlessly re-engaged with our projects. The code we revisited wasn’t a puzzle to be solved; it was a clear map, guiding us through the logic and decisions made in our absence. This clarity in code meant less time deciphering and more time contributing effectively, facilitating a smoother transition back into the team.

Moreover, these coding principles fostered a sense of ongoing collaboration. Despite not being physically present, the well-structured code acted as a continuous thread of communication. It bridged the gaps left by our absence, ensuring that projects didn’t just survive but thrived. This experience underscored the fact that good coding practices are more than technical necessities; they are vital for sustaining team momentum and adaptability in times of change

Personal Insights on Team Communication

During my time away and upon my return, the critical role of efficient communication within the team became increasingly apparent. It wasn’t just about staying in touch; it was about ensuring that the communication was effective and facilitated a smooth transition.

The essence of good communication in our team was rooted in clarity and precision. Every interaction, whether it was a quick update or a detailed discussion, was approached with a focus on clear, concise, and meaningful exchanges. This approach reduced misunderstandings and streamlined our collaborative efforts, making it easier for me and others who were away to reintegrate seamlessly.

Additionally, the importance of working cleanly and methodically played a significant role in our communication efficiency. When code, documentation, and project plans are structured and well-organized, they communicate as effectively as a well-crafted email or meeting. This clarity in our work products meant that a significant portion of our communication was already embedded in the work itself, reducing the need for lengthy explanations and clarifications.

This combination of efficient communication and clean working practices created an environment where information flowed smoothly and collaboration was effortless. It highlighted that effective communication is not just about the frequency or methods used but is deeply interconnected with how we approach our work. The efforts made by my team in maintaining these standards significantly eased the challenges of my reintegration, making it a cohesive and productive experience.

This experience taught a crucial lesson: the symbiotic relationship between effective communication and orderly work practices is key to team resilience and adaptability, particularly during times of transition.

Adapting to Task Nature During Transition Periods

There was a brief period during my absence when I was able to return to the team for a few days. This short stint back in the office offered a unique insight into how task assignments adapt during such transition periods. Instead of diving back into the deep end with mission-critical tasks, I was assigned to handle smaller, infrastructure-related tasks. This strategic choice by our team leadership proved to be incredibly beneficial for several reasons.

Firstly, these tasks, while less critical, were vital for the smooth running of our systems. They included minor coding tasks, system updates, and small-scale project management. This focus allowed me to contribute meaningfully without the pressure of immediately tackling complex, high-stakes projects.

Secondly, handling these tasks provided me with the opportunity to reacquaint myself with the team’s current workflow and technological stack. Changes, however minor, had occurred during my absence, and these tasks acted as a gentle reintroduction to these new elements.

Lastly, this approach had a positive impact on team dynamics. It eased the burden of my readjustment on my colleagues, ensuring that their workflow wasn’t disrupted by my need to catch up. It also demonstrated the team’s understanding and support, acknowledging that a gradual reintegration was more effective than an immediate deep dive.

This experience underscored a valuable lesson: the importance of thoughtful task allocation during transitional periods. It not only aids in the smooth reintegration of returning team members but also maintains team stability and productivity. It’s a strategy that not only benefits the returning team member but also the entire team, fostering a more supportive and adaptable work environment.

Transitioning Back to Civilian Life

Returning to civilian life after serving in the reserves is a process, one that unfolds over time and requires patience and understanding. This transition is not just a change in routine; it’s a shift in mindset and environment. It’s essential to recognize and accept that it’s okay for this adjustment to take time.

My own journey back to the civil world was significantly eased by the unwavering support I received from my manager. Their understanding and empathy during this period were invaluable. They recognized the challenges of this transition and provided the necessary space and support for me to gradually readjust to the civilian work environment. This support was not just about easing back into work; it was about reorienting myself to a life that had momentarily taken a backseat.

The patience and guidance from my manager and colleagues reminded me that it’s not about rushing to ‘get back to normal’ but allowing oneself the time and space to adapt at a comfortable pace. Their support was a critical element in my smooth transition, reinforcing the idea that the journey back to civilian life is a gradual process, one that benefits greatly from a supportive and understanding work environment.

Conclusion

The journey of stepping away and then returning to a tech team, especially under extraordinary circumstances like a national crisis, is fraught with challenges. Yet, it also brings invaluable lessons and opportunities for growth. The experiences shared in this blog post — from adapting to changes in team dynamics to embracing efficient communication and orderly work practices — demonstrate that we are equipped with the tools and resilience needed to navigate whatever lies ahead.

As I reflect on the myriad of challenges and transitions we’ve faced, one thing becomes clear: the future is uncertain, but our preparation for it is not. While we cannot predict the future, our journey thus far has armed us with adaptability, empathy, and innovative thinking. These are the tools that will guide us through unknown territories. It’s with this mindset that we can approach the future, not with apprehension, but with the confidence that comes from knowing we are prepared to face and adapt to whatever challenges it may bring.

Resilience in Code: Lessons Learned After 97 Days at War was originally published in Similarweb Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Reality of Technical Debt

Technical debt is like that credit card bill you keep saying you’ll pay off next month but never do. It accumulates interest, and before you know it, you’re stuck in a cycle of just paying the minimum amount, never really reducing the principal. In software terms, this means your team is spending more time fixing bugs and navigating through complex, outdated code than actually building new features.

Strategies for Fighting Tech Debt: A Deeper Dive

Regular Audits: The Health Check-Ups

Regular audits are akin to the health check-ups we all know we should be getting but often neglect. In the context of software engineering, these audits serve as a diagnostic tool to identify areas of the codebase that have accumulated technical debt. I’ve found that setting aside time for these audits at least once a quarter has been invaluable.

But the audit doesn’t stop at identification; it extends to action. Once the audit is complete, we categorize the issues based on their severity and impact. We then create actionable tickets and prioritize them in our development backlog. This ensures that the identified issues don’t just sit there but are actively addressed in subsequent sprints.

The key to making audits effective is consistency and follow-through. It’s easy to conduct an audit once and forget about it, but the real value comes from making it a recurring activity. This allows us to track our progress over time and ensures that we’re moving in the right direction in terms of code quality and maintainability.

Prioritize Refactoring: The Diet Plan

Refactoring is the “diet plan” of the software world. We all know it’s good for us, but it’s often the first thing to be sacrificed when deadlines loom. I’ve been guilty of this more times than I’d like to admit. However, I’ve come to realize that consistent, small-scale refactoring is far more manageable and effective than occasional, large-scale overhauls.

To make refactoring a priority, I’ve started allocating a fixed percentage of each quarter solely for these tasks. This ensures that refactoring becomes an integral part of our development cycle rather than a one-off activity that happens “when we have time.” The trick is to make it non-negotiable, just like you would with a diet plan.

The benefits of this approach are twofold. First, it helps in gradually reducing the existing technical debt. Second, it prevents the accumulation of new debt by ensuring that we continuously improve the codebase. It’s a proactive approach that pays dividends in the long run.

Automated Testing: The Exercise Regimen

Automated testing is the exercise regimen that keeps your codebase fit and healthy. I’ve found that a robust automated testing framework is an invaluable asset in the fight against technical debt. We use a combination of unit tests, integration tests, and end-to-end tests to cover as much ground as possible. These tests are run automatically as part of our CI/CD pipeline, ensuring that any new code or changes to existing code are thoroughly vetted before being deployed.

The beauty of automated testing is that it provides immediate feedback. If a piece of code doesn’t meet the expected standards or if it breaks existing functionality, we know right away. This allows us to catch issues early in the development cycle, making them easier and less costly to fix.

Moreover, a strong testing framework acts as a safety net, giving developers the confidence to refactor and make changes to the codebase. This is crucial for reducing technical debt, as it allows us to improve the code quality without the fear of breaking existing functionality.

Code Reviews: The Personal Trainer

Code reviews are the personal trainers of the software development world. They provide an external perspective, catch potential issues, and push you to do better. I’ve made it a rule in my team that no code gets merged into the main branch without undergoing a peer review. This practice serves multiple purposes.

First, it acts as a quality gate, ensuring that the code meets the team’s standards both in terms of functionality and readability. Second, it fosters a culture of collective code ownership. When multiple eyes scrutinize every line of code, it’s less likely that technical debt will slip through the cracks.

Lastly, code reviews are an excellent platform for knowledge sharing and mentorship. More experienced team members can provide insights and best practices, while less experienced members get the opportunity to learn and improve. It’s a win-win situation that not only helps in reducing technical debt but also contributes to the team’s overall growth and development.

Building a Technical Immune System

Monitoring: The Vital Signs

Monitoring is the heartbeat of a technical immune system. Imagine walking into a hospital room where the patient’s vital signs are continuously displayed on a monitor. The doctors and nurses can instantly see if something goes wrong. Similarly, in the realm of software engineering, monitoring tools act as our eyes and ears, continuously scanning the codebase for “vital signs” like code complexity, dependency vulnerabilities, and performance metrics.

Monitoring is not just about collecting data; it’s about making sense of it. We use tools like DataDog to visualize this data in real-time dashboards. We set up alerts that notify us via Slack or email if certain thresholds are crossed. For instance, if the build fails or if some data is missing, the team is immediately alerted.

The beauty of monitoring is that it allows for proactive rather than reactive measures. Instead of waiting for a system to fail or for a user to report an issue, we can identify potential problems before they escalate. This is akin to catching a disease in its early stages, making it much easier to treat. Monitoring is the cornerstone of our technical immune system, providing the data we need to make informed decisions.

Automated Workflows: The Auto-Healing Mechanism

Automated workflows are the auto-healing mechanisms of our technical immune system. Just like white blood cells in our body rush to the site of an infection to combat pathogens, automated workflows kick in when they detect issues in the codebase. We use Continuous Integration/Continuous Deployment (CI/CD) pipelines to automate a series of checks and balances. These pipelines run a battery of tests, perform code quality assessments, and even auto-refactor code where possible.

The power of automation lies in its consistency and speed. Manual processes are prone to human error and can be time-consuming. Automated workflows, on the other hand, execute the same set of tasks with machine-like precision, and they do it fast. This ensures that any new code or changes to existing code meet the predefined quality standards before they are deployed.

Moreover, these workflows are not set in stone; they evolve. As we identify new types of issues or adopt new technologies, we update our workflows to include checks for them. This adaptability makes our technical immune system resilient and up-to-date, capable of dealing with new “pathogens” as they emerge.

Knowledge Sharing: The Collective Immunity

Knowledge sharing is what I like to call the “collective immunity” of our technical ecosystem. Just as herd immunity protects a community from the spread of diseases, a shared knowledge base safeguards the team from repeating past mistakes and poor practices. We maintain an internal wiki that serves as a repository for all things technical — best practices, coding guidelines, lessons learned from past incidents, and even architectural decisions.

This knowledge base is a living document, continuously updated and enriched by contributions from team members. New hires are encouraged to go through this repository as part of their onboarding process. This not only brings them up to speed but also instills a culture of knowledge sharing right from the start.

The impact of this collective knowledge is exponential. It not only helps in reducing the introduction of new technical debt but also aids in faster problem-solving. When faced with a challenge, team members can refer to the knowledge base to see if a similar issue has been tackled before, saving time and effort.

Feedback Loops: The Body’s Response System

Feedback loops are akin to the body’s nervous system, sending signals from various parts to the brain for interpretation and action. In our technical environment, these loops are channels of continuous feedback from all stakeholders — developers, QA teams, product managers, and even end-users. We use tools like Jira and Slack to facilitate this communication, and we hold regular retrospectives to discuss what’s working and what’s not.

Feedback loops serve multiple purposes. First, they help us gauge the impact of technical debt on the product and user experience. Second, they provide insights into areas that may not be on our radar but are causing pain points for others. For example, a feature that we consider “done” might be causing usability issues for the end-users.

By closing the feedback loop, we not only improve the product but also fine-tune our technical immune system. We learn from our mistakes and successes alike, making necessary adjustments to our strategies, tools, and workflows. This iterative learning process is what makes our technical immune system robust and effective, capable of adapting to new challenges and complexities.

Conclusion

Navigating the dangerous waters of software development — filled with tight deadlines, rapid changes, and high stakes — can often lead to accumulating technical debt. Fighting it is a continuous journey, not a destination. It’s about making conscious choices and trade-offs.
By implementing the right strategies and building a resilient technical immune system, I’ve found a sustainable way to manage technical debt without stifling innovation. It’s all about being prepared and proactive, so you can not only survive but thrive in this challenging environment.

Navigating Rough Waters: Shedding Technical Debt was originally published in Similarweb Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.