The File System

Spring Boot is magic. So I built an HTTP server in Java to ruin the illusion.

Colin Venancio — Fri, 22 May 2026 00:00:00 GMT

Introduction

Spring Boot makes building a backend almost embarrassingly easy. Slap @RestController on a class, throw a @GetMapping on a method, hit "run", and boom... you've got a functioning HTTP server before your coffee's done brewing. An embedded Tomcat server just... appears. Routes just... work. Annotations just... do things. Magic!

This is great, until I started asking myself: how does this actually work? What exactly is happening under the hood from the moment I make a GET request, to the moment I receive a 200 OK back from the server?

So, I did what curiosity demanded. I decided that I'd take a shot at building my own HTTP server from scratch in Java — just sockets, threads, and bytes.

The Goal: Develop a minimalistic system that provided enough functionality to allow me to expose some of the abstractions that Spring Boot was hiding from me.

Follow along — by the end, I'll have pulled back the curtain on some of that sweet, sweet Spring Boot "magic".

:::note The code I reference in this post is available in my GitHub repo. I encourage you to dig around, fork the repo, and tinker with it yourself. :::

What We're Building

Let's not waste any time! So what's really happening during the lifecycle of an HTTP request?

At a high level, we're going to establish a client -> server connection, read incoming bytes off of a socket, parse them into a request object, find the right method to handle it, build a response object, and write bytes back. You can visualize this process like so:

Establish a connection
       ↓
Read bytes off of a socket
       ↓
Parse into a request object
       ↓
Route request to a handler
       ↓
Build a response object
       ↓
Write back as bytes

That's the whole job. Pretty simple, right? Spring Boot does this for us right out of the box, but today we're going to do it ourselves.

Step 1: Accepting Connections

Our first job is to establish a connection between our client and our server. Java conveniently provides us with java.net.ServerSocket which we'll use here.

You can think of a ServerSocket as a telephone operator whose job is to sit and wait for the phone to ring. Once a call comes in, the operator hands the caller off to a new private line (a Socket) to handle that specific conversation. The operator then returns to waiting for the next call.

All we need to do is create a ServerSocket bound to a port. We then call its accept() method, which blocks the calling thread until a client connects. When one does, you get back a new Socket object representing that connection. Wrap that whole thing in a loop and voilà, you've got a server that can accept connections forever:

public void start() throws IOException {
    final int PORT = 8080;
    try (ServerSocket serverSocket = new ServerSocket(PORT)) {
        while (true) {
            Socket client = serverSocket.accept(); // blocks until a client connects
            // ...handle the connection
        }
    }
}

That's the whole foundation. Every HTTP server on the planet, including the embedded Tomcat that Spring Boot spins up for you, has some version of this loop running underneath. The rest of the work is what happens after accept() returns.

Once we've established a client connection, and received a Socket object back, we now need the ability to read and write messages over this connection. HTTP data is transferred as a byte stream (InputStream and OutputStream). We can access these streams by calling Socket.getInputStream() and Socket.getOutputStream().

But before we worry about HTTP specifically, let's prove we can successfully move bytes through this socket. For this example, we'll create a simple "echo server" which will read whatever the client sends us through InputStream, and send it right back through OutputStream.

That'll look something like this:

public void start() throws IOException {
    final int PORT = 8080;
    try (ServerSocket serverSocket = new ServerSocket(PORT)) {
        while (true) {
            Socket client = serverSocket.accept();
            // client connection established...
            InputStream inputStream = client.getInputStream();
            OutputStream outputStream = client.getOutputStream();

            BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
            PrintWriter writer = new PrintWriter(outputStream, true); //auto flush
            
            String inputLine;
            // read a line from the buffer, write it back
            while ((inputLine = reader.readLine()) != null) {
                writer.println(inputLine);
            }
            client.close(); // close the connection when buffer is empty
        }
    }
}

Now let's test it out. In our terminal:

