An AI-generated grandfather keeps showing up in fitness feeds. He’s 62, shredded, and he says Tai Chi walking gave him abs in three weeks. Seven minutes a day. In a week your eyes will change. In a month your son won’t recognize you.

My first reaction was probably the same as yours: who falls for this? Then I dug into it and found the uncomfortable answer. Nobody is supposed to fall for the ad. The ad is a filter. The real machine starts after the click, and that machine is built almost entirely out of dark patterns.

Most of the facts below come from an investigation by YouTuber Josh Brett, who bought a fresh debit card and walked into the funnel himself. The pattern names come from Harry Brignull, the UK designer who has been cataloging these tricks for over a decade. What I want to do here is line the two up, because this funnel is close to a complete tour of his catalog.

The Ads Are Bad. The Operation Is Not.

Some context before the list, because the scale is the whole point.

There’ve reportedly been over 18,000 variants of these ads. A single one passed 100 million views. The estimated spend behind them is around $195 million over 12 months. That money doesn’t come from an amateur fumbling with AI video tools.

The ads funnel into Mad Muscles, a fitness app. Mad Muscles is run by Ammo Apps, which sits inside Ammo, a company of around 600 people. Above all of it sits Genesis, a Ukrainian holding company whose app portfolio reports over 400 million downloads. The company is registered in Cyprus and bills from Las Vegas while the ads run worldwide.

So the amateur look of the ads is not a budget problem. It’s a design choice. Hold that thought until pattern number one.

What a Dark Pattern Actually Is

Dark patterns, now often called deceptive patterns, are interface tricks designed to make you do things you didn’t intend: buy add-ons, accept a subscription, or hand over personal data. Brignull started documenting them in 2010, and some, like sneaking items into your basket, have already been made illegal in parts of the world.

One caveat before the list. The line between persuasion and deception can be blurry. A discount is persuasion. A discount with a fake timer is deception. What pushes this funnel over the line is the combination: every stage uses one of these tricks, wrapped around health claims that the evidence doesn’t support.

The 10 Dark Patterns in the Tai Chi Funnel

1. The self-selection filter. The ads are absurd on purpose. A 2012 Microsoft paper asked why Nigerian prince emails look so fake and landed on this: an unbelievable message repels skeptics for free, so only the most trusting people ever reply. If you laugh at the AI grandfather and scroll past, the advertiser hasn’t spent a cent on you. You filtered yourself out.

2. The data-harvest quiz. Before any product appears, you answer roughly ten minutes of questions about your age, weight, goals, and insecurities. Brett entered a body weight that made him almost underweight, and the quiz still prescribed a 1,040-calorie diet to drop 12% body fat. The quiz isn’t diagnosis. It’s commitment. After ten minutes of answering, walking away feels like a waste.

3. The rigged prize wheel. Before showing the price, the site spins a gambling-style wheel and you “win” a discount. Brett won the maximum discount, as everyone presumably does. A price you won feels like a gift, and gifts are hard to refuse.

4. The countdown that never ends. A timer pressures you to buy before your discount expires. Brignull has documented what many of these timers do at zero: they restart. The urgency is manufactured.

5. Fake scarcity. “Hurry, only five spots left.” It’s a subscription app. There are no spots.

6. Misdirection. After you pay, a sequence of pop-ups begins. Each has a huge, bright yes button and a tiny gray skip link hidden off-center. Judging by the angry reviews, many buyers thought these pop-ups were the product they’d already paid for.

7. Sneak into basket. Those pop-ups are stacked add-ons that can pile up to hundreds of dollars before you notice. Sports Direct ran the physical version of this trick with a magazine and a giant mug at checkout, and the UK made that practice illegal in 2014. Online, it lives on.

8. Hidden auto-renew. The subscription renews itself, disclosed in small print. Scroll through Mad Muscles’ 26,000+ Trustpilot reviews and the complaints cluster exactly there, coming from men over 50 and women over 40. That’s the same audience the ads target.

9. The paywalled lifeline. Brett tried to ask the in-app coach whether 1,040 calories a day at 50 kilograms is actually safe. The coach sits behind another paywall. The one feature that could catch a dangerous recommendation costs extra.

10. The roach motel. Easy to get in, hard to get out. The money-back guarantee requires many consecutive days of completed workouts, screenshots as proof, and sometimes ongoing messages with a coach. There’s no cancel button anywhere in the app. Brignull coined the name for this pattern, and the timing is grim: the US “click-to-cancel” rule that would have forced a cancel button was struck down in federal court in July 2025.

Why Nobody Stops It

Here’s the part that bothered me the most. Every layer of oversight has a reason to look away.

The corporate structure spans jurisdictions, so a person hit with a surprise charge doesn’t know who to complain to. The UK’s Advertising Standards Authority can ask for an ad to be taken down, but it rarely fines or prosecutes. Health regulators police medical products, and these apps are structured to fall between the categories. Meta, YouTube, and TikTok earn money every time one of these ads runs. And when a fine does land, it’s often smaller than the revenue it punishes.

Nobody in the chain has a financial reason to stop. So it doesn’t stop.

What You Can Actually Do

Don’t skip the ad. This one is petty, and I love it. Advertisers pay per completed view. If you watch all 30 seconds of the AI grandfather without clicking, the company pays for a viewer it specifically built the ad to repel. Their filter, used against them.

Talk to the actual targets. The people falling for this aren’t reading breakdowns like this one. They’re on Facebook. They’re your parents, or your aunt who has struggled with her weight for years and just wants to feel better. A two-minute conversation about fake countdown timers protects them more than any regulator currently does.

If you build products, audit your own funnel. Every pattern on this list ships in some growth playbook as a conversion tactic. The wheel, the timer, the pre-checked add-on. If your funnel only works because the user didn’t notice something, you already know which side of the line you’re on.

The Takeaway

The lesson I keep coming back to: the badness was engineering. Every instinct says a $195 million operation should produce polished ads, and every instinct is wrong. The polish lives where it pays off, in the funnel, and the crudeness lives where it pays off, in the filter.

So the next time an ad looks too stupid to work, don’t ask who it repels. Ask who it keeps.

The full investigation is Josh Brett’s video, The $295,000,000 Tai Chi Walking Scam. Worth 13 minutes of your time. Harry Brignull’s catalog of deceptive patterns lives at deceptive.design.

If you have come this far, I guess I can assume you’re interested in tech and how it shapes behavior. If you want more reads in tech and lifestyle around tech, don’t forget to check out my profile.

Stay skeptical out there. The wheel always lands on the maximum discount.

Those Absurd Tai Chi Ads Are a Masterclass in Dark Patterns was originally published in Seek For Wealth on Medium, where people are continuing the conversation by highlighting and responding to this story.

I’ve spent months building a custom AI development pipeline. Ideation, specification, planning, plan validation, execution, code review, findings triage. Every stage produces an artifact. Every artifact gets checked before the next stage runs. I wrote about it, refined it, and ran it on real projects. It worked, and I was proud of it.

Last week, a single conversation with a newer model did what the pipeline used to do. No plan file. No validation gate. No review loop. One prompt, some back-and-forth, done.

I should be happy about that. I’m mostly not.

The Test Bed

