DEV Community: Ali Raza

Why Your Web App Feels Slow Even When Your Server Is Fast

Ali Raza — Fri, 16 Oct 2026 19:32:12 +0000

Understanding frontend bottlenecks, JavaScript execution, API latency, rendering delays, and the performance problems that server metrics often miss.

A web application can run on a powerful server, return API responses in milliseconds, and still feel frustratingly slow to its users.

A button takes too long to respond. A dashboard appears in pieces. A page remains blank even though the network requests have completed. Scrolling becomes uncomfortable when a complex component renders, and a simple interaction occasionally freezes the entire interface.

When developers investigate these problems, the first instinct is often to check server response times, database queries, and infrastructure resources.

Those checks are important, but they do not tell the whole story.

Server speed and perceived application speed are two different things.

A web application is a complete pipeline involving network communication, browser processing, JavaScript execution, rendering, asset delivery, and user interaction. A bottleneck anywhere in that pipeline can make the application feel slow, even when the backend is performing well.

In this article, we will examine why that happens, how to identify the actual bottleneck, and which optimization techniques can improve the experience without unnecessary infrastructure changes.

1. Understanding the Difference Between Server Performance and User Experience

Consider a web application that returns its main API response in 100 milliseconds.

That sounds fast. However, the user might still wait several seconds before seeing usable content.

The application may need to:

Resolve the domain and establish a connection.
Download the HTML document and JavaScript bundles.
Parse and execute JavaScript.
Request data from multiple API endpoints.
Transform the received data.
Render components and calculate layout.
Download images and other visual assets.
Wait for the interface to become interactive.

Some operations happen in parallel, while others depend on previous operations completing.

For example, a dashboard might wait for a user profile before requesting personalized content. The content then needs to be processed before its components can render.

Even if every individual API response is fast, a poorly designed sequence of dependent operations can introduce significant delays.

This is why developers should distinguish between backend performance and the complete user-facing experience.

A simple example

Imagine a page with the following approximate timings:

Operation	Time
Initial HTML response	100 ms
JavaScript download	500 ms
JavaScript processing and execution	700 ms
API request	150 ms
Rendering and layout work	250 ms

These numbers are illustrative, not benchmark results. The operations may overlap, so adding them together does not necessarily produce the actual page load time.

However, the example demonstrates an important point: a fast API does not guarantee that a page will become usable quickly.

The objective is to measure the user's experience, not just the server's response.

2. JavaScript Can Become the Main Performance Bottleneck

Modern web applications often rely on JavaScript for routing, state management, data transformation, form validation, and dynamic rendering.

This flexibility comes with a cost.

Downloading JavaScript is only one part of the process. The browser must also parse, compile, and execute the code. Large bundles, expensive computations, and excessive rendering work can delay user interactions.

The problem with long-running JavaScript tasks

JavaScript running on the browser's main thread can prevent the browser from responding promptly to user input while a long task is executing.

For example:

function processLargeDataset(items) {
  const results = [];

  for (const item of items) {
    results.push({
      ...item,
      normalizedName: item.name.trim().toLowerCase(),
    });
  }

  return results;
}

This function is reasonable for a small collection. However, if it processes hundreds of thousands of objects synchronously, it can block the main thread long enough to make the interface unresponsive.

A better approach depends on the workload.

Possible improvements include:

Processing data in smaller chunks.
Moving expensive computations into a Web Worker.
Avoiding unnecessary transformations.
Using pagination or virtualization for large datasets.
Performing filtering and aggregation on the server when appropriate.

For computationally intensive work, a Web Worker can execute JavaScript away from the main UI thread:

const worker = new Worker("/data-worker.js");

worker.postMessage(largeDataset);

worker.onmessage = (event) => {
  renderResults(event.data);
};

The worker file must implement the corresponding message handler and processing logic. The main thread can then receive the results without performing the entire computation itself.

Workers have overhead and cannot directly manipulate the DOM, so they are most useful for independent computational tasks.

Reduce unnecessary JavaScript

Bundle size also matters.

A large dependency tree can increase download, parsing, and execution costs, particularly on slower devices.

Useful techniques include:

Tree-shaking unused exports.
Lazy-loading routes and expensive components.
Splitting code according to user journeys.
Removing unnecessary dependencies.
Avoiding loading administrative features on public pages.
Analyzing production bundles before adding new libraries.

The goal is not simply to minimize the total number of kilobytes. It is to deliver the JavaScript required for the current task without making users wait for code they may never need.

3. Your API Can Be Fast While Your Application Is Slow

A backend endpoint returning a response in 100 milliseconds sounds efficient. But the frontend may depend on several endpoints before it can display the information users need.

One common problem is sequential API requests.

Consider this example:

async function loadDashboard() {
  const user = await fetch("/api/user")
    .then((response) => response.json());

  const courses = await fetch(`/api/courses?userId=${user.id}`)
    .then((response) => response.json());

  const progress = await fetch(`/api/progress?userId=${user.id}`)
    .then((response) => response.json());

  return { user, courses, progress };
}

The course and progress requests do not start until the user request finishes.

If the user request takes 100 milliseconds and the other two each take 150 milliseconds, the request sequence can require approximately 400 milliseconds, excluding additional processing and network overhead.

If the second and third requests are independent after the user ID is known, they can run concurrently:

async function loadDashboard() {
  const userResponse = await fetch("/api/user");

  if (!userResponse.ok) {
    throw new Error("Unable to load user");
  }

  const user = await userResponse.json();

  const [coursesResponse, progressResponse] = await Promise.all([
    fetch(`/api/courses?userId=${user.id}`),
    fetch(`/api/progress?userId=${user.id}`),
  ]);

  if (!coursesResponse.ok || !progressResponse.ok) {
    throw new Error("Unable to load dashboard data");
  }

  const [courses, progress] = await Promise.all([
    coursesResponse.json(),
    progressResponse.json(),
  ]);

  return { user, courses, progress };
}

This removes the unnecessary sequential dependency between the course and progress requests.

However, concurrency is not always the answer. Too many simultaneous requests can overload services, duplicate work, or consume unnecessary resources.

Developers should identify actual dependencies before changing request patterns.

Other API-related bottlenecks

Even when response times are low, the application can suffer from:

Fetching entire datasets when only a few records are needed.
Returning unnecessarily large JSON payloads.
Repeatedly requesting the same data.
Refetching data after every small interaction.
Waiting for nonessential analytics or recommendations.
Requiring multiple round trips for information that could be combined.

Measure the complete request flow, not just the duration reported by the backend.

4. Rendering Too Much Can Make the UI Feel Unresponsive

A frontend framework makes it easier to build complex interfaces, but it does not eliminate the cost of rendering them.

A component may rerender because its state changes, its parent rerenders, or its props receive new references. Some rerenders are necessary. Others perform work that does not contribute to the visible result.

Consider a dashboard displaying hundreds of cards, each with several nested components.

If the application repeatedly recalculates every card after a small state change, users may notice delays when filtering, sorting, or opening a menu.

Common rendering problems

Rendering large lists without virtualization

Displaying thousands of DOM elements creates layout, memory, and rendering overhead.

List virtualization renders only the visible items and a small surrounding buffer. Libraries such as react-window can help implement this approach.

Performing expensive calculations during rendering

Large sorting, filtering, or aggregation operations can make repeated renders costly.

Move calculations to appropriate locations, cache results when useful, or process the data outside the main thread if the workload warrants it.

Recreating expensive components unnecessarily

Memoization can help when a component repeatedly receives unchanged inputs and its rendering cost is significant.

In React, for example:

import { memo } from "react";

const CourseCard = memo(function CourseCard({ course }) {
  return (
    <article>
      <h2>{course.title}</h2>
      <p>{course.description}</p>
    </article>
  );
});

memo can skip some rerenders when props remain equal under its comparison rules. It does not guarantee that every render will be skipped, and it will not prevent rerenders caused by the component's own state or consumed context.

Measure before adding memoization everywhere. Unnecessary memoization adds complexity and can make code harder to maintain.

5. Large Images and Fonts Can Delay the Visible Page

An application may have efficient JavaScript and fast APIs but still appear slow because its visual assets arrive late.

Large hero images, unoptimized screenshots, oversized illustrations, and font files can delay rendering or cause visible layout shifts.

This is especially important for content-heavy applications, dashboards, education platforms, and marketing websites.

Optimize image delivery

Useful techniques include:

Serving appropriately sized images for each viewport.
Using modern formats such as WebP or AVIF when supported by the delivery pipeline.
Compressing images without unacceptable quality loss.
Providing width and height dimensions to reduce layout shifts.
Using responsive image candidates through srcset and sizes.
Lazy-loading images that are below the fold.

For example:

<img
  src="/images/study-guide-800.webp"
  srcset="
    /images/study-guide-400.webp 400w,
    /images/study-guide-800.webp 800w
  "
  sizes="(max-width: 600px) 100vw, 800px"
  width="800"
  height="450"
  alt="Example of an organized study guide"
/>

The browser can select a suitable image candidate based on the available information.

Do not lazy-load the primary above-the-fold image if it is likely to be the Largest Contentful Paint element. Delaying that image can make the page feel slower.

Fonts also matter

Custom fonts may block or delay text rendering, introduce additional network requests, or cause layout shifts when fallback fonts are replaced.

Consider using fewer font weights, serving appropriately subsetted font files, and applying font-display: swap where suitable.

The goal is to make meaningful content visible quickly, rather than waiting for every visual detail to load.

6. Core Web Vitals Help Explain What Users Experience

Google's Core Web Vitals provide useful measurements for evaluating loading performance, responsiveness, and visual stability.

The three current Core Web Vitals are:

Metric	What it measures	Good threshold
Largest Contentful Paint (LCP)	How quickly the main visible content loads	2.5 seconds or less
Interaction to Next Paint (INP)	How responsive the page is to user interactions	200 milliseconds or less
Cumulative Layout Shift (CLS)	Unexpected visual movement during page use	0.1 or less

These thresholds are evaluated at the 75th percentile of page visits, segmented by mobile and desktop where applicable.

Largest Contentful Paint

A slow LCP may indicate that the main content is delayed by server response time, render-blocking resources, JavaScript dependencies, or a large image.

Investigate the actual LCP element before selecting an optimization.

Interaction to Next Paint

A poor INP can indicate that clicks, keyboard input, or other interactions trigger excessive JavaScript work, expensive rendering, or delayed presentation of the result.

Use browser performance traces to determine which part of the interaction is consuming time.

Cumulative Layout Shift

A poor CLS often results from images without reserved dimensions, dynamically inserted content, or fonts that change the layout after rendering.

Reserve space for content that loads asynchronously and avoid inserting elements above existing content without accounting for their dimensions.

Core Web Vitals are valuable signals, but no single metric explains every performance problem. A page can meet the thresholds and still have frustrating interactions that deserve investigation.

7. Caching Can Reduce Repeated Work

If users repeatedly request the same data, the application may be performing work that could have been avoided.

Caching can reduce network requests, server load, and perceived waiting time.

Different layers offer different opportunities:

Browser caching: Store reusable static resources such as images, stylesheets, and versioned JavaScript bundles.

CDN caching: Deliver cacheable resources from locations closer to users.

Application data caching: Reuse API results when the data remains valid for the current user and context.

Server-side caching: Avoid repeatedly calculating expensive results when they can safely be reused.

HTTP caching headers, such as Cache-Control and ETag, can help browsers and intermediary caches determine whether a resource can be reused or needs revalidation.

However, caching must respect data freshness, user permissions, and privacy.

Personalized dashboards and private educational records should not be placed in shared caches without careful control. A fast response is not worth exposing one user's information to another.
https://goodoff.co/

8. Measure Performance Before Making Changes

One of the most expensive mistakes in performance optimization is fixing a problem that does not exist.

Developers may compress assets, rewrite components, add caching layers, or upgrade infrastructure without identifying what users are actually waiting for.

A more reliable process begins with measurement.

Step 1: Reproduce the problem

Test the affected page under realistic conditions.

Check whether the slowdown occurs on initial load, navigation, search, filtering, scrolling, or a particular user interaction.

Step 2: Inspect the browser Network panel

Look for:

Slow requests.
Long dependency chains.
Large response payloads.
Duplicate API calls.
Requests that block important content.
Images and fonts that arrive too late.

Remember that the browser's reported timings may reflect several stages, including connection setup, waiting for the response, and downloading the body.

Step 3: Use the Performance panel

Chrome DevTools can help identify long tasks, JavaScript execution, layout recalculations, painting, and interaction delays.

Record the problem while reproducing it. A trace can reveal whether the main thread is busy when the interface becomes unresponsive.

Step 4: Test with Lighthouse

Lighthouse can identify common performance issues and provide diagnostic information about page loading, resources, and rendering.

Use it as a starting point, not as a substitute for real-user data. Lab conditions may differ from users' devices, networks, and browsing behavior.

Step 5: Compare before and after

Record the relevant metric, make one meaningful change, and test again under comparable conditions.

For production websites, field data from real users can help confirm whether the improvement persists beyond a controlled development environment.

Useful tools include Chrome DevTools, Lighthouse, PageSpeed Insights, and the browser's Performance APIs.

9. A Practical Performance Checklist for Developers

Before increasing server capacity, review the entire application.

[ ] Measure real user performance and identify the slowest user journeys.
[ ] Check LCP, INP, and CLS for the affected pages.
[ ] Identify large JavaScript bundles and unused dependencies.
[ ] Investigate long tasks on the browser's main thread.
[ ] Remove unnecessary sequential API requests.
[ ] Reduce oversized responses and duplicate data fetching.
[ ] Virtualize large lists when rendering costs justify it.
[ ] Optimize images, fonts, and other critical assets.
[ ] Cache reusable resources with appropriate freshness rules.
[ ] Reserve layout space for asynchronously loaded content.
[ ] Retest after each significant optimization.

Not every application needs every technique. Prioritize changes based on evidence, user impact, implementation cost, and regression risk.

10. Why This Matters for Modern Web Applications

The distinction between server performance and perceived speed becomes especially important in applications that display frequently changing or generated content.

For example, an educational web application may need to load study materials, render flashcards, display quiz results, and update learning progress. Even when its backend responds quickly, large client-side bundles, unnecessary rendering, or inefficient data flows can make the experience feel sluggish.

A platform such as GoodOff, which helps students work with study materials in different learning formats, provides a relevant example of the kind of product where responsive interfaces and efficient content delivery can matter to the overall learning experience.

This is not a claim about GoodOff's current performance or architecture. It illustrates why developers of content-rich applications should evaluate the complete user journey, from requesting material to interacting with the finished interface.

When users are trying to learn, complete a task, or find information, unnecessary waiting can interrupt their workflow.

Performance is therefore not just an infrastructure concern. It is part of product usability.

Conclusion

A fast server is valuable, but it is only one component of a responsive web application.

Users experience the entire system: network requests, JavaScript execution, data processing, rendering, asset delivery, and interaction feedback. A bottleneck in any of these areas can undermine the work invested in backend optimization.

The most effective approach is to measure the experience, identify the actual bottleneck, make a targeted improvement, and verify the result.

Start with the browser's Network and Performance panels. Examine Core Web Vitals. Investigate JavaScript execution, rendering behavior, API dependencies, and asset delivery before assuming that your server needs more resources.

The real goal is not simply to make the server respond faster. It is to make the application feel fast when people use it.

When developers optimize for the complete user experience, performance improvements become more measurable, more meaningful, and more likely to solve the problem users actually notice.

Suggested discussion question: What has caused the biggest performance bottleneck in your web applications: JavaScript execution, API latency, rendering, or asset delivery? Share your experience in the comments.

Your API Works Locally but Fails in Production: A Systematic Debugging Guide

Ali Raza — Wed, 14 Oct 2026 18:39:15 +0000

Your API works perfectly on your laptop. The endpoints return the expected responses, database queries succeed, and your frontend communicates with the backend without any issues.

Then you deploy.

Suddenly, requests return 500 Internal Server Error. Authentication stops working. Database connections fail. Some endpoints work in Postman but fail in the browser. Other requests remain pending until they time out.

The frustrating part is that you did not intentionally change the application logic.

This is one of the most challenging parts of software development: an application that works in a development environment does not necessarily behave the same way in production.

The solution is not to randomly change configuration values or rewrite working code. It is to identify what changed between the two environments and isolate the failure systematically.

In this guide, we will examine the most common causes of production API failures, practical debugging techniques, and a repeatable workflow developers can use to diagnose problems without wasting hours.

1. Start by Identifying Where the Request Fails

Before changing code, determine which part of the request lifecycle is failing.

A typical API request passes through several stages:

The client sends an HTTP request.
DNS resolves the API domain.
A network connection is established.
A reverse proxy or load balancer forwards the request.
The application receives and processes it.
Authentication and validation run.
The application accesses a database or external service.
The server returns a response.
The client receives and processes that response.

A failure at any stage can make the API appear broken.

For example, a 502 Bad Gateway may indicate that a proxy cannot communicate successfully with the upstream application. A 401 Unauthorized usually points toward authentication, while a 500 Internal Server Error indicates an unexpected server-side failure.

These status codes are clues, not definitive diagnoses.

Start with the browser's Network tab, your API client, and the server logs. Record the failing endpoint, HTTP method, status code, response body, and approximate timestamp.

Then compare a successful local request with the failing production request.

The objective is simple: identify the earliest stage where their behavior differs.

2. Missing or Incorrect Environment Variables

Environment configuration is one of the first things to investigate when an application works locally but fails after deployment.

Your local machine may contain a .env file with values such as:

PORT=3000
DATABASE_URL=postgresql://localhost:5432/myapp
JWT_SECRET=local-development-secret
API_BASE_URL=http://localhost:3000

However, your production server may use a completely different configuration system.

The deployment platform might not have all the required variables. A variable name may be incorrect, or the application may be reading a development URL instead of the production URL.

For example:

const databaseUrl = process.env.DATABASE_URL;

if (!databaseUrl) {
  throw new Error("DATABASE_URL is not configured");
}

Failing early with a clear error is better than allowing the application to start and fail unpredictably when the first database request arrives.

You can also validate configuration during startup:

const requiredVariables = [
  "DATABASE_URL",
  "JWT_SECRET",
  "API_BASE_URL"
];

for (const key of requiredVariables) {
  if (!process.env[key]) {
    throw new Error(
      `Missing required environment variable: ${key}`
    );
  }
}

Do not print secret values to the logs. Log whether a required variable exists, not its contents.

Also remember that frontend environment variables and backend environment variables are not necessarily interchangeable. Some frontend build systems embed configuration into the generated bundle during the build process. Changing a server variable after deployment may not update an already-built frontend.

Debugging tip: Compare configuration names and non-sensitive settings between environments. Check whether the application was rebuilt or restarted after configuration changes.

Reference: Node.js documentation on environment variables.

3. CORS Errors That Appear Only in Production

Cross-Origin Resource Sharing, or CORS, is another common source of confusion.

Imagine your frontend runs locally at:

http://localhost:5173

Your backend runs at:

http://localhost:3000

During development, your backend might explicitly allow the local frontend origin.

After deployment, the frontend moves to:

https://app.example.com

If the backend does not allow that production origin, browser requests can fail even though the API itself is running correctly.

For an Express application, a basic configuration might look like this:

import express from "express";
import cors from "cors";

const app = express();

const allowedOrigins = [
  "http://localhost:5173",
  "https://app.example.com"
];

app.use(cors({
  origin: allowedOrigins,
  methods: ["GET", "POST", "PUT", "PATCH", "DELETE"],
  allowedHeaders: ["Content-Type", "Authorization"]
}));

This is only an example. Your allowed origins, methods, and headers should match your application's actual requirements.

If your application uses cookies or other credentialed requests, additional configuration is needed. Credentialed CORS requests cannot use a wildcard origin.