$ echo "Hello, world!" | nc localhost 8080
# Hello, world!
^C

Success! "Hello, world!" in -> "Hello, world!" out.

Now, I know what you're thinking. This isn't quite an HTTP server yet. It doesn't speak the protocol. At this point, it's just a glorified byte-pipe. Bytes come in via getInputStream(), bytes go out via getOutputStream(). Simply put, HTTP is just a universally agreed-upon format for what those bytes mean. We'll teach it HTTP in Step 3.

Now, a Spring Boot controller never makes you touch a stream directly. You write something like this:

@PostMapping("/echo")
public String echo(@RequestBody String body) {
    return body;
}

You get a String parameter handed to you, and your return value is sent back. But underneath, Tomcat is calling request.getInputStream() and reading bytes similarly to how we just did. Spring converts those bytes into a String (using an HttpMessageConverter), passes it to your method, converts your return value back to bytes, and writes them to response.getOutputStream(). The streams are still there. They're just buried under a few layers of "convenience".

Currently, our server can establish a connection to a client and read/ write bytes through a Socket. This is cool, but what happens when our server gets two requests at the same time?

Step 2: Handling Many Connections at Once

With our current setup, we'd have to wait for each request to finish before handling a new one. That doesn't scale. Ideally, we want our server to be able to handle lots of requests simultaneously. That's where we introduce concurrency.

Conceptually, we need a way for our server to hand off incoming connections to other threads. This way, as requests come in, our main ServerSocket thread can delegate the work and immediately go back to listening for the next connection.

There are a couple of ways we can do this in Java (virtual threads, NIO selectors, reactive frameworks). We'll use a fixed thread pool with an arbitrary number of threads for this example:


ExecutorService pool = Executors.newFixedThreadPool(50);

public void start() {
    try (ServerSocket serverSocket = new ServerSocket(PORT)) {
        while (true) {
            Socket client = serverSocket.accept();
            pool.submit(() -> handle(client)); // hand off, keep accepting
        }
    } 
}
public void handle(Socket client) {
    // ...read/write bytes, close socket (from previous section)    
}

The accept loop is now non-blocking with respect to request handling. accept() returns a Socket, we hand it to the pool, and immediately loop back to wait for another connection.

To prove that the thread pool is actually doing what we think it is, we can fire 50 concurrent connections at the server and clock the time it took to handle those connections.

For this test, I temporarily added Thread.sleep(100) in handle() so each request has a measurable clock time.

In our terminal:

$ time seq 1 50 | xargs -n1 -P50 -I{} sh -c 'echo "hello {}" | nc -q1 localhost 8080'

# Sequential (no thread pool): ~6.1 sec
# Concurrent: ~1.2 sec

As you can see, the thread pool has significantly improved our performance. The 1.2 seconds isn't pure server time either. About a second of that is nc's per-connection wait timer. The point is the contrast between sequential and concurrent.

Our server can now handle many connections at once, but every one of those connections is protocol-agnostic. The next layer is where those bytes start to mean something. Next, we'll teach our server to read the bytes coming off the socket as structured HTTP requests.

Step 3: Parsing Requests

At the end of the day, bytes are just bytes. HTTP is what imposes structure on them. When we create a parsing layer, our job is to turn raw bytes -> request object.

To accomplish this, we must first understand the anatomy of an HTTP request since a request abides by strict syntactic standards. If our incoming request does not abide by these standards, we must consider it malformed and reject it.

An HTTP/1.1 request consists of four main parts:

Request-Line: The first line containing the method, target URI, and HTTP version, separated by spaces, terminated by CRLF. (e.g. GET /users HTTP/1.1\r\n)
Request Headers: Key-value pairs providing metadata, each on a new line, terminated by CRLF (e.g. Host: example.com\r\n)
Blank Line: A mandatory empty line (CRLF) to signify the transition from headers -> body.
Body (optional): The payload of the request.

This comes together to look something like this:

POST /greeting HTTP/1.1\r\n
Host: example.com\r\n
User-Agent: Mozilla/5.0\r\n
Content-Type: text/plain\r\n
Content-Length: 13\r\n
\r\n
Hello, World!

When we parse a request, our job is to turn this block of text into a structured HttpRequest object that we can work with.

To accomplish this, we want to "walk through" the request byte-by-byte, acknowledge what portion of the request we are currently in, and parse that specific portion accordingly. For this, we'll build a State Machine that keeps an internal state variable that tells us what section of the request we are currently in.

For clarity, these are the data structures that we'll be constructing from the raw request:

record HttpRequest(RequestLine requestLine, Map<String, List<String>> headers, byte[] body) {}
record RequestLine(HttpMethod method, String target, String version) {}
enum HttpMethod { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS }

Here's the skeleton of our state machine, with the internals stubbed out to keep it concise for this article (I encourage you to take a look at the full code in the repo):

private enum ParserState {
    REQUEST_LINE,
    HEADER_NAME,
    HEADER_VALUE,
    BODY,
    COMPLETE,
    ERROR
}

ParserState state = ParserState.REQUEST_LINE;
StringBuilder buffer = new StringBuilder();

int prev = -1;
int curr;

while ((curr = in.read()) != -1) {
    switch (state) {
        case REQUEST_LINE -> {
            // read bytes into buffer until CRLF, then parse:
            // "GET /users HTTP/1.1" -> new RequestLine("GET", "/users", "HTTP/1.1"). 
            // change state to HEADER_NAME.
        }
        case HEADER_NAME -> {
            // read until ':' -> capture headerName -> change state to HEADER_VALUE
            // if CRLF (blank line) -> change state to BODY
        }
        case HEADER_VALUE -> {
            // read until CRLF, insert (headerName, headerValue) into map, 
            // change state back to HEADER_NAME (next header)
        }
        case ERROR -> throw new HttpParseException(400, "Malformed request");
    }

    if (state == ParserState.BODY) {
        // if Content-Length header is present, read exactly that many bytes
        // change state to COMPLETE
    }
    if (state == ParserState.COMPLETE) break;
    prev = curr;
}

return new HttpRequest(requestLine, headers, body.length > 0 ? body : null);

The loop reads one byte at a time. Depending on which state we're in, that byte either gets accumulated into the current buffer (mid-token) or triggers a state transition (end of token, like \r\n or :). Once we transition to BODY, we leave the byte-by-byte loop and read the body in one shot. We read exactly n bytes where n = Content-Length. If there is no Content-Length header present, we skip this step entirely.

If we encounter any part of the request which is malformed (missing Host header, bare LF without CR, invalid HTTP version, etc.), we throw a MalformedRequestException.

This parser handles the basics (request line, headers, Content-Length framing, malformed input rejection). Production parsers handle chunked Transfer-Encoding, header folding, percent-decoding, and a dozen other edge cases I didn't touch. The point isn't to compete with Tomcat, but rather to make the shape of the work visible so that the next time you write @RequestBody User user in your Spring app, you've got an idea of what's happening under the hood.

So now we've got a parsed HttpRequest which contains a method, a target, headers, and a body. Now what? We need to figure out what to do with it. This is where routing comes in. Next, we'll build the mechanism that matches each endpoint with the code that handles it.

Step 4: Routing to a Handler

Let's clarify exactly what our routing mechanism needs to do. Two things:

Keep an internal registry that says "when a GET /greeting request comes in, run this code".
Given an incoming request, we need to search through that registry to find the right code to run.

Our end goal is to create an intuitive interface that looks like this:

Router router = new Router();
// register our routes
router.get("/greeting", (req) -> { /* our desired action/method */ });
router.post("/echo", (req) -> { /* our desired action/method */ });

RouteHandler handler = router.getHandler(request); // find the correct route

