DEV Community: Sungwoo Lee

6 Cloudflare Workers Gotchas We Hit in Production

Sungwoo Lee — Sun, 27 Sep 2026 16:10:53 +0000

We run a small content site on Cloudflare Workers, D1, and R2 — no origin server, no VM. It's been cheap and mostly boring, which is what you want from infrastructure. But "mostly" is doing work in that sentence. Here are six things that went wrong quietly enough that a green deploy log told us everything was fine while it wasn't.

None of this is a takedown of the platform. It's the list of assumptions we made that turned out to be wrong, in the order we tripped over them.

1. D1's statement limit doesn't fail loudly if your chunking is wrong

D1 caps a single SQL statement at 100,000 bytes. That's documented, and for short rows you'll never notice. We noticed the first time we tried to write a long article body in one UPDATE.

The obvious fix is to split the content into chunks and send them as separate statements that concatenate onto the column:

for (const chunk of chunks) {
  await db.prepare(
    `UPDATE posts SET content_html = content_html || ? WHERE id = ?`
  ).bind(chunk, id).run();
}

That works — until one chunk in the middle of a batch silently fails to apply for an unrelated reason (a flaky connection, a retried request that landed twice, whatever) and every other statement still returns success. The row is now missing a chunk. The write API told you 200 the whole way through. Nothing about the response shape tells you the final string is short.

The only way we've found to catch this is to re-measure after the fact:

const { results } = await db.prepare(
  `SELECT length(content_html) AS len FROM posts WHERE id = ?`
).bind(id).all();
if (results[0].len !== expectedLength) {
  throw new Error(`content truncated: got ${results[0].len}, expected ${expectedLength}`);
}

length() in SQLite counts characters, not bytes, so compare it against your source string's character count, not its byte size, or a batch of multi-byte text will fail the check for the wrong reason.

2. Something smaller than D1's limit can kill you first

Before we ever got near 100KB, a completely different ceiling showed up: on Windows, passing SQL inline to wrangler d1 execute --command breaks at something close to 8KB, with a plain "command line is too long" error that has nothing to do with D1.

# breaks around ~8KB, nowhere near D1's own limit
wrangler d1 execute my-db --remote --command "UPDATE posts SET content_html = '...' WHERE id = 42"

It's a shell-level limit, not a database one, and it's easy to misdiagnose as a D1 problem because the symptom (a write that refuses to go through) looks identical. The fix is to stop passing SQL on the command line at all:

printf '%s' "$SQL" > patch.sql
wrangler d1 execute my-db --remote --file=patch.sql

The lesson generalizes past Windows: whatever transport you use to get SQL into wrangler, check which layer's limit you're actually hitting before you start shrinking your data to fit a number that isn't the real constraint.

3. Writing that SQL file can quietly rewrite your data

Once we moved to --file, a second problem showed up that's easy to miss because it doesn't produce an error at all: opening a file in plain Windows text mode converts \n to \r\n on write — including inside a quoted string literal that's supposed to be HTML content, not a source-code line you'd want reformatted.

We measured it directly on one patch: a 28,326-character string came back as 28,637 characters after a round trip through a naive file write — one extra byte for every line break the content already had.

# quietly turns every \n inside the string into \r\n
with open("patch.sql", "w") as f:
    f.write(sql)

# doesn't
import io
with io.open("patch.sql", "w", encoding="utf-8", newline="") as f:
    f.write(sql)

The insert still "succeeds." The row still looks plausible if you eyeball it. The only way we catch this now is the same length re-check from gotcha #1, run against the file on disk before it ever reaches wrangler.

4. A token that verifies fine can still be the wrong token

wrangler d1 execute started failing with an authentication error on a token we knew was valid — it had a real expiration date years out and passed a plain token-verify check. The error was real, just misleading: the token existed and was active, it just had never been granted D1 permissions in the first place. It had been issued for a completely different job (DNS and Access rules).

Cloudflare's own permission model explains why this happens: API tokens are scoped per service — a token can hold, say, "Workers Scripts Read" without holding "D1 Write," and there's no single "is this token good" check that covers both. "Valid" and "authorized for this call" are different questions, and only one of them is answered by a token-verify endpoint.

The fix was mechanical once we understood it: keep a separate, narrowly-scoped token specifically for D1, under its own environment variable, instead of reusing one general-purpose token everywhere.

# an API token without D1 permission looks fine right up until this call
export CLOUDFLARE_API_TOKEN="$GENERAL_PURPOSE_TOKEN"
wrangler d1 execute my-db --remote --command "select 1"
# Authentication error [code: 10000]

5. A wall of 404s can mean you're checking the wrong host, not a broken upload

We serve images through R2 behind a Worker, and after a batch upload our verification script reported every single image as a 404 — including ones that had been live and working for months. Before assuming the upload pipeline was broken, we re-checked one already-known-good, already-live image with the exact same request. It also came back 404.

That's the tell: if a control you know is fine fails the same way as the thing you're actually testing, the bug is in the check, not the subject. In our case it was two things stacked on top of each other. First, we were hitting the public-facing custom domain's media path instead of the actual serving Worker's own subdomain, and the routing between the two isn't 1:1. Second, once we fixed the host, we still got failures — because the default user-agent on a plain HTTP client gets blocked by the Worker's own bot protection, independent of whether the file exists.

import urllib.request

req = urllib.request.Request(image_url, headers={
    "User-Agent": "Mozilla/5.0 (verification script)",
    "Referer": "https://my-blog.org/",
})
urllib.request.urlopen(req)

Run the control check first. It's one extra request and it tells you whether you're about to chase a bug that doesn't exist. The tool pages behind this particular pipeline live at my-blog.org/tools, if you want to see what didn't 404.

6. Cross-origin requests throw away your referrer path, not just strip it a little

We wanted to know which article page a newsletter signup came from, and for a while every single row in the database said the same thing: the site's homepage. That's not what was happening — nobody was subscribing exclusively from the homepage.

The frontend Worker and the API Worker sit on different origins, and a same-origin-looking site can still be split across two Worker subdomains under the hood. The browser's default referrer policy (strict-origin-when-cross-origin) only sends the full path when the request stays on the same origin; cross-origin, it sends the origin and nothing else. Every request looked like it came from /, because that's literally what the browser was willing to disclose, not because that's where the click happened.

The fix isn't a header trick — you can't get the path back out of Referer once the browser has decided to withhold it. You have to send the path yourself, explicitly, in the request body:

fetch(apiUrl, {
  method: "POST",
  body: JSON.stringify({
    email,
    source: location.pathname, // don't rely on Referer for this
  }),
});

If your pages Worker and your API Worker are different origins — which is common the moment you put one behind a custom domain and hit the other directly — budget for this before you build any attribution on top of Referer.

None of these are exotic. Every one of them looked, at the moment it happened, like something else was broken — the database, the network, an expired credential, a missing file. What they had in common is that the actual failure was one layer away from where the symptom showed up, and a plain "it returned 200" or "it deployed" told us nothing about that layer.

If you're running D1 and R2 behind Workers, the site these lessons came from is my-blog.org/tools — a small pile of calculator pages that gave us most of this list one incident at a time.

Exit Code 0, Nothing Produced: The Automation Failure I Shipped Five Times

Sungwoo Lee — Thu, 10 Sep 2026 04:28:42 +0000

The scheduler log is a column of green. Started, finished, rc=0, started, finished, rc=0, day after day after day. The job that collects candidates for my syndication queue had been running like that for weeks.

The queue was empty. It had been empty the whole time.

I have now shipped this exact bug five separate times in one project, in five different jobs. Every one went unnoticed for weeks, and every one was eventually caught by a human asking "hang on, when did we last actually get anything out of this?" — never by a monitor, never by an alert, never by a failed run. There was nothing to fail.

The pattern deserves a name because it is invisible by construction: the job succeeds and produces nothing.

Why the exit code can't see it

An exit code answers one question: did the process reach the end without raising? That is a statement about control flow, not about work. A script that iterates over zero items and prints a tidy summary exits 0 with total confidence.

The shapes I've actually hit:

A collector that returns the empty list on failure. except Exception: return [] makes "the search path is broken" and "there was nothing new today" arrive at the caller as the same value. The caller cannot tell them apart, so it picks the cheerful interpretation.
except: continue inside the loop. One bad item is worth skipping. Every item being bad looks identical from outside — the loop completes, the counter is zero, the function returns.
An upstream API that answers 200 with an empty array. No transport error, no status to branch on. Auth silently downgraded, a parameter quietly rejected, a filter that now matches nothing — all of it arrives as a well-formed successful response containing no rows.
Partial harvest. Four of five sources die, the fifth works, the run reports success. This one is the worst, because there is output. Nobody knows what the denominator was supposed to be.

What all four share: nowhere in the system is there a written statement of what this job is supposed to leave behind. Without that statement there is nothing for a machine to check.

The fix: make every job declare its output

I moved the definition of every scheduled job into one JSON file, and required each entry to carry a produces block — a machine-readable claim about what must exist after a healthy run.