The project is a Flutter rewrite of a ten-year-old Java Android app with thousands of live users. It’s the kind of project where mistakes are not abstract. The new app has to read the old app’s SQLite database in place after a Play Store update. The crypto has to match the old implementation byte for byte: AES-256-GCM, PBKDF2 with exactly 65536 iterations, a 12-byte IV prepended to every payload. Backup restore has to handle four different legacy data formats, because ten years of users means ten years of formats.

I built my pipeline for exactly this kind of work. Work where a “reasonable guess” by an agent corrupts real user data.

For months, the pipeline earned its keep. The validation gate caught unverified package versions. The review stage caught assumptions that would have broken the migration path. The structure was doing real work.

Then the Model Emerged: Fable 5

The recent task: replace the app’s manual backup and restore flow with a background sync service. Not a small change. One service deleted, two new modules, the auth flow touched, tests rewritten, user-facing strings updated in eleven languages.

Old me would have run the full pipeline. Spec, plan, validate, execute in phases.

Instead I described the goal in a normal conversation and watched. The model asked the clarifying questions my specification stage used to force. It checked the legacy formats before touching the codec, which is what my validation stage used to verify. It ran the tests without being told, which is what my execution harness used to enforce.

The pipeline’s stages didn’t disappear. They moved inside the model.

That’s the pattern I keep seeing now. Most of my harness was compensation. Compensation for a model that wouldn’t ask questions, wouldn’t check its assumptions, wouldn’t verify its own work. Each model generation needs less compensation. The harness shrinks with every release.

Where the Pipeline Still Wins

But not all of it shrinks. There’s a category of work where I still run the full pipeline, and I don’t expect that to change soon: well-established, quality-critical, deterministic implementations.

The crypto compatibility layer is the clearest example. There is exactly one correct output. The old app’s ciphertext either decrypts or it doesn’t. “The model is smart” is not a guarantee I can ship to thousands of users. What I need there is determinism: the same checks, in the same order, every single time, with acceptance criteria a machine can verify. A smart model gets it right most of the time. A pipeline proves it got it right this time.

Same for the four backup formats. Same for the database migration. The pipeline isn’t there because the model is dumb. It’s there because “probably correct” and “verified correct” are different products, and some code has to be the second one.

The dividing line, as far as I can tell: intelligence replaces process where judgment was the bottleneck. It doesn’t replace process where proof is the bottleneck.

The Part That Should Worry You

Here’s the uncomfortable conclusion I keep circling back to.

My pipeline was never really a tool. It was my judgment, written down. Years of knowing what to check, when to stop and validate, which assumptions kill projects. Encoding that into a workflow was my edge over someone who just types “build me a sync service” into a chat box.

The models are absorbing that judgment. Not the domain knowledge, the engineering discipline itself. The instinct to verify a package version before depending on it. The habit of checking repository state before executing a plan. These were senior engineer behaviors. Now they’re default model behaviors.

So the moat moves again. First it was writing code. Then it was reviewing AI code. Then it was orchestrating AI with custom harnesses. Each of those felt durable when I was doing it. None of them were.

What’s left, for now, is narrower: knowing which slice of the work is quality-critical, and being able to write its invariants down precisely enough to verify. In my rewrite project, that’s maybe ten percent of the codebase. The crypto, the migration, the legacy formats. The other ninety percent, the model increasingly handles from a conversation.

I don’t think that ten percent goes away. But I also thought my pipeline wouldn’t be optional this soon.

The Takeaway

If you’ve built a custom AI workflow, re-test it against the newest models with an honest eye. Some stages still do real work. Some are compensation for a weakness that no longer exists. Keep the first kind, delete the second kind, and be honest about which is which.

And if your professional value currently lives in your harness, start moving it. The durable skill isn’t the pipeline. It’s knowing which parts of your system deserve one.

I’ve written before about the pipeline this article is now partially retiring, in By the time execution starts, there should be nothing left to decide. If you have come this far, I guess I can assume that you are interested in AI and tech. If you want more reads in tech and lifestyle around tech, don’t forget to check out my profile.

Always review what AI generates before pushing. It handles the tedious stuff, you stay the engineer.

Wish you all the best in your AI journey!

The Smarter the Model Gets, the Less My Custom Pipeline Matters was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

Every Claude Code session starts with amnesia. You explain your project, the agent does great work, you close the terminal, and tomorrow you explain it all over again. The code persists in git. The understanding doesn’t.

I’ve written before about treating execution state as a first-class artifact: plan files, state files, project logs. That solved continuity inside a single task. But project-level knowledge was still scattered across markdown files, chat histories, and my head. Task backlogs, competitor research, architecture decisions, open questions. The kind of knowledge that spans weeks.

So I moved it to Notion and let Claude Code manage it through the Notion MCP server. A few weeks in, this is the setup I keep coming back to.

The First Decision: A Separate Workspace

Before connecting anything, I had a problem. My Notion workspace is my life. Personal notes, journals, plans, things no agent has any business reading, let alone editing.

MCP permissions are not granular enough for my comfort here. Once Claude has access to a workspace, it can search and touch what’s in it. I didn’t want to rely on “it probably won’t open my journal.”

The fix was boring and effective: I created a second Notion workspace. “Rutkay’s Notes” stays private, untouched, disconnected. “Rutkay’s Projects” is the only workspace the MCP integration can see, and it contains nothing but project material.

This one decision removed the entire category of worry. Claude can read, write, and reorganize anything in the projects workspace, and the blast radius is exactly zero for everything I actually care about protecting. If you take one thing from this article, take this: don’t point an agent at the workspace where you keep your life.

Two Skills to Make It Usable

Raw MCP access works, but it’s chatty. Every operation is a round of tool calls, and Claude has to rediscover the workspace structure each session. I wrapped the common paths into two custom skills.

/notion-project-sync keeps a project’s Notion presence in sync with reality. It knows where the project’s task database and documentation pages live, so Claude can pull the current state at the start of a session and push updates back (new tasks, status changes, fresh docs) without me spelling out page IDs every time.

/notion-cli wraps the Notion CLI (ntn) for the operations where the API is the better tool: direct API calls, batch operations, file uploads. When MCP is too slow or too coarse for a job, Claude drops down to the CLI instead of fighting the tool interface.

I won’t paste the skill files here. The point is the division of labor, not the implementation. One skill for the routine sync loop, one for the escape hatch.

What Claude Actually Built

Here’s where it got interesting. I didn’t design the databases myself. I described what I wanted tracked, and Claude created the structure through MCP.

For one project, that became a task database with fields for Area (Platform, Security, Monetization, Trust & Safety), Phase, and Priority. Claude populated it: DB schema and migrations, rate limiting, age gating, secure key storage, crash reporting. Each task with a one-line note explaining the why. Not a template I filled in. A backlog the agent derived from our planning conversations and wrote directly into Notion.

Around the tasks, it built the documentation layer: a documentation hub, a competitor and review analysis, a field analysis of the domain, mockup collections, and a page of rough task ideas waiting to be triaged into the real backlog.

The part that matters: because Claude wrote this structure, Claude can navigate it. There’s no impedance mismatch between how the docs are organized and how the agent expects them to be organized. It reads its own filing system fluently.

Two Real Tests

I didn’t want to evaluate this on a toy project, so I ran two very different workloads through it.