Another important distinction: CORS is enforced by browsers. A request succeeding in Postman does not prove that a browser request will succeed.
https://goodoff.co/
Check the browser console and inspect the response headers. Also verify that the server handles preflight OPTIONS requests correctly.

Avoid fixing CORS by allowing every origin without understanding the security implications.

Reference: MDN: Cross-Origin Resource Sharing.

4. Database Connections That Work Locally but Fail After Deployment

Local development often uses a database running on the same machine. Production databases typically have different network boundaries, authentication rules, connection limits, and security requirements.

A connection string that works locally may point to the wrong host in production.

Other common causes include:

The production database does not allow connections from the application.
Credentials are incorrect or expired.
The database requires TLS.
The application exceeds its connection pool limit.
Database migrations have not been applied.
The database hostname cannot be resolved.
The database is temporarily unavailable.

Start by checking the exact database error in the server logs.

A connection timeout suggests a different problem from an authentication failure or a missing table.

For example, if your application reports that a relation does not exist, repeatedly changing firewall rules will not solve the issue. You need to investigate schema migrations and database selection.

A useful production health check can verify database connectivity:

app.get("/health", async (req, res) => {
  try {
    await db.query("SELECT 1");

    res.status(200).json({
      status: "ok"
    });
  } catch (error) {
    console.error("Database health check failed", {
      name: error.name,
      code: error.code
    });

    res.status(503).json({
      status: "unavailable"
    });
  }
});

Here, db.query() represents your database client's query method. Adapt it to your database library.

Keep health checks separate from detailed diagnostic endpoints. Public health endpoints should not expose connection strings, internal hostnames, stack traces, or other sensitive infrastructure details.

5. Reverse Proxies, Ports, and Deployment Configuration

Your application may listen on the correct port locally but fail behind a production proxy.

Consider this code:

app.listen(3000, () => {
  console.log("Server started");
});

This can work locally, but some hosting environments expect the application to use a port supplied through an environment variable.

A more flexible configuration is:

const port = Number(process.env.PORT) || 3000;

app.listen(port, "0.0.0.0", () => {
  console.log(`Server listening on port ${port}`);
});

Whether you need to bind to 0.0.0.0 depends on your hosting environment. Some platforms manage networking differently, so follow their deployment requirements.

You should also investigate reverse proxy configuration.

For example, the proxy might forward /api/users to an incorrect upstream address. It may also remove a URL prefix, impose a request body size limit, or terminate a connection before the application finishes processing.

When investigating these problems, check:

Is the application process running?
Is it listening on the expected port?
Can the proxy reach the application?
Are the forwarded paths correct?
Are proxy and application timeout settings compatible?
Do the proxy logs show an upstream connection error?

A 502 or 504 should lead you to investigate the proxy and upstream service rather than immediately changing application business logic.

6. Production Builds Behave Differently

Development and production builds may execute different code paths.

A development server can provide hot reloading, local proxies, detailed error messages, and permissive settings. A production build may use optimized assets, different environment variables, stricter security rules, or a different startup command.

For frontend applications, a development proxy may forward requests from /api to your local backend. That proxy may not exist after deployment.

For backend applications, a missing dependency, incorrect module format, or incompatible runtime version can prevent the application from starting.

Reproduce the production build as closely as possible before deploying:

npm ci
npm run build
npm start

These commands are examples. Use the scripts defined by your project.

Also verify the runtime version:

node --version
npm --version

Compare the results with your production runtime. If your application depends on a particular Node.js version, declare that requirement and configure the deployment environment accordingly.

For containerized applications, test the actual production container image rather than relying exclusively on your local development environment.

7. Authentication and HTTPS Problems

An endpoint may work locally because your development environment uses different authentication settings.

Production introduces additional variables, including HTTPS, cookie security, OAuth redirect URLs, token expiration, and secret rotation.

Suppose your frontend sends a bearer token:

const response = await fetch(
  "https://api.example.com/profile",
  {
    headers: {
      Authorization: `Bearer ${token}`
    }
  }
);

If the request returns 401, investigate whether the token is present, valid, unexpired, and signed with the expected key.

If the server returns 403, the identity may be valid but lack the necessary permission. However, applications can use these status codes differently, so inspect your authentication middleware.

For cookie-based authentication, verify the cookie's domain, Secure, SameSite, and path settings. Cross-site cookie behavior can differ significantly between localhost and production.

Never solve a TLS certificate problem by disabling certificate verification. Fix the certificate chain, hostname, trust configuration, or server certificate instead.

Useful checks include:

Confirming that the correct production identity provider is configured.
Verifying allowed OAuth redirect URLs.
Checking token issuer and audience validation.
Confirming that cookies are actually sent by the browser.
Ensuring that secret rotation has been applied consistently.

8. Missing Logs Turn Small Problems Into Long Investigations

When production fails, a developer needs evidence.

A generic message such as Something went wrong does not tell you whether the failure came from a database query, external API, validation rule, or application bug.

Structured logging makes requests easier to trace:

console.error("Request failed", {
  requestId,
  method: req.method,
  path: req.path,
  errorName: error.name,
  errorCode: error.code
});

In a real application, use a logging library and middleware to generate or propagate request IDs.

A request ID allows you to connect the same request across application logs, proxy logs, and downstream service logs.

Be careful about logging request bodies, authorization headers, passwords, session cookies, and personal information. Diagnostic data should help you investigate the failure without creating a security incident.

Production logging should capture enough information to answer four questions:

What operation failed?
When did it fail?
Which dependency or component was involved?
What error category explains the failure?

For larger systems, distributed tracing can help identify where latency accumulates across multiple services.

References: Express debugging guide and NestJS deployment and observability guidance.

9. A Systematic Debugging Workflow

Instead of trying fixes randomly, follow a consistent process.

Step 1: Reproduce the failure

Record the endpoint, HTTP method, request payload, response status, and timestamp. Use a test account and non-sensitive data whenever possible.

Step 2: Compare environments

Compare runtime versions, environment variable names, API base URLs, database configuration, network access, and build commands.

Step 3: Inspect the response

Look at response headers, response bodies, browser console messages, and network timing. Determine whether the request reached the application.

Step 4: Check server-side evidence

Search logs using the request timestamp or request ID. Identify the first meaningful error rather than focusing only on the final HTTP status.

Step 5: Test dependencies independently

Verify database connectivity, external API availability, DNS resolution, authentication, and network access from the production environment.

Step 6: Change one variable at a time

Apply the smallest reasonable fix. Changing several settings simultaneously makes it harder to identify the actual cause.

Step 7: Verify the fix

Repeat the original failing request. Test nearby cases, inspect logs, and confirm that the change has not introduced a new problem.

Step 8: Prevent recurrence

Add regression tests, configuration validation, monitoring, or deployment checks that catch the same failure earlier next time.

This process may feel slower than immediately changing code, but it usually reduces wasted debugging time.

10. Build a Production Readiness Checklist

Before deploying an API, verify the following:

[ ] Required environment variables are validated at startup.
[ ] Production secrets are configured securely.
[ ] The application uses the expected runtime version.
[ ] Database connectivity and migrations are verified.
[ ] CORS allows only the required origins.
[ ] Authentication and authorization work in the production environment.
[ ] Reverse proxy routes and timeout settings are correct.
[ ] Logs include request IDs and useful error context.
[ ] Health checks distinguish application availability from dependency health.
[ ] External services have sensible timeout and retry policies.
[ ] Production builds are tested before release.
[ ] A rollback procedure exists for failed deployments.

Not every application needs the same infrastructure. A small API may not require distributed tracing or a complex monitoring platform. The important thing is to introduce controls that match your application's risks and operational requirements.

Conclusion

When an API works locally but fails in production, the problem is not necessarily the code itself. It may be configuration, networking, database access, authentication, deployment behavior, or an interaction between several components.

The most effective approach is to isolate the failing stage, compare the two environments, collect evidence, and test one hypothesis at a time.

Developers who treat production debugging as a repeatable engineering process spend less time guessing and more time fixing the actual cause.

The goal is not just to make the API work again. It is to understand why it failed and make the next failure easier to diagnose.

How to Debug AI-Generated Code Without Blindly Copying Its Fixes

Ali Raza — Mon, 12 Oct 2026 18:42:42 +0000

Introduction

AI coding assistants can generate functions, explain stack traces, suggest fixes, and even modify several files in a single task. For developers, this can significantly reduce the time spent writing repetitive code.

However, generating a fix and verifying a fix are two different engineering tasks.

Imagine that your API crashes when a user submits an empty email address. You ask an AI assistant to fix it. The assistant adds a condition, the error disappears, and the application starts working again.

But what if the change only hides the error? What if it breaks valid requests, introduces a security weakness, or leaves another code path unprotected?

This is where developers need a reliable debugging process.

Instead of accepting an AI-generated solution because it looks reasonable, you should treat it as a hypothesis that needs evidence. The objective is not to stop using AI. It is to use AI in a way that makes debugging more systematic, predictable, and reliable.

1. Understand the Bug Before Asking AI to Fix It

One of the most common mistakes in AI-assisted development is describing a problem too vaguely.

A developer might write:

My API is not working. Fix the code.

The AI assistant has almost no useful information. It must guess the intended behavior, the possible failure, and the surrounding architecture. Even if it produces valid code, the solution may not address the real problem.

A better approach is to collect evidence before requesting a solution.

Start by identifying four things:

Expected behavior: What should the application do?
Actual behavior: What happens instead?
Reproduction steps: How can you consistently trigger the problem?
Relevant evidence: What do the logs, error messages, tests, or network requests reveal?

For example, instead of saying that a login endpoint is broken, describe the specific behavior:

Expected:
A valid login request should return a user session.

Actual:
The endpoint returns HTTP 500 when the email field is missing.

Reproduction:
Send a POST request to /api/login with an empty JSON object.

Recent change:
The request validation logic was modified in the latest commit.

This gives the assistant a concrete problem to investigate.

It also gives you a way to verify the proposed solution later.

The principle is simple: do not ask AI to guess what is wrong when you can provide evidence about what is wrong.

2. Reproduce the Bug Before Changing the Code

A bug that cannot be reproduced is difficult to diagnose reliably.

Before editing the implementation, try to reproduce the issue in a controlled environment. Use the same inputs, request parameters, application state, and relevant configuration whenever possible.

For a web application, useful debugging evidence may include:

Browser console errors
Network requests and responses
Server logs
Stack traces
Database query results
Failed automated tests
Recent code changes

Suppose an endpoint returns an unexpected response. Before changing it, inspect the request and response in the browser's Network panel or through a tool such as curl.
https://goodoff.co/
You might discover that the frontend sends a string where the backend expects a number. The apparent backend bug could actually be an input-contract problem between two components.

Without reproduction, an AI assistant might change the backend to accommodate the wrong input. That may hide the original issue and create inconsistencies elsewhere.

Once you have reproduced the problem, create a test that captures the failure if practical. This gives you a measurable way to determine whether the proposed fix works.

3. Ask AI to Investigate Before Asking It to Edit

Many developers jump directly from an error message to a request for a code change. A more reliable workflow separates investigation from implementation.

First, ask the assistant to analyze the evidence without modifying files.

For example:

Analyze this bug without changing any files.

Here is the error message:
[Paste error]

Here is the relevant code:
[Paste code]

Expected behavior:
[Describe expected behavior]

Actual behavior:
[Describe actual behavior]

Please provide:
1. The most likely root causes.
2. Evidence supporting each hypothesis.
3. Other possible explanations.
4. The smallest test that could distinguish between them.
5. Any assumptions that need verification.

This encourages the assistant to identify competing explanations instead of immediately committing to one.

You can then test the most plausible hypothesis and update your understanding based on the results.

For example, a database timeout could result from a slow query, a connection pool limit, a network issue, or a lock held by another transaction. Rewriting the query before checking these possibilities might waste time or make the system harder to maintain.

AI can help generate hypotheses, explain unfamiliar code, and suggest diagnostic commands. However, the evidence still needs to determine which hypothesis is correct.

4. Follow the Smallest-Change Principle

When AI modifies a large section of code to fix a small issue, reviewing the result becomes harder.

A change that touches several unrelated functions introduces more opportunities for regressions. It can also make it difficult to determine which modification caused a new failure.

Prefer the smallest change that satisfies the requirement.

Consider a simple example:

function calculateDiscount(price, percentage) {
  if (price < 0 || percentage < 0 || percentage > 100) {
    throw new Error("Invalid discount inputs");
  }

  return price * (1 - percentage / 100);
}

Suppose the bug is that negative prices are accepted. The correct change might be a single validation condition.

An AI assistant could instead introduce a new validation library, refactor the pricing module, change function signatures, and update unrelated formatting.

Those changes might be justified in a larger refactoring task, but they are unnecessary if the immediate requirement is simply to reject negative prices.

When reviewing a suggested fix, ask:

Does every changed line contribute to solving the problem?
Has the assistant modified unrelated behavior?
Does the change follow the project's existing conventions?
Can the same result be achieved with a smaller patch?

Smaller changes are generally easier to test, review, explain, and revert.

5. Verify the Fix With Tests, Not Confidence

A successful explanation from an AI assistant is not proof that the code works.

The most important question is whether the implementation satisfies the required behavior under realistic conditions.

Start with a regression test that fails before the fix and passes afterward.

For the discount example, you might test valid inputs and invalid boundaries:

import { describe, expect, it } from "vitest";

describe("calculateDiscount", () => {
  it("calculates a valid discount", () => {
    expect(calculateDiscount(100, 20)).toBe(80);
  });

  it("accepts a zero discount", () => {
    expect(calculateDiscount(100, 0)).toBe(100);
  });

  it("rejects negative prices", () => {
    expect(() => calculateDiscount(-100, 20))
      .toThrow("Invalid discount inputs");
  });

  it("rejects discounts above 100 percent", () => {
    expect(() => calculateDiscount(100, 120))
      .toThrow("Invalid discount inputs");
  });
});

This example uses Vitest, but the same principle applies to other testing frameworks.

A useful test suite should cover more than the exact input that exposed the bug. It should also examine boundary conditions and related behavior.

For a login endpoint, this could mean testing missing fields, malformed input, valid credentials, invalid credentials, and unauthorized access.

For a database operation, it might include duplicate records, concurrent requests, transaction failures, and unexpected values.

You can also ask AI to identify missing tests:

Review this patch and propose tests for:
- The original failure
- Boundary conditions
- Invalid input
- Regression risks
- Security-sensitive behavior

Do not assume the implementation is correct.

Use the resulting suggestions as a starting point, then inspect the tests yourself. A test can pass while checking the wrong behavior.

GitHub's guidance on reviewing AI-generated code similarly recommends functional checks, testing, architectural alignment, and human oversight.

6. Check Whether the Fix Introduces New Problems

A patch can resolve the original bug while introducing another one.

This is particularly important when the change affects authentication, authorization, database queries, file uploads, payment processing, or external API calls.

Consider a simplified login check:

if (!user) {
  return res.status(401).json({ error: "Invalid credentials" });
}

An AI-generated patch might make the endpoint stop crashing by bypassing a failing user lookup or returning a default user object. The endpoint could now return a successful response, but the authentication logic might no longer be trustworthy.

The immediate error has disappeared, yet the application is less secure.

When reviewing a patch, examine:

Input validation: Are unexpected or malformed values handled safely?

Authentication and authorization: Does the change preserve the requirement that users can access only permitted resources?

Error handling: Does the application handle failures correctly, or does it simply suppress them?

Data integrity: Could the change create duplicate records, overwrite valid data, or leave a transaction incomplete?

Dependencies: Has the assistant introduced a package that is unnecessary, unmaintained, or incorrectly named?

Secrets and logging: Does the change expose tokens, credentials, or sensitive user information?

The OWASP Secure Code Review Cheat Sheet provides a useful framework for examining input validation, access control, data flow, business logic, and security boundaries.

Automated scanners and tests can catch many problems, but they do not eliminate the need to understand what the code is supposed to protect.

7. Use Logs and Observability to Verify Real Behavior

Passing tests is essential, but tests cannot reproduce every condition found in a production environment.

Some bugs depend on network latency, concurrency, unexpected data, configuration differences, or external services.

For these problems, inspect logs, metrics, traces, and the behavior of the application after deployment.

Suppose an AI assistant changes a database query to improve performance. A local test may pass, but production requests may still time out because the real bottleneck is connection contention.

Instead of asking the assistant to repeatedly rewrite the query, examine:

Query execution time
Database connection usage
Request latency
Error frequency
Resource consumption
Changes in behavior after deployment

Use this evidence to determine whether the proposed fix addresses the underlying cause.

For higher-risk changes, deploy through a staged release or canary process when your infrastructure supports it. Monitor relevant metrics and keep a rollback plan available.

The goal is to establish a chain of evidence: the original failure was reproduced, the cause was investigated, the patch passed tests, and the application behaved correctly under relevant operating conditions.

8. Learn to Recognize Common AI Debugging Mistakes

AI coding assistants can produce useful solutions, but developers should watch for recurring failure patterns.

Fixing the symptom instead of the cause

An assistant may add a fallback value to prevent a crash without explaining why the expected value was missing.

Ask where the invalid state originated and whether the fallback is correct according to the requirements.

Changing tests to make the code pass

If a test fails, the implementation might be wrong. The test might also be outdated, but that requires evidence.

Do not accept a patch that removes an assertion or weakens a test simply because the build becomes green.

Inventing APIs or configuration options

Generated code may refer to a method, package, parameter, or configuration setting that does not exist in your installed version.

Check official documentation, inspect the dependency version, and run the relevant code.

Ignoring project architecture

A solution may work in isolation but violate established patterns for error handling, data access, authentication, or state management.

Give the assistant relevant project documentation and examples, then verify that the implementation fits the actual codebase.

Overengineering a simple fix

A complicated abstraction can create more maintenance work than the original bug.

Ask whether the additional complexity is necessary and whether the simpler solution meets the requirements.

These are reasons to inspect AI-generated code carefully, not reasons to reject AI assistance altogether.

9. A Practical AI Debugging Workflow

You can use the following process for everyday development:

Reproduce: Confirm the bug using specific steps.
Collect evidence: Inspect logs, stack traces, requests, and recent changes.
Investigate: Ask AI for plausible root causes without modifying the code.
Form a hypothesis: Choose an explanation supported by evidence.
Test the hypothesis: Use a minimal experiment or failing regression test.
Implement: Apply the smallest justified change.
Verify: Run the regression test, relevant test suite, and static analysis.
Review: Inspect the diff for unrelated changes, security issues, and broken assumptions.
Validate: Check application behavior in a representative environment.
Document: Record the root cause and why the fix works.

This workflow does not require every bug to receive a lengthy investigation. A minor formatting issue may need only a quick check. A defect involving payments or access control deserves a much deeper review.

The depth of verification should match the potential impact of failure.

10. The Best Way to Prompt AI During Debugging

The quality of a debugging interaction depends partly on the information and constraints you provide.

Instead of repeatedly asking, "Can you fix this?", use a prompt that defines the task and limits unnecessary changes.

Here is a reusable template:

You are helping me debug an existing application.

Problem:
[Describe the observed behavior]

Expected behavior:
[Describe the intended behavior]

Evidence:
[Paste logs, stack traces, relevant code, and test results]

Constraints:
- Do not change unrelated files.
- Do not remove or weaken existing tests.
- Do not introduce new dependencies without justification.
- Preserve existing architecture and public interfaces unless a change is necessary.
- Explain assumptions and uncertainty.

First, identify likely root causes.
Then propose the smallest test that can distinguish between them.
Wait for the test results before recommending a final patch.

After the fix, explain:
1. The root cause
2. Why the change resolves it
3. The tests required
4. Possible regressions
5. Any security or compatibility concerns