The first thing we need to define is our RouteHandler. In our case, a handler is simply any method that accepts an HttpRequest object as a parameter, and returns an HttpResponse (we'll cover response shapes in step 5). This handler will represent the logic that we wish to run for a particular route.

@FunctionalInterface
public interface RouteHandler {
    HttpResponse handle(HttpRequest request) throws Exception;
}

The @FunctionalInterface annotation is our contract. A RouteHandler is anything shaped like HttpRequest -> HttpResponse. The router doesn't know if the handler queries a database, returns a hardcoded string, or launches missiles. It only knows about the shape.

Next, we need a way to uniquely identify a route by its method and its path. GET /users and POST /users are two different routes. Same path, different code. That's where a RouteKey comes in:

public record RouteKey(HttpMethod method, String path) {}

Now, we have a way to map a specific method to a path to create a key. Next, we need a way to map that key to a handler. This is where our Router class begins to come together.

Inside of this class, we will keep an internal registry for all of the available routes in our application. We'll then create a few methods which will allow us to add specific routes to that registry:

public class Router {

    private final Map<RouteKey, RouteHandler> registry = new HashMap<>();

    public void get(String path, RouteHandler handler) {
        registry.put(new RouteKey(HttpMethod.GET, path), handler);
    }
    public void post(String path, RouteHandler handler) {
        registry.put(new RouteKey(HttpMethod.POST, path), handler);
    }
    // ... put(), patch(), delete() -> same shape
}

The Router is literally just a HashMap with a friendlier API. That's it. get() and post() just wrap put() with the method baked in. Now that we have a way to store routes, the only question left to answer is how we look up those routes.

To solve this, we'll create a method which decomposes the incoming HttpRequest, extracts the method and path from the RequestLine, constructs a RouteKey for that particular request, looks through the registry for a matching key, and returns the correct RouteHandler:

public RouteHandler getHandler(HttpRequest request) {
        HttpMethod method = request.requestLine().method();
        String path = request.requestLine().target();

        return registry.get(new RouteKey(method, path));
}

Notice that getHandler() returns a RouteHandler, not an HttpResponse. The router's job ends at "here's the method you should call." Actually calling that method happens back in our handle() method.

Down the road, if we need to add any middleware (auth, logging, rate limiting, etc.), we can slot it in between lookup and invocation. Fuse those two steps together and you'd have to cram that logic into the router itself, which has nothing to do with routing.

Spring's HandlerMapping makes the same call for the exact same reason. It doesn't invoke the handler directly. Instead, it returns a HandlerExecutionChain which contains the handler itself, along with any interceptors that must run before or after it. Auth, logging, the same things we just talked about. Same seam, same reason.

public void handle(Socket client) {
    try (
            BufferedInputStream input = new BufferedInputStream(client.getInputStream());
            BufferedOutputStream output = new BufferedOutputStream(client.getOutputStream());
        ){

            HttpRequest request = parser.parseRequest(input);
            RouteHandler handler = router.getHandler(request);
            HttpResponse response = handler.handle(request);
            // ...write to client (next section)
    } 
}

:::note A small change: I switched from BufferedReader/PrintWriter, to BufferedInputStream/BufferedOutputStream. The reader/writer pair assumes character data, but HTTP bodies may be binary (images, gzipped JSON). Reading at the byte level is more honest. :::

While we're at it, we'll also create a method for configuring our routes. You can create this method in its own config class, but for clarity I'll just create a configureRoutes() method within our HttpServer class:

public class HttpServer {
    private final Router router = new Router();
    private final RequestParser parser = new RequestParser();
    private final int PORT = 8080;
    
    public void start() throws IOException {
        configureRoutes();
        
        try (ServerSocket serverSocket = new ServerSocket(PORT)) {
            while (true) {
                Socket client = serverSocket.accept();
                pool.submit(() -> handle(client));
            }
        }
    }
    
    private void configureRoutes() {
        router.get("/greeting", req -> HttpResponse.ok("hello, world"));
        router.post("/echo", req -> HttpResponse.ok(req.body()));
    }
    
    private void handle(Socket client) {
        // ...previous snippet
    }
}

Step 5: Building & Writing the Response

We've spent four sections turning bytes into something meaningful. Now we run the whole thing in reverse. The response layer is HttpResponse object → bytes on the wire.

A response has the same shape as a request: a status line, headers, a blank line, and a body.

HTTP/1.1 200 OK\r\n
Content-Type: text/plain\r\n
Content-Length: 13\r\n
\r\n
Hello, World!

The data model mirrors the request side:

public class HttpResponse {
    private final int statusCode;
    private final String reasonPhrase;
    private final Map<String, String> headers;
    private final byte[] body;

    // constructor, getters omitted...
}

Building one of these by hand every time would be tedious and error-prone. Every handler would have to remember to set Content-Length, pick a sensible Content-Type, and get the status code right. Three opportunities to screw it up.

We'll centralize that work with factory methods:

public static HttpResponse okText(String body) {
    byte[] bodyBytes = body.getBytes(StandardCharsets.UTF_8);
    Map<String, String> headers = new HashMap<>();
    headers.put("Content-Type", "text/plain");
    headers.put("Content-Length", String.valueOf(bodyBytes.length));
    return new HttpResponse(200, headers, bodyBytes);
}

// notFound(), badRequest()... same shape -> different status code

Static factory methods provide us with a way to enforce correctness. One place to set Content-Length, one place to pick the default Content-Type, one place to fix when you get it wrong.

Now we need to write the response back to the client. Order matters: status line, headers, blank line, body. Get this wrong and the client can't parse what you sent.

public void write(BufferedOutputStream out) throws IOException {
    StringBuilder sb = new StringBuilder();
    sb.append("HTTP/1.1 ").append(statusCode).append(" ").append(reasonPhrase).append("\r\n");
    headers.forEach((k, v) -> sb.append(k).append(": ").append(v).append("\r\n"));
    sb.append("\r\n");
    out.write(sb.toString().getBytes(StandardCharsets.UTF_8));
    if (body != null && body.length > 0) out.write(body);
    out.flush();
}

Content-Length is very important here. It tells the client where the response ends. Without it (or chunked encoding, which we didn't build), the client doesn't know if it's done reading, so it just... waits. For eternity.

Now the full lifecycle fits in one method:

public void handle(Socket client) {
    try (
        BufferedInputStream input = new BufferedInputStream(client.getInputStream());
        BufferedOutputStream output = new BufferedOutputStream(client.getOutputStream());
    ) {
        HttpRequest request = parser.parseRequest(input);
        RouteHandler handler = router.getHandler(request);
        HttpResponse response = handler == null
            ? HttpResponse.notFound()
            : handler.handle(request);
        response.write(output);
    } catch (Exception e) {
        // ... error handling
    }
}

That's the entire request lifecycle in ten lines. Accept, parse, route, invoke, write. No matter how much framework you pile on top, the loop at the bottom looks like this. Tomcat's version is more defensive, more configurable, and significantly more battle-tested, but you get the point.

One last look at Spring. In your controller method, return user; is doing a lot. Under the hood, Spring wraps your object in a ResponseEntity, picks an HttpMessageConverter based on the Accept header (MappingJackson2HttpMessageConverter for JSON by default), serializes the object to bytes, sets Content-Length and Content-Type, and writes it all to the output stream. The factory methods we just wrote do the same job, but for strings. The difference is that Spring's converters know how to turn any object into bytes, and will pick the correct converter based on what the client asked for.

What I Didn't Build

The server we just built handles the happy path. Real HTTP servers handle a hundred ugly edge cases on top of that. Here's a quick map of what I deliberately skipped, so you know where the gaps are.

Chunked Transfer Encoding. Our parser requires a Content-Length header to read the body. That works just fine in instances where the sender knows the body size upfront, but breaks for streaming responses where the length isn't known until the last byte. HTTP/1.1's answer is chunked encoding. With chunked encoding, the body comes in pieces, each prefixed with its own length, terminated by a zero-length chunk. Not too hard conceptually, but it's another state in the parser and another branch in the response writer.

Path variables and pattern matching. This is probably the biggest "wait, can you actually use this?" gap. Our router does exact-string matching: /users works, /users/1234 would need to be registered separately. Real routers parse path templates such as /users/{id} with either a regex or a trie, capture the matched variables, and stash them on the request so the handler can read them. This is what makes REST APIs feel like REST APIs.

Virtual Threads. I used a fixed thread pool in Step 2. This model will scale to a few thousand concurrent connections, but OS thread overhead becomes the bottleneck. For ~20 years, Java's answer to "more concurrency" was async and reactive code (Reactor, WebFlux). The tradeoff was increased complexity for more connections-per-thread. Java 21's virtual threads eliminates that tradeoff. Tomcat 10.1+ supports them.

Hardening. Currently, our server will happily fall over to anyone who looks at it funny. There are a couple of examples worth naming. First, request size limits: a malicious client can send a 10GB request line with no newlines and our parser will buffer it all into memory before exploding. Real servers cap header sizes and reject anything over the limit. Second, slowloris: a client opens a connection, sends one byte every thirty seconds, and never finishes the request. The thread pool fills up with idle connections and the server stops accepting new ones. Real servers enforce read timeouts. There's more. TLS attacks, header injection, request smuggling, you get the point. Production HTTP servers need to be bulletproof.

Closing Thoughts

Accept, parse, route, invoke, write. Five verbs, five sections, and the whole request lifecycle fits in one handle() method. The black box has fewer sides now.

At the end of the day, when you use a framework, you're inheriting decisions that someone else made, and code that you never had to write. That's leverage. Most of the time, it's exactly what you want. The "magic" that everyone talks about? It's just layers, and most days you don't need to look under them.

The value of building something from scratch isn't that you'd ever ship it. It's that when something breaks, you know where to look to fix it. That's the real leverage.

If you're feeling ambitious, I encourage you to fork the repo, pick one thing from the "What I Didn't Build" section, and implement it yourself.

Accelerant or Substitute: Learning to Code in the Age of AI.

Colin Venancio — Tue, 09 Jun 2026 00:00:00 GMT

The Trap

You're deep in a project and staring at a feature that you have no idea how to build. Claude and ChatGPT are just a click away. You could take the time to actually understand the topic — the fundamentals, the nuances, why it works the way it does. Or you could take the path of least resistance: "Hey Claude, help me implement X feature in this project...". Next thing you know, AI spits out a couple hundred lines of code.

"Seems legit!", you tell yourself. Copy, paste, "It works," move on. Felt productive... but did you really learn anything? If I asked you to reason about that code, could you do it?

If the answer is no, you're not lazy and you're not stupid. You're just using the tool the way it was designed to be used. Something has fundamentally changed about how we access knowledge, and almost nobody is talking about what it's silently doing to us.

The New Interface to Knowledge

Just a few years ago, finding the solution to a problem meant analyzing multiple sources, reading through docs, digging through forums, and genuinely wrestling with the concept. AI has stripped away all of that friction. Now, we have instant conversational access to all the information we want.

The deceiving part is that this smooth, frictionless consumption feels like learning, but it's really just exposure.

Exposure != Learning

The default output of this new frictionless interface is breadth without depth: we feel like we know a little bit of everything, but can't actually articulate any of it. We can touch a hundred topics in an afternoon and retain none of them — because retention was the side effect of the friction that just got deleted.

Real learning happens when we sit with a problem past the point of comfort. On the other side of that annoyance and frustration lies true understanding. But now, nothing about the information-gathering process forces that on us. Instead of scouring the depths of the internet, the answer is one prompt away. The mechanism that developed depth was removed from the equation.

On the flip side: that same friction removal is also the best thing that has ever happened to learning (if we choose to use it that way). The tool raised the ceiling and removed the floor at the same time. We can research concepts deeper and faster than any generation of programmers before us. We can read source code with an expert explaining every line as we go. We can correct a confused mental model within seconds instead of struggling with it for a week. Before AI, that kind of depth took time and effort. Now, it's at our fingertips.

But that's the trap. The floor is gone. Nothing forces us to do the deep work anymore. Depth has become optional.

Accelerant vs. Substitute

The core distinction between AI usage that supports learning, and AI usage that inhibits learning comes down to when in the loop we choose to reach for the tool. Let me explain:

Scenario A: You hit that new feature. You don't understand it. Your first move: "Hey Claude, help me implement this feature..." Code appears, it works, you move on. The tool didn't reinforce your thinking... there was no thinking to reinforce! You completely skipped the step that would have built understanding.

Result: You ship the feature. You still have no clue how it works. The next time you encounter the same topic, you'll be just as lost. You learned nothing.

Scenario B: Same feature, same confusion. But this time, you sit with the problem. You read what you can — and based on that information, you form a hypothesis: "I think it works this way, and X seems like the hard part." You take a swing, hit a wall, and pin down exactly where you're stuck.

Then you reach for the AI, but you're not asking it to build the thing for you, you're asking it to resolve the gaps in your own mental model: "Hey Claude, I'm trying to implement this feature... here's what I understand about it... here's what I don't understand about it... what am I missing here?"

The AI picks apart your understanding, reinforces what's right, corrects what's wrong, and clarifies the fuzzy parts. The answer sticks because it lands on a mental model that you already constructed yourself.

Result: You ship the feature. But this time, you know how it works and why it works. The next time you encounter the same topic, instead of relearning it, you'll recognize it. You'll remember being wrong about it — and that memory holds a lot more cognitive weight than simply being told the right answer.

Notice what's identical in those two scenarios? In both, we utilized AI for help, but the timing of when we called for help changed.

When we're using AI as a tool for learning, we must ask ourselves "Am I using AI to reinforce my thinking, or to outsource it?" There's a fine line between the two: one uses the tool as an accelerant, the other uses it as a substitute.

The Rules I Actually Use

So how do you actually use AI as an accelerant for learning? I'm going to share a few 'rules' that I always follow that keep me in the right mindset:

Earn the Question.

A good rule of thumb: the questions you ask AI should be specific and concrete. This is because the action of forming a good question requires you to have previously internalized the problem well enough to find the exact edge of where your understanding breaks. The vagueness of your question is the measurement of your ignorance.

Here's the test: can you ask a specific question about the topic? Not "how does this work", but "I think this works like X, so why does Y happen?" If you can't get more specific than "I don't get it," you haven't truly wrapped your head around the problem yet.

Make the AI teach, not tell.

By default, AI is a vending machine. Put a question in, an answer drops out. Ask AI to teach you something and it'll default to just... telling you. Now don't get me wrong, this is great for getting unblocked, but it's a terrible way to learn. That's like your professor giving you the answer key to every exam — convenient, not effective.

The fix is to provide the AI with custom instructions that define how it should respond to your requests. By doing this, we can turn our high-tech vending machine into a tutor that actually makes us think.

Instead of dumping the answer on us, we program it to push back: ask us what we already think, make us reason toward the solution, point at where our logic breaks instead of just fixing it, hand us a missing fact when we genuinely can't derive it ourselves, and only hand over the direct answer when we explicitly ask for it.

Here's the prompt I actually use. Steal it:

When I'm trying to learn or understand a concept, act as a Socratic tutor rather than 
answering immediately:
- First ask what I already know or think, and make me reason toward the answer myself. 
  But calibrate — if I clearly already grasp the basics, skip ahead; don't make me 
  re-derive things I know.
- When my reasoning is wrong, tell me it's wrong and point to where it broke — don't 
  just correct it for me.
- Use follow-up questions to push me to the next step instead of completing it for me.
- You can give me a specific fact, term, or piece of syntax I couldn't reasonably derive 
  on my own, but only the minimum needed to unblock my next step, and never the conclusion 
  I'm working toward. Hand me the puzzle piece, not where it goes.
- Escalate when I'm stuck: if I've taken a couple of real swings at the same point without 
  progress, give me a hint that points the way — not the answer. If I'm still stuck after 
  that, or I say "just tell me," give me the direct answer.

This applies when I'm learning. When I'm clearly trying to unblock a task — debugging, 
looking up syntax, shipping something — just answer directly; don't make me reason through it.

When I ask you to review something I wrote to test my understanding, be direct and specific 
about where I'm vague, wrong, or hand-waving — name it rather than smoothing over it.

Copy and paste that prompt into your AI's custom instructions. The exact path depends on the provider you use. As of the time of writing this article:

Claude: Settings -> General -> Instructions for Claude
ChatGPT: Settings -> Personalization -> Custom Instructions
Gemini: Settings & Help -> Personal Context -> Your Instructions for Gemini

Never accept code you couldn't rewrite tomorrow.

First off, I'd like to say that I'm not against coding agents. Agentic coding could very well become the default in a few years. Even when learning, there are times where letting AI generate the code is the right call — sometimes code is the clearest way to express an idea.

Generating code is fine... accepting code you don't understand is the problem — and it's breadth-without-depth in its purest form. The trap is how easy it is: the code works, you tell yourself you get it, you move on. But "it runs" and "I understand it" are two very different claims.

Here's a test to run through before you click "Approve edits" in your coding agent: if someone asked me to explain this code, could I articulate how it works, why it's written the way it is, and point out any associated tradeoffs of the approach?

If the answer's no, you didn't learn anything — you just moved a problem you couldn't solve into a codebase that you can no longer fully explain. That's a skill issue.

The flip side of this is having the judgment to know when to reach for generated code. Boilerplate that you've written a hundred times? Let the AI cook. A new design pattern or API that you've never used? That's probably a good point to slow down and truly understand every line, because that's where the real learning occurs.

Write to find the holes.

If you really want to expose your knowledge gaps on any given topic, write about it. Open a fresh txt file and write out your understanding of it as if you were teaching it to someone who knows nothing about it. This should be straight off the dome — no peeking at Google.

This works extraordinarily well because writing forces ambiguity to the surface. You can't write a clean explanation of something you don't actually understand. The fuzzy parts show up as the sentences you can't finish.

Once you have your brain-dump of an explanation written out, hand it over to AI: "...here's my understanding of X. Pick it apart: where am I wrong, where am I being vague, and what am I missing?" By taking this approach, the AI is not generating your understanding, it's stress-testing the one you've already built.

Full circle: those specific, concrete questions from the first rule? This is where they come from. You write, and the gaps reveal themselves. Each gap is a precise question you've earned the right to ask.

The Discipline

Here's what it comes down to. The tools aren't going anywhere, and they're only going to get better at handing us answers. The way we access information has fundamentally changed — and that has tradeoffs. The increasingly valuable skill is the ability to think deeply and critically — which is the same skill that this new frictionless interface will atrophy without discipline.

The discipline is easy to state and hard to practice: do the thinking before we reach for the tool, not instead of it. Struggle first, then ask. Build the mental model, then let AI correct it — not the other way around. The hard part isn't understanding this principle — it's that the shortcut is one keystroke away every single time, and nothing forces us to skip it. We have to choose it, over and over.

I don't always get this right. Plenty of times the shortcut's right there and I take it, and tell myself I'll understand it later. But the difference between continuous growth and stalling out isn't talent, it's the act of choosing the harder path — even when the easy one is one click away. That's the real work.