The first was a rewrite. I have an Android app I wrote about ten years ago, and I’m rebuilding it with Flutter. This is exactly the kind of project that punishes lost context: legacy behavior to preserve, migration decisions that only make sense if you remember the constraint that forced them, a long backlog that evolves as the old code reveals its surprises. Claude tracks all of it in Notion now. When a session starts, it syncs the project state, sees which migration tasks are open, and picks up with full knowledge of decisions made weeks ago.

The second was research, not code. For a new project idea, I had Claude run a field analysis: the competitive landscape, existing products, user complaints from reviews, gaps worth building into. The output didn’t land in a chat window that would scroll into oblivion. It landed as structured Notion pages that later sessions cite when we discuss priorities. Last month’s research is now an input to this month’s planning, automatically.

Two workloads, one pattern: the value isn’t that Claude can write to Notion. It’s that a later session can read what an earlier session knew.

What Changed

Before this, resuming a project meant reconstructing context by hand. Re-explaining the architecture, re-stating the priorities, hoping I remembered the reasoning behind last month’s decisions.

Now the session starts with a sync. Claude reads the task database, checks the documentation, and asks about the things that actually changed. When we finish, it updates task statuses and appends what we learned. The project’s memory lives outside both my head and the conversation.

There’s a second-order effect I didn’t expect. Because the docs are in Notion rather than buried in a repo, I read them too. On my phone, away from the terminal. I catch stale priorities and wrong assumptions while making coffee, not while burning a coding session. The shared memory works in both directions.

It’s not free. The sync adds a bit of overhead at session boundaries, and every MCP tool call is slower than reading a local file. For a quick one-off script, I skip it. For anything that spans more than a couple of sessions, the overhead pays for itself the first time I don’t have to re-explain the project.

The Takeaway

If your agent workflow loses everything between sessions, the fix isn’t longer conversations or bigger context windows. It’s an external memory the agent can read and write, structured well enough that it can navigate it without you.

Notion through MCP is one way to build that. Whatever you pick, two rules held up for me: give the agent its own space, isolated from anything personal, and let it build the structure it will later have to navigate.

Front-load the isolation. Externalize the memory. Let the agent do its own filing.

If you have come this far, I guess I can assume that you are interested in AI and tech. If you want more reads in tech and lifestyle around tech don’t forget to check out my profile. If you wanna choose your next read immediately, you can go for this one: My Idea Finder Had Exactly One Idea: Make It Cheaper

Always review what AI generates before pushing. It handles the tedious stuff, you stay the engineer.

Wish you all the best in your AI journey!

I Gave Claude Code Its Own Notion Workspace was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

My AI coding sessions kept dying in the middle. Always on my home Wi-Fi, never on my phone hotspot

The error was always the same: `API Error: Unable to connect to API (ECONNRESET)`. ECONNRESET means the connection got reset out from under the app. Short prompts worked fine. The moment a session got long, it would run for a few minutes and then drop.

I have been debugging networks and systems for a decade, so I did the responsible thing and blamed everything in order. None of it was the real cause. The real cause was a single number my own Mac had picked, and it took a full afternoon of tests to corner it.

Here is the whole hunt, because if you are on a German DSL line, or any asymmetric home connection behind an ISP-provided router, this is probably waiting for you too.

The First Misread: It Looked Like a Slow Death

The story everyone tells themselves is “long connection, dies after a while.” My sessions died after 12 minutes once, 6 minutes another time. That sounds like a connection getting tired and giving up.

The debug log said otherwise. Claude Code does not give up after one failure. It retries. The log showed 10 attempts, and each single attempt died at a consistent 15 to 16 seconds. The “12 minutes” was just 10 retries with backoff added together.

That reframe mattered. The real question was never “what dies after 12 minutes.” It was “what dies after 15 seconds, reliably, on every attempt.”

The Wrong Turns I Took First

I want to be honest about the dead ends, because they are the obvious suspects and you will reach for them too.

MTU. The classic culprit for “small requests work, big ones hang.” I set the interface MTU down from 1500, confirmed it held, and tested again. Still dead. Then I proved it could not be MTU: the upload failed after exactly 2,293,760 bytes at MTU 1500, and after exactly 2,293,760 bytes at MTU 1400. If packet size were the trigger, that number would move. It did not.

Bufferbloat. My next theory. A saturated uplink fills the modem buffer, latency explodes, things reset. So I pinged my provider’s path while hammering the upload. Latency stayed flat at about 22 ms the whole time. No bloat.

The usual scapegoats. IPv6 was already off. No VPN, no proxy, no corporate middlebox. A bare connection to the API succeeded, so the client and the TLS stack were fine. The phone hotspot worked perfectly with the same laptop, same binary, same everything.

Every easy answer was wrong. That is usually the sign you are measuring the wrong thing.

The Test That Cracked It

I had been testing downloads. A 5.5 GB download held one connection open for 16 minutes at 44 Mbps without a hiccup. So the link was not flaky, and long-lived connections were not the problem.

The problem was the other direction. Every API request uploads your full conversation context as the request body. I had never tested uploads.

So I uploaded. A 100 MB upload reset at 2.29 MB and 15 seconds, the exact signature from the real failures. Then I changed one thing: I paced the upload with a rate limit.

- 5 MB at full speed: dead at 2.29 MB.

- 5 MB throttled to 700 KB/s: full success.

- 5 MB throttled to 250 KB/s: full success.

Read that again. The same 5 MB, more than double the “2.29 MB limit,” went through fine, as long as it was paced. There was no size cap and no time cap. The only thing that failed was an unpaced burst.

The Real Reason

Here is what was actually happening.

macOS auto-tunes the TCP send buffer. The ceiling is a sysctl called `net.inet.tcp.autosndbufmax`, and the stock value is 4 MB. For a large upload, the kernel grows the buffer toward that ceiling, so a single connection can have several megabytes in flight at once.

My request body got dumped into the modem’s upstream buffer in one fast burst. That buffer tail-drops at about 2.29 MB. Once it overflowed, the flow stalled, and the server reset it around 15 seconds later. A throttled upload never bursts that far, so the buffer never overflows. The uplink itself is fast, about 24 Mbit when measured cleanly. The burst was the whole problem.

This is also why it tracked session length so precisely. A short Claude Code session has a small body and never bursts far enough to overflow. A long session carries a multi-megabyte context, bursts past the cliff, and dies. The hotspot worked because the mobile path soaks up the burst differently.

So the bug was a bad marriage: a generous default send buffer on my Mac, plus a home router with an oversized, badly behaved upstream buffer.

The One-Line Fix

If no single connection can burst more than a quarter megabyte into the modem, the buffer can never overflow. So cap the send buffer.

Check your current values first:

```
sysctl net.inet.tcp.autosndbufmax net.inet.tcp.sendspace
```

Then cap them to 256 KiB:

```
sudo sysctl -w net.inet.tcp.autosndbufmax=262144 net.inet.tcp.sendspace=262144
```

256 KiB is the smallest value that still keeps your full upload speed, which is also the value with the most safety margin.

After that, my 100 MB upload completed at 3 MB/s with no reset. The cap costs zero throughput on this link, because the bandwidth-delay product (how much data should be in flight to keep the pipe full) is only about 22 KB. A 256 KB ceiling is more than ten times that, but still far below the 2.29 MB overflow point.

One catch: `sysctl -w` resets on reboot. To make it stick, load it at boot with a small LaunchDaemon that re-applies the two values. I wrapped the whole thing in a tiny on and off script so I can toggle it on demand, which matters when I am on a different network and want my full burst speed back.