If your coding tool can edit files directly, explicitly request an investigation-only phase before allowing modifications.

This reduces the risk of a long sequence of speculative edits that leaves you with code you do not fully understand.

Conclusion: AI Can Suggest the Fix, but Evidence Must Validate It

AI coding assistants are changing how developers write and debug software. They can help explain unfamiliar code, generate test cases, identify suspicious logic, and explore possible solutions.

But faster code generation does not remove the need for engineering judgment.

A fix is not reliable because it sounds convincing, looks clean, or makes an error message disappear. It is reliable when it satisfies the requirements, passes meaningful tests, preserves essential system behavior, and withstands appropriate review.

The most valuable developers will not necessarily be the ones who generate the most code with AI. They will be the ones who know how to evaluate its output, identify incorrect assumptions, and prove that a change works.

Use AI to accelerate the investigation. Use tests and evidence to decide whether the fix deserves to be trusted.

How to Understand Technical Documentation as a Beginner Developer

Ali Raza — Thu, 08 Oct 2026 19:22:26 +0000

Technical documentation can feel confusing when you are new to programming. Learn how to read documentation, find the information you need, understand examples, and turn documentation into practical knowledge.

One of the biggest changes that happens when you move from beginner tutorials to real software development is the amount of documentation you need to read.

A tutorial might tell you exactly what to type.

Documentation usually does not.

Instead, you may see unfamiliar terms, configuration options, code examples, parameters, return values, warnings, and links to other pages. When you are new to development, even a simple API documentation page can feel overwhelming.

The problem is usually not that you are bad at programming.

You simply have not learned how to read technical documentation yet.

Documentation is a skill. Like programming itself, it becomes easier with practice.

This guide explains how beginner developers can approach technical documentation without trying to understand every line at once.

Why Technical Documentation Feels Difficult

Technical documentation is generally written to be useful for people who already understand the technology.

That means documentation often assumes you already know certain concepts.

For example, a documentation page might say:

"Pass the authentication token in the Authorization header."

If you are a beginner, several questions immediately appear:

What is an authentication token?
What is a header?
Where do I get the token?
How do I send it?
What does Authorization mean?
Where does this code belong?

A beginner may read the entire page hoping these questions will eventually become clear.

Usually, that is not the most effective approach.

Instead, identify what you are trying to accomplish first.

1. Start With a Specific Goal

Do not begin by trying to read an entire documentation website.

Start with a question.

For example:

How do I install this library?
How do I authenticate with this API?
How do I create a user?
How do I upload a file?
How do I connect this SDK to my project?
How do I handle an error?
How do I retrieve data from this endpoint?

A specific goal gives you a reason to read the documentation.

Imagine you are learning a payment API.

Instead of reading every available page, your first goal might be:

"I want to create my first test payment."

Now you can search the documentation for installation, authentication, creating a payment, and testing.

This immediately reduces the amount of information you need to process.

2. Understand the Structure Before Reading the Details

Most technical documentation follows some type of structure.

You may find sections such as:

Getting Started
Installation
Quick Start
Authentication
Guides
API Reference
Examples
Configuration
Troubleshooting
Frequently Asked Questions

Do not immediately read everything.

First, scan the navigation.

Ask yourself:

Where is the information I need?

If you are completely new to a technology, start with the Getting Started or Quick Start section.

If you already understand the basics and need a specific function, the API Reference may be more useful.

Learning to navigate documentation is almost as important as understanding the content inside it.

3. Read the Quick Start First

When available, the Quick Start section is usually one of the best places for beginners.

It often gives you a minimal working example.

For example, instead of explaining every feature of a JavaScript library, the documentation may show:

Install the package
Import the library
Create an object
Call a method
Display the result

Do not worry if you do not understand everything immediately.

Your first objective is to understand the overall flow.

Ask:

What is being installed?
What is being imported?
What information is required?
What function is being called?
What result is produced?

Once you understand the basic flow, you can investigate individual parts.

https://goodoff.co/

4. Do Not Try to Understand Every Word

This is one of the most important lessons for beginner developers.

You do not need to understand every technical term before writing your first piece of code.

Suppose documentation contains this example:

client.users.create({
  name: "John",
  email: "john@example.com"
})

You might not know exactly what client, users, or create means yet.

That is okay.

Start by understanding the bigger picture:

A client is being used to create a user, and information about that user is being provided.

Then investigate the individual pieces.

Trying to understand everything simultaneously can turn a five-minute task into an hour of confusion.

5. Learn the Difference Between Guides and API References

Beginners often mix these two types of documentation.

They serve different purposes.

Guides

Guides explain how to accomplish something.

They may walk you through a complete process.

For example:

How to authenticate your application

This type of documentation is usually easier for beginners.

API Reference

API references explain what a particular function, endpoint, class, or parameter does.

You might see information such as:

Function name
Parameters
Required values
Optional values
Return type
Errors
Examples

API references are extremely useful, but they can be difficult if you do not understand the underlying concepts.

A good learning process is:

Guide first, reference second.

Use the guide to understand the workflow, then use the reference when you need specific details.

6. Focus on Examples

Code examples can sometimes teach you faster than paragraphs of explanation.

When you find an example, do not simply copy and paste it.

Read it line by line.

Ask:

What does this line do?

Then:

What happens if I change this value?

For example, if the documentation shows:

const user = await createUser("Ali");

Experiment with the example.

Change the name.

Remove a value.

Try an invalid value.

See what happens.

This turns documentation from something you are reading into something you are interacting with.

7. Learn Important Documentation Terms

A small vocabulary can make documentation much easier to understand.

Parameter

A value that you provide to a function or method.

Argument

The actual value you pass when calling a function.

Return Value

The result produced by a function.

Endpoint

A specific URL where an API can receive or provide data.

Request

The information your application sends.

Response

The information returned by a server or API.

Authentication

A process used to verify who or what is accessing a system.

Required

A value that must be provided.

Optional

A value that does not have to be provided.

You do not need to memorize every technical term immediately.

Keep a small glossary and add terms as you encounter them.

8. Turn Documentation Into Questions

One of the most effective ways to learn technical documentation is to stop treating it like something you simply read.

Turn it into questions.

For example, after reading an API page, ask:

What is this API used for?
How do I authenticate?
What parameters are required?
What does this endpoint return?
What errors can occur?
What is the simplest working example?
What happens if a required parameter is missing?

Now you are actively testing your understanding.

This is especially useful when documentation is long.

Instead of trying to remember everything, focus on answering the questions that matter for your project.

9. Turn Important Documentation Into Flashcards

Some technical information needs to be remembered.

Examples include:

Programming concepts
Syntax rules
Terminology
Common commands
Framework concepts
API parameters
Important configuration options
Keyboard shortcuts
Development principles

You can turn these into flashcards.

For example:

Question: What is the purpose of an API endpoint?

Answer: It is a specific location through which a client can interact with a server or service.

Flashcards should not replace hands-on coding.

They should support it.

A developer needs both knowledge and application.

10. Use AI to Make Documentation Easier to Understand

AI can be particularly useful when documentation contains concepts that are difficult to understand.

Instead of asking an AI tool to write your entire application, use it as a learning assistant.

For example, you can ask:

"Explain this documentation in beginner-friendly language."

Or:

"Explain each parameter in this example."

Or:

"What do I need to understand before using this API?"

You can also ask:

"Quiz me on this documentation without showing the answers first."

This creates an active learning process.

GoodOff can also be useful when you are learning from technical PDFs, notes, documentation, or other study material. Students and beginner developers can turn source material into formats such as study guides, flashcards, and quizzes, making it easier to move from reading technical information to actively practicing it.

The important thing is to use AI to increase understanding, not to skip understanding.

11. Build a Study System Around Technical Documentation

If you are learning a new technology, you can turn its documentation into a structured study routine.

For example:

Step 1: Choose one topic

Do not try to learn an entire framework in one day.

Choose something specific, such as authentication.

Step 2: Read the introductory guide

Understand what the feature does.

Step 3: Follow the example

Run the code yourself.

Step 4: Experiment

Change values and see what happens.

Step 5: Create questions

Write down questions about the concepts you need to remember.

Step 6: Create flashcards

Turn important concepts into recall questions.

Step 7: Take a quiz

Test whether you actually understand the topic.

Step 8: Build something

Use the concept in a small project.

This final step is critical.

Understanding documentation becomes much easier when you have a real reason to use it.

12. Do Not Depend Completely on AI-Generated Code

AI can explain documentation and generate examples, but blindly copying AI-generated code can create another problem.

You may end up with working code that you do not understand.

That becomes especially dangerous when something breaks.

Instead, use AI to explain:

Why the code works
What each function does
What the parameters mean
What assumptions the code makes
What could cause an error
How you could test it

Then try writing or modifying the code yourself.

The goal is not:

AI writes code → Developer copies code

A better process is:

Documentation → Understanding → Experimentation → AI assistance → Testing → Understanding again

13. Keep a Personal Documentation Knowledge Base

As you become a developer, you will repeatedly encounter useful information.

Do not rely entirely on memory.

Create your own collection of:

Important commands
Common errors
Useful code patterns
Documentation links
Concepts you struggled with
Solutions you discovered
Framework notes
API examples

Over time, this becomes a personal technical knowledge base.

The next time you encounter the same problem, you will not have to start from zero.

This can also help you identify gaps in your knowledge.

If you repeatedly save notes about authentication, for example, that may be a sign that authentication deserves deeper study.

14. Practice With Real Projects

Reading documentation without applying it can quickly become passive learning.

After learning a concept, build something small.

If you are learning an API, build a simple application that uses it.

If you are learning a database library, create a small CRUD project.

If you are learning authentication, build a basic login system.

The project does not need to be impressive.

It needs to force you to use the documentation.

Every time you get stuck, return to the relevant section.

This creates a powerful cycle:

Read → Build → Get stuck → Search documentation → Understand → Continue building

That is how documentation gradually becomes familiar.

A Simple 45-Minute Documentation Study Routine

If you are learning a new technology, try this routine:

10 minutes: Read

Choose one small documentation section.

10 minutes: Understand

Identify unfamiliar terms and concepts.

10 minutes: Practice

Follow the example in your own development environment.

10 minutes: Recall

Close the documentation and explain the concept from memory.

5 minutes: Review

Write down what you still do not understand.

You can then use those weak areas to guide your next study session.

This is far more manageable than trying to read hundreds of pages at once.

Final Thoughts

Technical documentation is not something developers eventually stop needing.

It becomes one of the most important resources in everyday development.

The difference is that experienced developers usually become better at finding the right information quickly.

As a beginner, do not measure your progress by how much documentation you can read.

Measure it by what you can understand and use.

Start with a specific goal.

Find the relevant guide.

Study the example.

Understand the important terms.

Experiment with the code.

Turn difficult concepts into questions.

Use flashcards and quizzes to reinforce important information.

Then build something with what you learned.

Tools such as GoodOff can support this process by helping students and beginner developers transform technical learning material into structured study resources instead of relying only on passive reading.

You do not need to memorize an entire documentation website.

You need to learn how to navigate it, understand it, question it, and use it.

Once that skill develops, documentation stops looking like a wall of technical information and starts becoming one of your most useful tools as a developer.

How to Learn Programming With AI Without Skipping the Fundamentals

Ali Raza — Wed, 07 Oct 2026 17:58:44 +0000

Artificial intelligence has changed the way people learn programming.

A beginner can now ask an AI assistant to explain an error, generate a function, write a SQL query, build a webpage, or even create an entire application. What once required hours of searching through documentation can sometimes be reduced to a few well-written prompts.

That convenience is powerful, but it creates an important question:

Are developers actually learning programming, or are they simply learning how to ask AI for code?

AI can be an excellent programming tutor, but only when it is used to strengthen understanding rather than replace it. GitHub itself warns that AI-generated code can appear correct while being inaccurate or unsuitable, and recommends reviewing and testing generated code rather than treating it as automatically trustworthy.
The best approach is therefore not to avoid AI.

It is to learn programming with AI while keeping the fundamentals at the center of the process.

Why Programming Fundamentals Still Matter in the AI Era

Programming languages and development tools will continue to change.

Python may become more popular. New JavaScript frameworks will appear. AI coding assistants will become more capable. Development environments will continue to automate repetitive tasks.

But fundamental programming concepts remain useful across technologies.

A developer who understands:

Variables
Data types
Functions
Conditions
Loops
Data structures
Algorithms
APIs
Databases
Debugging
Version control
Software architecture
Testing

can transfer those skills to different languages and frameworks.

Someone who only knows how to generate code may struggle when the generated solution does not work.

This is the difference between using AI to write code and understanding the code AI writes.

The Biggest Risk of Learning Programming With AI

The biggest problem is not that AI generates code.

The problem is when beginners accept that code without understanding it.

Imagine a student asks an AI:

"Build me a login system in Python."

The AI produces several files, database logic, authentication functions, validation, and error handling.

The application might even work.

But if the student cannot explain how authentication works, why passwords need secure handling, what a database query is doing, or how the application responds to invalid input, they have not necessarily learned programming.

They have learned how to obtain a solution.

That distinction becomes important when the problem changes.

AI can generate an answer for a familiar request. A developer needs to understand how to reason when the request is unfamiliar.

Use AI as a Tutor, Not a Shortcut

One of the best ways to learn programming with AI is to change the role you give it.

Instead of saying:

"Write the code for me."

try asking:

"Explain the concept first, then give me a small example."

Instead of:

"Fix this code."

try:

"Help me identify why this code is failing. Give me hints before showing the solution."

Instead of:

"Build this project."

try:

"Break this project into smaller programming concepts and help me implement them one at a time."

This forces you to participate in the learning process.

GitHub's own documentation includes a learning workflow where Copilot can be configured to act as a tutor, explain basic coding concepts, and focus on helping the learner understand the overall approach rather than simply providing solutions. ([GitHub Docs][2])

That is a much healthier relationship with AI for beginners.

Learn the Concept Before the Framework

A common mistake among new developers is jumping directly into frameworks.

A beginner might start with React, Next.js, Django, Laravel, or another framework without understanding the underlying concepts.

Frameworks are useful, but they do not replace fundamentals.

Before asking AI to help you build a React application, for example, understand basic JavaScript concepts.

Before building a database-driven application, understand:

What data is
What tables are
What relationships are
What queries do
What CRUD means
Why validation matters

Before building an API, understand:

Requests
Responses
HTTP methods
Status codes
Authentication
Data formats such as JSON

AI can help explain all of these concepts.

But you should learn the underlying idea before relying on the framework to hide it.

Use the Explain, Predict, Test Method

A simple learning system can help prevent AI from doing all the thinking.

Use three stages:

1. Explain

Ask AI to explain the programming concept in simple language.

For example:

"Explain recursion as if I understand functions but have never used recursion."

Focus on the idea.

Do not immediately copy code.

2. Predict

Before asking AI for the solution, try to predict what should happen.

If you are debugging a program, ask yourself:

What should this function return?
Which line should execute first?
What value should this variable contain?
What happens when the input changes?

This develops your programming reasoning.

3. Test

Write your own attempt.

Run it.

Look at the result.

Only then use AI to help identify what went wrong.

This process makes AI part of your learning loop instead of replacing the loop.

Ask AI for Hints Before Asking for Answers

When you are stuck, do not immediately ask for the complete solution.

Try a progression.

Level 1: Ask for a hint

"Give me one hint about what I should check."

Level 2: Ask for an explanation

"Explain the concept I need to understand to solve this."

Level 3: Ask for debugging guidance

"Point out where my reasoning is going wrong without rewriting the code."

Level 4: Ask for a solution

Only after trying yourself should you ask AI to demonstrate a complete approach.

This method preserves the productive struggle that comes with learning programming.

The goal is not to make every problem easy.

The goal is to become better at solving problems.

Do Not Copy Code You Cannot Explain

A simple rule can dramatically improve AI-assisted learning:

If you cannot explain the code, do not consider the task finished.

Suppose AI generates a function containing:

A loop
A conditional statement
An array method
An asynchronous operation
An API request

You should be able to explain what each major part does.

Ask yourself:

What problem does this code solve?

Why is this approach being used?

What happens if the input changes?

What happens if the API fails?

What are the limitations of this solution?

If you cannot answer these questions, stop and learn the underlying concepts.

Build Small Projects Instead of Generating Large Applications

AI makes it incredibly easy to generate large projects.

That can actually hurt beginners.

If you ask AI to build an entire task-management application, you might receive thousands of lines of code.

It can look impressive.

But it can also become impossible to understand.

Instead, build small projects.

For example:

Project 1

Build a simple calculator.

Learn:

Variables
Functions
Conditions
Input handling

Project 2

Build a to-do list.

Learn:

Arrays
Objects
DOM manipulation
Events

Project 3

Build a small API.

Learn:

HTTP
Routes
Requests
Responses

Project 4

Connect an application to a database.

Learn:

Data modeling
Queries
CRUD operations
Validation

AI can help at every stage, but the project should remain small enough for you to understand.

Use AI to Explain Documentation, Not Replace It

Programming requires reading documentation.

There is no realistic way around it.

Developers regularly need to understand APIs, libraries, frameworks, configuration files, error messages, and technical specifications.

AI can make documentation easier to understand.

Instead of asking AI to replace the documentation, give it the relevant section and ask:

"Explain this documentation in simple terms and give me a small example."

Then go back to the original documentation.

This creates an important habit:

AI helps you understand the source. The source remains the authority.

This is especially important because AI can provide outdated or incorrect technical information.

Turn Documentation Into a Personal Learning System

Long technical documentation can be difficult to study.

Instead of repeatedly reading the same pages, developers can convert important concepts into questions.

For example:

Question:
What does an HTTP 404 status code indicate?

Answer:
The requested resource could not be found.

Or:

Question:
What is the purpose of a database index?

The goal is to turn passive reading into retrieval practice.

Tools such as GoodOff can support this workflow by transforming source material into different learning formats. A developer can bring PDFs, notes, documents, slides, or other material into GoodOff and create flashcards, quizzes, study guides, and source-grounded explanations. ([GoodOff][3])

Its flashcard system is designed around active recall and uses FSRS spaced repetition to schedule reviews. ([GoodOff][4])

This can be particularly useful when learning:

Programming documentation
Course notes
Certification material
Technical PDFs
API documentation
Computer science concepts
Software architecture

The goal is not to create more notes.

The goal is to create more opportunities to retrieve and apply what you learned.

Use Quizzes to Discover What You Actually Know

One of the easiest ways to overestimate your programming knowledge is to recognize concepts while reading them.

You may think:

"I understand this."

But can you answer a question about it without looking?

Try testing yourself.

After studying functions, ask:

What is a function?
Why are functions useful?
What is a parameter?
What is a return value?
What happens if a function receives unexpected input?

After studying APIs, ask:

What is an API?
What is an endpoint?
What is an HTTP request?
What is the difference between GET and POST?
What does a 404 response mean?

GoodOff can generate quizzes from your learning material and provide explanations for answers, allowing the student to identify gaps instead of relying only on rereading. ([GoodOff][5])

This is particularly useful for technical subjects because understanding a concept and being able to retrieve it are different skills.

Use AI to Debug Your Thinking

Debugging is one of the most important programming skills.

AI can be extremely useful here, but there is a better approach than simply pasting an error and copying the response.

First, describe what you expected.

Then explain what actually happened.

Then show the relevant code.

For example:

"I expected the function to return three items, but it returns an empty array. Here is what I expected, what I observed, and the relevant code. Help me identify possible causes."

This teaches you to communicate technical problems clearly.

You can then ask AI:

What assumptions am I making?
What should I test first?
Which variable should I inspect?
What possible causes could produce this result?
What experiment would eliminate each possibility?

Now AI becomes a debugging partner rather than a code vending machine.