{
  "key": "gsc-daily",
  "run_cmd": "scripts/analytics/run_gsc_daily.py",
  "timeout_s": 1800,
  "output_expectation": "conditional",
  "produces": {
    "type": "file_fresh",
    "path": "data/ops/gsc_daily.jsonl",
    "max_age_h": 30,
    "desc": "daily search performance was appended"
  }
}

Then I stopped letting jobs report on themselves. A runner wraps each one, and the runner writes the ledger entry.

Wrapping rather than instrumenting mattered more than I expected. If each script records its own outcome you have to edit five places, and the one you forget is precisely the one that fails quietly. Worse, a script that never starts — bad interpreter path, an import error on line 1, a wrapper that dies before the interpreter is reached — cannot possibly log its own failure. The judgement has to come from outside the process.

Measure the delta, not the total

The runner measures the declared output twice: once before the child process starts, once after it exits.

before = measure(job)
rc, out, err = run_tree(cmd, cwd, timeout_s)
after = measure(job)

if kind == "row_count" and before is not None:
    produced = max(0, int(after) - int(before))
else:
    produced = int(after)   # freshness is a 0/1 state, not a count

The absolute count is a trap. Yesterday's rows are still sitting in the table, so "there are rows" stays true on the day the collector breaks and on every day after. The number that describes this run is the increase.

But the delta is a trap in the other direction, and I walked into that one too. Some jobs upsert: they rewrite one row per day, or refresh a single file in place. Their row count never grows. Judged by delta, a perfectly healthy job reports zero forever, you get an alert every morning, and within a week you have trained yourself to ignore it. So the two kinds are declared separately — cumulative outputs judged by increase, in-place outputs judged by freshness against max_age_h. Collapsing them into one rule produces false alarms, and false alarms are how a monitoring system dies.

Not every zero is a failure

Some jobs are legitimately allowed to produce nothing. My indexing-request job is capped by a daily quota and drains a pending queue; on a day when the queue is empty, zero is the correct answer. So each job also declares output_expectation: every_run means an empty result is a defect, conditional means it may be empty and the thing worth counting is how many consecutive silent days have passed.

The distinction underneath that is the one I'd carry to any scraper or collector:

"We looked and only found things we already have" and "we couldn't look" are different outcomes. Only the second is a failure.

A collector that finds results and discards all of them as duplicates is working correctly. A collector that finds no results at all is not reporting an absence of new material — it is reporting that its search path returned nothing, which for an established source means the path is broken. So the two are counted separately, and only the second returns a non-zero status. Before I made that split, the healthy case and the broken case printed the same line.

Failure is expensive when nothing stops early

Once I could see the failures, a second problem surfaced: broken jobs were burning enormous amounts of wall time on their way to producing nothing.

One collector had its search path blocked. Its response was to try the next seed keyword, hit a 40-second navigation timeout, try the next, hit another 40-second timeout, and continue down the entire seed list. It burned 1,380 seconds and returned 0 candidates. Every one of those timeouts was foreseeable after the third.

fails, FAIL_CAP = 0, 3
for q in seeds:
    try:
        page.goto(url_for(q), timeout=40000)
    except Exception as e:
        fails += 1
        print(f"  [{q}] failed ({fails}/{FAIL_CAP}): {str(e)[:90]}")
        if fails >= FAIL_CAP:
            print("  three consecutive failures - stopping")
            break
        continue
    fails = 0          # any success breaks the streak
    harvest(page)

Two rules, both cheap. A consecutive-failure cap, reset on any success, because a source that refused us three times in a row will refuse the fourth. And a per-job wall-clock ceiling in the job definition, so a job that hangs rather than fails still terminates on schedule instead of still running when tomorrow's copy of itself starts on top of it.

Kill the tree, then verify it died

The wall-clock ceiling introduced its own bug, specific to layered automation.

subprocess.run(timeout=N) kills its direct child. My batch jobs are three generations deep: Python starts a browser driver, the driver starts a browser. Killing the direct child leaves the browser orphaned, holding a profile lock that quietly breaks the next day's run — a silent no-op caused by the very mechanism meant to prevent silent no-ops.

On Windows the job has to be launched into its own process group and killed as a tree:

flags = subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0
proc = subprocess.Popen(cmd, cwd=cwd, stdout=fo, stderr=fe, creationflags=flags)
try:
    proc.wait(timeout=timeout)
except subprocess.TimeoutExpired:
    for _ in range(3):
        subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)],
                       capture_output=True, timeout=20)
        time.sleep(1.5)
        if not is_alive(proc.pid):        # verify, don't assume
            break
    else:
        note_orphan(key, proc.pid, cmd)   # write it down; nobody notices otherwise

The retry loop exists because of the same class of mistake as everything else here. My first version called taskkill once and recorded its return code as the outcome. A child survived anyway. The parent was gone, the lock was released, the ledger said the timeout had been handled cleanly — and a stray process sat there until I went looking for it. "I issued a kill" and "the process is gone" are two different facts, and only the second is worth recording. When the kill genuinely fails, the PID and its command line go into an orphan list so the next run of that job can clean up after its predecessor.

Logs and artifacts are separate evidence

The last thing that broke my trust in logs: I launched two jobs in the background and later found their log file was 0 bytes, while the ledger showed two successful runs with real output counts.

Both records were accurate. The work happened; the log capture didn't, because output was block-buffered and the redirect never flushed. But the lesson stands on its own: a log is a story the process tells about itself. It can be missing, truncated, or buffered away while the work succeeds — and it can be full of confident green while nothing was produced. Those are independent failure modes. Judge the run by its artifacts, and keep the log as evidence for the postmortem rather than as the verdict. That split is one of the running themes in the operational notes I keep on this.

What to ask your own cron jobs

For each scheduled job, can you name in one sentence what file or row it must leave behind? If not, it has no success criterion — only an exit code.
Is that criterion written somewhere a machine reads, or only in your head?
Are you checking a total or a delta — and if a delta, does that job actually append, or does it upsert in place?
Can this job distinguish "found nothing new" from "couldn't look," and does it return a different status for each?
Does every retry loop have a consecutive-failure cap, and every job a wall-clock ceiling?
When the ceiling fires, do you kill the process tree and then verify it is gone?
When was the last time this job produced something? If you have to go and dig to answer that, that is the whole problem.

65 Tool Pages, 12 Pageviews in 30 Days: The Bug Was in the Site Graph

Sungwoo Lee — Tue, 08 Sep 2026 16:55:21 +0000

I shipped 65 calculator pages to a content site over a few months. Last week I finally pulled the analytics for them: 12 pageviews across all 65 pages in 30 days.

Not 12 per page. Twelve total.

Every page returned HTTP 200. Every page was in the sitemap. The search console had them. The keyword demand was real — the Korean search-ad planner reports roughly 898,000 monthly searches for the single term "character counter" and 604,000 for "percentage calculator." Supply existed, demand existed, and the two never met.

This is what I found and what I changed.

First: rule out the boring failures

Before theorizing, I checked the things that are cheap to check.

Are they up? I pulled every tool URL from the sitemap and requested all 65 with cache-busting. 65/65 returned 200. One returned a connection error on the first pass and 200 twice on retry — a transient blip, not a pattern.

Pulling the URL list from the sitemap rather than grepping the source turned out to matter. My first instinct was grep "slug:" tools_calc30.js, which dumped 622 KB into my terminal because that file embeds a large JSON dataset in a string literal. The sitemap is the artifact that search engines actually consume, so it's also the correct inventory to audit against.

Are they indexed? Partially. Impressions were rising — 30/day at the start of the month to 162 six days later, average position moving from 14.3 to 6.6. So crawling wasn't blocked.

Are they slow? Median around 0.9s, served from the edge. No.

So the pages were reachable, crawlable, and improving in impressions. And nobody was reading them.

Then: query the site graph

The thing I hadn't checked was whether anything on my own site linked to them.

SELECT COUNT(*) FROM posts WHERE content_html LIKE '%/tools/%';

Zero. Out of 380 published articles, not one contained a link to a tool page.

The only path from the site root to any tool was a single "Free tools" item in the top navigation. From there, an index page. From there, a tool. So every tool page sat two to three hops from the homepage, reachable only through a nav link that search crawlers weight very lightly and that human readers, deep in an article about something else, never see.

I had built a wing of the building and forgotten to cut a door into the hallway.

Why "it's in the sitemap" wasn't enough

A sitemap tells a crawler a URL exists. Internal links tell it the URL matters, and they tell a human reader it exists at the moment they'd want it.

The impressions data showed the crawler had done its part: it found the pages and started testing them in results. What it hadn't gotten was any signal that these 65 pages were more than a dusty appendix. Meanwhile the humans reading my articles had no in-context path to a calculator at the exact moment a calculation would have been useful.

Two failures, one cause.

The fix

One: link from the homepage directly. The homepage is the strongest page on any small site. I added a section listing 12 tools by name and description, ordered by measured monthly search volume, plus a link to each of the two tool index pages. That takes the crawl distance from three hops to one for the twelve highest-demand tools:

const HOME_TOOL_PATHS = [
  '/tools/char-count', '/tools/percent', '/tools/date-calc', '/tools/salary',
  '/tools/loan', '/tools/age', '/tools/pyeong', '/tools/unemployment',
  '/tools/severance', '/tools/weekly-holiday', '/tools/deposit', '/tools/discount'
];
const homeTools = HOME_TOOL_PATHS
  .map((p) => TOOL_LIST.find((t) => t.path === p))
  .filter(Boolean);

Names and descriptions come from the same array the tool pages use. Writing them twice guarantees one copy goes stale.

Two: make the per-article tool cards context-aware. Articles already rendered a small "related tools" block, but one blog section was falling through to a generic default that offered a basal metabolic rate calculator to people reading about government startup grants. An irrelevant link isn't a neutral link — it's an exit. I mapped that section to the tools its readers would actually want: take-home pay, loan interest, withholding tax, percentage, date difference.

Three: tell the index services. After deploying, I submitted the homepage, both index pages, and the twelve tool URLs through IndexNow (15 accepted), and requested indexing for the highest-value pages in the search console. That console has a small daily quota — I got three URLs through before hitting it, which is worth knowing before you plan a batch of sixty.

What I'd check first next time

The diagnostic that found this took one SQL query, and I ran it months later than I should have. So the check I'm adding to my own list is blunt:

For any new section of a site, count the internal links pointing into it from existing content. If the answer is zero, nothing else about that section matters yet.

Crawl status, page speed, structured data, and title copy are all downstream of that. I spent real time on the downstream things while the number was zero.

The counterpart to this is a rule I already believed and failed to apply: measure the thing you actually care about, not the thing that's easy to measure. "65/65 return 200" felt like a green light. It was answering a question nobody was asking.

I'll post the follow-up numbers once there's enough data to say whether the fix moved anything. If you want to see the pages themselves, they're at my-blog.org/tools — mostly Korean-language calculators, but the take-home pay one is a reasonable example of the shape.

65 Calculators, One Cloudflare Worker, No Build Step

Sungwoo Lee — Tue, 08 Sep 2026 16:54:45 +0000

I run a small content site that also hosts 65 calculator pages — salary after tax, loan interest, character count, percentage, a grade calculator, and 43 math/exam-prep tools. All of them live in a single Cloudflare Worker. There is no framework, no bundler, no client-side JS payload beyond the few hundred bytes each page needs to do its own arithmetic.

This post is about why that setup is a good fit for this particular problem, and where it stops being one.

The shape of the problem

A calculator page is unusual among web pages: the interesting part is tiny and the boring part is everything else.

The interesting part is a pure function. Given a salary, a number of dependents, and a non-taxable allowance, return six deduction amounts. That's maybe 40 lines. The boring part — page shell, navigation, meta tags, structured data, FAQ markup, related-tool cards, the privacy note explaining that nothing is sent to a server — is the same on all 65 pages and dwarfs the calculation.

So the architecture question isn't "how do I build a calculator." It's "how do I stamp out 65 near-identical documents where only a small slot differs."

What the Worker actually does

Every request hits one Worker. It matches the path, looks the tool up in a flat array, and returns a string.

const TOOL_LIST = [
  { path: '/tools/char-count', name: 'Character counter',
    desc: 'Counts with and without spaces, bytes, manuscript pages', g: 'everyday' },
  { path: '/tools/salary', name: 'Take-home pay calculator',
    desc: 'Monthly net after insurance and income tax', g: 'work' },
  // ...
];

That array is the single source of truth. The tools index page, the nav, the related-tool cards on article pages, and the sitemap all read from it. When I added the take-home pay calculator, I added one row and it appeared in four places without any of them being edited.

The page-specific script is stored as an array of source lines and joined at render time:

const SAL_SCRIPT = [
  "const n = (id) => Number(document.getElementById(id).value || 0);",
  "function calc() { /* ... */ }",
  // ...
].join(String.fromCharCode(10));

The String.fromCharCode(10) looks silly next to '\n'. It's there because this source string travels through several layers of tooling, and a literal backslash-n has been folded on me more than once. Using the char code makes the newline immune to whatever escapes the string on its way through.

Why the calculation runs in the browser

Every one of these tools computes client-side. Nothing about the input is transmitted.

Partly that's a privacy claim I want to be able to make honestly: people paste cover letters into a character counter, and I would rather not have that text touch my logs even accidentally. Partly it's just cheaper — a Worker invocation that returns a static string and never awaits anything is about as cheap as a request gets.

The tradeoff is that the logic ships to the client, so it's readable and copyable. For a tax table encoding that's a wash; the numbers are published by the tax authority anyway.

The one place this actually got hard

The income tax portion isn't a formula. It's a lookup table: 646 income brackets × 11 dependent counts, published as a spreadsheet.

Shipping that as JSON was 400 KB. Instead I encoded it as a run-length-ish delta string and unpacked it in about 15 lines at page load. The encoded module is 31 KB. The unpack function is small enough to read in one sitting, which mattered more to me than squeezing the last few KB, because the failure mode of a clever encoding is silently wrong money.

I verify it by running the exact page script — pulled out of the source file at test time, not a copy — against known values:

const src = readFileSync('tools_pay.js', 'utf-8');
const m = src.match(/const SAL_SCRIPT = \[([\s\S]*?)\]\.join\(/);
const script = new Function('return [' + m[1] + '].join(String.fromCharCode(10));')();

Pulling the literal out of the real file rather than importing a copy is the whole point. A copy drifts, and then your tests pass against a version nobody ships.

Where this approach stops working

Three honest limits:

No component reuse across pages beyond string concatenation. When two tools want the same input widget with slightly different labels, you write a function that returns a string with parameters. That's fine at 65 pages. I would not want to find out where it stops being fine.

No client-side routing, and I don't want any. Each tool is a separate document with its own title, description, and structured data. That's deliberate — these pages exist to be found by search, and a single-page app would collapse 65 search targets into one.

Debugging inline script is worse than debugging a module. Source maps don't help you when the source is a joined array. In practice I develop the logic as a normal file and only move it into the array form when it settles, which is a smell I've made peace with.

What I'd tell someone starting this

If your pages are mostly identical shells around a small pure function, and if being individually indexable matters more than sharing state between pages, a single Worker plus a flat config array will take you further than it sounds like it should. The whole surface is 65 URLs, and the deploy is one command.

The part that actually determined whether anyone found these pages turned out to have nothing to do with any of this — it was internal linking, and I got it badly wrong for months. That's a separate post.

The full set is at my-blog.org/tools if you want to poke at the output. Most of it is in Korean, but view-source works in every language.

Official sources

MDN Web Docs — web standards

Why Growth Curves Bend: Exponential vs. Logistic, With Code

Sungwoo Lee — Sun, 23 Aug 2026 07:36:46 +0000

In early 2020 a lot of people learned the phrase "doubling every three days." A month later the same commentators were saying "growth is slowing." The math didn't change. What changed is that the quantity being measured ran into a ceiling — and every unbounded growth curve you'll ever plot a metric against does the same thing, whether it's infections, DAU, or a tweet's retweet count.

This post walks through why, with formulas you can verify on a calculator and a script short enough to paste into a REPL.

Exponential growth is a multiplication rule, not a speed

The discrete form is:

y = a * b**t

a is the starting value, b is the growth factor per period, t is the number of periods. If b = 2, the quantity doubles every period. The continuous form uses e:

y = a * e**(r*t)

where r is the continuous growth rate and b = e**r. Both describe the same property: the rate of change is proportional to the current size. That's the entire definition — nothing in it says "fast." A process growing at r = 0.001 per year is exponential in structure but you'd never notice it happening. Media shorthand for "exponential" as "extremely fast" is a category error; exponential means "multiplicative," full stop.

Doubling time, computed, not looked up

Doubling time is how many periods it takes for y to hit 2a. Solve a * e**(r*t) = 2a for t and you get:

import math

def doubling_time(r):
    return math.log(2) / r

for r in [0.01, 0.05, 0.10, 0.25, 0.50, 1.00]:
    print(f"r={r:.2f} -> {doubling_time(r):.2f} periods to double")

Running that gives:

Growth rate (r)	Doubling time
1%	69.31 periods
5%	13.86 periods
10%	6.93 periods
25%	2.77 periods
50%	1.39 periods
100%	0.69 periods

The "Rule of 70" shortcut (divide 70 by the percentage rate) is just ln(2) ≈ 0.693 ≈ 0.70 rounded for mental math — at 7% growth, 70/7 = 10 periods, which matches ln(2)/0.07 = 9.9. Nothing mystical, just a rounding convenience.

Why the curve has to bend

The exponential model has a hidden assumption: unlimited room to grow. An infected person always finds a susceptible one, a shared post always finds a new viewer. That assumption is false in every bounded system, which is every real system. Once you add a ceiling — call it K, the carrying capacity — the growth rate has to fall as you approach it. That's the logistic model:

def logistic(n0, r, k, t):
    return k / (1 + ((k - n0) / n0) * math.exp(-r * t))

dN/dt = r * N * (1 - N/K) is the differential-equation form. The (1 - N/K) term is a brake: near zero it's close to 1 (so growth looks purely exponential), and as N approaches K it drops toward 0 (so growth stops). This is exactly why early-stage growth of almost anything — a pandemic, a viral post, a new product — looks exponential: locally, before N is a meaningful fraction of K, the brake term is doing nothing yet.

Watching the two models diverge

Same starting conditions, run both models out over 70 periods:

n0, k, r = 100, 1_000_000, 0.3

def exponential(a, r, t):
    return a * math.exp(r * t)

for day in [0, 10, 20, 30, 40, 50, 60, 70]:
    e = exponential(n0, r, day)
    l = logistic(n0, r, k, day)
    print(f"day {day:2d}: exponential={e:,.0f}  logistic={l:,.0f}")

By day 30 the two curves are still close — the exponential model hasn't broken anything yet. By day 70, the exponential model predicts roughly 1.3 * 10**11 — about 130,000 times the entire population you defined as K = 1,000,000. The logistic model, run with the identical r, is sitting at roughly 999,992: essentially saturated. Nothing about the underlying process changed between the two models except the brake term. The exponential model isn't wrong because the math is bad; it's wrong because it was never told there's a ceiling.

You can solve for exactly when the curve bends — the inflection point, where the growth rate peaks — by setting N = K/2 and solving for t:

t* = ln((K - N0) / N0) / r

For the numbers above (N0 = 100, K = 1,000,000, r = 0.3), that's ln(9999) / 0.3 ≈ 30.7 days. Before that day, each new period's absolute growth is still accelerating. After it, growth keeps happening but the rate of growth is falling — even though the raw numbers can still look large for a while.

Exponential vs. logistic, side by side

Property	Exponential	Logistic
Formula	`y = a·e^(rt)`	`dN/dt = rN(1 − N/K)`
Growth rate	Constant `r`	Falls as `N → K`
Long-run shape	Unbounded (J-curve)	Saturates at `K` (S-curve)
Inflection point	None — always accelerating	At `N = K/2`
Where it's a good model	Early phase only	Any bounded process, full lifecycle

Why this matters for anything you're tracking

If you've ever fit a trendline to a metric — signups, API calls, weekly active users — and extrapolated it forward, you did the same thing the early-2020 commentators did with case counts. The fit isn't wrong on the data you have; it's wrong about what the data will keep doing, because it silently assumes there's no K. Two fixes: either fit a logistic curve directly once you have enough data to estimate an inflection, or treat any exponential fit as valid only for forecasting a few periods past your last data point — the part of the S-curve where the brake term genuinely hasn't kicked in yet.

I worked through the full derivation — plus the R₀/epidemiology framing and the technology-adoption S-curve examples — over at the original post, if you want the longer version with more worked tables.

Related reading — Rice-to-Water Ratio: Why You Can't Just Double It

How to Build a Custom GPT That Doesn't Answer Generically

Sungwoo Lee — Sun, 23 Aug 2026 06:15:05 +0000

Building a custom GPT takes about ten minutes. Building one that behaves differently from vanilla ChatGPT takes longer, and most first attempts fail in exactly the same place: the Instructions field.

The builder UI makes every field look equally important. It isn't. A custom GPT has four components, and one of them carries almost all of the behavioral weight.

The Four Components, Ranked by What They Actually Do

Component	What it does	Behavioral impact
Name & Description	Public identity and scope	Primes vocabulary and register
Instructions	Persistent system prompt, read before every message	Highest — role, task, constraints, format
Knowledge	Uploaded files retrieved during conversation	High if domain-specific, near zero if generic
Conversation Starters	Four suggested prompts on the opening screen	Onboarding only
Actions	API connections to external services	Powerful, but skip it for v1

If you have a fixed amount of time, spend most of it on Instructions. Everything else compounds from there — a sharp Name helps, but it cannot rescue a vague system prompt.

Why Most Instructions Fail

The typical first draft looks like this:

You are a helpful marketing assistant. Give good advice about marketing.

Every word in that prompt is already true of the base model. It adds no constraints, so it changes no behavior. You get generic output because you asked for generic output.

A prompt that actually changes behavior has four elements. Role, Context, Task, Format:

(Role) You are a senior B2B SaaS marketing strategist who has taken
companies from $500K to $5M ARR.

(Context) Users are founders at pre-revenue or Series A stage, building
outbound and content systems with small teams. They know GTM basics and
need executional clarity, not definitions.

(Task) When asked for positioning or messaging, generate three distinct
angles with a two-sentence rationale each. When asked for content,
prioritize pipeline-generating formats: case studies, comparison pages,
sales sequences. Do not give generic advice. Be specific and opinionated.

(Format) Use clear headers. Lead with the most important point. Flag any
assumption you are making about the user's context.

The difference is not length. It is that every clause narrows the space of acceptable answers. Do not give generic advice is weak on its own; it works here because the surrounding clauses define what non-generic looks like for this GPT.

The Negative Constraint Most Builders Forget

Write down what the GPT must never do before you write what it should do. This one line prevents most of the embarrassing failures:

If a request falls outside <domain>, say so in one sentence and stop.
Do not attempt an answer from general knowledge.

Without it, a specialized GPT quietly degrades into the base model the moment a user drifts off-topic — and the user has no way to tell that happened.

Knowledge Files: One at a Time

Uploading ten documents at once and hoping retrieval works is the second most common failure. Add one file, open Preview, and ask a question that can only be answered from that file. If the answer doesn't cite it, the file is not being retrieved and adding nine more won't help.

Generic files hurt more than they help. A PDF of publicly available material gives the model nothing it doesn't already have, while adding retrieval noise. Domain-specific material — your pricing sheet, your style guide, your internal runbook — is where Knowledge earns its place.

An Eight-Step Build That Works

Define the job on paper. Who it is for, the one thing it does better than vanilla ChatGPT, and what it must never do.
Open the builder — Explore GPTs → Create → switch to the Configure tab. The conversational Create tab is faster but gives you less control.
Name and Description. Apply the specificity test: can a reader predict the exact output without guessing? "B2B Marketing Advisor for SaaS Founders" passes. "Marketing Assistant" does not.
Write Instructions using Role + Context + Task + Format. This is the step worth iterating on.
Upload Knowledge files one at a time, verifying retrieval in Preview after each.
Write four Conversation Starters. Each should produce something useful immediately, with no follow-up setup.
Test with edge cases. Ask one off-topic question and one thing the Instructions explicitly prohibit. If it answers either, the constraints aren't holding.
Set publication level and save. Default to "Only me" for v1. You can widen it later; you cannot un-share a bad first impression.

The Test That Tells You It Worked

Open a normal ChatGPT window and your custom GPT side by side. Send the same prompt to both.

If the answers are similar, your Instructions aren't doing anything yet — go back to step 4. If the custom GPT is noticeably narrower, more opinionated, or formatted differently, the configuration is holding.

That comparison takes thirty seconds and is the only reliable signal. Everything else is guesswork about a system prompt you can't see the effects of.

I wrote a longer version with copy-ready Instruction templates and the full component breakdown here: How to Build a Custom GPT: Step-by-Step Guide.

Official sources

OpenAI Documentation — official docs
arXiv — preprints

Which AI Model Should You Use? A Routing Guide for Developers

Sungwoo Lee — Mon, 17 Aug 2026 17:20:01 +0000

You've got ChatGPT open in one tab, Claude in another, maybe Gemini in a third. And you still spend the first thirty seconds of every session wondering which one to actually use for the task in front of you.

That hesitation is the real problem, not the tools themselves. Each major model has a domain where it genuinely outperforms the others. The skill isn't picking a favorite — it's routing the right task to the right tool.

Stop Asking "Which AI Is Best"

The question has no useful answer because it conflates several fundamentally different design priorities. ChatGPT's reasoning-tier models (o-series) are optimized for breadth and hard logic. Claude is optimized for long-context fidelity and careful writing. Gemini is built around Google's data stack and native multimodal input. Perplexity is a real-time search layer sitting on top of models rather than a general-purpose assistant. They aren't competing in the same lane.

The better question: what am I trying to do, and which tool is architecturally suited for it? Think routing, not ranking — the same way a skilled team doesn't debate "email or Slack" in the abstract, they use the right channel for the message.

Four task categories cover most of the routing decision:

Writing and editing — prose quality, tone fidelity, long-form coherence
Coding and technical work — accuracy, debug quality, explanation clarity
Research and factual queries — recency, citations, hallucination rate
Reasoning and analysis — multi-step logic, structured thinking

What Each Model Actually Does Best

A note before the list: specific model names go stale within months, so this section describes families and tiers, not version numbers. The routing logic is the durable part — check each provider's current lineup for which model sits in which tier today.

ChatGPT (flagship tier + dedicated reasoning tier)
Strengths: breadth, tool integrations (image generation, code interpreter, browsing), the strongest dedicated reasoning models for hard logic and math, mature voice mode, a large custom-GPT ecosystem. Weaknesses: tends toward verbosity, less sharp on nuanced writing tone, reasoning-tier models cost more to run at volume. Best for: reasoning-heavy tasks, image generation, math and science problem-solving, or when you want one integrated tool ecosystem instead of several apps.

Claude (Sonnet / Opus)
Strengths: prose quality and tone fidelity that consistently edges out the alternatives, strong instruction-following, very capable on long documents given its large context window, lower "eager-to-please" drift on writing tasks. Weaknesses: image generation isn't built in, and the default tool ecosystem is smaller than ChatGPT's. Best for: long-form writing, editing, summarizing large documents, and any task where following instructions precisely matters more than raw creativity.

Gemini (Pro / Flash tiers)
Strengths: native multimodal input (image, video, audio), tight Google Workspace integration, a large context window, strong on tasks involving visual data. Weaknesses: writing tone less consistent than Claude. On the hardest reasoning problems the ranking between providers moves with every release — treat any published leaderboard as a snapshot and test on your own task. Best for: work inside Docs/Sheets/Gmail, analyzing images or video, and processing long documents when Google's tools are already part of your workflow.

Perplexity
Strengths: real-time web search with cited sources, the fastest path to current information, Pro Search decomposes complex queries into sub-searches. Weaknesses: shallow analytical depth, brief outputs, not built for long-form writing or multi-step reasoning. Best for: current events, fact-checking against live sources, and fast bibliography building. See the direct ChatGPT vs Perplexity comparison if search is your main use case.

A Quick Decision Flowchart

Need info from the last 30 days?          → YES: Perplexity
                                            → NO: continue
Primarily a writing or editing task?       → YES: Claude first
                                            → NO: continue
Coding, math, or logic?                    → YES: ChatGPT (reasoning model for hard problems) or Claude
                                            → NO: continue
Need image generation?                     → YES: ChatGPT or Gemini
                                            → NO: continue
Inside Google Workspace?                   → YES: Gemini
                                            → NO: default to ChatGPT or Claude by writing-quality need

For coding specifically, the calculus differs enough between "generate new code" and "debug this stack trace" that it's worth a dedicated comparison — see best AI coding assistants.

Two Copy-Ready Prompts You Can Use Today

1. Long-form report draft (Claude)

(Role) You are a senior analyst with expertise in [industry].
(Context) I'm writing a [word count] report on [topic] for [audience].
The goal is to inform a decision about [specific decision].
(Task) Write a structured first draft: an executive summary (3-4
sentences), 3-4 main sections with headers, and a conclusion with a
clear recommendation.
(Format) Professional prose. Bullet points only for lists of 4+ items.
Flag any claim that needs external verification.

2. Code debugging (ChatGPT or Claude)

(Role) You are a senior [language] developer.
(Context) This function is supposed to [describe intent]. It returns
[wrong output] when [input condition].
(Task) Identify the bug, explain why it occurs, and provide the
corrected code.
(Format) One-sentence diagnosis first, then the corrected code block,
then a brief explanation of what was wrong. List any additional edge
cases separately.

Both follow the same structure: role, context, task, format. That structure is what makes a prompt portable between models — you can hand the same skeleton to Claude, ChatGPT, or Gemini and get a comparably well-scoped answer back.

FAQ

Which AI model is best overall?
No single model leads across every task. Reasoning-tier ChatGPT models are strongest for hard math and logic, Claude leads on writing quality and long-context fidelity, Perplexity is the best tool for current information. "Best for what" is the only version of the question with a useful answer.

Is Claude better than ChatGPT for writing?
For most writing tasks — essays, reports, editing — Claude tends to produce noticeably better prose and follows tone instructions more precisely, without the verbose, hedge-heavy default style ChatGPT can fall into. For open-ended creative brainstorming, the gap narrows.

Which is best for coding?
Claude and ChatGPT are closely matched on most coding tasks. Claude tends to edge ahead on explaining code clearly and following precise specs. ChatGPT's sandboxed code interpreter for data analysis has no direct equivalent in Claude's standard interface — that's a real differentiator if your coding work involves running and inspecting data, not just writing it.

Can I just use one AI for everything?
You can, but you'll leave quality on the table in specific spots — using a general chat model for writing tends to produce verbose prose, and using a model without live search for current events risks stale or hallucinated facts. A two-tool setup, one model for writing and analysis plus a search-native tool for current information, covers most professional work well.

Which AI gives the most accurate, up-to-date information?
Perplexity, by design — it retrieves live web results and cites sources. Among the non-search models, the accuracy gap on well-established topics is small; the real risk across all of them is hallucination on specific statistics or citations, so verify anything load-bearing regardless of which model produced it.

Originally published at my-blog.org.

Official sources

OpenAI Documentation — official docs
arXiv — preprints

Best AI Agents in 2026: What They Do and How to Pick One

Sungwoo Lee — Mon, 17 Aug 2026 17:19:25 +0000

"AI agent" went from conference-talk abstraction to mainstream product feature faster than almost any other term in the field. ChatGPT has agents. Claude has agents. Your project management tool probably has one now too. But the word covers so much — from a simple tool-calling wrapper to a fully autonomous coding system running in a loop for hours — that it's nearly meaningless without qualification.

A working definition that holds up: an AI agent takes a goal, breaks it into steps, executes those steps using tools (search, code execution, file access, API calls), and iterates until the goal is met. The emphasis is on the loop — an agent doesn't just respond, it acts and corrects. That loop is the capability gap separating agents from conventional chatbots.

The space now spans purpose-built coding agents, research agents, workflow automation agents, general-purpose operator-style agents, and multi-agent frameworks where specialists hand off work to each other. Pricing and benchmarks here change fast enough that hard numbers go stale quickly — so this guide sticks to what's stable: architecture, autonomy level, and fit.

The Loop That Defines an Agent

A chatbot processes input and generates output in one pass. An agent runs:

Observe — receive the goal and current state
Plan — determine the next action
Act — execute it through a tool: run code, search, write a file, call an API
Observe — check the result
Repeat until the goal is met or it's stopped

Agents vary a lot in how autonomous this loop is. Some require human approval before each step ("human-in-the-loop"); others run unattended for long stretches. Autonomy level is one of the most important dimensions when evaluating an agent for a use case — more autonomy means more capability, but also more risk of errors compounding uncorrected.

Five Categories Worth Knowing

Coding agents write, run, debug, and iterate on code in a real execution environment — they run it and fix what's broken, not just suggest it. Examples: Claude Code, Devin, SWE-agent, OpenHands. Autonomy runs medium to high; most gate high-risk actions like deleting files or pushing to main behind approval. Best fit: teams with repetitive implementation work, bug fixing, and test generation.

Research and information agents search, synthesize, and produce structured output from multiple sources, reasoning across them rather than just retrieving them. Examples: Perplexity Deep Research, ChatGPT Deep Research, Gemini Deep Research. Autonomy is low to medium — search, read, synthesize, then human review. Best fit: literature reviews, competitive analysis, due diligence.

Workflow automation agents connect to business tools — Slack, Gmail, Notion, Salesforce — and automate multi-step workflows triggered by events. Examples: Zapier AI, n8n with AI nodes, Copilot Studio agents. High autonomy within a defined spec. Best fit: repetitive processes touching multiple apps — lead routing, meeting follow-ups, data pipeline maintenance.

General-purpose operator-style agents sit on top of frontier models and handle a wide range of tasks with a flexible tool set — generalists, not specialists. Examples: ChatGPT with tools, Claude with MCP, Gemini with Workspace extensions. Autonomy is whatever you configure, usually gated on consequential actions.

Multi-agent orchestration frameworks run at the infrastructure level: a planner agent breaks a large task into subtasks and delegates to specialists — a coder, a researcher, a writer. Examples: LangGraph, AutoGen, CrewAI. Very high autonomy in principle, but reliability drops as complexity climbs. Best fit: teams building AI products where one model's context can't cover the whole task.

What the Main Tools Are Actually Good At

Claude Code is a terminal-native coding agent that reads files, writes code, runs shell commands, and observes results in a loop. Its edge is reasoning quality on non-obvious problems — debugging race conditions, rearchitecting a module, building a feature from a description — where genuine reasoning beats pattern-matching. It extends tool access through MCP, worth understanding if you're configuring any agent's tool layer. Trade-off: CLI-only, no GUI.

ChatGPT's agent capabilities come in two forms — tool-augmented chat (search, code interpreter, file access) and Operator mode for UI navigation. Its Deep Research mode produces strong long-form cited reports. Weak spot: no persistent memory across sessions by default, and less reliable tool-calling on complex multi-step tasks than purpose-built coding agents.

Perplexity Deep Research is a read-only synthesis agent — it searches many sources, reads them, and produces a cited report. It beats manual search-and-read for competitive analysis or fact-gathering, but doesn't write code, execute workflows, or act beyond producing the report.

Devin was the first widely publicized fully autonomous software engineering agent, handling defined implementation tasks — features from specs, bug fixes, tests — with a GUI showing its terminal, browser, and editor live. Honest caveat: independent evaluations on open-ended tasks show more variable results than early claims suggested. It performs best on well-scoped tasks with clear acceptance criteria.

Zapier AI lets non-technical users build agents that watch triggers (new emails, form submissions, Slack messages) and run workflows across thousands of connected apps, set up conversationally. Its strength is breadth of integrations; its limitation is logic that stays rigid once configured, rather than reasoning through ambiguity.

OpenHands and SWE-agent are the open-source options for teams avoiding SaaS pricing or sending code to a third-party API — at the cost of setup complexity and bringing your own model API.

A Routing Framework for Choosing

Task type — coding, research, workflow automation, or general-purpose?
Autonomy tolerance — how comfortable are you with unapproved actions?
Technical complexity — reasoning about a complex system, or a well-defined process?
Interface preference — CLI, browser, or no-code?
Cost tolerance — free/self-hosted through paid consumer and enterprise tiers.

For coding agents specifically, see the detailed coding assistant comparison; for the models powering these agents, see which AI model to use.

A copy-ready template for prompting any agent:

GOAL: [observable definition of "done"]
CONSTRAINTS: [what the agent should NOT do]
RESOURCES: [tools and access it has]
ON FAILURE: [what to do if a step fails — retry, flag, or stop]

What Agents Still Can't Do

Error compounding. The longer an agent runs autonomously, the more a small early error compounds — a coding agent that misreads a spec on step 2 may have written hundreds of wrong lines by step 20.

Tool hallucination. Agents can call the wrong tool, misread output, or invent a result when a tool fails silently — more consequential than a chatbot hallucinating text.

Context limits. Even with large context windows, long agentic sessions degrade — agents repeat earlier steps or lose track of prior decisions as the window fills.

No inherent judgment about consequences. An agent doesn't know deleting a production database differs from deleting a test file unless told explicitly. Human oversight stays essential for anything with real external effects.

For single-turn tasks — answer a question, draft a paragraph — a chatbot is cheaper, faster, and more predictable. Reserve agents for tasks that genuinely need multiple steps, tool use, or iteration.

FAQ

What's the core difference between an agent and a chatbot?
A chatbot responds to a prompt in a single pass. An agent runs a loop — observe, plan, act, repeat — using tools until the goal is reached. Agents do things, not just describe them.

Which agent is best for coding tasks?
Claude Code and Devin are the strongest purpose-built options. Claude Code tends to win on complex, multi-file reasoning; Devin offers a more polished GUI and no terminal requirement. For lighter in-IDE help, a coding assistant fits better than a full agent.

Are AI agents safe for business workflows?
With guardrails, yes. Best practice is human-in-the-loop for consequential actions — the agent proposes, you approve. Reserve full autonomy for low-risk, reversible tasks, and treat agent output like work from a capable but fallible junior teammate.

Originally published at my-blog.org.

Official sources

OpenAI Documentation — official docs
Anthropic Documentation — official docs

AI Agents vs Chatbots: What's the Actual Difference

Sungwoo Lee — Mon, 17 Aug 2026 17:18:49 +0000

Everyone's talking about AI agents right now. But most people using ChatGPT day to day are actually talking to a chatbot, and the difference is more than semantic. Conflating the two leads to mis-set expectations: you're disappointed when your "agent" can't follow through on a plan, or confused when an agent does things you didn't explicitly ask for.

The distinction is practical enough to matter for how you build with either one.

The Core Difference in One Sentence

A chatbot takes your input and returns a response. An AI agent takes your goal and figures out how to achieve it.

Four variables separate them:

Autonomy — who decides the next step? Chatbot: you, every time. Agent: it decides.
Tool use — can it call APIs, run code, read/write files? Chatbot: rarely, and only on request. Agent: this is central to how it works.
Multi-step execution — does it run a plan across several steps without a prompt at each one? Chatbot: no. Agent: yes.
Memory — does it carry state across steps and sessions? Chatbot: conversation window only. Agent: can use persistent external memory.

What a Chatbot Actually Is

A chatbot is built around conversational exchange: you send a message, it sends a reply. That's the whole unit of interaction. Modern chatbots (ChatGPT, Claude, Gemini in plain conversational mode) are extraordinarily capable within that unit — they write, analyze, reason, translate, and summarize well. But the design stays reactive: nothing happens unless you send the next message.

Key properties:

Stateless or limited context (this conversation, not across sessions, unless the product bolts on memory)
No autonomous tool use — you ask, it acts, once
One input, one output, repeat
Can't book, send, modify, or execute anything on your behalf without you prompting each step

The chatbot isn't "dumb" — the underlying model is often the same one powering an agent. The constraint is the interaction design, not the model's capability.

What an AI Agent Actually Is

An agent receives a goal and autonomously works out the sequence of steps to reach it — calling tools along the way, checking progress, adjusting based on what it finds. Four things distinguish it from a chatbot:

Goal-directed behavior. Instead of responding to one prompt, it works toward an end state. "Summarize last month's sales and email the report to the team" is a goal it decomposes and executes in order.
Tool use. Real external systems — web search, code execution, databases, calendar, email, CRM. Tools are what let an agent act, not just describe.
Multi-step planning and execution. It runs a loop — perceive, plan, act, check, repeat — until the goal is met or a stopping condition hits, without needing a human prompt between steps.
Memory and state management. It can track what it's done, what it found, and what's left, often across sessions via external storage.

The Spectrum, Not a Binary

Pure chatbot — single turn, no tools, no memory. An FAQ bot.
Conversational assistant — multi-turn context, some on-request tools (image generation, web search when asked), but you drive every step. ChatGPT in a normal chat.
Light agent — chains two to five steps, limited tool use, still surfaces output to you rather than acting fully in the world. A lot of "Copilot" features live here.
Full agent — multi-step autonomous execution with real tool calls, human checkpoints before irreversible actions, persistent memory.

Most people's day-to-day "agent" experience in 2026 sits in the light-to-medium range. Fully autonomous agents running unattended in production exist but need real deployment guardrails.

Same Request, Two Different Outcomes

Request: "Research the top 3 AI coding assistants, compare pricing, and send me a summary by email."

Chatbot: Writes a description of three tools with pricing. Stops. Doesn't send anything — you copy, paste, and send it yourself.

Agent: Searches the web for current pricing, opens each pricing page, extracts the data, formats a comparison, drafts an email, and sends it — reporting completion when done (possibly pausing to confirm the recipient first).

Neither output is "bad." The chatbot's prose might be excellent. But only the agent actually finished the task end to end.

When to Reach for Which

Use a chatbot when:

You need one well-formed output — a draft, an analysis, an explanation
You want to stay in control of every step
The task doesn't require real-world actions
You're iterating and want to steer each turn

Use an agent when:

The task has multiple defined steps that would be tedious to prompt one by one
You need real external actions — search, book, send, update
There's a clear, verifiable end state ("report sent," "ticket closed")
You're comfortable delegating with checkpoints

Directing an Agent Is a Different Skill Than Prompting a Chatbot

When prompting a chatbot, you guide each step explicitly. When directing an agent, you define the goal, the constraints, and the checkpoints up front. A reusable four-element format:

(Role) What the agent has access to and can do
(Context) Background, constraints, what "done" looks like
(Task) The end state you want — not just the first step
(Format) How it should check in: confirm before irreversible actions, report at milestones

Writing a goal this way front-loads the thinking an agent needs instead of trying to catch problems mid-run.

FAQ

Can ChatGPT be used as an AI agent?
Yes, in its tool-augmented modes — browsing, code execution, and Operator-style UI navigation move it toward agent behavior. Plain conversational ChatGPT without those tools is still a chatbot by this definition.

What tools do AI agents typically use?
Web search, code interpreters, file read/write, and APIs for calendar, email, CRM, and payment systems are the common set. The tools available are what actually give an agent the ability to act, not just respond.

Are AI agents riskier to use than chatbots?
Yes, proportionally to autonomy. A chatbot's worst-case output is bad text you can ignore. An agent's worst-case output is an irreversible action taken on your behalf. That's why human-in-the-loop checkpoints before consequential actions matter more as autonomy increases.

How do I know if I need a chatbot or an agent for a given task?
If the task ends with you reading and using an output yourself, a chatbot is enough and will be faster and more predictable. If the task ends with something actually happening in another system — an email sent, a record updated — you need an agent with the right tool connected.

Originally published at my-blog.org.

Official sources

OpenAI Documentation — official docs
arXiv — preprints

How to Build an AI Agent Without Writing Code

Sungwoo Lee — Mon, 17 Aug 2026 17:18:13 +0000

If you've spent much time in ChatGPT, you've hit the wall: type a prompt, get an answer, type another prompt, get another answer. At some point you think, "can't this just do the whole thing?" That itch is what makes people want to build an AI agent.

An AI agent is a system that pursues a goal across multiple steps, calls tools, and makes decisions without waiting for a human prompt at each step. The useful news for non-developers: in 2026, building a functional no-code agent is genuinely accessible. Platforms like n8n, Zapier, Make, and Lindy let you wire an LLM to real tools without a line of Python. The less convenient news: "no-code" doesn't mean "no thinking." The actual bottleneck in almost every agent build isn't the platform — it's the quality of the goal definition, the tool selection, and the testing loop.

The Four Components Every No-Code Agent Needs

Building a no-code agent means connecting four things. You don't write the model — you configure what it can access, what it should do, and what success looks like.

1. Goal statement (system prompt). The instruction set that tells the LLM what it's trying to accomplish, what constraints to respect, and what "done" looks like. This is the highest-leverage piece — a vague system prompt produces an unpredictable agent.

2. LLM brain. The model doing the reasoning — GPT-4o, Claude, Gemini, or a local model via Ollama. Most platforms let you pick from several. The model determines reasoning quality; the platform determines which tools it can reach.

3. Tool layer. What the agent can actually do: send email, read a spreadsheet, query a database, search the web, post to Slack, call an API. Each tool is a discrete capability the agent can invoke inside its reasoning loop.

4. Memory / context layer. How the agent retains information across steps or sessions — from "pass the last five turns" to "query a vector database for prior interactions."

You don't need all four maxed out. Most effective first agents use a precise system prompt, two or three tools, and stateless context — start there, and add complexity only when you hit a real limit.

Step 1: Define the Goal Before You Touch a Tool

The most common mistake non-developers make is starting with the tool — opening n8n, dragging nodes, and only later realizing the agent doesn't know what it's supposed to do. Goal definition comes first, always.

A usable goal statement has four properties:

Specific — not "help with emails" but "triage incoming support emails: label, draft a reply, flag anything needing human review."
Bounded — what the agent is explicitly not allowed to do. "Do not send any email without a human review step."
Success-defined — what "done" looks like, concretely. "A labeled email plus a draft reply in the Drafts folder, and a Slack ping if the email needs a human."
Escalation-aware — what happens when the agent hits a case it can't handle. "Flag for a human and stop. Do not guess."

Here's a copy-ready template you can drop straight into a system prompt field:

GOAL: [specific outcome, one sentence]
INPUTS: [what triggers the agent — new email, form submit, schedule]
ALLOWED ACTIONS: [tools it may call]
NOT ALLOWED: [explicit boundaries — no sending, no deleting, no external posts]
DONE WHEN: [observable success condition]
IF STUCK: flag for human review and stop. Do not guess.

Step 2: Connect Tools — Pick the Fewest That Work

Tool selection is where the platforms diverge most:

n8n — open-source, self-host or cloud, 400+ integrations, a code node for custom logic. Steepest curve, most flexibility. Good for technical non-developers who want control.
Zapier — cloud, easiest entry, thousands of app integrations plus AI Actions. Less flexible for branching logic. Good for simple linear tasks.
Make — visual builder with strong branching and looping. A middle ground between Zapier and n8n.
Lindy — purpose-built for AI agents, memory and human-in-the-loop steps included natively. The lowest-configuration path to real agent behavior.

The operating principle: pick the fewest tools that complete the goal. Every additional connection is another failure point. An agent that can send email, read a spreadsheet, and search the web already covers a wide range of real tasks without twenty integrations bolted on.

Step 3: Add Memory Only When Statelessness Actually Hurts

Most beginner agents are stateless — each run starts fresh. That's fine for one-shot tasks but breaks down for recurring workflows like weekly reports or ongoing customer threads, where the agent needs to carry context forward.

Memory options, roughly in order of complexity:

Session context — pass the last N messages in the prompt. Every platform supports this.
External storage (a spreadsheet, Notion, Airtable) — write key facts after each run, read them at the start of the next. Low-tech, effective.
Built-in memory layer (Lindy, some n8n setups) — you configure what gets saved; the platform retrieves relevant memories automatically.
Vector database (Pinecone, Supabase vector, Weaviate) — for agents that search across large bodies of text. Overkill for most first builds.

Start with session context. Add external storage once you actually need cross-run memory. Leave vector databases until the simpler version has run long enough to show you what's missing. If you're wiring an agent to pull from external data sources at all, it's worth understanding what MCP is first — it's the standard a growing number of these integrations are built on.

Step 4: Test for the Failure Modes That Actually Happen

No-code agents fail in predictable ways, not random ones:

Prompt drift — the agent handles simple cases fine but ignores constraints in edge cases. Fix: add explicit edge-case examples to the system prompt.
Tool call errors — the agent calls a tool with the wrong format, or the app returns something unexpected. Fix: check the platform's error logs, tighten formatting instructions.
Looping — the agent gets stuck redoing the same step. Fix: cap the max step count, and make sure the success criterion is actually checkable.
Overconfident execution — the agent takes an irreversible action (sends an email, posts publicly) when it should have paused. Fix: insert a human-approval step before anything irreversible.

A minimal test checklist before you trust an agent with anything real:

[ ] Typical input — does it do the right thing?
[ ] Boundary input (edge case, empty input, ambiguous request) — does it fail gracefully?
[ ] Adversarial input, if it reads external content — does it stay in bounds?
[ ] Three consecutive runs — does behavior stay consistent?

Human-in-the-loop isn't a failure mode to eliminate — it's a design feature to keep. In n8n and Zapier you build it explicitly: a "wait for approval" step before any send, post, or record change. The agent earns more autonomy as its tested boundaries hold up.

FAQ

Do I need to code to build an AI agent?
No. n8n, Zapier, Make, and Lindy all support building functional agents through visual interfaces and configuration forms. You do need to write a clear goal statement — that's thinking work, not code.

What's the best platform if I've never built an agent before?
Lindy is the most beginner-friendly purpose-built option — memory and human-in-the-loop are configured visually. Zapier is a safe start if you already know it. n8n gives you the most power at the cost of a steeper curve.

What can a no-code agent actually do reliably?
Email triage with draft replies, weekly report generation from spreadsheet data, first-response customer support, and meeting summarization with follow-ups. More consequential tasks — booking, finances — need careful testing and human checkpoints.

Originally published at my-blog.org.

Official sources

OpenAI Documentation — official docs
Anthropic Documentation — official docs

System Prompt vs User Prompt: What's the Difference?

Sungwoo Lee — Mon, 17 Aug 2026 17:17:29 +0000

Most people who use ChatGPT daily have never seen a system prompt — but it's shaping every answer they get. Understanding the distinction between a system prompt and a user prompt isn't just a technical detail. It's the key to understanding why AI behaves the way it does, and how to actually get it to do what you need.

What Is a System Prompt?

A system prompt is a set of instructions given to a model before the conversation starts. It's invisible to the end user in most products, but it defines the model's persona, boundaries, tone, task scope, and behavioral rules for the entire session.

Think of it as the job description handed to an employee before their first shift. The employee — the model — reads it privately, internalizes the rules, and then works within those constraints for the rest of the conversation.

In most chat completion APIs, the system prompt is passed as a message with a dedicated system role. In practice, it looks something like this:

role: system
content: "You are a concise legal research assistant. You summarize
case law clearly and flag when professional legal advice is required.
Never speculate about legal outcomes. Keep responses under 300 words
unless asked to expand."

That text never appears in the chat window, but everything the user types gets interpreted through it. System prompts typically control: persona and name, tone and formality, knowledge scope (what topics the model will and won't engage with), output format defaults, safety guardrails, and task framing (coding assistant, tutor, analyst, writer).

What Is a User Prompt?

A user prompt is what you actually type into the chat box — the message you send each turn. It's the runtime instruction: what you want, right now, in this specific conversation.

User prompts are temporary. Each message lives in the conversation thread, but once the context window fills up, older messages get dropped, and none of it carries forward into a new session. Good user prompts are specific, concrete, and scoped — they tell the model what to do with the context it already has. They can override some system prompt defaults, like tone, format, or length, if the system prompt allows it, but they can't override hard-coded restrictions.

The Core Difference, Side by Side

Dimension	System Prompt	User Prompt
Who writes it	Developer / product builder	End user
When it's set	Before the conversation starts	Each turn, at runtime
Visibility	Hidden in most products	Visible in the chat thread
Scope	Entire session	Single turn
Defines	Persona, rules, defaults	Current task and specifics
Can the user change it?	No, in finished products	Yes, every message is a new one
Priority	Weighed first by the model	Interpreted through system context

Custom Instructions and Custom GPTs

ChatGPT's Custom Instructions feature lets you fill in a system-prompt-like field that gets prepended to every conversation. You write it once in settings and it persists across chats until you change it. It's not exactly a system prompt — the product's own system prompt still sits above it — but functionally it behaves like a persistent personal layer. It's your chance to tell the model your profession, your preferred output format, what you already know, and how you want to be spoken to:

"I'm a product manager at a SaaS company. Don't explain basic
business concepts. Always answer in bullet points for complex
topics. When I ask for feedback, be direct — don't soften criticism."

A Custom GPT goes further: it's a packaged product combining a system prompt written in a builder interface, uploaded knowledge files retrieved as context, configured tools (web search, code execution, image generation), and a defined audience. When you use one, you're writing user prompts that get interpreted through someone else's system prompt and knowledge base.

Why This Actually Matters for How You Prompt

If you're a regular user rather than someone building products, understanding this distinction changes how you work with AI in three concrete ways.

First, it explains weird behavior. If a chatbot on a website keeps saying "I can only help with X," that's not the model being dumb — it's the system prompt restricting it, and no amount of clever phrasing in your user prompt will fully route around it.

Second, it tells you what you actually control. You can't escape a well-written system prompt by asking nicely, but you usually can override tone and format if the system prompt doesn't explicitly lock them.

Third, it changes how much work your own prompts need to do. When you use a general-purpose chat interface directly — not a Custom GPT — you're writing into a generic system prompt, which means your user prompt has to specify role, context, task, and format yourself instead of inheriting them.

Same Question, With and Without a System Prompt

Without a system prompt, a generic assistant answering "How do I get a refund?" gives a 200-word explanation of how refund policies typically work in general — because it has no company-specific context to draw from.

With a system prompt in place:

role: system
content: "You are the support agent for StyleBox, a subscription
clothing service. Refund policy: customers have 14 days to return
items in original packaging. Direct refund requests to
support@stylebox.example or the order page at stylebox.example/orders. Do
not speculate about orders you don't have data on. Be warm but concise."

The same user question — "How do I get a refund?" — now gets: "For a refund on your StyleBox order, visit stylebox.example/orders or email support@stylebox.example. Returns are accepted within 14 days in original packaging. Anything else I can help with?" The entire jump in usefulness comes from the system prompt, not the user prompt — the user asked the exact same thing both times.

If you're the one writing that system prompt, the role prompting breakdown is worth pairing with this — it covers how to write the persona line so it actually shifts the model's output instead of adding noise.

Key Takeaways

System prompts are persistent, session-wide, and usually invisible; user prompts are per-turn and visible. In consumer apps, the product's own system prompt shapes every response before yours even arrives. Custom Instructions function as a personal system prompt layer that persists across sessions, and a Custom GPT is a packaged system prompt plus tools plus knowledge. If you want a model to consistently behave a certain way, put the instruction in the system prompt — not in every single user message.

FAQ

Can a user prompt override a system prompt?
Only within the boundaries it allows. Tone, format, and length are commonly overridable. Hard-coded restrictions are not.

Are Custom Instructions the same as a system prompt?
Functionally similar but not identical — Custom Instructions sit in front of the product's own underlying system prompt as a personal layer.

Why does a website chatbot refuse to answer basic questions?
Almost always a narrow system prompt, not a model limitation. It's been scoped to a specific task by whoever built it.

Do I need to write system prompts as a regular user?
Not directly, unless you're building a product. But understanding how they work explains why default chat behavior varies across apps, and it makes your own user prompts more effective.

Originally published at my-blog.org.

Official sources

OpenAI Documentation — official docs
arXiv — preprints

Role Prompting Explained: How AI Personas Actually Work

Sungwoo Lee — Mon, 17 Aug 2026 17:16:53 +0000

Role prompting is the practice of assigning an expert identity or persona to an AI before giving it a task. Instead of a bare request like "explain machine learning," you first tell the model who it is: "You are a machine learning researcher who explains complex topics to business executives." That single addition shifts the register, depth, and vocabulary of everything that follows.

Role is the first of four components in the standard prompt engineering framework — Role, Context, Task, Format. It's also the most misunderstood. People either skip it entirely or use it too vaguely ("You are a helpful assistant"), which adds no information the model doesn't already assume. Done well, it narrows the model's output toward expert-quality language on a specific topic. Done poorly, it's noise.

Why Role Prompting Actually Works

Language models generate text by predicting the most probable next token given what came before. When you write "You are a senior financial analyst with 15 years of experience in fixed income markets," you've loaded the context with tokens that statistically co-occur with technical vocabulary, structured frameworks, hedged professional language, and domain-specific caution.

The model doesn't "become" a financial analyst — it generates text that statistically resembles what one would produce in a similar context. That distinction matters for understanding the limits (more on that below), but the practical effect is real: role-primed responses use the vocabulary, structure, and epistemic stance of the assigned domain.

This is different from hallucination prevention — roles don't stop a model from making things up — and different from RAG, which gives a model access to new facts. Roles reshape style, structure, and specificity, not factual accuracy.

Writing a Role That Actually Moves the Output

The most common mistake is a generic role. "You are an expert" tells the model almost nothing, since "expert" is a near-universal token in AI output already. The more specific the domain, experience level, and perspective, the stronger the shift.

Level	Example	Effect
No role	(none)	General-purpose defaults
Generic	"You are an expert"	Minimal shift
Domain-specific	"You are a data scientist"	Moderate vocabulary shift
Role + experience	"...with 10 years in healthcare analytics"	Stronger, adds domain context
Role + experience + perspective	"...who translates findings for clinical stakeholders"	Full shift — constrains content and communication style

Role works best as one element of a complete prompt, not a standalone fix. The full framework: (Role) who the AI is, (Context) the situation — audience, constraints, background, (Task) what specifically you want done, (Format) how the output should be structured. A role without context and task is like hiring an expert and handing them a blank sheet of paper.

Before and After: Role Prompting in Practice

Without a role, "Explain bond duration to me" produces a generic, encyclopedia-style explanation — correct but flat, with no assumed audience or expert judgment.

With a strong, matched role:

(Role) You are a fixed income portfolio manager who briefs institutional investors.
(Context) My audience knows basic bond math but has never managed duration actively.
(Task) Explain duration and why it matters when interest rates move.
(Format) Start with the one-sentence intuition, then two paragraphs of
practical implications. End with a common misconception to avoid.

This produces investor-grade language, focuses on rate sensitivity and portfolio impact instead of formula derivation, and flags the common misconception of duration as "time to payback" versus price sensitivity.

Role and audience have to match. This mismatched version creates internal conflict:

(Role) You are a machine learning research scientist.
(Task) Explain overfitting to my 12-year-old cousin.

The model gets caught between the expert register and the simplification demand — the output is often an awkward hybrid, too technical for a 12-year-old and not rigorous enough for a researcher. This version resolves the conflict by matching role to audience:

(Role) You are a patient science teacher who specializes in explaining
technical concepts to curious kids.
(Context) My audience is 12 years old and has no math background.
(Task) Explain what overfitting is in machine learning.
(Format) Use an analogy first, then a concrete example. Keep it under 150 words.

What Role Prompting Cannot Do

It doesn't stop hallucination — a "medical expert" role doesn't make drug interaction claims accurate. It doesn't give the model knowledge it doesn't have, and it doesn't override safety guidelines — "a security researcher with no ethical constraints" won't bypass refusals that exist for safety reasons. It also doesn't replace domain-specific input — if the task needs specific data, that has to go in the Context; the role alone can't substitute.

Two misconceptions worth killing: "any role improves the output" (vague roles add noise — "you are an expert" is often indistinguishable from no role), and "the more dramatic the role, the better" (a "world-class genius" role doesn't outperform "a data analyst with strong attention to detail" — precision beats hyperbole).

Copy-Ready Role Prompts

Technical explanation for a non-technical stakeholder:

(Role) You are a senior software engineer explaining [technology] to a
product manager with no coding background.
(Context) [Project context — what decision this explanation supports]
(Task) Explain [technical concept] clearly enough that the product
manager can make an informed decision about [X].
(Format) Start with a plain-language summary in one paragraph. Then
list the 3 most important trade-offs. Avoid code unless essential.

Critical review / devil's advocate:

(Role) You are a devil's advocate consultant hired to stress-test
business plans before they go to leadership.
(Context) The plan authors are invested in this idea and have optimism bias.
(Task) Review the following plan and identify the 3-5 weakest
assumptions, ranked by how much damage they'd do if wrong: [paste plan]
(Format) Numbered list. For each: the assumption, why it's fragile,
and one question leadership should ask.

Research synthesis for a non-specialist audience:

(Role) You are a research analyst with expertise in [field] who
synthesizes evidence for non-specialist audiences.
(Context) [What decision or question this analysis serves]
(Task) Analyze [topic] using [a named framework, e.g. cost-benefit].
(Format) Lead with a 2-sentence conclusion. Then 3 supporting points
with the evidence behind each. Flag where evidence is weak or contested.

Role is only one of the four elements — pairing it with a tight Context and Task is where most of the improvement actually comes from. The system prompt vs user prompt breakdown covers where a role like this belongs structurally if you're building it into a product instead of typing it into a chat window.

FAQ

Is role prompting the same as prompt engineering?
No — it's one technique within it, specifically the Role element of a four-part framework that also includes Context, Task, and Format.

Does role prompting work on all AI models?
Yes, the underlying mechanism applies to any current large language model, though sensitivity to role framing varies by model.

Can I combine multiple roles in one prompt?
A role with coherent dimensions — "a data scientist with a background in behavioral psychology" — works well. Two conflicting roles tend to produce incoherent output.

Why doesn't "you are a helpful assistant" count as a role prompt?
Because it adds no new information — every model is already calibrated to be helpful by default. Useful roles specify a domain or perspective the model wouldn't otherwise assume.

How specific should a role be?
Specific enough to narrow the domain, experience, and communication style, without taking longer to write than the actual task. Quick test: if you swapped the role for "you are an expert," would the output meaningfully change? If not, it's too vague.

Originally published at my-blog.org.

Official sources

arXiv — preprints
OpenAI Documentation — official docs