Persistent Fix

Here is the script as GitHub Gist (with a README) that applies cap + installs LaunchDaemon to persist the fix across reboots. You can use it after you confirm the fix is working for you.

How to Tell If This Is You

You do not need to reproduce my afternoon. The fingerprint is specific:

• Long AI sessions, large git pushes, or big file uploads reset, but downloads and short requests are fine.
• It dies on your home line but works on a phone hotspot.
• The failure is a connection reset, not a timeout or a DNS error.

One quick test tells you if uploads are the problem. Push 100 MB at your server and watch it die:

```
head -c 104857600 /dev/zero | curl -4 -sS -X POST — data-binary @- — max-time 120 \

-w ‘http=%{http_code} up=%{size_upload} time=%{time_total}\n’ \

https://speed.cloudflare.com/__up
```

If that resets partway with a tiny `up=` count, you have the same bug. Apply the cap and run it again. It should report the full 104857600 bytes.

This is not a Claude Code problem, by the way. Any tool that sends large request bodies over an asymmetric line with a bloated router buffer can hit it. AI coding agents just trigger it more, because they upload your whole context on every call.

The Takeaway

The proper fix lives in the router, not the laptop. A box that runs smart queue management (SQM, which keeps the upstream buffer from bloating) makes this disappear for every device on the network. Put the ISP router in bridge mode behind something that does fq_codel, and you never think about it again.

But the per-host send-buffer cap works today, on the hardware I already have, and it is reversible in one command.

The debugging lesson is the part I will keep. The consistent 15 seconds and the identical byte count across two different MTUs were the real clues, and I almost ignored both because the easy answers felt close enough. When the obvious fix does not work, stop adjusting it harder. Measure the thing you have not measured yet. For me, that was the upload.

If you have come this far, I guess I can assume you spend real time fighting your tools so they get out of your way. If you want more reads on tech and the lifestyle around it, check out my profile. If a tool you rely on keeps resetting on your home network, run the upload test above before you blame anything else.

Wish you all the best in your debugging journey!

A few weeks ago, I developed an internal tool for myself, a niche idea finder program. In my head, it was simple: Fetch the latest comments from the app stores, pull search engine results, cross-reference Google Trends, and surface the real pain points people are complaining about. Find the signal. Build the product.

I ran it and waited for the magic.

The top insight my idea finder returned, after rounds of “analysis,” was this: people want subscription prices to be lower, and someone should build a product that helps with that.

That was it. That was the signal 😅

What the script actually did

The script did exactly what I told it to do. It scraped comments. It clustered complaints. It matched them against search volume. It correlated trends. Every step worked. Every box was ticked. There were even some unit tests that all passed, full green.

The problem was upstream of the code. I had never defined what a “good idea signal” looked like to me. I mean, I did give some examples and some ideas on how it should be. Not in a way you could write a function against. I just had a vague feeling that I’d recognize one when I saw it. But it was not precise, not like I am paying tens of thousands of dollars to get this product from a 3rd-party company. If it were the case, I wouldn't have let them hallucinate on my money and half-baked ideas.

So when the agent wrote the correlation logic, it optimized for what was measurable, not what was meaningful. What does meaningful even mean here? Dude… I need a philosophy degree to be a good product owner.

The loudest complaints across the largest cluster of people. That’s “price is too high,” every time, in every category. Of course it is. That’s gravity.

The agent wasn’t wrong in the end.

The third-party company trap

When I started coding with Claude Code for days, then weeks, then months, my working model was this: treat the agent like a third-party company I’m hiring to build things for me. Write a brief, hand it off, review the output, iterate.

That model held up for small tasks. It fell apart on anything that required taste, domain expertise, and hard work on the product side.

As an experienced developer, I already know how third-party engagements go wrong. The requirements looked clear. The vendor delivered something that technically matches. You open it and it’s not what you wanted, and the gap between “what you said” and “what you meant” is where the whole project lived.

Agents have the same failure mode, except faster and cheaper, so you stop noticing it.

You blow through 40 iterations in a day, each one slightly off, and you never stop to ask the uncomfortable question: Do I actually know what I want here? Could I describe the target output to a human, concretely, before any code is written?

For my idea finder, the answer was no. I was outsourcing a decision I hadn’t made.

The questions only you can answer

There’s a category of questions your agent physically cannot answer for you. Not because it’s not smart enough. Because the answer lives in your head and nowhere else.

For the idea finder, the questions I hadn’t answered were things like:

• What counts as a “good” signal? A complaint with high volume? High emotional intensity? Low competition? A complaint that implies a workflow people are already paying to solve badly?
• Why am I even scraping store reviews in the first place? Are indie app reviewers representative of the market I want to build for? Or am I just fishing where the water is shallow?
• What does a valid output look like? Can I write down three real examples of “good signals” from products I admire, so the agent has something to match against?
• What am I going to reject? Price complaints. Generic UX gripes. “Make it free.” If I can’t list what to filter out, my signal is going to drown in noise.

None of these are coding questions. They’re product questions. And I had handed them all to the agent by accident, just by not writing them down.

When the script returned “people want cheaper subscriptions,” it wasn’t a bug. It was the honest answer to a brief I hadn’t written.

Target output examples, before anything else

The fix was embarrassingly simple, yet requires diligence and proper hard work instead of only "talking to an agent". It’s the lesson I keep learning over and over.

Before the agent writes a single line, I now force myself to produce target output examples, run a complete manual round myself if possible. Not acceptance criteria in the abstract. Actual, concrete examples of what “success” looks like if this thing ran perfectly.

For the idea finder, that meant sitting down and writing three fake “ideal” outputs by hand. “Users of budgeting apps in the EU keep asking for shared household budgets with separate personal envelopes, and three of the top four apps either don’t support it or charge for it as a premium tier.” That kind of thing. Specific. Opinionated. Impossible to mistake for “lower the prices.”

Once I had three examples I actually wanted to see, the whole script changed. The filters changed. The correlation logic changed. Half the data sources I was scraping went in the trash because they couldn’t produce the shape of output I was now asking for. Maybe app store comments were the wrong place to look at all. Maybe I needed forum threads, support tickets, Reddit niche subreddits. The target output was telling me where to fish.

That reshaping was never going to come from the agent. It came from me writing down what “good” meant, in examples, before pretending the agent could find it.

Owning the product means owning the definitions

Here’s the shift that’s been building in me for months, and the idea finder just made it loud.

When I delegate execution to agents, I don’t get to delegate the product. I still have to own it. Owning it doesn’t mean writing the code. It means owning the definitions the code depends on.

What “good” means for this output. What “correlated” means for this data. What “done” means for this PRD. What “a signal worth chasing” means versus “noise that happens to be loud.” What I’m willing to reject, even when the agent produces it confidently.

The more I let the agent handle the typing, the more I have to work on my own methods of thinking about the product. Summaries I can actually skim. Diagrams I can actually read. Documentation I can come back to in a week and recognize. Target output examples for every non-trivial task. A running sense of the state of the product that doesn’t live only in transcripts.

I used to draw a lot of diagrams by hand when I was the one writing every line. I thought I drew them for documentation. Nope! I drew them to understand what I was building. Now that the agent is doing the building, I need those diagrams more, not less, because they’re the only thing that keeps me in the driver’s seat.