Always Test AI-Generated Code

This should be one of the strongest rules in AI-assisted programming.

Generated code is not automatically correct because it compiles.

GitHub's documentation specifically notes that AI-generated code can be inaccurate and recommends careful review and testing. It also warns that generated code may introduce security concerns or fail to fit the architecture and style of an existing codebase.

Therefore, after AI generates code:

Read it.
Understand the logic.
Run it.
Test normal inputs.
Test unusual inputs.
Test failure cases.
Check security implications.
Compare it with official documentation.
Review it as if another developer wrote it.

This process is not just about safety.

It is also learning.

Every review teaches you something about programming.

Use AI to Increase Practice, Not Reduce It

The best use of AI may not be generating more code.

It may be generating more practice opportunities.

For example, ask AI:

"Teach me arrays through five progressively difficult exercises."

Or:

"Give me a debugging problem involving a loop. Do not show the solution until I attempt it."

Or:

"Give me three API design questions and evaluate my answers."

Or:

"Create a small programming challenge that tests whether I understand recursion."

Now AI is helping you practice.

That is fundamentally different from asking it to complete every assignment.

Create a Developer Learning Loop

A strong AI-assisted learning routine can look like this:

Learn → Attempt → Get Stuck → Ask AI → Understand → Implement → Test → Explain → Review

Each step has a purpose.

Learn

Understand the concept.

Attempt

Try solving the problem yourself.

Get Stuck

Identify exactly where you are struggling.

Ask AI

Use AI for explanation or guidance.

Understand

Make sure you understand the solution.

Implement

Write or modify the code yourself.

Test

Verify that it actually works.

Explain

Explain the solution in your own words.

Review

Return to the concept later and test yourself again.

This creates a learning process where AI accelerates the journey without removing the important parts.

Where GoodOff Can Fit Into Developer Learning

GoodOff is primarily a learning platform, but its source-based workflow can also be useful for developers who are studying technical material.

For example, imagine you are learning a new programming language and have a 100-page PDF course guide.

Instead of rereading the entire document every weekend, you can turn that source into:

Study Guide

Understand the major concepts, definitions, and questions. GoodOff's study guide workflow organizes source material into an overview, key concepts, definitions, likely questions, and memory aids. ([GoodOff][6])

Flashcards

Turn important programming concepts into active-recall questions.

Quizzes

Test whether you actually understand the material.

Sage Tutor

Ask questions about the material while keeping the learning grounded in your uploaded source. GoodOff says Sage provides answers with citations to the passages it used. ([GoodOff][3])

Spaced Repetition

Return to important concepts over time instead of relying on one long study session.

This creates a useful distinction:

AI writes code. AI also helps you learn.

Those are two different uses of AI, and the second one can help developers become better at the first.

A Practical AI Programming Study Routine

If you are learning programming today, try this simple routine.

First: Learn one concept

Spend 30 to 60 minutes learning a specific concept.

Do not try to learn an entire framework in one sitting.

Second: Write something yourself

Create a small exercise using that concept.

Third: Ask AI for help only when necessary

Start with hints and explanations.

Fourth: Test your solution

Try normal and unexpected inputs.

Fifth: Explain what you built

If you cannot explain it, identify what you do not understand.

Sixth: Turn difficult concepts into questions

Create flashcards or quiz questions.

Seventh: Review later

Use spaced repetition to revisit concepts that are easy to forget.

This process may feel slower than simply generating an application.

But the objective is not to generate an application.

The objective is to become a developer who can build applications.

The Future Developer Will Need More Than Coding Speed

AI is making code generation faster.

That means typing speed and memorizing syntax may become less important than they once were.

But other skills become more important:

Understanding requirements
Breaking problems into smaller parts
Evaluating AI-generated solutions
Debugging
Testing
Security awareness
Reading documentation
Understanding architecture
Making technical decisions
Knowing when AI is wrong

A 2025 systematic literature review of AI in computer programming education found that research has increasingly shifted toward practical classroom implementation and assessment of AI-supported programming education

The technology is changing quickly.

The need for strong reasoning is not disappearing.

If anything, it is becoming more important.

Conclusion: Learn With AI, Not Instead of Learning

AI has made programming more accessible than ever.

A beginner can ask questions at any time, receive explanations, generate examples, analyze errors, and explore unfamiliar concepts.

But the best programmers will not be the people who ask AI to do everything.

They will be the people who understand what AI is doing, why it works, when it is wrong, and how to improve it.

Use AI to explain difficult concepts.

Use it to create practice problems.

Use it to help debug your reasoning.

Use it to simplify documentation.

Use it to generate quizzes and flashcards from technical learning material.

But keep the fundamentals.

Learn how programming works.

Write code yourself.

Break problems down.

Make mistakes.

Debug them.

Test your solutions.

And explain what you built.

Why Your Website Is Slow Even When Your Server Is Fast

Ali Raza — Tue, 06 Oct 2026 18:02:41 +0000

A common web performance misconception is that a fast server automatically means a fast website.

It does not.

Your server may return the initial HTML quickly, yet users can still experience a page that feels slow, unresponsive, or unstable. The reason is simple: server response time is only one part of the browser's work.

After receiving the first byte, the browser still has to download resources, parse HTML, process CSS, execute JavaScript, decode images, build the page, render content, and respond to user interactions.

This is why developers should stop treating performance as a purely backend problem.

Modern web performance is a full pipeline involving the network, server, browser, JavaScript, CSS, images, third-party scripts, and rendering process. Google's Core Web Vitals reflect this broader experience through metrics such as Largest Contentful Paint (LCP), Interaction to Next Paint (INP), and Cumulative Layout Shift (CLS). ([Google for Developers][1])

The Server Can Be Fast While the Website Is Slow

Consider a simple example.

Your server responds to an HTML request in 300 milliseconds.

That sounds excellent.

But then the browser downloads:

2 MB of JavaScript
1.5 MB of images
Several CSS files
Multiple third-party scripts
Web fonts
Analytics libraries
Tracking pixels
API requests

The browser now has substantial work to perform before the user can interact comfortably with the page.

The result could look like this:

Server response:       300 ms
HTML parsing:          200 ms
CSS processing:        150 ms
JavaScript download:   900 ms
JavaScript execution:  1,200 ms
Image decoding:        500 ms
Third-party scripts:   700 ms
Rendering:              400 ms
--------------------------------
Actual user experience: much slower

The exact numbers will vary, but the principle is important.

Fast TTFB does not guarantee fast LCP, INP, or overall user experience.

TTFB, or Time to First Byte, measures the time between navigation and the beginning of the response. It includes factors such as DNS, connection setup, TLS negotiation, and server processing. web.dev recommends roughly 0.8 seconds or less as a general TTFB target, but also emphasizes that TTFB is not itself a Core Web Vital. ([web.dev][2])

1. JavaScript May Be Your Real Bottleneck

One of the biggest reasons modern websites become slow is JavaScript.

Developers often focus on the size of JavaScript files, but file size is only part of the problem.

The browser has to:

Download JavaScript
Parse it
Compile it
Execute it
Perform DOM operations
Run event handlers
Process framework code
Recalculate styles
Render updates

A JavaScript file can therefore affect performance even after it has finished downloading.

For example:

for (let i = 0; i < 1000000; i++) {
    calculateSomething(i);
}

A task like this can occupy the browser's main thread.

While the main thread is busy, user interactions may have to wait.
https://goodoff.co/
This matters particularly for Interaction to Next Paint, or INP. INP measures how responsive a page is to user interactions throughout the page lifecycle. Google currently recommends an INP below 200 milliseconds for a good experience. ([Google for Developers][1])

What developers can do

Start by identifying unnecessary JavaScript.

Look for:

Large framework bundles
Unused libraries
Duplicate dependencies
Heavy UI components
Unnecessary animations
Large client-side calculations
Scripts loaded on pages where they are not needed

Use:

<script defer src="/app.js"></script>

where appropriate, rather than forcing scripts to block HTML parsing.

For larger applications, consider:

Code splitting
Tree shaking
Dynamic imports
Lazy loading
Removing unused dependencies
Moving expensive work away from the main thread

The goal is not simply to make JavaScript smaller.

The goal is to make the browser do less work.

2. Your Images May Be Slowing Down the Page

Images are another common performance problem.

A developer may upload a 4 MB image because the original looks high quality on a desktop monitor.

The browser does not care that the original file looks good.

It still has to download it.

Imagine a landing page with:

Hero image       3.2 MB
Feature image    1.8 MB
Team image       1.1 MB
Background       1.5 MB
Other images     2.0 MB
----------------------
Total            9.6 MB

That can become a serious problem, particularly on mobile networks.

Better approach

Use modern image formats such as:

WebP
AVIF

Serve images at appropriate dimensions and avoid downloading a 2000px-wide image when the browser only displays it at 500px.

Responsive images can help:

<img
  src="image-800.webp"
  srcset="
    image-400.webp 400w,
    image-800.webp 800w,
    image-1200.webp 1200w"
  sizes="(max-width: 600px) 100vw, 800px"
  alt="Product dashboard">

For images that are below the fold, lazy loading can also reduce initial network work:

<img
  src="feature.webp"
  loading="lazy"
  alt="Feature illustration">

However, do not blindly lazy-load your most important above-the-fold image.

Your primary LCP element should be discoverable and prioritized appropriately. Google's LCP guidance specifically recommends making the LCP resource discoverable from the HTML and avoiding unnecessary JavaScript dependency before it can render. ([web.dev][3])

3. CSS Can Also Delay Rendering

CSS looks lightweight compared with JavaScript, but large or poorly structured stylesheets can still affect rendering.

Consider a website loading:

global.css
theme.css
components.css
animations.css
responsive.css
plugin.css

If most of these styles are required before the page can render, the browser has additional work before presenting the final page.

Developers should examine:

Unused CSS
Large CSS frameworks
Excessive selectors
Duplicate styles
Unnecessary animations
Render-blocking stylesheets

Critical styles for the initial viewport can sometimes be prioritized while non-critical styles are loaded later.

The objective is simple:

Deliver the styles needed for the first screen as quickly as possible.

4. Third-Party Scripts Can Quietly Destroy Performance

This is one of the most overlooked problems.

Your application may be fast.

Your server may be fast.

Your code may be optimized.

Then someone adds:

Analytics
Chat widget
Heatmaps
Advertising
Social media pixels
A/B testing
Customer support
Consent management
Embedded videos
Marketing automation

Suddenly the browser has dozens of additional requests and scripts to process.

Third-party resources can also introduce connection latency because the browser may need to establish connections to external origins. web.dev specifically notes that resources hosted on cross-origin servers can introduce additional latency during connection setup. ([web.dev][2])

What should developers do?

Audit third-party scripts regularly.

Ask:

Does this script directly contribute to the user's current task?

If not, consider:

Loading it later
Loading it after interaction
Loading it asynchronously
Removing it entirely
Replacing multiple tools with one solution

Every third-party script should have a performance cost that the team consciously accepts.

5. Too Many API Requests Can Make a Fast Server Feel Slow

Suppose your API responds in 100 milliseconds.

That sounds fast.

But imagine the frontend makes 15 sequential API requests.

If requests depend on one another, the user may experience a much longer wait.

For example:

Request A
   ↓
Request B
   ↓
Request C
   ↓
Request D
   ↓
Render

Even fast individual requests can create slow user experiences when chained together.

Where possible, independent requests can run in parallel:

await Promise.all([
    fetchUser(),
    fetchProducts(),
    fetchRecommendations()
]);

Developers should also look for:

Duplicate API requests
Sequential requests that could run in parallel
Over-fetching
Large JSON responses
Unnecessary polling
Missing caching
API calls triggered repeatedly by UI updates

The question should not only be:

"How fast is my API?"

It should also be:

"How much work does the browser need from my API before the user can use the page?"

6. Caching Can Be More Important Than Server Speed

A request that never reaches the server is faster than a request handled by the fastest server.

Caching can reduce unnecessary network and server work.

Depending on your application, caching can exist at several levels:

Browser Cache
      ↓
CDN Cache
      ↓
Application Cache
      ↓
Database Cache
      ↓
Database

Static resources such as CSS, JavaScript, fonts, and versioned images are often strong candidates for long-lived caching.

For example:

Cache-Control: public, max-age=31536000, immutable

This strategy works particularly well for assets with content-hashed filenames:

app.82f31a.js
styles.91af21.css
logo.18d9c2.webp

When the file changes, the filename changes.

That allows browsers to cache the old asset without creating stale-content problems.

7. Your Database Can Be Fast Yet Your Application Can Still Be Slow

Another common mistake is measuring database query time independently.

A query might take 30 milliseconds.

But the application may perform:

Query user
Query permissions
Query subscription
Query products
Query recommendations
Query notifications
Query analytics

Now the total backend processing time is significantly higher.

This is where application profiling becomes important.

Look for:

N+1 queries
Unnecessary joins
Missing indexes
Repeated queries
Large database responses
Excessive serialization
Synchronous operations
External API calls inside request paths

The goal is not simply to optimize individual queries.

It is to understand the entire request lifecycle.

8. Your LCP Can Be Poor Even With Excellent TTFB

This is one of the most important concepts for developers.

Largest Contentful Paint measures when the largest visible image, text block, or video is rendered relative to the beginning of navigation. Google recommends an LCP of 2.5 seconds or less for a good user experience, measured at the 75th percentile. ([web.dev][3])

Imagine:

TTFB = 400 ms

Excellent.

But then:

HTML arrives
    ↓
JavaScript executes
    ↓
Hero component mounts
    ↓
API request starts
    ↓
Hero image is discovered
    ↓
Image downloads
    ↓
Image decodes
    ↓
Hero finally renders

Your server was fast.

Your LCP was not.

This is why performance optimization needs to follow the user's experience rather than a single backend metric.

9. Measure Real Users, Not Just Your Laptop

A common developer mistake is testing a website on:

A powerful desktop
High-speed Wi-Fi
Cached resources
Local development environment
Minimal browser extensions

Then concluding:

"The website is fast."

Real users may have:

Older phones
Slower CPUs
Weak mobile networks
Cold caches
Different geographic locations
Battery-saving modes
Different browsers

This is why field data matters.

Chrome's Real User Measurement ecosystem, including the Chrome User Experience Report, can provide real-world performance information. Lab tools such as Lighthouse and Chrome DevTools are useful for controlled testing and debugging. web.dev recommends combining lab and field measurements because certain metrics, particularly INP and CLS, can behave differently in real user environments. ([web.dev][4])

A Practical Performance Debugging Workflow

Instead of randomly compressing files and rewriting code, developers should follow a structured process.

Step 1: Measure

Start with:

Chrome DevTools
Lighthouse
PageSpeed Insights
Search Console Core Web Vitals
Real User Monitoring

Google recommends using Core Web Vitals and related page experience tools to understand how users actually experience a site. ([Google for Developers][5])

Step 2: Identify the bottleneck

Ask:

Is TTFB high?
Is LCP high?
Is JavaScript blocking the main thread?
Are images too large?
Are there too many requests?
Are third-party scripts involved?
Are API calls sequential?
Is the browser doing unnecessary work?

Step 3: Fix the largest bottleneck first

Do not spend three hours optimizing a 20 KB CSS file when a 4 MB hero image is causing the problem.

Prioritize the changes that have the largest impact.

Step 4: Test again

Performance optimization is an iterative process:

Measure
   ↓
Diagnose
   ↓
Optimize
   ↓
Measure again
   ↓
Compare

Never assume an optimization worked simply because the code looks cleaner.

A Fast Server Is Only the Beginning

Website performance is not a competition between frontend and backend developers.

It is a system.

A fast server helps reduce TTFB. But after the response arrives, the browser still has to process everything you send it.

That includes JavaScript, CSS, images, fonts, API responses, third-party scripts, animations, and DOM updates.

The modern performance mindset should therefore be:

Do less work, send fewer bytes, make fewer requests, render important content sooner, and measure what real users experience.

Core Web Vitals provide useful targets for the user experience: LCP at or below 2.5 seconds, INP below 200 milliseconds, and CLS below 0.1 are Google's current "good" thresholds. ([Google for Developers][1])

And performance is not only about SEO. Google explicitly recommends good Core Web Vitals and overall page experience because they contribute to a better experience for users, while also making clear that strong Core Web Vitals alone do not guarantee higher search rankings. ([Google for Developers][5])

So the next time someone says:

"Our server is fast. Why is the website still slow?"

Do not immediately look at the server.

Open DevTools.

Look at the network waterfall.

Inspect the main thread.

Check the LCP element.

Audit JavaScript.

Inspect images.

Review API calls.

Measure real users.

Because website performance is not determined by how quickly your server responds. It is determined by how quickly the user can actually see, understand, and interact with your page.

Developer Performance Checklist

[ ] Check TTFB
[ ] Check LCP
[ ] Check INP
[ ] Check CLS
[ ] Analyze JavaScript execution
[ ] Remove unused JavaScript
[ ] Optimize images
[ ] Review render-blocking resources
[ ] Audit third-party scripts
[ ] Reduce unnecessary API requests
[ ] Check database queries
[ ] Implement effective caching
[ ] Test mobile performance
[ ] Test with cold cache
[ ] Compare lab and real-user data
[ ] Measure again after every major optimization

AI Agents vs Chatbots: Why the Difference Matters

Ali Raza — Thu, 01 Oct 2026 19:24:38 +0000

AI chatbots answer questions. AI agents can reason about goals, use tools, execute actions, and adapt their next steps. Understanding the difference matters when building real AI applications.

Artificial intelligence has moved quickly from simple chat interfaces to systems that can interact with software, retrieve information, call APIs, execute workflows, and make decisions within defined boundaries.

That shift has created a lot of confusion around one question:

What is the actual difference between an AI agent and a chatbot?

The two terms are sometimes used interchangeably, but they describe different levels of system behavior.

A chatbot can have memory, retrieval, tools, and sophisticated reasoning. An AI agent can also have all of these capabilities. The important distinction is not whether a system has a chat interface or uses an LLM.

The more useful distinction is what the system is designed and authorized to do after receiving a request.

A research review published in 2026 describes an AI agent through an action loop involving goals, planning, tool use, observations, revisions, and outputs. Google Cloud similarly describes agents as applications that process inputs, reason with available tools, and take actions toward a goal. ([PubMed Central (PMC)][1])

This difference has major implications for developers.

What Is a Chatbot?

A chatbot is a software application designed primarily to communicate with users through conversation.

A simplified architecture looks like this:

User
  ↓
Message
  ↓
AI Model
  ↓
Response

For example:

User:
Explain REST APIs.

Chatbot:
A REST API is an application programming interface
that follows REST architectural principles...

The system receives an input and generates an appropriate response.

Modern chatbots can be much more sophisticated than this example. They may use:

Large language models
Retrieval-augmented generation
Conversation history
Knowledge bases
Tool calling
File analysis
Web search
Structured outputs

Therefore, a chatbot is not necessarily a simple system.

The important point is that conversation is generally the primary interaction model.

What Is an AI Agent?

An AI agent is a system designed to pursue a goal by reasoning about tasks, using available tools, taking actions, observing results, and deciding what to do next.

A simplified architecture looks like this:

User Goal
   ↓
AI Model
   ↓
Plan
   ↓
Select Tool
   ↓
Execute Action
   ↓
Observe Result
   ↓
Evaluate
   ↓
Next Action
   ↓
Final Result

Google Cloud identifies several major components of agentic architectures, including the model, grounding, tools, memory, orchestration, and runtime. ([Google Cloud][2])

For example, imagine a developer says:

"Investigate why our API is returning 500 errors and prepare a report."

A conventional chatbot might explain common causes of HTTP 500 errors.

An agent could potentially:

Inspect authorized logs
Identify recent errors
Search the relevant code
Compare recent deployments
Run approved diagnostic commands
Identify a likely cause
Test a hypothesis
Produce a report

The important difference is that the agent is participating in the workflow, not simply explaining the workflow.

The Core Difference: Response vs Goal

The simplest way to think about the difference is:

Chatbot

"Give me an answer."

AI Agent

"Achieve this goal."

A chatbot generally focuses on generating a response to the current interaction.

An agent focuses on accomplishing an objective through one or more steps.

This distinction is more useful than simply asking whether the application uses GPT, Gemini, Claude, or another model.

A system can use a highly capable LLM and still function primarily as a chatbot.

Likewise, an agent can use an LLM as only one component of a much larger software architecture.

AI Agents vs Chatbots: A Technical Comparison

Capability	Chatbot	AI Agent
Conversational interface	Yes	Often
Generates text	Yes	Yes
Uses conversation context	Usually	Usually
Retrieves information	Sometimes	Often
Uses external tools	Sometimes	Core capability
Multi-step planning	Limited or application-dependent	Core capability
Executes actions	Limited	Often
Observes tool results	Limited	Yes
Maintains task state	Sometimes	Common
Autonomous workflow	Limited	Core use case
Human approval	Common	Important for sensitive actions
Goal-oriented execution	Limited	Central concept

This table should not be interpreted as a strict technical taxonomy. There is significant overlap between modern chatbot and agent architectures.

The distinction is primarily about system behavior and architecture.

Why Tools Change Everything

One of the biggest differences between a chatbot and an agent is tool access.

An LLM can generate a response.

A tool gives the AI a way to interact with something outside the model.

Tools can include:

Web Search
Database Query
REST API
Code Execution
File System
CRM
Email
Calendar
Cloud Infrastructure
Analytics Platform

Google Cloud describes tools as functions or APIs that allow an agent to interact with external systems and data sources. It also notes that tools transform an AI model from a text generator into a system capable of automating complex, multi-step tasks. ([Google Cloud Documentation][3])

Consider a customer support application.

A chatbot might answer:

"Your order appears to be delayed."

An agent with authorized access could:

1. Identify the customer
2. Query the order database
3. Check shipping status
4. Retrieve carrier information
5. Determine the issue
6. Draft an appropriate response
7. Escalate the case if necessary

The model is still responsible for reasoning and language, but the surrounding application gives it capabilities.

Planning Is Another Major Difference

Chatbots often operate one interaction at a time.

Agents can decompose a goal into multiple tasks.

Suppose the goal is:

"Research three competitors and create a comparison."

An agent might create an internal plan:

Goal:
Create competitor comparison

Step 1:
Identify competitors

Step 2:
Collect product information

Step 3:
Collect pricing information

Step 4:
Compare features

Step 5:
Evaluate positioning

Step 6:
Organize findings

Step 7:
Generate report

Google Cloud's agent architecture documentation describes agents as systems that can understand user intent, create multi-step plans, and execute those plans using available tools. ([Google Cloud Documentation][3])

Planning does not necessarily mean that an agent creates a visible checklist.

The planning process may happen internally through model reasoning, orchestration code, workflows, or a combination of these approaches.

Memory: Why Agents Need State

Another important concept is memory.

Imagine an agent working on a software project for several hours.

It may need to remember:

Previous decisions
Files it inspected
Tool results
User preferences
Current task state
Errors encountered
Completed steps

Google's current agent architecture guidance distinguishes short-term memory, which maintains context within a session, from long-term memory, which can persist relevant information across interactions. ([Google Cloud Documentation][3])

A simple chatbot may only need conversation history.

An agent often needs state management.

For example:

{
  "task": "debug_api",
  "status": "investigating",
  "files_checked": [
    "server.js",
    "routes.js"
  ],
  "errors_found": 4,
  "next_action": "inspect_database_connection"
}

This state can be stored outside the model.

That is an important architectural point:

Memory is not the same thing as model intelligence.

The application must deliberately design how information is stored, retrieved, updated, isolated, and deleted.

RAG Is Not the Same as an AI Agent

Another common source of confusion is Retrieval-Augmented Generation, or RAG.

A typical RAG workflow looks like:

User Question
     ↓
Search Knowledge Base
     ↓
Retrieve Relevant Documents
     ↓
Send Context to Model
     ↓
Generate Answer

An agentic workflow can be more dynamic:

User Goal
     ↓
Determine Required Information
     ↓
Search Knowledge Base
     ↓
Call API
     ↓
Analyze Result
     ↓
Search Again
     ↓
Execute Tool
     ↓
Evaluate Outcome
     ↓
Return Result

https://goodoff.co/
RAG can therefore be one component inside an agent.

Google Cloud explicitly distinguishes agentic architectures from non-agentic approaches such as direct model reasoning and RAG, noting that agents can dynamically decide which tools and information to use during a multi-step task. ([Google Cloud Documentation][4])

So:

RAG is a retrieval technique.

An agent is a goal-oriented system architecture.

They can work together.

Where Chatbots Still Make Sense

Not every AI application needs to become an agent.

This is an important point for developers.

If the task is:

Summarizing text
Translating content
Explaining a concept
Answering questions from a document
Generating an email draft
Classifying customer feedback

A simple AI application may be sufficient.

Google Cloud specifically notes that deterministic tasks such as summarization, translation, and classification do not necessarily require an agentic workflow and that other approaches can be more efficient and cost-effective. ([Google Cloud Documentation][3])

Adding autonomous planning and tool use to a simple task can increase:

Complexity
Latency
Cost
Failure modes
Security requirements
Testing requirements

The engineering goal should not be:

"Use an agent because agents are more advanced."

It should be:

"Use the simplest architecture that reliably solves the problem."

Where AI Agents Make Sense

Agents become more useful when a task is:

Multi-step
Open-ended
Tool-dependent
Goal-oriented
Dynamic
Difficult to represent with fixed rules

Examples include:

Coding Agents

A coding agent may inspect a repository, modify files, execute tests, analyze errors, and iterate.

Research Agents

A research agent may search multiple sources, collect information, compare findings, and produce a structured report.

Customer Support Agents

A support agent may retrieve account information, investigate an issue, update records, and escalate cases.

IT Operations Agents

An operations agent may analyze alerts, inspect logs, investigate infrastructure problems, and perform approved remediation.

Business Workflow Agents

An agent may coordinate information across CRM, email, analytics, databases, and internal applications.

The common pattern is not the industry.

It is the workflow.

The Security Problem Changes Too

Giving an AI system the ability to take actions also increases its attack surface.

OWASP identifies risks for agentic systems including prompt injection, tool abuse, privilege escalation, data exfiltration, memory poisoning, goal hijacking, excessive autonomy, and cascading failures. ([OWASP Cheat Sheet Series][5])

Consider this scenario:

Agent
  ↓
Reads webpage
  ↓
Webpage contains malicious instructions
  ↓
Agent interprets instructions as relevant
  ↓
Agent calls a privileged tool
  ↓
Unexpected action

This is one reason developers should treat external information as untrusted input.

OWASP recommends least-privilege tool access, input validation, prompt injection defenses, memory protection, and structured testing for agentic systems. ([OWASP Cheat Sheet Series][5])

OWASP also identifies excessive agency as a vulnerability when an LLM-based system has enough permissions to perform damaging actions in response to unexpected, ambiguous, or manipulated model outputs. ([OWASP Gen AI Security Project][6])

This leads to a fundamental engineering principle:

An agent should have only the permissions it actually needs.

Human-in-the-Loop Still Matters

Autonomy does not mean removing humans from every workflow.

For high-impact actions, developers can require approval.

For example:

AI Agent
   ↓
Generate database update
   ↓
Validation
   ↓
Human Approval
   ↓
Execute

This can be especially useful for:

Financial transactions
Production deployments
Deleting data
Sending external communications
Changing permissions
Legal or compliance workflows
Administrative actions

A well-designed agent is not necessarily one that acts without humans.

It is one that has clearly defined boundaries around when it can act and when it must ask for help.

A Simple Agent Architecture for Developers

A basic implementation can be represented as:

                    ┌──────────────┐
                    │     User     │
                    └──────┬───────┘
                           ↓
                    ┌──────────────┐
                    │ Agent Runtime│
                    └──────┬───────┘
                           ↓
                    ┌──────────────┐
                    │  AI Model    │
                    └──────┬───────┘
                           ↓
                 ┌─────────┴─────────┐
                 ↓                   ↓
            ┌─────────┐         ┌─────────┐
            │ Memory  │         │  Tools  │
            └─────────┘         └────┬────┘
                                     ↓
                              External Systems

In production, additional layers may include:

Authentication
Authorization
Observability
Rate limiting
Validation
Guardrails
Audit logs
Human approval
Error handling
Cost controls

The architecture should grow according to the task rather than adding components simply because they are available.

The Real Shift: From Generating Text to Operating Software

This is why the chatbot versus agent distinction matters.

A chatbot primarily gives you an interface to an AI model.

An agent gives the model a runtime environment in which it can pursue a goal.

That environment can contain:

Model
+
Context
+
Memory
+
Tools
+
Data
+
Orchestration
+
Permissions
+
Evaluation

Google Cloud's current architecture guidance describes these components as part of the broader agentic application architecture. ([Google Cloud Documentation][3])

This means the future of AI development is not simply about choosing a smarter model.

Developers increasingly need to think about the entire system surrounding the model.

Final Thoughts

AI agents and chatbots are closely related, but they are not interchangeable concepts.

A chatbot is primarily designed around conversation and response generation.

An AI agent is designed around goals, reasoning, tools, actions, state, and feedback.

The difference can be summarized as:

Chatbot

Input
  ↓
Reason
  ↓
Answer

Versus:

AI Agent

Goal
  ↓
Reason
  ↓
Plan
  ↓
Use Tools
  ↓
Act
  ↓
Observe
  ↓
Evaluate
  ↓
Repeat or Finish

Neither architecture is universally better.

For simple, predictable tasks, a chatbot or direct AI workflow can be easier to build, test, operate, and secure.

For complex workflows requiring multiple steps, external data, and actions, an agentic architecture can provide capabilities that a conventional chatbot does not.

The most important question for developers is therefore not:

"Should I build an AI agent?"

It is:

"Does this problem actually require an AI system to plan, use tools, and take actions?"

If the answer is yes, an agent may be the right architecture.

If the answer is no, keeping the system simpler may be the better engineering decision.

What Happens When You Turn One Lecture Into a Complete Study System?

Ali Raza — Wed, 30 Sep 2026 18:49:12 +0000

A lecture is only the beginning. The real learning happens when information is transformed into understanding, retrieval, practice, and feedback.*

A student attends a lecture.

They download the slides.

Maybe they also receive a PDF from the professor.

Everything they need for the exam appears to be sitting in one folder.

Then the week before the exam arrives.

They open the lecture again.

They reread the slides.

They highlight important sections.

They watch the recording again.

Eventually, they take a practice test and discover that they cannot remember half of what they thought they knew.

The problem may not be a lack of information.

The problem is the workflow.

Modern students often have more educational material than ever. Lectures, PDFs, slides, recordings, articles, textbooks, online videos, notes, AI explanations, and practice resources can all exist around the same course.

But having information available does not automatically create a learning system.

A better approach starts with one simple idea:

One source of information can become many connected learning activities.

A lecture can become an explanation.

The explanation can become a study guide.

The study guide can become questions.

The questions can become retrieval practice.

Retrieval can become spaced review.

Review can lead to a practice exam.

The practice exam can generate feedback.

The result is not simply a collection of study materials.

It is a learning pipeline.

The Problem Is Not the Lecture

Lectures are designed to introduce information.

They are not necessarily designed to become a complete study system.

Imagine a 60-minute lecture about the cardiovascular system.

The student might receive:

45 presentation slides
A lecture recording
12 pages of notes
Several diagrams
A recommended textbook chapter
A list of learning objectives

The student now has plenty of information.

But what should happen next?

Most students improvise.

They reread.

They highlight.

They make summaries.

They search for videos.

They create random flashcards.

They find old quizzes.

Each activity might be useful on its own, but there is often no connection between them.

This creates a fragmented workflow.

A better system starts with the original source and deliberately transforms it through multiple stages:

Lecture/PDF

↓

Understanding

↓

Study Guide

↓

Questions

↓

Retrieval

↓

Spaced Review

↓

Practice Exam

↓

Feedback

↓

Targeted Review

This is a fundamentally different way of thinking about studying.

1. Start With the Source

The first stage is simple:

Capture the original material.

That could be:

A lecture
PDF
Slide deck
Textbook chapter
Class notes
Research paper
Recorded lesson
Course handout

The source matters because it provides context.

A generic explanation of a topic may be accurate, but a student's course has its own terminology, examples, emphasis, and learning objectives.

For example, two biology courses may teach the same topic but emphasize different mechanisms.

One professor might focus heavily on molecular pathways.

Another might emphasize clinical applications.

The student's learning system should therefore remain connected to the material they are actually expected to learn.

This is one reason source-based learning can be powerful.

Instead of starting with:

"What does the internet say about this topic?"

the workflow begins with:

"What does my course material require me to understand?"

That distinction can keep the rest of the study process focused.

2. Turn the Lecture Into Understanding

A lecture is not knowledge simply because it has been attended.

The first transformation should be from raw information into structure.

Ask:

What are the major concepts?
What are the important definitions?
What processes need to be understood?
Which concepts are connected?
What examples explain the ideas?
What could easily be confused?
What questions should a student be able to answer after studying this?

This creates a conceptual map of the material.

For example:

Photosynthesis

→ Light-dependent reactions
→ ATP and NADPH
→ Calvin cycle
→ Carbon fixation
→ Glucose production

Now the student has more than a collection of paragraphs.

They have a structure that can support later learning.

Research on learning strategies consistently emphasizes active processes such as retrieval, spacing, elaboration, and organization rather than relying entirely on passive rereading. ([Springer][1])

The purpose of this stage is not to memorize.

It is to make the material understandable enough that it can later be retrieved and applied.

3. Build a Study Guide

Once the material is understood at a basic level, the next step is compression with structure.

A good study guide should answer:

What do I actually need to know?

Instead of keeping the lecture as a 60-slide presentation, transform it into something like:

Core Concepts

The five ideas that define the topic.

Important Terms

Definitions students need to understand.

Processes

Steps, mechanisms, or sequences.

Relationships

Cause and effect, comparisons, dependencies, and connections.

Common Confusions

Ideas that students are likely to mix up.

Questions

Things the student should eventually be able to answer without looking.

This is more useful than simply shortening the lecture.

The objective is to create a map from which future learning activities can be generated.

And that leads to an important distinction:

A study guide should not be the final product. It should be the starting point for practice.

4. Turn Information Into Questions

This is where the workflow changes from consumption to active learning.

Instead of asking:

"What should I reread?"

ask:

"What should I be able to answer?"

Take a statement:

The mitochondria produce ATP through cellular respiration.

Turn it into questions:

What is the role of mitochondria in cellular respiration?

How is ATP produced?

What happens during oxidative phosphorylation?

Why is oxygen important?

What would happen if oxygen were unavailable?

Now the student has potential retrieval opportunities.

This matters because questions force the learner to produce knowledge.

A systematic review of classroom research on retrieval practice examined 50 experiments involving 5,374 participants. The authors reported that 57% of the observed effect sizes represented medium or large benefits, with benefits appearing across different educational levels, subject areas, testing formats, and timing conditions. The authors also noted that only 6% of the experiments were conducted in non-WEIRD countries, which is an important limitation when generalizing the evidence globally. ([DOI][2])

The lesson is not that every question automatically improves learning.

It is that retrieval deserves a deliberate place in the study workflow.

5. Retrieval Is Where the Student Has to Do the Work

This may be the most important transformation in the entire pipeline.

The student reads the study guide.

Then the guide disappears.

Now they try to answer the questions.

That moment is different.

There is no visible answer to recognize.

The student has to search memory.

Maybe they remember everything.

Maybe they remember part of it.

Maybe they realize they understood far less than they thought.

All three outcomes provide useful information.

Retrieval practice is not simply a way of measuring learning after it happens.

It can also contribute to learning itself. Research reviews have examined how practicing retrieval improves the ability to retrieve information again later. ([Annual Reviews][3])

This is why a strong study system should repeatedly move students from:

Read → Retrieve

rather than:

Read → Read again → Read again

The difference may feel small.

The learning process is not.

6. Add Spaced Review

One lecture should not become one study session.

The student should encounter the important material again over time.

For example:

Day 1: Learn the material
Day 2: Short retrieval session
Day 5: Review difficult questions
Day 9: Mixed retrieval
Day 15: Practice exam
Day 25: Final review

The exact schedule can vary.

The principle is what matters:

Spread learning opportunities across time.

A major review in Nature Reviews Psychology identifies spacing and retrieval practice as two well-supported strategies for improving learning across different domains and stages of life. ([DOI][4])

A systematic review in health professions education also examined 56 studies containing 63 experiments. Forty-three experiments demonstrated significant benefits for distributed practice and/or retrieval practice compared with control or comparison conditions, although the studies varied considerably in design and context. ([Springer][5])

This means the lecture should not disappear after the first study session.

It should become the source of future retrieval opportunities.

7. Turn the Same Material Into a Practice Exam

Eventually, the student needs to move beyond individual questions.

They need to simulate the situation where the information must be used under constraints.

That means a practice exam.

A good practice exam can combine:

Recall
Application
Problem solving
Comparisons
Scenario-based questions
Multiple concepts
Different levels of difficulty

The purpose is not simply to generate another document.

It is to create a realistic test of whether the learning pipeline worked.

A student may perform well on isolated flashcards but struggle when several concepts appear together.

That is useful information.

It reveals a gap between recognition and application.

Research on learning techniques has repeatedly highlighted practice testing and distributed practice as important evidence-based approaches. A 2021 meta-analysis of ten learning techniques, based on 242 studies and 169,179 participants, identified distributed practice and practice testing among the strongest techniques examined in that analysis. ([Frontiers][6])

The practice exam therefore becomes a diagnostic tool.

8. Feedback Closes the Loop

A practice exam without feedback only tells you that something went wrong.

Feedback explains what happened.

Suppose a student gets five questions wrong.

The useful next question is not:

"How many did I get wrong?"

It is:

"Why did I get them wrong?"

Maybe the student:

Forgot a definition
Misunderstood a concept
Confused two similar ideas
Applied the wrong formula
Misread the question
Knew the information but could not retrieve it
Could retrieve the information but could not apply it

Each problem requires a different response.

If the student forgot a definition, retrieval practice may help.

If the student misunderstood the concept, they need another explanation.

If they cannot apply the concept, they need more problem solving.

This is where the learning pipeline becomes adaptive.

Test → Diagnose → Target the weakness → Retrieve again

The objective is not simply to generate a score.

It is to generate useful information about what happens next.

A Lecture Can Become a Complete Learning System

Now consider what happened to that original 60-minute lecture.

It started as:

One lecture

Then became:

A structured study guide

Then:

A set of questions

Then:

Retrieval practice

Then:

Spaced review

Then:

A practice exam

Then:

Feedback

Then:

Targeted revision

The original source has not changed.

The student's interaction with it has.

That is the important idea.

The value of educational technology should not simply be measured by how quickly it creates content.

It should also be measured by whether it helps students move through the right learning activities.

AI Can Make the Transformation Easier

This is where generative AI becomes particularly interesting.

AI can help transform a source into different formats much faster than a student can manually create everything.

A PDF can become a structured study guide.

A study guide can generate questions.

Questions can become flashcards.

The same source can produce practice quizzes.

A complicated section can become a visual explanation.

A difficult concept can be explained at different levels.

A practice exam can reveal weak areas.

The technology can therefore reduce the friction between stages.

But there is an important distinction.

Automation should reduce preparation work, not eliminate learning work.

If AI creates a 20-page summary and the student simply reads it, the workflow may still be passive.

If AI uses the source to create questions that the student must answer, the technology is supporting retrieval.

If it generates a practice exam and explains mistakes after the student attempts it, the system becomes more interactive.

The difference is not the AI model.

The difference is the workflow around the model.

One Source, Multiple Learning Modes

A particularly useful principle is that students should not have to start from scratch for every study activity.

The same source can support multiple modes:

Reading

Understand the original material.

Structured learning

Create a study guide.

Retrieval

Answer questions without looking.

Visual learning

Represent difficult relationships or processes visually.

Audio learning

Review concepts through spoken explanations.

Practice

Solve questions and problems.

Assessment

Take a practice exam.

Feedback

Identify weaknesses.

Review

Return to weak material later.

This creates continuity.

Instead of having a lecture in one application, flashcards in another, practice questions somewhere else, and notes in a fourth location, the learning activities can remain connected to the same underlying source.
https://goodoff.co/
That connection matters because context is preserved.

The Real Bottleneck Is Workflow

Students do not necessarily need more educational content.

They need better ways to move through the content they already have.

Consider the difference:

Traditional workflow

Lecture → Notes → Reread → Exam

versus:

Learning pipeline

Source → Understand → Organize → Question → Retrieve → Space → Practice → Feedback → Review

The second workflow contains more opportunities to discover problems before the final exam.

That is important.

The exam should not be the first time a student discovers that they do not understand the material.

A good learning system creates smaller feedback loops along the way.

The Pipeline Should Be Designed Around Failure

This is an underrated idea.

A strong learning system should make failure useful.

If a student cannot answer a question, that is data.

If they repeatedly miss the same concept, that is data.

If they understand a definition but fail a scenario question, that is data.

If they perform well immediately but forget the material two weeks later, that is data.

The system should respond accordingly.

This is much closer to debugging software than simply reading documentation.

You do not debug by rereading the entire codebase every time something breaks.

You identify the failing component.

Then you investigate it.

Learning can work similarly.

Identify the weak concept.

Understand the failure.

Practice it again.

Test it later.

That creates a feedback-driven learning loop.

What Good Learning Technology Should Actually Do

The future of educational software should not simply be:

"Give students more content."

It should be:

"Help students transform content into learning activities."

That means useful systems should help students move naturally between:

Source

↓

Understanding

↓

Practice

↓

Retrieval

↓

Review

↓

Assessment

↓

Feedback

The technology becomes infrastructure around the learning process.

This is a different product philosophy from simply building another content library.

The content already exists.

The challenge is turning it into action.

The Student Should Remain in the Loop

There is one final principle that matters.

Automation should never confuse activity with learning.

An AI system can generate 100 flashcards.

That does not mean the student knows the material.

It can generate a beautiful study guide.

That does not mean the concepts are understood.

It can create a difficult practice exam.

That does not mean the student can solve the problems independently.

The student still needs to think.

They need to retrieve.

They need to make mistakes.

They need to receive feedback.

They need to return to difficult material.

They need to test themselves again.

The system can make these activities easier to create and organize.

It cannot remove the need to perform them.

From One Lecture to a Learning Engine

The most useful way to think about educational content may be as an input rather than an endpoint.

A lecture is an input.

A PDF is an input.

A textbook chapter is an input.

The learning system begins when that source is transformed.

Lecture/PDF

→ Understanding

→ Study Guide

→ Questions

→ Retrieval

→ Spaced Review

→ Practice Exam

→ Feedback

→ Targeted Review

That is more than a study workflow.

It is a feedback system.

And that may be one of the most important opportunities for AI in education.

AI does not need to replace the student.

It can help connect the different activities that students already need to perform.

The goal is not to make studying require zero effort.

The goal is to make the effort more deliberate.

Because the biggest problem students face may not be that they have too little information.

It may be that the information they already have has nowhere to go.

A lecture should not be the end of learning.

It should be the beginning of a system that turns information into knowledge.

The Internet Is Changing From Search to Answers. What Do We Lose?

Ali Raza — Mon, 28 Sep 2026 19:47:41 +0000

For years, the internet worked in a relatively simple way.

You had a question. You opened a search engine, typed a few keywords, looked through a list of results, and clicked the websites that seemed useful. You compared sources, read explanations, followed links, and gradually built your own understanding.

Today, that experience is changing.

Instead of giving you a list of websites, AI-powered search experiences can generate summaries, explain concepts, compare options, and answer questions directly. You can ask a follow-up question without opening another page. You can request a summary of a complicated subject and receive one in seconds.

It feels like progress, and in many ways, it is.

Finding information is becoming faster and more convenient. But as the internet becomes better at delivering answers, I think we should ask an important question:

If we no longer need to visit websites to get answers, what happens to the websites that make those answers possible?

This is not just a debate about search engines or artificial intelligence. It is about how knowledge is created, how independent publishers survive, how developers discover solutions, and how the next generation of the internet will work.

1. Search Was More Than Finding an Answer

Traditional search engines did not simply provide information. They provided a path to information.

When you searched for a programming error, you might find an official documentation page, a GitHub issue, a Stack Overflow discussion, a personal blog, or a tutorial written by someone who had encountered the same problem.

Each source offered a different perspective.

Official documentation explained the intended behavior. Community discussions revealed confusing edge cases. Personal blogs described practical mistakes. GitHub issues sometimes exposed bugs that were not documented anywhere else.

You had to navigate these sources, compare explanations, and decide which information applied to your situation.

That process could be frustrating, but it also exposed you to information you did not initially know you needed.

An AI-generated answer changes this experience. It can combine information into a single explanation, removing much of the effort required to find and compare sources.

For straightforward questions, this is genuinely useful.

But the process of searching, comparing, and reading also served another purpose: it connected readers with the people and communities that created the information.

When that connection disappears, the consequences extend beyond convenience.

2. AI Answers Are Changing How People Visit Websites

This shift is already visible in research on online browsing behavior.

A Pew Research Center study published in July 2025 analyzed 68,879 Google searches conducted by 900 US adults during March 2025. The researchers found that users who encountered an AI summary clicked a traditional search result in 8% of visits, compared with 15% of visits without an AI summary. Links within AI summaries were clicked in just 1% of visits where summaries appeared.

Pew Research Center

Research context: These figures describe the observed browsing behavior of the study participants during the study period. They are not universal click-through rates for every search engine, country, or type of query.

The findings illustrate an important change in user behavior.

When an answer appears directly on the results page, some users have less reason to visit another website.

Imagine searching for a simple technical question, such as how to convert a string to an integer in Python. An AI summary might provide a working example, explain the function, and mention a common error.

For a quick task, that could be everything you need.

Now consider a more complicated question: how should you design authentication for a production application?

A short answer might explain the basic concepts, but you may still need official documentation, implementation examples, security guidance, and discussions of edge cases.

The challenge is that AI search can present both kinds of answers in a similarly convenient format. Users may receive a concise explanation without immediately knowing what important context is missing.

The convenience is real. So is the possibility that useful sources receive fewer visits.

3. What Happens to Independent Publishers?

Websites require time, effort, and often money to maintain.

Independent developers write tutorials. Researchers publish explanations. Journalists investigate stories. Educators create learning materials. Small businesses maintain documentation to help customers solve problems.

Many of these creators depend on some combination of advertising revenue, subscriptions, donations, product sales, consulting, and referrals.

Search traffic can help readers discover their work.

If an AI system uses information from across the web to generate an answer, but fewer users visit the original websites, the relationship between information creation and its economic rewards becomes more complicated.

A creator might invest hours testing a solution, documenting an edge case, and publishing a detailed tutorial. An AI-generated summary could communicate the central idea in a few sentences, satisfying a user's immediate need without generating a visit to the original article.

This does not mean every AI answer replaces a website visit. Some people will still click through to read detailed explanations, verify sources, or explore related material. Search behavior also varies by topic and intent.

However, the possibility of reduced referral traffic raises a difficult question.

If creators receive less traffic from the systems that use their work, how will they continue producing high-quality information?

This is not only a concern for publishers trying to protect their income. It affects the availability of future knowledge.

A healthy internet needs people who are willing and able to investigate problems, test solutions, maintain documentation, and share what they learn.

If those activities become harder to sustain financially, the long-term effects could reach well beyond individual websites.

4. The Risk of Losing Original Experience

There is a difference between knowing an answer and understanding how someone arrived at it.

Consider a developer who publishes a tutorial about debugging a database connection problem.

The article might explain the error message, but its real value could be in the details: the operating system, the database version, the failed configuration, the misleading error, and the exact change that fixed the problem.

These details often come from experience rather than simply knowing the correct command.

An AI system can summarize the explanation, but a short summary may leave out the conditions under which the solution works. If the reader receives only the summary, they might miss the details needed to apply it safely.

This becomes particularly important in software development.

A code snippet that works in a demonstration may fail in production because of concurrency, permissions, input validation, performance constraints, or differences between software versions.

Original articles often preserve the reasoning behind a solution, including failed attempts and lessons learned.

For example, a developer writing about a URL shortener might explain why a database constraint was necessary to prevent duplicate codes, how invalid URLs were handled, and what happened when two requests attempted to create the same identifier.

Those experiences provide context that is difficult to capture in a generic answer.

AI summaries can help people access information more quickly. But we should not confuse a shorter explanation with a complete understanding.

5. The Internet Could Become More Convenient but Less Diverse

Another potential loss is diversity of perspective.

When you visit several websites, you encounter different writing styles, opinions, priorities, and ways of explaining the same problem.

One developer may prefer a minimal implementation. Another may emphasize security. A third may explain the historical reasons behind a design decision.

Reading these different perspectives helps you recognize that technical problems rarely have only one reasonable solution.

AI-generated answers can bring multiple perspectives together, but they can also present a single synthesized explanation that hides the disagreements or uncertainty behind it.

This creates a subtle risk.

Readers may become accustomed to receiving one polished answer instead of exploring the range of ideas available across the web.

That does not mean AI answers are inherently less diverse. Their quality depends on the sources they use, how they synthesize information, and whether they accurately communicate disagreement and uncertainty.

The concern is what happens when the summarized answer becomes the user's entire information experience.

A search engine that directs you to several sources invites exploration. An answer engine can make exploration feel unnecessary.

For routine questions, that may be a reasonable trade-off. For subjects involving security, public policy, scientific uncertainty, or important personal decisions, the ability to examine original evidence remains valuable.

6. What Developers Could Lose

For developers, the changing relationship between search and websites deserves particular attention.

The open web has traditionally provided a large, distributed knowledge base. Developers can search error messages, inspect code examples, read official documentation, and learn from discussions about unusual bugs.

Much of this knowledge exists because people chose to publish their experiences.

A developer who encounters a strange framework issue might discover a small personal blog describing the exact problem. That blog may have limited traffic, but it can be extremely useful to someone facing the same issue.

If discovery increasingly happens through generated answers, smaller sources could become harder to find, especially when their content is summarized without a strong reason for users to visit the original page.
https://goodoff.co/
There is also a potential feedback problem.

Developers publish solutions and documentation.
AI systems use publicly accessible information to help answer questions.
Users receive answers without necessarily visiting the original sources.
Some creators receive less traffic or fewer opportunities to earn revenue.
Fewer creators may have the resources or motivation to maintain detailed public resources.

This is a possible risk, not an inevitable outcome. AI tools can also direct users to useful documentation, introduce readers to unfamiliar projects, and help more people discover technical knowledge.

The question is whether those benefits will be sufficient to sustain the communities that produce the information.

For developers who rely on the open web, preserving access to original documentation, code repositories, issue discussions, and tested examples remains important.

7. Can AI Search and the Open Web Coexist?

I do not think the solution is to reject AI-powered search.

There are clear benefits to generating direct answers. People can find information faster, ask follow-up questions naturally, and get explanations adapted to their level of understanding.

AI can also help users discover relevant concepts they might not have known how to search for.

The challenge is designing these experiences so that convenience does not come at the expense of the wider information ecosystem.

There are several practical ways to move in that direction.

Make Sources Visible and Useful

An AI-generated answer should make it easy to identify and visit the sources behind important claims.

Source links should lead to the relevant material, not merely a generic homepage. Readers should be able to distinguish between information supported by original research, official documentation, and secondary commentary.

Citations are most valuable when they help users investigate a claim rather than simply decorate an answer.

Give Original Work a Reason to Be Visited

Websites can provide value that is difficult to reproduce in a short summary.

For technical publishers, that could mean runnable examples, downloadable projects, interactive demonstrations, benchmark results, detailed experiments, and explanations of failure cases.

For researchers and journalists, it might mean access to underlying data, methodology, interviews, original documents, and detailed reporting.

The objective should not be to make information unnecessarily difficult to access. It should be to make the original resource useful beyond the basic answer.

Measure More Than Convenience

Search systems are often evaluated by how effectively they satisfy a user's information need. That is important, but the broader ecosystem matters too.

It is also worth asking whether the system directs users toward reliable sources, preserves attribution, supports independent publishers, and encourages further investigation when a question requires more depth.

These are different goals, and they may sometimes conflict. A short answer can satisfy a user's immediate need while reducing the likelihood of a click.

Recognizing that trade-off is an important part of designing responsible information systems.

8. What Can Bloggers and Developers Do About It?

The shift toward AI-generated answers creates challenges, but it also gives creators a reason to rethink how they publish information.

If your work simply repeats information that already appears on hundreds of websites, it may be difficult to distinguish your article from a generated summary.

Originality becomes more important.

For bloggers and developers, a few strategies are worth considering.

Publish firsthand experience. Share what you built, what failed, what you measured, and what you learned. Real experiments provide context that generic explanations often lack.

Show your evidence. Include source links, code, screenshots, test results, and relevant examples. Make it possible for readers to verify your claims.

Explain the reasoning. Do not just provide the final solution. Explain why it works, when it might fail, and what alternatives you considered.

Build direct relationships with readers. Newsletters, communities, open-source projects, and professional networks can help people discover your work without depending entirely on search traffic.

Make content genuinely useful. Clear documentation, practical tutorials, original research, and detailed troubleshooting guides serve readers who need more than a quick answer.

None of these strategies guarantees traffic. Search engines, recommendation systems, and audience preferences will continue to change. But publishing work with distinctive value gives readers a reason to seek it out.

Conclusion: Answers Are Useful, but Discovery Still Matters

The internet is moving toward a model in which people can ask questions and receive immediate answers without navigating multiple websites.

That change offers genuine benefits. It can reduce friction, make complicated subjects easier to approach, and help people find information more efficiently.

But the internet is not simply a database of facts waiting to be summarized.

It is also a collection of people, communities, experiments, arguments, documentation, and original discoveries. Websites are not just containers for answers. They are places where knowledge is created, tested, challenged, and improved.

If AI systems make information easier to consume while making original sources harder to sustain, we could end up with a more convenient internet that has fewer incentives to produce the detailed work on which its answers depend.

That outcome is not inevitable. Search systems can link to sources, publishers can develop more distinctive resources, and readers can continue exploring beyond the first answer.

As developers, we should care about this because the open web has always been one of our most valuable learning resources.

The next time an AI system answers a technical question, consider opening the documentation or article behind it. Read the original explanation. Explore the alternatives. Support the people who took the time to investigate the problem.

The future of the internet should not be measured only by how quickly we receive an answer, but also by whether the people creating useful knowledge can continue doing so.

Because when we lose the habit of discovering sources, we risk losing more than clicks. We risk weakening the ecosystem that makes reliable answers possible in the first place.

I Built a URL Shortener in Python. Here's What Broke

Ali Raza — Thu, 24 Sep 2026 18:54:51 +0000

Building a URL shortener sounds almost too simple.

Take a long URL:

https://example.com/articles/how-to-build-a-python-project

Turn it into:

http://localhost:5000/aB91x

When someone visits /aB91x, redirect them to the original URL.

That is the basic idea.

But while building a simple URL shortener with Python, Flask, and SQLite, I discovered that the redirect itself was probably the easiest part of the project.

The interesting problems appeared around it.

What happens if two URLs get the same short code?

What happens if someone submits an invalid URL?

What happens if the database contains thousands of links?

What happens if someone tries to use the service for malicious redirects?

And what happens when a project that worked perfectly on my laptop meets real users?

This is what I learned while building it.

What I Wanted to Build

I wanted a small application with four basic features:

Accept a long URL
Generate a short code
Store the URL in a database
Redirect users when they visit the short URL

The architecture looked like this:

User
  |
  v
Flask Application
  |
  +---- Generate Short Code
  |
  +---- Store URL
  |
  v
SQLite Database
  |
  v
Short URL
  |
  v
Redirect to Original URL

I deliberately kept the first version simple.

The goal was not to build the next Bitly.

The goal was to understand what actually happens inside a URL shortener.

The First Version

I started with Flask because it provides everything needed for a small HTTP application without adding unnecessary complexity.

The project structure looked like this:

url-shortener/
│
├── app.py
├── database.db
└── templates/
    └── index.html

I installed Flask:

pip install flask

Then created the application.

from flask import Flask, request, redirect, render_template
import sqlite3
import string
import random

app = Flask(__name__)


def get_db():
    connection = sqlite3.connect("database.db")
    connection.row_factory = sqlite3.Row
    return connection


def generate_code(length=6):
    characters = string.ascii_letters + string.digits
    return "".join(random.choice(characters) for _ in range(length))


@app.route("/", methods=["GET", "POST"])
def index():
    if request.method == "POST":
        url = request.form["url"]
        code = generate_code()

        db = get_db()

        db.execute(
            "INSERT INTO urls (code, url) VALUES (?, ?)",
            (code, url)
        )

        db.commit()
        db.close()

        return render_template(
            "index.html",
            short_url=f"http://localhost:5000/{code}"
        )

    return render_template("index.html")


@app.route("/<code>")
def shorten_redirect(code):
    db = get_db()

    result = db.execute(
        "SELECT url FROM urls WHERE code = ?",
        (code,)
    ).fetchone()

    db.close()

    if result:
        return redirect(result["url"])

    return "URL not found", 404


if __name__ == "__main__":
    app.run(debug=True)

It worked.

I entered a URL.

The application generated a short code.

I clicked the short URL.

The browser redirected me to the original website.

For about five minutes, everything looked perfect.

Then I started asking what could go wrong.

Problem 1: Short Codes Can Collide

My first implementation generated a random six-character code.

For example:

a91Bc2

But random does not mean unique.

Eventually, the application could generate the same code twice.

Imagine the database contains:

abc123 -> https://example.com

Then another user creates a URL and the application generates:

abc123

Now what?

The application cannot safely use the same code for two different URLs.

The first solution is to check whether the code already exists.

def generate_unique_code(db):
    while True:
        code = generate_code()

        existing = db.execute(
            "SELECT id FROM urls WHERE code = ?",
            (code,)
        ).fetchone()

        if not existing:
            return code

Then:

code = generate_unique_code(db)

This is much better.

But there is still another problem.

Two requests could theoretically check the database at almost the same time and both discover that the code is available.

That is why the database should also enforce uniqueness.

CREATE TABLE urls (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    code TEXT UNIQUE NOT NULL,
    url TEXT NOT NULL
);

The application checks.

The database enforces.

I learned an important lesson here:

Application logic should not be the only thing protecting data integrity.

Problem 2: I Forgot URL Validation

My first version basically trusted whatever the user submitted.

That means someone could enter:

hello

instead of:

https://example.com

Or they could enter a completely different URL scheme.

A basic validation function is better:

from urllib.parse import urlparse


def is_valid_url(url):
    try:
        parsed = urlparse(url)

        return parsed.scheme in ("http", "https") and bool(parsed.netloc)

    except Exception:
        return False

Then:

if not is_valid_url(url):
    return "Invalid URL", 400