The test I run on myself now

Before I hand anything non-trivial to an agent, I try to answer one question honestly: could I describe the target output to a smart human collaborator, with examples, and have them push back where I’m being vague?

If I can’t, the task isn’t ready for an agent. It’s not even ready for me yet. What it’s ready for is ten minutes of me sitting with a notebook, writing down what “good” looks like for this specific thing, on this specific day, for this specific product.

Ten minutes of that will save me from building another idea finder that confidently tells me to make things cheaper.

The takeaway

Agents are fast, patient, and relentlessly literal. They execute whatever definition of “good” you encode into their inputs, even if that definition is “the loudest thing in the dataset.” They can’t nudge you when your framing is off. They can’t know what’s in your head. They can’t own your product.

You can. And if you don’t, nobody will, because the agent is busy shipping the wrong thing correctly.

Own the definitions. Write the target output examples. Draw the diagrams for yourself, not for the agent. The agent will do the rest, well.

If you have come this far, I guess you are interested in AI and tech. If you want more reads in tech and lifestyle around tech, don’t forget to check out my profile. If you wanna choose your next read immediately, you can go for I Added One Step to My AI Workflow, and It Boomed the Quality.

Always review what AI generates before pushing. It handles the tedious stuff, you stay the engineer and product owner.

Wish you all the best in your AI journey!

My Idea Finder Had Exactly One Idea: Make It Cheaper was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

Everything started with a huge feature request last week.

I generated a detailed plan for restructuring a Flutter project. It ended up having five tasks, 30+ implementation steps, 4 big Architecture Decision Records. The plan covered everything: error handling patterns, folder structure, dependency injection, testing strategy. It looked perfect to me.

Before, I would’ve sent this straight to execution. An agent picks up the plan, starts writing code, and I review the output later. That was my AI workflow for months. Plan, execute, review.

A couple of weeks ago, Claude Code accidentally pushed their source code to public (see Claude Code Source Leak Megathread on Reddit). After checking what they have myself and reading the community analysis over it, I decided to adopt some practices from them. And, I implemented a validation step between the plan and execution. Ten minutes. Zero code written.

The result: seven issues surfaced, including unverified package versions that could’ve broken the build, a task that touched 20+ files per step without checkpoint guidance, and acceptance criteria that were too vague for an agent to verify against.