This is not a complete security system, but it prevents many obviously invalid inputs.

It also makes the application behave more predictably.

Problem 3: I Started Thinking About Security

A URL shortener looks harmless.

But URL shorteners can be abused.

Someone could create a short link pointing toward a phishing page, malware download, or other malicious website.

That means a production URL shortener needs to think about abuse.

Depending on the application, additional protections could include:

Rate limiting
Abuse reporting
Link scanning
Domain reputation checks
CAPTCHA for suspicious activity
Authentication
Expiration dates
Link ownership
Logging
Blocking known malicious destinations

For a small learning project, I did not need to implement all of these.

But realizing that a technically functional application could still be abused changed how I thought about "finished."

Working is not the same thing as production-ready.

Problem 4: The Database Was Too Basic

Initially, my table only contained two useful fields:

code
url

That was enough for a demo.

But then I wanted to answer basic questions.

When was the link created?

How many times was it visited?

Who created it?

Should it expire?

The schema could evolve into something like:

CREATE TABLE urls (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    code TEXT UNIQUE NOT NULL,
    url TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    clicks INTEGER DEFAULT 0,
    expires_at TIMESTAMP
);

Now the application can support additional features later.

For example:

Short URL
   |
   +-- Original URL
   +-- Created date
   +-- Number of clicks
   +-- Expiration date

This made me realize something important about database design.

You do not need to design everything perfectly before writing your first line of code.

But you should think about what information the application will probably need later.

Problem 5: Counting Clicks Was Not as Simple as I Expected

I wanted to count how many times each link was opened.

The obvious solution was:

db.execute(
    "UPDATE urls SET clicks = clicks + 1 WHERE code = ?",
    (code,)
)

Then redirect the user.

Something like:

@app.route("/<code>")
def shorten_redirect(code):
    db = get_db()

    result = db.execute(
        "SELECT url FROM urls WHERE code = ?",
        (code,)
    ).fetchone()

    if not result:
        db.close()
        return "URL not found", 404

    db.execute(
        "UPDATE urls SET clicks = clicks + 1 WHERE code = ?",
        (code,)
    )

    db.commit()
    db.close()

    return redirect(result["url"])

For a small project, this is fine.

But with a large number of requests, constantly updating the database for every redirect can become a performance consideration.

A production system might need a different architecture involving caching, queues, analytics systems, or other infrastructure.

Again, the simple version worked.

But scaling changes the problem.

Problem 6: SQLite Was Great Until I Thought About Scale

SQLite was perfect for learning.

There was no database server to configure.

The entire database lived in one file:

database.db

That made development extremely easy.

But a public URL-shortening service could eventually need:

More concurrent writes
Replication
Backups
Monitoring
High availability
Better scaling characteristics

At that point, a production application might use a database such as PostgreSQL or another system designed around the application's workload.

This taught me another useful lesson:

The best technology for a prototype is not always the best technology for production.

That does not mean SQLite was a bad choice.

It was the right level of complexity for what I was building.

Problem 7: My URL Codes Were Not Really "Short"

I initially thought that six characters was automatically the correct answer.

It isn't.

The length of the code depends on the number of available characters and the number of URLs you need to represent.

If the code uses:

a-z
A-Z
0-9

there are 62 possible characters.

With six characters, there are:

62^6

possible combinations.

That gives a large address space for a small project.

But if the application becomes extremely large, code length and collision probability become important design considerations.

This was one of those moments where a simple programming project suddenly became a small lesson in probability and system design.

Problem 8: My Error Handling Was Terrible

The first version assumed everything would work.

Real applications do not get that luxury.

What if:

The database is unavailable?
The submitted URL is empty?
The generated code already exists?
The user requests a nonexistent code?
The database insert fails?
The application receives malformed input?

Instead of letting unexpected errors reach the user, the application should handle expected failures.

For example:

try:
    db.execute(
        "INSERT INTO urls (code, url) VALUES (?, ?)",
        (code, url)
    )

    db.commit()

except sqlite3.IntegrityError:
    db.rollback()
    return "Could not create short URL", 500

finally:
    db.close()

Error handling is not the most exciting part of programming.

But it is one of the things that separates a demo from a reliable application.

What the Final Flow Looked Like

After fixing the main problems, the application flow became:

User submits URL
       |
       v
Validate URL
       |
       v
Generate short code
       |
       v
Check uniqueness
       |
       v
Store in database
       |
       v
Return short URL
       |
       v
User opens short URL
       |
       v
Find code in database
       |
       v
Record click
       |
       v
Redirect to destination

It was still a small application.

But it was now a much better representation of how a real system needs to behave.

What I Would Add Next

If I continued developing the project, I would add:

Authentication

Users could manage the links they created.

Expiration

Links could automatically stop working after a specific date.

Analytics

Users could see:

Total clicks
Clicks per day
Referrer
Device type
Country

Analytics would need to be designed carefully because collecting additional information also introduces privacy considerations.

Custom aliases

Instead of:

aB91x

users could choose:

my-blog

Rate limiting

This would help prevent automated abuse.

Caching

Frequently accessed URLs could potentially be served without querying the primary database every time.

Production database

If the application grew significantly, I would consider moving beyond SQLite depending on the workload and deployment architecture.

The Biggest Lesson

The biggest lesson was not how to generate a six-character string.

It was learning how quickly a simple idea becomes a system.

At first, the project looked like this:

Long URL
   ↓
Short Code
   ↓
Redirect

After thinking about real usage, it became:

Input validation
       ↓
Code generation
       ↓
Uniqueness
       ↓
Database constraints
       ↓
Security
       ↓
Analytics
       ↓
Error handling
       ↓
Performance
       ↓
Abuse prevention
       ↓
Monitoring

That is what I like about small projects.

You can start with something that looks almost trivial and slowly discover the engineering decisions hiding underneath.

Final Thoughts

Building a URL shortener is one of those projects that looks like a beginner exercise until you start asking production-level questions.

The redirect itself took very little code.

The difficult part was everything around it.

I learned about database constraints, URL validation, collision handling, security, analytics, error handling, and scalability from one relatively small project.

That is why I think developers should build small applications instead of only following tutorials.

A tutorial can show you the happy path.

A real project shows you what breaks.

And those broken parts are often where the actual learning happens.

How to Design Tool APIs for AI Agents

Ali Raza — Tue, 22 Sep 2026 20:24:44 +0000

The architecture, schemas, error handling, and safety patterns behind reliable agent tool use

AI agents become useful when they can do more than generate text.

They need to search databases, read documents, call APIs, create records, execute code, send messages, update systems, and sometimes recover from failures.

That means an agent is only as capable as the tools it can use.

But there is an important engineering distinction:

A tool API designed for humans is not necessarily a good tool API for an AI agent.

Traditional APIs are usually designed around predictable software clients. The client developer knows the API contract, understands the parameter names, validates inputs, handles errors, and writes the control flow.

An AI agent is different.

The model has to decide whether to call a tool, which tool to call, what arguments to provide, and how to interpret the result.

That makes tool design part of the agent's reasoning architecture.

Modern agent frameworks expose tools through structured schemas. For example, MCP tools define names, descriptions, input schemas, and optionally output schemas. MCP implementations can also expose behavioral hints such as read-only or destructive behavior. ([Model Context Protocol][1])

So the question is no longer:

"How do I expose my API to an AI?"

The better question is:

"How do I design an API that an AI can reliably reason about?"

1. A Tool Is an Interface Between Reasoning and Software

Consider a simple agent:

User
  ↓
AI Agent
  ↓
Model decides what to do
  ↓
Tool
  ↓
Application / Database / API
  ↓
Tool result
  ↓
Model continues reasoning

The tool sits directly between the model and your software.

Suppose a user says:

"Find my latest invoice and tell me whether it has been paid."

The agent may need to:

Identify the user.
Search invoices.
Select the relevant invoice.
Inspect its payment status.
Explain the result.

You could expose one enormous function:

get_invoice(
    user_id,
    invoice_id,
    customer_name,
    email,
    status,
    date_from,
    date_to,
    include_payment,
    include_items,
    include_customer,
    ...
)

Technically, this might work.

For an AI agent, it creates a much harder decision problem.

A better tool surface might be:

search_invoices
get_invoice
get_invoice_payment

Each tool has a narrower responsibility.

This leads to the first principle:

Design Tools Around Decisions, Not Database Operations

A tool should represent a meaningful capability the agent can reason about.

Bad:

execute_sql
call_api
update_database

Better:

search_invoices
create_invoice
cancel_invoice
get_payment_status

The second set gives the model a semantic vocabulary.

The model does not need to understand your internal database structure.

It only needs to understand:

"When should I use this capability?"

2. Tool Names Are Part of the Interface

Developers sometimes treat tool names as implementation details.

For agents, they are part of the model-facing API.

Compare:

get_data

with:

search_customer_orders

The second immediately communicates intent.
https://goodoff.co/
A good tool name should answer:

What capability does this tool provide?

Examples:

search_documents
get_document
create_presentation
generate_chart
send_email
schedule_meeting
get_weather

Avoid names that require internal knowledge:

process_v2
execute_operation
handler_7
data_service
run_query

The agent should not need to inspect your source code to understand the purpose of a tool.

3. Tool Descriptions Are Instructions for the Model

This is one of the most overlooked parts of agent engineering.

A tool description is not just API documentation.

It becomes part of the model's decision context.

Google's Agent Development Kit documentation, for example, notes that a tool's Python docstring becomes part of what the model sees and recommends writing it clearly because it tells the model when and how to use the tool. ([Google GitHub][2])

Consider:

def search_documents(query: str):
    """Search documents."""

This is technically valid.

But it leaves important questions unanswered:

What should query contain?
Is this semantic search?
Should the agent use it for exact matches?
What does it return?
When should the agent prefer another tool?

A better description:

def search_documents(query: str, limit: int = 10):
    """
    Search the document library using semantic and keyword matching.

    Use this when the user asks about information that may exist
    inside uploaded documents.

    Do not use this tool for exact document IDs.

    Returns matching documents with their titles, IDs,
    relevance scores, and short excerpts.
    """

Now the model has decision guidance.

4. Treat the Tool Schema as a Contract

A tool should have a strict input contract.

For example:

{
  "name": "search_documents",
  "description": "Search the document library for relevant content.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The information or concept to search for."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 20,
        "default": 5
      }
    },
    "required": ["query"]
  }
}

This is significantly better than:

{
  "query": "string"
}

because the schema communicates constraints.

Modern MCP tooling uses JSON Schema for tool inputs and can also define structured output schemas. Current MCP SDK documentation shows schemas being used both to describe what arguments a tool accepts and to validate those arguments before the handler executes. ([MCP TypeScript SDK][3])

That gives you an important architecture:

Model
  ↓
Tool schema
  ↓
Validation
  ↓
Tool implementation

Do not rely on the model alone for validation.

5. Keep Parameters Small and Semantic

One common mistake is exposing every possible API parameter to the model.

Imagine:

{
  "customer_id": "...",
  "organization_id": "...",
  "region": "...",
  "locale": "...",
  "timezone": "...",
  "include_deleted": false,
  "include_archived": false,
  "include_metadata": true,
  "include_permissions": false,
  "sort_field": "...",
  "sort_direction": "...",
  "page": 1,
  "page_size": 50,
  "cursor": "...",
  "debug": false
}

This may be appropriate for a low-level backend API.

It is usually a poor model-facing tool.

The model has to reason about too many choices.

Instead, create an agent-oriented interface:

{
  "query": "customer invoices from March",
  "limit": 10
}

The backend can translate that into the complex internal API call.

This creates a useful separation:

                 Agent-facing API
                        ↓
                Simple tool contract
                        ↓
                 Adapter layer
                        ↓
                  Internal APIs
                        ↓
                    Database

Your internal architecture can remain complicated.

The model-facing interface should remain understandable.

6. Avoid Ambiguous Parameters

Names matter.

Compare:

{
  "id": "123"
}

with:

{
  "invoice_id": "123"
}

The second is safer because the semantic meaning is explicit.

Similarly:

date

is ambiguous.

Prefer:

start_date
end_date
created_after
created_before

Instead of:

type

consider:

document_type

Instead of:

name

consider:

customer_name

AI systems operate through semantic interpretation.

Reducing ambiguity reduces unnecessary reasoning.

7. Make Invalid States Difficult to Express

Suppose your API expects a date range.

Instead of allowing:

{
  "start_date": "tomorrow",
  "end_date": "yesterday"
}

and hoping the backend handles it, define explicit validation.

For example:

{
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "format": "date"
    },
    "end_date": {
      "type": "string",
      "format": "date"
    }
  },
  "required": ["start_date", "end_date"]
}

Then validate the relationship server-side:

if start_date > end_date:
    raise InvalidDateRange()

Schema validation catches structural problems.

Business validation catches semantic problems.

You need both.

8. Design Tool Outputs for the Next Decision

Tool design is not only about inputs.

The output is equally important.

Suppose a search tool returns:

{
  "data": [
    {
      "id": "123",
      "text": "...",
      "metadata": "..."
    }
  ]
}

The model has to figure out what each field means.

Instead:

{
  "results": [
    {
      "document_id": "123",
      "title": "Product Strategy",
      "relevance": 0.91,
      "excerpt": "The product strategy focuses on..."
    }
  ],
  "total_results": 18
}

Now the model has useful information for the next step.

The output should help answer:

What should the agent do next?

This is especially important for multi-step agents.

9. Use Structured Outputs When the Next Step Needs Structure

Suppose a tool returns:

The customer has three unpaid invoices. The oldest
was created on January 12 and is currently overdue.

A human can understand it.

Another model call has to interpret the text.

A structured result is easier to consume:

{
  "customer_id": "cus_123",
  "unpaid_invoices": 3,
  "oldest_invoice": {
    "invoice_id": "inv_456",
    "created_at": "2026-01-12",
    "status": "overdue"
  }
}

MCP currently supports optional outputSchema definitions for structured tool results, and its SDK can validate structured content against that schema. ([MCP TypeScript SDK][3])

Structured output becomes particularly valuable when tools are chained:

Search customer
      ↓
Get invoice
      ↓
Check payment
      ↓
Generate response

Each step should produce information that the next step can reliably consume.

10. Do Not Hide Side Effects

There is a major difference between:

search_orders

and:

cancel_order

The first reads information.

The second changes state.

Your tool interface should make that distinction obvious.

For example:

get_customer
search_orders
get_invoice

versus:

create_customer
update_customer
cancel_order
send_email
delete_document

MCP tool metadata can include behavioral hints such as readOnlyHint, destructiveHint, and idempotentHint. These are useful signals, although they should not be treated as security controls. ([Model Context Protocol][1])

A practical architecture is:

Read operation
    ↓
Can often execute automatically

Write operation
    ↓
Validate
    ↓
Check permissions
    ↓
Potential approval
    ↓
Execute

Destructive operation
    ↓
Validate
    ↓
Explicit confirmation
    ↓
Execute

The tool itself should enforce authorization.

Never assume that because the model selected a tool, the action is authorized.

11. Idempotency Matters More With Agents

Agents retry.

Networks fail.

Models repeat actions.

A user may say:

"Send the report to Sarah."

The agent calls:

send_report()

The server processes it.

The response is lost.

The agent does not know whether the operation succeeded.

It might call the tool again.

Now Sarah receives two reports.

For side-effecting tools, consider idempotency keys:

{
  "recipient": "sarah@example.com",
  "report_id": "report_123",
  "idempotency_key": "agent-run-789-send-report"
}

The backend can recognize that the operation has already been performed.

This turns retries from a dangerous behavior into a manageable one.

12. Design Errors for Recovery

Traditional APIs often return:

{
  "error": "Bad Request"
}

That is not very useful to an agent.

Consider:

{
  "error": {
    "code": "INSUFFICIENT_PERMISSION",
    "message": "The current user cannot access this project.",
    "retryable": false,
    "action": "Ask the user to select a project they have access to."
  }
}

Now the model has information for the next decision.

Useful error categories include:

INVALID_ARGUMENT
NOT_FOUND
PERMISSION_DENIED
RATE_LIMITED
TEMPORARY_FAILURE
CONFLICT
REQUIRES_CONFIRMATION

The model should be able to distinguish:

Try again

from:

Change the request

from:

Ask the user

from:

Stop

13. Separate Retryable and Non-Retryable Errors

This distinction becomes critical in autonomous systems.

For example:

{
  "code": "RATE_LIMITED",
  "retryable": true,
  "retry_after_seconds": 10
}

versus:

{
  "code": "INVALID_CUSTOMER_ID",
  "retryable": false
}

The agent can then make a more informed decision.

A simple retry policy might look like:

if error.retryable:
    retry_with_backoff()
elif error.code == "INVALID_ARGUMENT":
    reconsider_arguments()
elif error.code == "PERMISSION_DENIED":
    ask_user()
else:
    stop_and_report()

This is much safer than blindly retrying every failure.

14. Keep Tools Focused

A tool should generally have one clear responsibility.

Consider:

manage_customer

which can:

create
read
update
delete
search
merge
archive
restore

This gives the model a large decision surface.

Instead:

search_customers
get_customer
create_customer
update_customer
archive_customer

Each tool has a more precise meaning.

Google's MCP security guidance similarly recommends keeping MCP tools focused on a single responsibility. ([Google GitHub][4])

The principle is simple:

Fewer decisions per tool usually means clearer decisions for the agent.

15. But Do Not Create Hundreds of Tiny Tools

There is another failure mode.

You can overcorrect.

Imagine:

get_user_name
get_user_email
get_user_timezone
get_user_language
get_user_company
get_user_role
get_user_status

Now the model has to discover seven tools just to understand one user.

Tool granularity should match meaningful agent actions.

A useful test is:

Would an agent naturally think of this as a distinct capability?

If yes, it may deserve its own tool.

If not, it may belong inside another operation.

16. Tool Descriptions Should Explain When Not to Use Them

This is an advanced but powerful pattern.

Instead of:

Search documents.

use:

Search the document library for information contained
in uploaded documents.

Use this when the answer may exist inside user documents.

Do not use this for general web research.
Do not use this when the user provides an exact document ID.

The negative guidance reduces tool confusion.

This becomes increasingly important when an agent has many tools with overlapping capabilities.

17. Build an Agent-Friendly API Layer

Your existing backend probably looks something like:

Frontend
    ↓
REST API
    ↓
Services
    ↓
Database

Adding agents does not mean the model should receive unrestricted access to that REST API.

Instead:

                    ┌──────────────┐
                    │    Agent     │
                    └──────┬───────┘
                           ↓
                  ┌─────────────────┐
                  │  Tool Layer     │
                  │                 │
                  │ search_docs     │
                  │ create_report   │
                  │ send_report     │
                  └────────┬────────┘
                           ↓
                  ┌─────────────────┐
                  │ Adapter Layer   │
                  └────────┬────────┘
                           ↓
                  ┌─────────────────┐
                  │ Internal APIs   │
                  └────────┬────────┘
                           ↓
                     Database

This adapter layer is valuable because your internal APIs can evolve independently from the agent interface.

18. Example: Building a Document Tool

Let's build a simple Python tool.

from typing import TypedDict


class DocumentResult(TypedDict):
    document_id: str
    title: str
    excerpt: str
    relevance: float


def search_documents(
    query: str,
    limit: int = 5
) -> list[DocumentResult]:
    """
    Search uploaded documents for information relevant to the query.

    Use this when the user asks about information that may exist
    inside uploaded documents.

    Do not use this for general web research.

    Args:
        query: Natural-language description of the information to find.
        limit: Maximum number of results. Must be between 1 and 10.

    Returns:
        Matching documents with titles, excerpts, and relevance scores.
    """

    if not query.strip():
        raise ValueError("query cannot be empty")

    if not 1 <= limit <= 10:
        raise ValueError("limit must be between 1 and 10")

    results = document_search_engine.search(
        query=query,
        limit=limit
    )

    return [
        {
            "document_id": result.id,
            "title": result.title,
            "excerpt": result.excerpt,
            "relevance": result.score
        }
        for result in results
    ]