Neither my agents nor my half-baked (especially when they are my own stupid indie projects) code review would have caught these before (at least some of them, I'm still reviewing them OK?!)

The Plan-Execute Trap

Most AI-assisted development workflows have two phases. You describe what you want (the plan), then an agent builds it (the execution). Maybe you add code review at the end. This is the setup you’ll find in most tutorials, most tools, most workflows.

It looks efficient. You’re not wasting time on ceremony. You plan, you execute, you review. Three clean steps.

The problem is the gap between planning and execution. Plans contain assumptions. Some are explicit, like “use fpdart for error handling.” Some are implicit, like assuming a package version exists, or assuming a directory structure is already in place, or writing “verify the feature works” as an acceptance criterion without defining what “works” means.

Agents don’t question these assumptions. They execute. If your plan says “implement authentication,” the agent will make a reasonable guess about what that means. Its guess might be wrong. You won’t find out until code review, after the agent has built an entire feature on top of that guess.

I kept running into this. Not on small tasks. On the bigger ones, the ones where planning felt thorough and comprehensive. The more detailed the plan, the more hiding spots for unresolved decisions.

What Falls Through the Cracks

Here’s what I was finding in code review that shouldn’t have made it that far:

Unverified dependencies. A plan says “add fpdart ^1.1.0.” Does that version exist? Does it support the Dart SDK version in the project? The plan doesn’t check. The agent doesn’t check. It adds the line to pubspec.yaml and moves on. If it breaks, you find out during execution, not planning.

High-risk steps without guardrails. A task that touches 20+ files in a single step is risky. If something breaks halfway through, you need to know where to roll back to. But the plan just lists the files and moves on. No checkpoints, no intermediate verification.

Vague acceptance criteria. “Verify the DI setup works” isn’t something an agent can verify. What does “works” mean? All dependencies resolve? The app compiles? A specific test passes? The vaguer the criterion, the more the agent has to guess. And guessing is where bugs come from.

Orphaned references. A plan mentions a file in its “Files Touched” section that no step actually creates or modifies. Or a step references a directory that doesn’t exist yet without a creation step. These are small things. They cascade.

Stale assumptions. The plan was written against a specific branch state. By the time execution starts, has anything changed? Are there uncommitted changes that might conflict? The plan doesn’t know.

Every one of these is fixable. But they’re only fixable if you catch them before execution starts. Once code is being written, these assumptions become load-bearing walls. Changing them means rework.

The Validation Gate

The fix was adding a single step between planning and execution. I call it validate-plan. It reads the plan file and runs five checks:

Plan syntax. Does the plan follow the expected structure? Are there acceptance criteria for each task? Are dependencies between tasks declared? This is mechanical, like a linter for plans.

Scope boundaries. Does the plan stay within what was originally requested? Plans tend to grow. A task that started as “migrate error handling” quietly expands to include refactoring three unrelated modules. Scope creep in a plan becomes scope creep in execution, except now an agent is doing the creeping and you won’t notice until review.

Decision register integrity. Every architectural decision in the plan should map to a documented rationale. If the plan says “use feature-first folder structure,” is there a record of why? If not, the agent has no way to make judgment calls when edge cases come up during execution.

Execution step viability. Can each step be completed as described? Are the referenced files and directories real? Are the tools and commands available? Are the steps ordered correctly based on their dependencies?

File and folder readiness. Does the current state of the repository match what the plan expects? Are there uncommitted changes that could conflict? Missing directories that need to be created first?

The output is a report: blockers (must fix before execution) and warnings (should address, won’t break things). In the Flutter project case: zero blockers, seven warnings. Ten minutes to generate. All seven warnings were things I fixed in the plan before a single line of code was written.

Why Code Review Doesn’t Catch This

Code review is good at catching implementation bugs. Wrong logic, missing edge cases, bad patterns. It’s not good at catching planning bugs. Funnily, there is no code before the execution at all. And, you are handing over the plan to an agent and believing that the code will be sound! Not happening.

By the time you’re reviewing code, the architectural decisions are already made. The folder structure exists. The dependency versions are locked. The acceptance criteria were already interpreted by the agent, one way or another.

If the plan said “use injectable for DI” but didn’t specify whether to use lazy or eager initialization, the agent picked one. Code review will show you which one it picked. But at that point, you’re evaluating “is this acceptable?” instead of “what should this be?” Those are different questions. The second one should have been answered before any code was written.

Code review also can’t catch what wasn’t done. If a plan was missing a step, the agent didn’t skip it. It was never there. There’s nothing in the code to review because the work was never performed. You’d have to notice the absence of something, and that’s much harder than noticing the presence of a bug.

Validation catches absences. “This plan doesn’t verify the output after a high-risk step.” “This acceptance criterion is not agent-verifiable.” “This dependency version hasn’t been confirmed.” These are things that are visible in a plan and invisible in code.

What Actually Changed

Before adding the validation gate, I’d estimate about 30–40% of the issues I caught in code review were things that shouldn’t have made it past planning. Not code bugs. Planning bugs. Assumptions that should have been resolved, decisions that should have been made, criteria that should have been sharpened.

After adding it, that category dropped significantly. The issues I find in code review now are real implementation issues, things that couldn’t have been caught without seeing the actual code. That’s what code review is supposed to be for.

The bigger shift is how I think about plans. Writing a plan used to feel like the last creative step before handing off to automation. Now it feels like a draft. The validation step is the editorial pass. It makes the plan tighter, more explicit, more executable. And it takes ten minutes.

It’s cheaper to fix a plan than to fix code. That sounds obvious when you say it out loud. But most AI workflows skip the step that makes it actually true.

The Takeaway

If you’re using AI agents for anything beyond small one-shot tasks, your workflow probably has a gap between planning and execution. A gap where assumptions live unchallenged, where decisions are implied but not recorded, where “works” means different things to you and the agent.

Adding a validation step there doesn’t require new tools or frameworks. It requires the discipline to ask: is this plan actually ready to execute? Not “does it look good,” but “can an agent execute this without making any decisions on my behalf?”

If the answer is no, the plan isn’t done yet. And that’s a much better time to find out than during code review.

I’ve been building this validation step as a custom Claude Code skill that plugs into my planning-to-execution pipeline. If you’re interested in how the full workflow fits together, I wrote about the broader approach in By the time execution starts, there should be nothing left to decide.

If you have come this far, I guess I can assume that you are interested in AI and tech. If you want more reads in tech and lifestyle around tech don’t forget to check out my profile. If you wanna choose your next read immediately, you can go for this one: I Forgot What I Worked On Yesterday

Always review what AI generates before pushing. It handles the tedious stuff, you stay the engineer.

Wish you all the best in your AI journey!

I Added One Step to My AI Workflow, and It Boomed the Quality was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

There’s a repository out there, agency-agents, with 200+ Claude Code agent personas well clustered under their expertise, such as Marketing, Sales, Development, everything a tech business might need. Each one is a detailed character with personality traits, domain frameworks, code examples, and communication style guidelines. Some are genuinely impressive, to be honest.

I spent a few hours going through the repository and the agent details. Going through them helped me understand something that’s easy to miss when you’re new to agentic development: agents and skills solve completely different problems.

What Agents Actually Do

An agent in Claude Code is essentially a persona. It tells Claude who to BE for the duration of your session. A Security Engineer agent comes loaded with threat modeling methodologies, OWASP frameworks, secure coding opinions, and a specific communication style — “I approach every system with an adversarial mindset.”

That sounds powerful. And it can be, for the right situation.

Agents are great for ad-hoc advice. You’re staring at a weird architecture decision and you want a Software Architect’s perspective. You load the persona, have the conversation, and close it out.

But that’s it. The next session? You load it again. Start over. No memory of the project. No continuity. No phases. No workflow.

What Skills Actually Do

A skill is different. It tells Claude what to DO, and in which way you want Claude to do that. Not who to be.

Specifically:

- What phases to run through

- What files to read and write

- What model to use for which step

- What tools are allowed or restricted

- What the output looks like at the end

You run a skill, it produces something concrete, and next session you can pick up exactly where you left off. The skill doesn’t care about personality. It cares about process.

That’s a fundamentally different thing.

The Problem with Installing 300 Lines of Personality

Here’s where I started developing a skepticism about full agent installs.

Those 201 personas are 300-500 lines each. Personality guidelines. Communication style. How the agent responds to pushback. Preferred frameworks. Examples of good vs. bad output.

Every time you invoke an agent, all of that loads. Every single call. Most of it is noise for your specific situation.

The Security Engineer agent has hardcoded opinions about how to structure a threat model. But your system doesn’t look like the system the agent was designed for. Your stack, your risk surface, your team’s tolerance for ceremony, all different.

You end up fighting the agent as often as using it.

The extraction from an agent to a skill isn’t refactoring. It’s a contract boundary. The skill describes what to do, and the orchestrator decides when and with what data.

The Valuable Part Is Buried Inside

But here’s what I noticed after a few hours of reading through these personas. Every good agent has a gem inside it. One specific framework. One methodology that would genuinely improve a workflow if applied correctly.

The Security Engineer? STRIDE threat modeling. A structured way to think about adversarial scenarios: Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege. That’s a real, battle-tested framework. Worth having.

The problem isn’t the content. It’s the packaging. 400 lines of persona wrapper around 20 lines of actual value.

What I Did Instead

I didn’t install any agents for my development workflows. I extracted the frameworks instead. Two small additions to skills I already had running:

1. My security review skill now starts with an adversarial threat assessment phase. I took the STRIDE model out of the Security Engineer agent and embedded the questions directly into the review workflow. No persona needed.
2. My planning skill now generates an ADR automatically when a change involves an architectural decision. Borrowed the template from the Software Architect agent. Works exactly the same.

Zero persona bloat, great addition to the skills I already tailored.

The security review runs the same way every time, on every project, without loading 400 lines of Security Engineer personality. The ADR template shows up exactly when it should, without me having to remember to ask for it.

That’s the difference between a workflow and a persona. One is reliable. The other depends on you remembering to use it.

The One Question Worth Asking

Before you install any agent, from this repo, from anywhere, ask one question: What is the one thing this agent knows that my current setup does not?

Not what the agent does in general, or not what persona it assumes. The one specific piece of knowledge that would make your existing workflow better.

Find that piece. Extract it. Embed it where it belongs in your workflow, and leave the rest behind.

Most of the time, the answer is a framework, a template, or a checklist. Something you can write in 15 to 20 lines and slot directly into the right skill phase. No personality guidelines needed. No hardcoded communication style.

The agent was a container for the knowledge. You don’t need the container.

Why This Matters for How You Work

This distinction, agent vs. skill, persona vs. process, matters more as you build out your AI-assisted development setup.

If everything you use is persona-based, your workflow depends on you knowing which persona to invoke at which moment. You become the orchestrator, manually selecting the right character for each situation. That’s cognitive load you’ve added to yourself.

If your setup is skill-based, the workflow knows when to apply what. The adversarial threat assessment happens because the security review skill runs it. The ADR gets generated because the planning skill detects an architectural decision. You’re not managing personas. You’re running repeatable processes. That’s the shift worth making.

I’ve been building out this kind of skill-based setup for a while now. If you want more reads in tech and lifestyle around tech, don’t forget to check out my profile. If you wanna choose your next read immediately, you can go for this one: I Forgot What I Worked On Yesterday

Wish you all the best in your AI journey!

201 Claude Code Agent Personas. I Installed Zero was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

Since I started to work with agents, I have stopped knowing what I did each day. Not because I did not own the AI work. I understood everything that it has done as a responsible senior developer, for sure! Yet, the context switch and mental load were messing with me.

I mean literally, I’d sit down the next morning, open my laptop, and draw a blank on what I shipped, what I fixed, what I decided the day before. The tools were doing a lot. I was doing a lot. But none of it was sticking.

This started to be a problem at work as I started to report the necessary details during the dailies, as well as losing track of details I should've given attention to.

It was clear at some point: I was developing brain fog that is way more dense, by using Claude Code than doom scrolling.

The Day That Made Me Build Something

A few weeks ago, I ran 22 Claude Code sessions across 6projects. 886 messages. In a single day.

The energy I spent and the output were the kind of things that used to take a week or so. Bugs fixed, features shipped, experiments run, a whole pipeline redesigned, all before dinner. And I felt great about it while it was happening.

That night, when I tried to actually reflect on what I’d done, I couldn’t reconstruct it. I remembered the shape of the day, something about calendar bugs, something about a pricing test, but the specifics were gone. The wins, the gotchas, the decisions I’d made and why, all blurred together.

I wrote a note to myself: “The cognitive cost of agentic parallelism. High throughput, but declining awareness.” (The actual note was more like "I often realize that idk what I did these days")

That note became my tiny open source project dear-diary

What dear-diary Does

Claude Code stores your conversation transcripts as raw JSONL files in ~/.claude/projects/. They’re noisy, full of tool calls, thinking blocks, internal metadata. There’s no way to look at them and understand what actually happened.

dear-diary cleans that up in two stages.

Stage 1 is a pure Python script called extract.py. Zero external dependencies — no pip, no virtual environment, just the standard library. It scans your Claude session files for a given date, strips the noise, groups everything by project, and writes a clean JSON file. No LLM is involved at this stage. Same input, same output, every time.

Stage 2 is a Claude Code skill called /diary-review. You run it from the project directory, and it reads the diary JSON from Stage 1 and produces a structured reflection: Day Overview, What I Worked On, Wins, Learnings, Challenges, Patterns, Key Takeaways, and Seeds for Content (blog angles, basically).

The skill has two modes. Auto mode runs parallel subagents against each project and synthesizes everything without you. Reflection mode — the default — is different. It talks to you first.

The Thing I Didn’t Expect

I thought I was building a logging tool. I was wrong.

The first time I ran /diary-review in reflection mode, it gave me a quick summary of the day — project names, what was done — and then asked me a specific question. Not “how did the day go?” but something like: “You ran three production bug fixes today, all triggered by funnel analytics, not crash logs. What made you look at the funnel instead of Crashlytics?”

That question surfaced something I had completely lost. I sat down and typed the answer. Then it asked a follow-up.

By the end of that 10-minute conversation, I had a reflection that captured not just what I did, but why I made the choices I made, what I was worried about, and what I was actually proud of.

That’s different from logging. The manual Q&A process forces awareness, it makes you realize what you actually accomplished, not just what you touched. The reflection question bank is organized by the shape of your day: bug-heavy days get different questions than multi-project days or feature-shipped days. It’s contextual, not generic.

One word I wrote in my diary for that day: “euphorically exhausting.” Touching 6 projects in a day with agents is both the blessing and the curse.

The Funny Part

dear-diary itself was built in a single day, using the same workflow it’s designed to reflect on.

A bunch of commits, step by step: CLI skeleton, output writer, session discovery, date filtering, message extraction, full pipeline, tests. Then the skill, then iteration on friction (inline Python in Claude skills triggers security heuristics — had to extract helper scripts to fix that), then a README, then an open-source release.

The next morning, I ran the diary review on the day I built it. That first reflection made clear the tool wasn’t about logging. It was about building awareness of your own work. About feeling proud of what you shipped instead of wondering what day it even was.

A Different Kind of Productivity

I’ve thought about what actually changed. It’s not speed. dear-diary doesn’t make me write code faster.

It’s awareness. And awareness compounds. When you know what you shipped yesterday, you make better decisions about today. When you can articulate a win clearly, it stops blurring into the noise.

The repo is at github.com/arutkayb/dear-diary. If you use Claude Code and have been feeling the same blur at the end of the day, give it a try. And do not hesitate to open a PR to extend it to agentic tools other than Claude Code.

If you have come this far, I guess I can assume that you are interested in AI and tech. If you want more reads in tech and lifestyle around tech don’t forget to check out my profile. If you wanna choose your next read immediately, you can go for this one By the time execution starts, there should be nothing left to decide

Always review what AI generates before pushing. It handles the tedious stuff, you stay the engineer.

Wish you all the best in your AI journey!

I Forgot What I Worked On Yesterday was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

There’s a version of AI-assisted development that looks productive but isn’t. You describe something, the agent writes code, you review it, realize it missed the point, describe it again — slightly differently — and the cycle repeats. The agent isn’t broken. The input was.

I kept running into this loop. Not because the tools were bad, but because I was treating AI agents like they had judgment they don’t have. Eventually, I stopped trying to make agents smarter and started making my inputs better. What came out of that was a structured workflow I’ve been refining for weeks — and it changed not just how I build, but how I think about development.

The Real Problem With “Just Ask AI”

When you delegate a task to another person, they ask clarifying questions. They flag ambiguity. They tell you when your requirements don’t make sense. Agents don’t do that — or at least, they do it at the wrong time: mid-execution, when undoing mistakes costs more than the original task.

The root cause is almost always the same: the requirements going into execution contain open questions. Not always obvious ones. Sometimes it’s something as subtle as “what counts as done?” Sometimes it’s a decision that seemed clear in your head but never made it into writing.

I started thinking about this differently after a project where I handed an agent a solid-sounding task and got back something technically correct but architecturally wrong. The agent had made a reasonable guess where I should have made a decision.

That’s when I landed on the principle I now design everything around:

By the time execution starts, there should be nothing left to decide.

Front-Loading Human Judgment

The shift this required was counterintuitive. Instead of spending less time upfront (the whole appeal of AI), I started spending more — deliberately, in structured stages, before any code got written.

The idea is simple: every stage of development resolves the open questions produced by the previous stage. Ideation produces questions about what you’re actually building. Specification resolves those and produces questions about technical approach. Planning resolves those and produces a step-by-step execution path with no remaining ambiguity.

By the time an agent runs, it’s not reasoning under uncertainty. It’s executing a plan someone already thought through. That someone is me.

This sounds like more work. It is — up front. But the execution phase becomes dramatically faster and more accurate. More importantly, when something does go wrong, it’s easy to trace back to which stage the assumption broke down. That’s something you can fix. A tangle of agent-generated code built on a vague brief is much harder to untangle.

Two Different Requirements, One Design

Here’s the part that took me longest to get right: the artifacts produced by this workflow serve two very different audiences simultaneously.

Agents need precision. They need machine-verifiable acceptance criteria, not “the feature should work well.” They need explicit decisions, not implied ones. They need each step scoped tightly enough that success or failure is unambiguous. A plan that says “implement authentication” is useless to an agent. A plan that says “implement JWT-based auth with 1-hour expiry, refresh tokens stored in HttpOnly cookies, endpoint returns 401 with error code on invalid token” — that’s something an agent can execute against.

Humans need narrative. I need to be able to open a plan file and understand what I was thinking when I wrote it. I need to see why certain decisions were made, what alternatives were considered, what risks were flagged. I need to be able to edit a plan before running it, and have that edit mean something.

Most frameworks optimize for one of these. I wanted both.

The answer was keeping everything in plain Markdown. Plans are readable documents, not database records. Every plan file has a clear structure: what’s being built, what each step does, what “done” looks like. A human can review and edit it before execution. An agent can read it and execute it step by step, checking off each item as it goes.

The same file serves both purposes. That constraint — that every artifact has to be legible to a human and executable by an agent — shaped every design decision in the workflow.

Execution That Doesn’t Lose Its Place

One of the underrated problems with AI-assisted development is context fragility. You have a great session, make good progress, close the terminal, and the next day you’re back to square one explaining what you were doing.

I solved this by treating execution state as a first-class artifact. Every task gets its own folder. Plans track their own progress with checkboxes. There’s a separate state file that records which steps completed, what was committed, what’s left. Execution always happens on a dedicated branch.

The result: resuming a task isn’t a memory exercise. You run the same command, the workflow reads the state file, and picks up exactly where it left off. The conversation context is gone. The execution context isn’t.

This also means the plan file becomes a historical record. After a task is done, I can look at the plan and see every step, in order, with the logic behind each one. That’s more useful than git blame.

The Project Log No One Thinks to Build

There’s a second layer I added that I didn’t anticipate needing: a project-level log that tracks everything that happened, in reverse chronological order.

Not code changes — git handles that. But decisions. Pivots. The time I abandoned an approach halfway through because I realized a dependency was wrong. The time I changed the data model three days in. These are the things that never make it into commit messages but are exactly what future-me (or future agents) need to understand why the codebase looks the way it does.

Every workflow stage appends to this log automatically. Decisions I make manually get logged with a dedicated command. The result is a single file — a timeline — that gives a complete narrative of the project. One file. Start here when resuming after a break. Read the decisions folder when something seems weird about a past choice.

The pattern I keep coming back to is: clarity compounds. Each bit of context you capture makes the next decision easier. Each decision you log makes the next agent run smarter. The overhead of maintaining this log is trivial. The payoff, over a project lifecycle, is significant.

What Changed

Before this, I’d estimate about 60–70% of my back-and-forth with agents was resolving ambiguity that should have been resolved before I started. Requirements that seemed clear to me but weren’t precise enough to execute. Decisions I thought were made but hadn’t been written down.

Now that percentage is much lower. Not zero — I still discover things during execution that change the plan. But they’re real discoveries, not just the cost of vague inputs.

The bigger shift is harder to quantify. I think more clearly about what I’m building before I start building it. The workflow forces a kind of structured deliberation — not paralysis, but rigor. Writing acceptance criteria that an agent can verify against turns out to be good practice whether an agent ever reads them or not. You learn a lot about what you actually want when you have to make it falsifiable.

The Takeaway

If you’re using AI agents and finding yourself in loops — re-explaining, course-correcting, undoing — the problem is probably not the agent. It’s that the inputs contain decisions that weren’t made yet.

The fix isn’t better prompting. It’s a workflow that forces you to make all the decisions before execution begins. One that produces artifacts a human can read and edit, and an agent can execute without guessing.

Front-load the thinking. Make everything readable. Trust the execution.

I’ve been building this framework as a set of custom Claude Code skills and have been running it on real projects for several weeks. If you want to know more about how I’ve structured the workflow or the tooling behind it, drop a comment — happy to go deeper on any part of it.

A few people have asked about the actual skill files behind this workflow. If you’d find it useful to have the raw files — the ones that power each stage of this pipeline — drop a comment below. If there’s enough interest, I’ll update this article with direct links so you can plug them straight into your own setup.

If you have come this far, I guess I can assume that you are interested in AI and tech. If you want more reads in tech and lifestyle around tech don’t forget to check out my profile. If you wanna choose your next read immediately, you can go for this one Frustrated with Boring Review Comments? Resolve them at once with Claude Code Custom Skills and Commands

Always review what AI generates before pushing. It handles the tedious stuff, you stay the engineer.

Wish you all the best in your AI journey!

Gitlab version is also explained with the necessary skill files attached

How familiar are you with these review comments?

• “Can you add comments to this code?”
• “Please rename this variable to something more descriptive.”
• “Can you break this function into smaller functions?”
• “Please remove this commented-out code.”
• “Can you add type annotations?”
• “This should be an enum, not a string.”
• “Can you move this to a separate file?”
• “This logic is duplicated — can you extract it?”
• “Please don’t use any here."
• “Can you use a more descriptive commit message?”
• “Can you use destructuring here?”
• “This import is unused.”
• “Please handle the edge case where this is empty.”
• “Can you add logging here?”
• “This could be a one-liner.”
• “Can you sort these imports?”
• “This belongs in the utils folder.”

AI coding tools and agents are drastically shaping the way we code these days. As a 10+ years experienced developer, I acquired a lot of knowledge and skills on my way to becoming today's me. Long architecture discussions, whiteboard brainstorming sessions, arguments end up being almost fights. Throughout the journey, I've seen many developer, regardless of their seniority and experience, getting frustrated by code review comments like above.

Don't get me wrong, they are really valid comments, and we all should follow certain practices that don't matter if it is as big as a wrong architectural choice or as small as word case formatting. But I am sure that after days, sometimes weeks, of development, seeing these small, easy-to-fix review comments can get your nerves.

Thanks to recent tools, today's developer can focus on the business impact and engineering concerns to operate the AI and review what's been done, instead of spending precious hours on straightforward, no-brainer review requests.

I was in Italy last month to visit a close friend for his birthday. He is working at one of the big tech companies in the data collection field. He told me that the engineers at his company received an ultimatum from their higher management: if they don't use AI sufficiently across all company tasks, they risk being fired. It was this clear. Though it is funny that they were counting the tokens their engineers use in a month to assess if they are using "AI" well enough :D

However, I heard that they've been exploring Claude and its capabilities deeply. I started to check it and realized that Claude is becoming a kind of tech World standard. And there are tons of fantastic ways to leverage it to pump up your productivity. Copilot seemed an ancient tool besides Claude.

I am relatively new to Claude code, as I've been using Copilot since its first day. And this X thread from Boris Cherny, the creator and head of Claude Code at Anthropic, gave me a great starting point to shape my CLAUDE.md files, Caude skills, and so on.

Let's get back to resolving review comments with Claude. If you haven't installed the command-line tool yet, you can do it by following the instructions in this link.

Once you start your Claude session with claude command, you will be able to use all kinds of skills/claude-commands. The one we are interested in here is pr-comments . As you can see in the description of the command, it gets all the comments from a GitHub pull request. Then, the only thing left is for you to tell Claude to resolve the issues listed in the command result, that's it!

But there is a problem if you are not using GitHub as a source control. I use GitLab and there is no mr-comments command to fetch the comments from GitLab by defult.

Adding a Custom skill

No worries! Claude Code gives you a way to create your own skills, which means custom commands.

Steps:

• Create .claude/skills/<command> . In our case glab-mr-comments
• Create SKILL.md file under the newly created skill folder.
• Create your skill file, or feel free to use mine directly https://gist.github.com/arutkayb/d842121ed0e76b61f835ff3983b4622e
• As my skill file uses the REST API of Gitlab to access the merge request, you need to define GITLAB_API_TOKEN environment variable and set your private Gitlab api token in your ~/.zprofile or any other env file export GITLAB_API_TOKEN=...

And now you can start a Claude session on your terminal and start using your new Gitlab MR comment command!

And an example response of the new command to follow up with "Resolve them":

If you have come this far, I guess I can assume that you are interested in AI and tech. If you want more reads in tech and lifestyle around tech don't forget to check out my profile. If you wanna choose your next read immediately, you can go for this one By the time execution starts, there should be nothing left to decide

Always review what AI generates before pushing. It handles the tedious stuff, you stay the engineer.

Wish you all the best in your AI journey!