Notice what this tool does not expose:

database connection
SQL query
embedding model
vector database
chunk size
index name
internal storage path

Those are implementation details.

The agent needs a capability, not your infrastructure.

19. Tool APIs Need Authentication Too

A common mistake is to think:

"The model is inside our application, so the tool is trusted."

The model is not an authorization system.

Every tool invocation should still pass through normal security controls.

For example:

Agent
 ↓
Tool
 ↓
Authenticated identity
 ↓
Authorization
 ↓
Validation
 ↓
Business logic
 ↓
Database

Never let a model-generated argument bypass authorization.

Bad:

def get_customer(customer_id):
    return database.get_customer(customer_id)

Better:

def get_customer(customer_id, user):
    authorize(
        user=user,
        resource=customer_id,
        action="read"
    )

    return database.get_customer(customer_id)

The model chooses what it wants to do.

Your application decides whether it is allowed to do it.

20. Add Observability to Every Tool Call

When an agent makes a wrong decision, you need to know why.

Log at least:

agent_run_id
tool_name
tool_version
arguments
user_id
timestamp
latency
result_status
error_code
retry_count

For sensitive systems, carefully control what arguments and results are logged.

A useful trace might look like:

Run: agent_9821

09:41:02
Tool: search_documents
Arguments:
query = "Q3 pricing strategy"

09:41:03
Result:
3 documents

09:41:04
Tool: get_document
Arguments:
document_id = "doc_918"

09:41:04
Result:
success

09:41:07
Tool: create_summary
Arguments:
document_id = "doc_918"

09:41:09
Result:
success

Now debugging becomes possible.

Without tool-level observability, an agent failure often looks like:

User: Why did you give me the wrong answer?

Agent: Sorry.

That is not an engineering strategy.

21. Version Your Tool Contracts

Tool APIs evolve.

Today:

{
  "query": "..."
}

Tomorrow:

{
  "query": "...",
  "filters": {}
}

Later:

{
  "query": "...",
  "filters": {},
  "ranking": "semantic"
}

Changing semantics without considering existing agents can cause subtle failures.

Treat tools like public APIs.

Consider:

search_documents.v1
search_documents.v2

or maintain backward-compatible schemas where possible.

This matters especially when multiple agents or external clients consume the same tool.

22. Test the Tool, Not Just the Model

An agent can fail for two completely different reasons:

Model failure

or:

Tool failure

You need to test both.

Tool-level tests

def test_search_documents_rejects_empty_query():
    with pytest.raises(ValueError):
        search_documents("")

def test_search_documents_rejects_invalid_limit():
    with pytest.raises(ValueError):
        search_documents("pricing", limit=100)

Agent-level tests

Test whether the model chooses the right tool:

User:
"Find the pricing information in my uploaded files."

Expected:
search_documents

And:

User:
"Search the internet for today's AI news."

Expected:
web_search

Tool selection is part of agent behavior and should be evaluated as such.

Modern agent development workflows increasingly include structured evaluation alongside unit and integration tests. Google's current agent tooling, for example, includes evaluation datasets and grading workflows as part of the development lifecycle. ([Google GitHub][2])

23. A Practical Tool Design Checklist

Before exposing a function to an AI agent, ask:

Identity

Is the tool name unambiguous?
Does it describe a meaningful capability?

Description

Does the description explain what the tool does?
Does it explain when to use it?
Does it explain when not to use it?

Inputs

Are parameters semantic?
Are types explicit?
Are required fields defined?
Are constraints validated?
Are ambiguous parameters avoided?

Outputs

Is the result structured?
Can the agent easily understand what happened?
Does the output provide enough information for the next decision?

Errors

Are errors machine-readable?
Can the agent distinguish retryable from permanent failures?
Does the error explain what the agent can do next?

Safety

Does the backend enforce authorization?
Are destructive operations clearly identified?
Are side effects explicit?
Are confirmation requirements enforced outside the model?

Reliability

Is the operation idempotent where appropriate?
Can requests safely be retried?
Are timeouts defined?

Observability

Can you trace every tool invocation?
Can you identify latency and failures?
Can you reproduce an agent run?

Evolution

Can the tool contract change safely?
Do you have a versioning strategy?

24. The Architecture to Aim For

A production agent should not look like this:

LLM
 ↓
Random API calls
 ↓
Database

A better architecture is:

                       ┌───────────────┐
                       │     User      │
                       └───────┬───────┘
                               ↓
                       ┌───────────────┐
                       │     Agent     │
                       └───────┬───────┘
                               ↓
                    ┌─────────────────────┐
                    │    Tool Registry    │
                    └─────────┬───────────┘
                              ↓
                 ┌────────────────────────┐
                 │ Agent-Friendly Tool API │
                 └────────────┬───────────┘
                              ↓
                  ┌────────────────────┐
                  │ Validation         │
                  │ Authorization      │
                  │ Rate Limits        │
                  │ Idempotency        │
                  │ Observability      │
                  └──────────┬─────────┘
                             ↓
                     ┌──────────────┐
                     │ Adapter Layer│
                     └──────┬───────┘
                            ↓
                ┌──────────────────────┐
                │ Internal APIs / DBs  │
                └──────────────────────┘

The model controls the reasoning loop.

Your application controls the execution boundary.

That separation is fundamental.

The Real API Is the Model's Mental Model

The biggest mistake in agent tool design is thinking of tools as simple wrappers around existing functions.

They are not.

A tool is a reasoning interface.

The model needs to understand:

What can I do?
When should I do it?
What information do I need?
What will happen?
What will I get back?
What should I do if it fails?

A well-designed tool API answers all six questions.

This is why tool descriptions, schemas, structured outputs, error contracts, permissions, and observability matter so much.

Protocols such as MCP are formalizing many of these concepts. Current MCP tooling supports tool descriptions, input schemas, output schemas, and behavioral annotations, while newer SDKs also provide schema-based validation for tool arguments and structured results. ([Model Context Protocol][1])

The future of agent engineering is not just about giving models more tools.

It is about giving them better interfaces to reason through.

And the difference between an unreliable agent and a production-grade agent may come down to something as small as this:

Bad tool:
"execute_action"

Good tool:
"cancel_subscription"

The second one gives the model something it can reason about.

That is the real job of an agent tool API.

Final Takeaway

When designing tools for AI agents:

Design for decisions.
Use explicit schemas.
Keep tools focused.
Write descriptions for the model.
Return structured results.
Make errors recoverable.
Separate reads from side effects.
Enforce authorization outside the model.
Support safe retries.
Instrument every invocation.
Evaluate tool selection.
Version important contracts.

The best tool API is not necessarily the one with the most capabilities.

It is the one that gives the agent clear, constrained, predictable actions.

That is how you turn tool calling from a demo feature into an engineering system.

Context Engineering Is Becoming More Important Than Prompt Engineering

Ali Raza — Thu, 17 Sep 2026 18:12:59 +0000

For the first few years of generative AI, one skill dominated the conversation: prompt engineering.

Developers learned how to write better instructions, structure prompts, provide examples, assign roles, specify output formats, and guide models toward better responses.

That still matters.

But as AI applications move beyond simple chat into coding assistants, research systems, autonomous agents, and tool-using workflows, another engineering problem is becoming harder to ignore:

What information should the model actually see at each step?

A good prompt cannot compensate for missing context.

An intelligent model with the wrong context can still produce the wrong result.

This is why context engineering is emerging as an important discipline for developers building production AI systems.

Anthropic describes context engineering as the broader practice of curating the information available to a model during inference, including system instructions, tools, external data, message history, and other relevant state. ([Anthropic][1])

The shift is simple to describe:

Prompt engineering asks, "What should I tell the model?"

Context engineering asks, "What does the model need to know right now?"

That difference becomes extremely important when building AI systems that operate over multiple steps.

Prompt Engineering Is Still Important

Let's start with something clear.

Prompt engineering is not dead.

Clear instructions remain one of the simplest ways to improve model behavior.

A developer might write:

You are a senior Python developer.

Review the following function.

Identify:
1. Bugs
2. Security issues
3. Performance problems
4. Maintainability concerns

Return your answer using Markdown headings.

This prompt establishes the role, task, evaluation criteria, and output format.

That is useful.

Official OpenAI guidance continues to recommend clear instructions and structured prompting techniques for getting more useful model outputs. ([OpenAI Help Center][2])

The problem appears when developers assume the prompt is the entire system.

In a simple question-answering application, that assumption might work.

In an agent that needs to inspect files, call APIs, remember previous actions, retrieve documents, and make decisions over several steps, it becomes much less effective.

The model needs more than instructions.

It needs state.

What Is Context Engineering?

Context engineering is the process of deciding what information enters the model's context, when it enters, how it is structured, and when it should be removed or replaced.

That context can include:

System instructions
User messages
Conversation history
Retrieved documents
Database records
Tool definitions
Tool results
User preferences
Application state
Previous actions
Code files
Error messages
External knowledge
Agent memory

Anthropic's engineering team describes context as a finite resource and argues that effective agent systems should focus on supplying the smallest set of high-signal information needed for the desired outcome. ([Anthropic][1])

This changes the developer's job.

Instead of writing one giant prompt containing everything, developers need to build systems that assemble the right context dynamically.

Why Bigger Context Is Not Always Better

A common assumption is:

"If more context helps, then giving the model everything should help even more."

It sounds logical.

It is often wrong.

More information can create noise.

Imagine asking an AI coding agent to fix a bug in one authentication function.

You could provide:

The entire repository
Every README
Every previous conversation
All database schemas
All logs from the last six months
Every API specification
Every dependency document

The model now has an enormous amount of information.

But most of it is irrelevant.

The actual bug may depend on three files and one recent error message.

The developer's job is therefore not simply to maximize context.

It is to maximize relevant context.

Anthropic refers to this challenge in terms of an attention budget and notes that model performance can degrade as context becomes increasingly crowded with information. ([Anthropic][1])

The goal is not:

More tokens.

The goal is:

More useful tokens.

Context Engineering vs Prompt Engineering

The easiest way to understand the difference is to compare their responsibilities.

Prompt Engineering	Context Engineering
Writes instructions	Curates information
Defines desired behavior	Defines available state
Optimizes wording	Optimizes information selection
Often static	Often dynamic
Focuses on prompts	Focuses on the entire context
Useful for individual tasks	Critical for multi-step systems
Defines what to do	Helps determine what to know

A prompt might tell an agent:

Review this pull request and identify potential bugs.

Context engineering determines whether the agent receives:

Pull request
+
Changed files
+
Relevant surrounding code
+
Existing tests
+
Project conventions
+
Related issue
+
Recent CI failures

The prompt gives the instruction.

The context gives the agent the information required to execute that instruction intelligently.

The Context Window Is an Engineering Constraint

Developers often talk about context windows as if they were simply storage limits.

They are more than that.

Even when a model supports a large context window, the engineering problem remains:

Which information deserves the model's attention?

Consider an AI coding agent working on a large repository.

At the beginning, it might need:

Project architecture
Developer instructions
Relevant source files

After discovering a bug, it might need:

Error logs
A related function
Test cases

After making a change, it might need:

The modified files
Test output
Compiler errors

The optimal context changes throughout the task.

This means context engineering is inherently dynamic.

The model does not need the same information at every step.

Retrieval Is Part of Context Engineering

This is where retrieval systems become important.

A traditional RAG system might retrieve documents based on the user's question and place those documents into the model's context.

That approach works well for many applications.

But agentic systems introduce another possibility.

Instead of loading everything up front, an agent can retrieve information when it becomes relevant.

For example:

User request
     ↓
Agent identifies problem
     ↓
Search relevant files
     ↓
Read selected files
     ↓
Analyze error
     ↓
Search related implementation
     ↓
Run tests
     ↓
Inspect results
     ↓
Modify code

This is different from dumping an entire repository into the initial prompt.

Anthropic describes this approach as "just in time" context retrieval, where agents maintain lightweight references and load information dynamically through tools when needed. ([Anthropic][1])

For large systems, that can be a much more scalable architecture.

Tools Are Also Context

One of the most interesting parts of context engineering is that tools themselves become part of the model's available context.

Consider an agent with these tools:

search_database()
read_file()
write_file()
run_tests()
send_email()
delete_record()

The model does not simply need to know that these tools exist.

It needs to understand:

What each tool does
When to use it
What arguments it requires
What it returns
What its limitations are
Whether the action is reversible
What permissions it requires

OpenAI's agent guidance emphasizes the importance of well-defined tools for agents, including tools for retrieving information and tools for taking actions. ([OpenAI][3])

Anthropic has similarly noted that tool descriptions are loaded into an agent's context and that precise descriptions can influence tool-calling behavior. ([Anthropic][4])

This means tool design is not separate from context design.

Your API documentation can become part of the agent's reasoning environment.

MCP Makes This Even More Interesting

The rise of the Model Context Protocol provides another example of why context engineering is becoming an architectural concern.

MCP defines standardized ways for applications to expose prompts, resources, and tools to AI systems. Resources can provide contextual data such as files or database schemas, while tools can allow models to retrieve information or perform actions. ([Model Context Protocol][5])

This creates a more structured relationship between models and external systems.

Instead of building every integration as a completely custom mechanism, applications can expose standardized capabilities.

But that creates another engineering question:

Which resources and tools should be exposed to the model at a particular moment?

Giving an agent access to 100 tools does not automatically make it more capable.

It can make the decision space more complicated.

Tool selection therefore becomes part of context engineering.

The Problem of Context Pollution

Long-running agents create another challenge.

Imagine an agent working for an hour.

During that time, it generates:

User messages
Tool calls
Tool results
Intermediate reasoning
Errors
Search results
File contents
Test results
Decisions
Temporary observations

Eventually, the context can become crowded.

Some information is still important.

Some information is outdated.

Some information is duplicated.

Some information is completely irrelevant.

This is context pollution.

If the system simply keeps appending everything, the model may have difficulty identifying the information that matters most.

The solution is not necessarily a larger context window.

Instead, developers can use strategies such as:

Compaction

Summarize older interactions and replace them with a more concise representation.

Structured notes

Store important discoveries separately from temporary conversation history.

Selective retrieval

Retrieve information again when it becomes relevant instead of carrying it through the entire interaction.

State management

Keep application state outside the conversation and inject only the necessary portion when required.

Anthropic discusses compaction, structured note-taking, and multi-agent approaches as strategies for handling long-horizon agent tasks. ([Anthropic][1])

Context Should Be Treated Like a System Resource

Developers already think carefully about:

CPU
Memory
Network bandwidth
Database connections
Cache usage
Storage

Context deserves similar treatment.

You should know:

What enters the context?

Why does it enter?

How long should it remain?

Who controls it?

Can it become stale?

What happens when it becomes too large?

This is especially important for production AI systems.

A context pipeline might look like:

User Request
     ↓
Intent Detection
     ↓
Relevant State
     ↓
Retrieval
     ↓
Tool Selection
     ↓
Context Assembly
     ↓
Model
     ↓
Tool Result
     ↓
Context Update
     ↓
Next Model Step

This is much closer to software architecture than simple prompt writing.

A Practical Context Engineering Architecture

Suppose you're building an AI support agent.

Instead of creating one massive prompt, divide the context into layers.

Layer 1: Stable instructions

Things that rarely change:

You are a customer support agent.
Follow company policies.
Never expose private customer information.

Layer 2: User context

Information about the current customer:

Customer ID: 12345
Plan: Pro
Account age: 2 years

Layer 3: Task context

What the customer currently needs:

Issue: Payment failed
Previous attempts: 2

Layer 4: Retrieved context

Relevant documentation:

Payment troubleshooting guide
Refund policy
Current billing status

Layer 5: Tool context

Available actions:

check_payment()
create_ticket()
issue_refund()

Layer 6: Current state

What happened during the current task:

Payment provider returned error 402.
Customer has already retried twice.

This layered approach makes the system easier to reason about and debug.

Context Engineering Changes How We Debug AI Systems

Traditional debugging asks:

"Why did the code produce this output?"

AI systems require another question:

"What information did the model have when it produced this output?"

That means production observability should capture context-related signals.

For example:

Request ID
Model
Prompt version
Retrieved documents
Tool definitions
Tool calls
Tool results
Context size
Output
Evaluation result

https://goodoff.co/
If an agent makes a bad decision, developers need to know whether:

The model misunderstood the instruction
The wrong document was retrieved
Important context was missing
Irrelevant context dominated the request
A tool returned incorrect information
The context contained stale information
The tool description was ambiguous

Without this visibility, debugging becomes guesswork.

Context Engineering Is Also About Security

Context is not just a performance concern.

It is a security boundary.

If an agent receives sensitive information that it does not need, the risk increases.

Consider an internal enterprise agent.

It might have access to:

Customer records
Financial information
Employee data
Internal documentation
Private source code

The correct question is not:

"Can the AI access all of this?"

It should be:

"What does the AI need to access for this specific task?"

The principle of least privilege applies to context just as it applies to traditional software permissions.

MCP's specification also includes security considerations around validating resource identifiers and implementing access controls for sensitive resources. ([Model Context Protocol][5])

Good context engineering therefore means giving an agent enough information to work effectively without unnecessarily exposing everything available.

How Developers Should Think About Context Engineering

A useful mental model is:

Prompt = instructions

Context = working environment

Tools = capabilities

Memory = persistent state

Retrieval = information selection

Model = reasoning engine

Once you think about AI systems this way, many architectural decisions become clearer.

The model is not operating in isolation.

Its behavior emerges from the combination of the model and the environment you construct around it.

That environment is increasingly becoming the real engineering challenge.

Five Practical Rules for Better Context Engineering

1. Give the model the smallest useful context

Do not automatically include everything.

Start with high-signal information.

2. Retrieve information when it becomes relevant

Dynamic retrieval can be better than loading large datasets upfront.

3. Keep instructions separate from data

Clearly distinguish rules, user information, retrieved content, and tool outputs.

4. Treat tool descriptions as part of the AI interface

Poorly documented tools can create poor agent behavior.

5. Measure context, not just output

Track what information the model received when evaluating failures.

These principles are simple, but they can significantly change how AI applications are designed.

The Future of AI Engineering Is Bigger Than Prompting

Prompt engineering became important because developers discovered that language models respond differently depending on how instructions are expressed.

Context engineering takes the next step.

It asks developers to design the information environment in which the model operates.

As AI applications become more agentic, that environment becomes increasingly dynamic.

The model may need to:

Search a database
Read a document
Inspect code
Call an API
Remember a previous decision
Check a policy
Run a test
Observe the result
Change its next action

Every one of those steps can change the context.

That makes context engineering less like writing a clever prompt and more like designing a runtime system.

The best AI application may not be the one with the longest prompt.

It may be the one that consistently gives the model the right information at the right time.

Conclusion

Prompt engineering taught developers how to communicate with language models.

Context engineering is teaching developers how to build the environment around them.

That distinction matters because modern AI systems are no longer limited to answering isolated questions.

They are becoming systems that retrieve information, use tools, maintain state, execute multi-step workflows, and operate for extended periods.

In that world, a perfect prompt is not enough.

The model needs relevant information.

It needs the right tools.

It needs useful state.

It needs reliable retrieval.

It needs protection from irrelevant or sensitive information.

And it needs a context that changes as the task changes.

The future of AI engineering is not about finding one perfect prompt.

It is about building systems that know what the model needs to know, when it needs to know it, and when it no longer needs to know it.

That is why context engineering is becoming one of the most important ideas in modern AI application development.