Let me back up.

In a recent newsletter email, I mentioned my steady US work might dry up. That worried me more than I let on. The backups I'd been "working on" weren't nearly ready, my last course launch sold exactly 3 copies (I published the full autopsy ), and I'd just spent a month in France feeling stuck, unable to move forward on anything.

The break itself was worth it: cutting off from everything in July, a family trip to Italy… highly recommended. But when I got back at the end of July, the math was simple: maybe a month of consulting left, then I'd need new clients or new revenue.

We have runway, but I wasn't going to sit around burning it.

Here's something I've learned about myself: my best ideas only show up when my back is against the wall. When things are comfortable, I coast. When they're not… I finally start seeing what's wrong.

And the first thing I saw was YouTube.

I've spent a stupid number of hours this past year on my channel, Tibo Denz, where I learn things, build things, and take on slightly insane challenges. Nothing to do with software (except the ESP32 code inside my Factorio build ). I finally nearly got monetized, passing 1,000 subs and getting close to 4,000 watch hours. But total revenue so far? $6 in affiliate sales.

The hourly rate on that "business" is abysmal.

BUT. I love it. It's the long-term play and I'm not stopping. It’s also opening opportunities I never dreamed of. But I just had to be honest with myself: I can only afford to pour hours into it when I know work is coming, else the stress just kills my creativity. So it went to the back of the line while I fixed two other things.

Thing one: Azky Consulting .

I took the thing I'm actually good at, software consulting, and packaged it so I could find new clients without billing hourly this time. That meant productized services: One page, four offers.

That's the whole company.

I'll write a dedicated breakdown soon, because pricing judgment instead of hours deserves its own article. I’m collecting testimonials and got my first client booked for next week. Hopefully, that goes well.

Thing two: Finally figuring out Devmystify.

Since reviving Devmystify last year, I tried to make it about everything. Tutorials, AI workflows, career tips. I didn't want to let go of the technical roots… so we kept publishing tutorials, and built a technical AI course... which didn't do very well.

That forced the realization: you guys don't need more tutorials. You can already build, AI made sure of that, and you can ask Claude for everything you don’t know yet.

But one thing that’s harder to learn with AI is the business half.

Don’t get me wrong, you can definitely pick up some useful knowledge from LLMs, but starting a business is about more than following predefined steps. It’s about accountability and understanding human beings. What to build, who it's for, how to get paid for it. That's the one direction where I actually have receipts, so that's the direction I want to take Devmystify towards… Which meant a complete rebrand with a clear promise: helping developers start businesses.

And then, the twist.

Last week, my US client told me the steady work is… continuing after all. The wave I'd been sprinting away from turned out to be fake.

I'm keeping everything the scare built anyway. The consulting practice is packaged and Devmystify finally knows what it is. The machine exists now, and next time the wave might be real.

If your only plan is "hope the work keeps coming" like me, you don't have a plan…. You have hope.

One more thing, and it's the part I'm most nervous about.

I'm building something I've never done before: a cohort. Live, eight weeks, a small group of developers.

It's called Full Stack Founder, and the promise is simple: you pick your path (consulting, digital products, or SaaS), and by week 8 your offer is live and in front of real buyers, hopefully making money outside your full-time job.

Weekly deliverables, real volume floors, group calls, two private 1-on-1s with me, and me in the room the whole way. It's the thing I wish existed when I was writing tutorials into the void hoping something would stick.

I'm not opening it yet. I want to run the first one small, with the right people in the room, so I'm not setting a date until the waitlist is ready. Your numbers get published on the site, wins and zeros, receipts culture from day one.

If you're unhappy with your current job or salary, or you've been thinking about starting a side business, get on the list. You'll be first in line, with first pick of the seats, when it opens.

Apply for a founding seat →

If you’re unhappy with your current job or salary, or have been thinking about starting a side business, this is the perfect opportunity. Don't wait for the scare like I did.

What went wrong? Is it because times have changed? Or did I just make a massive mistake?

The Idea

AI is changing what "productive developer" means, very fast. The Blueprint we created is a practical course on working with AI while remaining a real engineer, not just an operator, by focusing on workflows, methodology, automation, and code reviews.

It's not vibe-coding or pure theory, but concrete techniques I use on real client work every day. I wanted to teach it the way I wish someone had taught me.

State at Launch

Here's the honest inventory of what I had on launch day:

• An email list of about 2,700 developers, built years ago around my Ruby and Rails content. To be honest, when I revived Devmystify last year, that list was above 3,000. So we've lost quite a few people, that didn't get replaced. That was to be expected, and honestly better than I hoped.
• A finished course at $199 with a brand-new sales page.
• Zero reviews.
• No content engine. No YouTube, no socials for Devmystify, no lead magnet, no nurture sequence. Just the mailing list.

The Process I Used

I used the textbook launch playbook: Announcement, then a warm-up sequence with tiered discounts: my earliest supporters got 50% off, past buyers got 40%, then the whole list got a launch price with a real deadline. Final-day email, final-hours email, countdown timer on the page. Everything that's supposed to happen, executed on schedule.

What Happened

The emails performed fine on paper. Open rates between 32% and 48% depending on the email, honestly better than I expected from a list this cold. Click rates in the double digits, which looked amazing until I dug in and realized a big chunk of the clicks might be bots. Mail clients may be clicking links in emails to verify them, because when your click-to-open ratio looks too good to be true, it probably is. Especially when your conversion rate is terrible.

By the end of the launch week, I had a whopping… 3 sales.

I refreshed my kit.com dashboard every morning… watching it not move at all. If you've launched anything, you know that exact feeling.

Now for the number… those 3 sales made $417, which is great for a product I should have validated better.

Where It Went Wrong… Maybe

So now I'm going to make up some assumptions and come up with some theories about what I did wrong: three things specifically, and "the product is bad" isn't one of them. At least, I hope it isn't, which so far, has been reinforced by the feedback I got from early adopters.

1. Wrong audience, not small audience. My 2,700 subscribers signed up for Ruby and Rails content years ago. They didn't join for an AI course. Audience size is not audience fit, and I confused the two. I assumed everyone else was going through the same AI adaptability issues as me, and might want some tips… which they can likely get from Claude itself directly. Which I still don't think is enough, since you don't know what you don't know, and if you don't prompt the right questions, you'll never find those tips.

2. Zero social proof on a $199 decision. Every visitor saw an empty reviews box. That box quietly tells people "nobody has bought this." For a considered purchase, that's not great. But even with the review of one of the early buyers for the last day reminder, things didn't improve.

3. No engine, just a blast. I pointed a cold list at a page and hoped. Anyone who wasn't ready to buy that week had no reason to stick around, so they left and that was it.

I wasn't expecting too much honestly… but I was still expecting more than what I got. 100% my fault, and still a great lesson to learn from.

Plus, a failed launch doesn't mean that the product is a failure. It's there, it's available, and I can promote it going forward while I work on the next one. I'm also going to experiment with paid ads, something I've never really done before. I'll keep you updated on how that goes.

And that's not all.

Why I'm Not Giving Up

Because a developer I'd never met went through the course and left a genuine five-star review:

Which means he found value in it. If that first review had been 1-star instead, I might have deleted the course or completely remade it. I'm not someone who likes selling crap, I want people to get way more value than what they put in. That's always been my philosophy, be it for consulting or product creation.

So the plan is to build the missing link to get more sales:

• Running small ad tests now that the page has proof on it.
• Publishing short and long form content on new Devmystify channels: on YouTube, Instagram, and TikTok. This should help me build an audience that actually signed up for this topic. I've seen people talk about social media as a great source of leads, and I'm going to put it to the test.

What's Next for Devmystify

AI changed the game for developers, and the way I see it you have two moves.

Move one: get so good with AI that you're the developer your team can't replace. That's the Blueprint , and it's live today. But even then, an uninformed decision by the executive team can still leave you stranded, in a job market that seems really, really tough right now. Which leads me to the second move, something I've personally been working on: moving away from solely relying on software development as my source of revenue, just in case.

And that's move two: build something of your own before you need it. Start now, on the side, before it's too late.

That's the flagship course I'm building next, which will combine the 3 courses that were live on the site. Freelance to Freedom, Master Digital Products, and the SaaS Blueprint will now become one: The Independent Developer.

Because fundamentally, a SaaS or a digital product are just products, which need an audience to work, something you should build before you write a single line of code or text. As for Freelance to Freedom, I will lightly cover it, but again, I do not recommend freelancing in the traditional way anymore. Productized services are the way to go instead.

This will be a complete guide for developers who want to go from employee to business owner because they're worried about where AI is taking their jobs, or aren't enjoying the new era of software development.

And honestly, now is the best window there's ever been to jump in: the models are still affordable, which might not last. Companies are already starting to limit AI usage internally after all. So if you want to build something with AI assistance, the time is now, while the door is wide open.

The course will cover building an online presence, before monetizing it. It will also touch on pivoting into a whole new field and building a business on that if you dislike the new normal.

The Independent Developer launches first as a founding cohort. The waitlist is open on the courses page .

The code looked completely fine. It ran and passed every test. It was clean, well-formatted, and reasonable. None of that mattered when it broke, because it shipped in my codebase, under my name. "The AI wrote it" was not something I could say when it came time to explain what happened.

We're at a point where AI is a baseline in the software industry. A ticket that used to take a couple of hours can now be fixed in a fraction of the time. But even though you don't have to write the code by hand anymore, you still have to understand it as if you did. The code that gets generated ships in your name, under your responsibility, and there's no way to argue with that.

The Excuse That Never Worked

"The AI did it this way" should not be an excuse when something breaks.

This is not new. Stack Overflow used to be the holy grail for developers, the place you went when you were stuck on something you didn't know how to solve. Some people copied code from there and, when it broke, said "I just copied it." That excuse didn't work then, and it doesn't work now. AI-generated code looks good, correct, and plausible. That will never be a reason to trust it blindly.

Authorship and accountability have never been the same thing. Somewhere along the way, AI made that easy to forget, because the code arrives so fast and looks so complete that it feels like it came from somewhere outside the normal process. It didn't. It came through the same door everything else does. You just opened it.

What "Signing Off" Actually Is

Accepting a suggestion. Merging a PR. Running a script someone else generated. These all feel like small actions. One click, one keystroke. Barely a decision at all.

But each click is the moment ownership changes hands. Before you accept the code, it belongs to the model. After you accept it, it belongs to you: in your codebase, under your name. Nothing about the code changes in that moment. What changes is who is responsible for it.

The Gap Between "Looks Right" and "Is Right"

Most developers do review AI-generated code. The problem is what review quietly turns into when the code in front of you already looks clean, well-formatted, and reasonable.

It's easy to scan for the obvious stuff: does it run, do the tests pass, does the syntax look sane. That's a real check, but it's a shallow one. It answers "does this look like working code" without ever asking "does this do the right thing, in this system, for this problem." Those are two different questions, and only one of them matters when something breaks later.

That's exactly how my bug got through. The code ran. It passed the existing tests. It was also missing a condition that only mattered in a situation the tests never covered, one I would have caught if I had read it as carefully as I read code that feels less finished. The more finished code looks, the less carefully we read it... and that's the trap.

Who Gets the Blame

When something breaks in production, nobody asks who typed the original lines. They ask who approved the change, who merged it, who let it ship. That question has always pointed at a person, and it still does, even when a model generated every character of the code.

This was never really about blame. Responsibility never lived in the hands that typed the code. It lived in the decision to let that code represent your system to the rest of the world. AI changed who does the typing, but it did not change who makes that decision.

As Uncle Ben said, "With great power comes great responsibility." AI gives us more power than we've ever had. The best way to handle the responsibility that comes with it: keep AI tasks small enough that you can fully understand, review, and stand behind every change you ship.

It Was Never About Who Typed It

I didn't write the line of code that broke. But I approved it, I ran it, and I let it ship.

That makes it mine, in every way that matters.

The uncomfortable part isn't that AI writes code you didn't write yourself. Developers have shipped code they didn't fully write for years: libraries, teammates' code, templates. The uncomfortable part is how easy it became to treat the approval step as a formality instead of what it actually is, the point where you take ownership.

"The AI wrote it" was never going to be an explanation. It isn't one now. The explanation, if there is one, starts with what you did after the AI was done.

If you want the mental models I use to work with AI to reduce issues like this one, that's exactly what I teach in The Developer's AI Productivity Blueprint. It's out now, and 30% off through July 9.

Get the Blueprint

It isn't about mastering a specific model that might be outdated next month. It's about building a way of working that stays useful no matter how the tools evolve.

We've all been trained to fear the crash. Red text, a stack trace, a build that won't pass. Those are the bugs we know how to handle, because they announce themselves.

The bugs that should actually scare you in the age of AI are the quiet ones. The code that runs. No error. No stack trace. Looks completely reasonable. And is quietly, confidently wrong.

I've started calling these silent failures, and once you learn to see them, you can't unsee them in AI-generated code.

A function that lied to me

Here's a real one. I asked an AI to write a function that fetches a package's dependencies from a registry. This came back:

async function fetchDependencies(packageName) {  
    try {    
        const res = await fetch(`https://registry.example.com/${packageName}`);    
        const data = await res.json();    
        return data.dependencies;  
    } catch (err) 
    {    
        return [];  
    }
}

Read it quickly and it looks fine. It even looks careful, there's error handling. Tests pass. You ship it.

Then one day the network hiccups. The fetch fails. The catch swallows it and returns an empty array. And somewhere downstream, your security scanner reports zero vulnerabilities, because as far as it can tell, this package has zero dependencies.

The code didn't break. It lied. And it lied in the most reassuring way possible: by handing back something that looks like a valid answer.

Here's what it should have done:

async function fetchDependencies(packageName) {  
    const res = await fetch(`https://registry.example.com/${packageName}`);  

    if (!res.ok) {    
        throw new Error(`Registry request failed: ${res.status}`);  
    }  

    const data = await res.json();  
    return data.dependencies;
}

Let the failure be a failure. Let the caller decide what to do with it. An empty array should mean "no dependencies," not "something went wrong and I'm hiding it from you."

Why AI does this constantly

AI is optimizing to complete the task you gave it. You said "fetch the dependencies," so it returns dependencies, and it really doesn't want to hand you back an error, because an error looks like failure. So it reaches for the safe-looking default. Empty array. Null. Zero. false. Anything that makes the function "work."

This is the difference between code that looks correct and code that is correct, and it's the gap that bites you in production. The naming is sensible, the structure is familiar, the happy path works. None of that tells you what happens when something goes wrong, and "what happens when something goes wrong" is most of what senior engineering actually is.

Where to look

Once you know the pattern, silent failures hide in predictable places. When you review AI code, go straight to these:

• Any try/catch that doesn't log or re-throw. Ask: what does this swallow?
• Functions that return null, [], or 0 on a failure path. Ask: can the caller tell the difference between "empty" and "broken"?
• Network or file calls that don't check the response status before using the result.
• Any if with a branch that quietly does nothing.

None of these are exotic. They're the boring, high-frequency ways AI-generated code goes wrong, and they're invisible if you read for "does this look reasonable" instead of "what is this hiding."

The skill nobody's teaching yet

Here's the part that matters. Reading code AI wrote is not the same skill as writing code yourself. When you write it, you hold the failure modes in your head as you go. When AI writes it, you're handed a finished thing that looks done, and your brain wants to approve it and move on.

The developers who'll do well with AI aren't the ones who prompt the fastest. They're the ones who can look at a confident, clean-looking block of generated code and ask the uncomfortable question: where does this lie?

That's a learnable skill. It just isn't the one most "AI for developers" content teaches, because most of it stops at "write better prompts." Prompts are the easy half. Knowing what to do with what comes back is the half that keeps your name off a production incident.

One idea from a bigger system

This silent-failure stuff is covered in more detail in a course I just released, The Developer's AI Productivity Blueprint. The whole thing is about exactly this: using AI to go faster without quietly handing over the judgment that makes you worth hiring. Eight modules, the real workflow I use on production code every day, including a full live build where you watch it all come together on one project, start to finish.

If "where does this lie" is a question you want to get fast at figuring out, the Blueprint is out now, and 30% off for launch week: $139 instead of $199. The discount ends in 1 week, on July 9.

Get the Blueprint for $139

The problem is usually the same: at some point, during a bad period, work dries up. Without new clients, there's no money to pay developers. Without enough reserves, lots of agencies end up being forced to close.

I myself run a tiny web agency, but I do not consider it the heart of the business. Yes, it generates 99% of our revenue right now, but I'm working hard to add additional revenue channels because, in my gut, I know a recession could result in us closing down.

That said, I'm not planning to shut it down completely, even if our diversification efforts work. It's stable and predictable revenue, which lets me sleep better at night. The goal isn't to escape it. It's to stop depending on it exclusively.

Build Something That Doesn't Depend Only on You

The obvious move is to build something that doesn't need you in the room to generate money.

A product, a course, a small SaaS, something that people can pay for whether you're working or not. The agency is a time-for-money business. You stop working, the money stops. A product doesn't work like that.

This isn't a new idea. But most agency owners keep putting it off because client work always feels more urgent. The product never makes it past the idea stage.

The goal in year one isn't to replace your agency revenue. It's just to prove the model works. Pick one thing, give it a real time budget alongside your normal work, and build the habit.

Referrals Aren't a Strategy

Most agencies grow through word of mouth. Someone recommends you, you do good work, they recommend you again. It feels like a system but it's not really.

Referral networks dry up. Industries slow down. The people who used to send you work move on.

Building a public presence is the highest-leverage thing most agency owners skip. A newsletter, a blog, a YouTube channel, even just posting consistently on LinkedIn. It doesn't need to be perfectly polished. It needs to be consistent and genuine.

The math is simple: even if 0.1% of people who follow you become clients, it compounds over time in a way that referrals never will. Being known is the foundation. Everything else builds on top of it.

Make it fun. Show your work. Be a human, not a corporate account.

What Thoughtbot and Basecamp Got Right

Two agencies worth studying here are Thoughtbot and Basecamp, both built products alongside their services businesses, and both ended up with the product becoming more significant than the agency itself.

Thoughtbot built and open-sourced tools that became central to the Rails ecosystem. The tools generated awareness, trust, and inbound leads that the agency alone never could have. Basecamp built project management software to solve their own internal problems, then sold it to the world.

The pattern is the same: solve a real problem you already have, build it properly, and offer it to others who have the same problem. The agency gives you the context to identify real problems. The product gives you leverage beyond your headcount.

How to Actually Do It

There's a concept I keep coming back to: every small business should put 20% of its time into R&D.

And when I say R&D, I don't necessarily mean building a new product. It could be optimizing how you run projects so you actually have time for diversification. It could be figuring out where your margins really come from. It could be analyzing your services to find growth opportunities you're sitting on without knowing it.

The hard part is that client work always wins in the short term. A client with a deadline feels urgent. R&D doesn't have a deadline, so it keeps getting pushed. The way to fight that is to treat it like a scheduled commitment, not something you do when things slow down. Things never slow down. If you don't put it on the calendar, it won't happen.

Keep the scope small too. A dedicated hour or two a few times a week beats a big sprint that burns out in a month. Finish your client work for the day, then switch. Keeping them separate means you're not context switching all day, which is where most of the time actually goes.

If you're starting from scratch, keep it simple.

Pick one direction. A productized offer, a course on something you know well, a small tool that solves a problem your clients keep running into. Give it a real time slot alongside your agency work, not a sprint you'll drop after two weeks.

Build in public if you can. The marketing and the building happen at the same time that way.

Year one isn't about replacing your agency revenue. It's just about proving the model works.

Wrap Up

Agencies are great when they're working. The problem is they're fragile by design. They depend on a constant flow of clients, on your team showing up, on your own energy holding up.

Diversification isn't about abandoning what's working. It's about building something alongside it so that a bad quarter stays a bad quarter, and doesn't turn into something worse.

Client work feels safe because you can see the money. R&D feels risky because you can't. But that's exactly why most people never start, and why the ones who do end up somewhere different a few years later.

Nobody can tell you if it'll work. But you can't find out if you never try.

That wasn't there before. And it's not a coincidence. It means the tooling now expects you to think about AI context the same way you think about .gitignore or tsconfig.json: something you set up before you write a single line of code, not something you patch in later when things are already messy.

Most developers still skip this step, and honestly it's not hard to understand why. It looks like extra setup before you've even written a line of code. And if you've never seen the difference it makes, it's hard to know whether it's actually worth it or just one more config file to maintain.

So instead of just explaining it, let's see what actually happens.

Why Claude Keeps "Forgetting" Your Rules

Every Claude Code session starts completely fresh. No memory of last week. No recall of the architecture decision from three months ago. No awareness that your team agreed to never use default exports.

What Claude has is a context window: everything it can see at once, which includes your files, your prompt, and the conversation so far. It holds a lot, but not forever.

The annoying part is that long sessions drift. As a conversation gets long, Claude starts compressing earlier context to make room for new messages, and small details disappear in that process. It gets dumber, to put it simply. The naming rule you mentioned at the start of the session gets fuzzy. The instruction about where server actions should live stops being applied consistently. You end up typing the same correction multiple times without really knowing why.

CLAUDE.md sidesteps this because it's not part of the conversation at all. It's read directly from disk at the start of every session, before anything else happens. Your rules don't go through compaction because they never live in the conversation history in the first place.

Three Layers of Memory

Before getting into what to put in CLAUDE.md, it helps to understand that Claude Code actually has three different ways to carry knowledge across sessions. Each one does something different.

CLAUDE.md files are what you write. Project conventions, build commands, architectural decisions, naming rules. Anything a new developer joining the team would need to know before touching the codebase. These load at the start of every session.

Skills are on-demand files that Claude reads only when relevant. If you have detailed API documentation, component design guidelines, or a complex workflow that only applies to one part of the codebase, it doesn't need to be in CLAUDE.md. You reference it with @path/to/file syntax, and Claude pulls it in when needed. This is the right place for anything too long or too specific to load every session. It keeps your main CLAUDE.md short and your context window from filling up with things Claude doesn't need right now.

Auto memory is what Claude writes for itself. As you work, Claude saves notes: build commands that kept failing, debugging patterns that worked, preferences it noticed you correcting. It stores these in a MEMORY.md file in a project-specific directory on your machine. You don't manage it manually. Claude updates it on its own, and the first 200 lines load automatically with every new session.

The separation is worth understanding. CLAUDE.md is for rules that apply every session without exception. Skills are for knowledge that's only needed sometimes. Auto memory is for things Claude picked up from working with you specifically.

What Actually Belongs in CLAUDE.md

The official guidance from Anthropic is to keep it under 200 lines. That might sound like a lot, but it fills up faster than you'd expect once you start dumping things in. And a bloated CLAUDE.md is almost as bad as no CLAUDE.md at all. When Claude has to scan 500 lines to find what applies, it starts missing things. A short file gets followed more consistently than a thorough one.

A quick way to think about what belongs: would Claude get this wrong without being told? If yes, and it applies to the whole project, it belongs here. Things like exact build and test commands, file naming conventions, structural rules about where things live, non-default choices like "use named exports only" or "all server actions go in app/actions/."

What doesn't belong: vague guidance like "write clean code" (Claude already tries to do this), long documentation (that's what Skills are for), and anything that only applies to one corner of the codebase. For those, use path-scoped rules in .claude/rules/ so the instructions only load when Claude is actually working on matching files.

If you're not sure where to start, just run /init inside Claude Code. It'll analyze your project and generate a starting file based on what it finds. Not perfect, but a much better baseline than a blank file.

AGENTS.md and CLAUDE.md Together

If your repo already has an AGENTS.md for other tools like Cursor or Copilot, you don't need to duplicate everything. Claude Code reads CLAUDE.md, not AGENTS.md directly. But you can import one into the other:

@AGENTS.md

## Claude-Specific Instructions
Use plan mode for changes under `src/billing/`.

This way both tools read the same base conventions, and you add Claude-specific notes below the import. What create-next-app generates is already structured this way. The CLAUDE.md it creates imports AGENTS.md out of the box.

What This Actually Changes: A Comparison

I ran a small experiment to see how much difference this actually makes in practice. Two fresh Next.js projects, same prompt, same version of Claude Code. The only difference: one had an AGENTS.md with explicit project conventions, the other had only the default warning about Next.js breaking changes that create-next-app puts there.

Here's the AGENTS.md I used for the second project:

# Project Conventions

## Package Manager
- Use `npm` for all package operations

## Router
- Use Next.js App Router only
- No Pages Router patterns

## Exports
- Always use named exports
- Never use default exports

## File Naming
- Component files must use kebab-case (e.g. `todo-item.tsx`, `add-todo-form.tsx`)
- Component names inside files remain PascalCase

## Styling
- Tailwind only
- No inline styles
- Use `clsx` for conditional class names, never template literals

## Project Structure
- All server actions must live in `app/actions/` directory
- Components go in `components/` directory at the project root

## Testing
- Use Playwright for end-to-end tests
- Test files go in `e2e/` directory
- Run tests with `npx playwright test`

The prompt I gave both was intentionally vague:

Build a simple Todo app with the following features: add a new todo, mark a todo as complete, delete a todo. Use Next.js with Tailwind CSS.

Without conventions, the first thing I noticed was the file structure. Claude put everything into a single TodoApp.tsx inside app/components/: state, handlers, UI, all of it in one place. Which, when you let it assume everything, is kind of the expected result. There's no reason for it to split things up if nobody told it to. The architecture was pure client-side too, useState for everything, which works fine but doesn't use any of what App Router is actually designed for.

With AGENTS.md in place, the output was structurally different from the first prompt. Components landed in components/ at the project root, named in kebab-case. Server actions went into app/actions/. The page itself became a Server Component with client components underneath. clsx for conditional classes. crypto.randomUUID() instead of Date.now() for IDs. Named exports throughout.

Both apps looked nearly identical in the browser. That's what makes this easy to dismiss. But the code underneath was built completely differently. The difference wasn't just naming conventions. The architecture changed too.

In case the description isn't clear enough, here's the diff side by side:

And maybe the more practical payoff: I stopped having to say the same things twice. Once the conventions are in the file, they're just there. Every session, every feature, every time. That alone saves more time than it sounds like it would.

Worth noting: this experiment only tested architecture and structure. Add a Skill on top of it and the gap widens further. If your AGENTS.md imports something like @.claude/skills/component-design.md with your color tokens, spacing scale, and component patterns, Claude starts producing UI that actually looks like it belongs in your codebase. The more context you give it, the more the output feels like yours.

The File That Outlasts the Developer

There's a pattern that shows up in every codebase that's been around long enough. Some decisions are well-documented. Most aren't. The choice of a particular library, the reason a certain folder exists, the rule about never doing X in module Y: these things live in whoever made the decision, not in any file.

When that person leaves, the knowledge leaves with them.

CLAUDE.md is an opportunity to change that habit. Not because it's the right place to dump all your institutional knowledge, but because it asks a useful question at the start of every project: what does Claude need to know to work the way we work?

Answering that question honestly tends to surface the things that were never written down. The non-obvious choices. The decisions that would confuse a new engineer. The rules that exist because something went wrong once and everyone agreed never to do it again.

When that knowledge lives in a file instead of in someone's head, it doesn't just help Claude. It helps the next developer who joins the project. It helps you six months from now when you've forgotten why you made a choice. It becomes part of how the project explains itself.

AI made that useful in a new way. But the underlying habit, writing down what you know so the work can outlast any single person, was always worth having.

If you want to go deeper on building a real workflow around AI tools, I'm working on a course: The Developer's AI Productivity Blueprint . It covers everything from the basics through multi-agent workflows. Join the waitlist and I'll select a few people to get early access in exchange for feedback.

Some write structured prompts with labeled sections and explicit constraints. Some just describe what they need in plain sentences. Some have settled on a format that works for them and stopped thinking about it. Most of them are getting decent results either way.

So the question is worth asking: does the structure actually matter, or have we been optimizing something that was already fine?

The answer is yes, it matters. But only for one of the two things people use AI for, and most of the advice online doesn't make that distinction.

The Research Says One Thing. The Reality Is More Specific.

Someone recently did a meta-analysis of over 1,500 academic papers on prompt engineering and found that the companies generating real revenue from AI aren't following the advice circulating on social media. They're doing something more systematic, and more boring.

But buried inside that finding is something more interesting than "conventional wisdom is wrong."

The real distinction isn't between good prompts and bad prompts. It's between two completely different use cases that most people treat as the same thing.

Two Ways People Actually Use AI

The first is personal use. You need to draft something, debug a function, think through a decision. You open a chat window and describe what you want. Maybe you mention your role or give some context. You read the output, ask a follow-up, and move on.

The second is system use. An application calls an AI endpoint. It does this hundreds or thousands of times. Every call needs to return output in a specific format so the rest of the system can parse it. The response isn't being read by a human who can interpret variations. It's being consumed by code that expects consistency.

These are not the same problem. And the prompt engineering advice that applies to one doesn't necessarily apply to the other.

For personal use, a clearly scoped natural language prompt works fine. You don't need XML tags. You don't need a <role> block. You need to be clear about what you want, and modern models are good enough to handle the rest.

For system use, structure isn't a stylistic choice. It's a reliability requirement.

I Ran the Same Prompt Three Times

To make this concrete, I tested it.

I asked AI to write a JavaScript function that analyzes a user object and returns a structured report. The function needed to calculate days since last login, determine whether someone was a high-value customer, and return a specific status message based on that determination.

I ran the same request three times in natural language, then three times using a structured prompt. Fresh conversation each time.

The natural language prompt:

I have a JavaScript object representing a user with fields like name, email, age,
subscription (which can be "free", "pro", or "enterprise"), lastLoginDate, and
totalPurchases. Write a function called generateUserReport that takes this user
object and returns a report object. The report should include the user's full name
and email, whether they're a high value customer (pro or enterprise subscribers
who have made more than 5 purchases), how many days since they last logged in,
and a status message that says something different depending on whether they're
high value or not. Return just the code.

The structured prompt:

<role>Senior JavaScript Developer</role>

<task>
Write a function called generateUserReport(user) that analyzes a user object
and returns a structured report.
</task>

<input_shape>
{
  name: string,
  email: string,
  age: number,
  subscription: "free" | "pro" | "enterprise",
  lastLoginDate: ISO date string,
  totalPurchases: number
}
</input_shape>

<output_shape>
{
  fullName: string,
  email: string,
  isHighValue: boolean,
  daysSinceLogin: number,
  statusMessage: string
}
</output_shape>

<requirements>
- isHighValue: true only if subscription is "pro" or "enterprise" AND totalPurchases > 5
- daysSinceLogin: calculated from lastLoginDate to today
- statusMessage: "Priority customer - schedule check-in" if isHighValue,
  "Standard account" if not
</requirements>

<constraints>
- Output ONLY valid executable JavaScript
- NO markdown formatting or backticks
- NO explanations or comments
</constraints>

The natural language results all produced correct, working code. But look at what happened to statusMessage across three runs:

• Run 1: "Thank you for being a valued premium partner!"
• Run 2: "Check out our latest offers to upgrade your experience."
• Run 3: "Priority account: This user is a key contributor to revenue."

Three completely different strings. Different tone, different phrasing, different intent. The key name for days since login also drifted, appearing as daysSinceLastLogin in some runs. Some runs added JSDoc comments. Others didn't.

The structured prompt told a different story. Across all three runs, statusMessage was identical every time: "Priority customer - schedule check-in" or "Standard account". Key names matched the <output_shape> exactly. No comments appeared unless specified.

The code quality wasn't meaningfully better. What changed was the predictability.

Predictability Is the Point

This is the thing that most prompt engineering content misses.

When you're using AI yourself, variation is often fine. If the output is slightly different each time, you read it, evaluate it, and decide if it works. You're in the loop.

When AI is part of a system, variation becomes a bug. If a status message changes between calls, something downstream breaks. If a key name shifts, a parser fails. No one is reading the output before it gets used. Consistency isn't a nice-to-have. It's the requirement.

Structured prompts with explicit output definitions, clear constraints, and specific key names lock the model into a narrower range of responses. That's what makes them useful in production, not that they produce higher quality output, but that they produce the same output reliably.

For everything else, the overhead usually isn't worth it. Describing what you need in plain language, with clear scope and context, is enough. The model understands you. It doesn't need to be spoken to in a specific dialect.

So Is It Real?

Prompt engineering is real, but it's a specific tool for a specific problem.

If you're building a system where AI output feeds into code, where consistency across calls matters, where no human is reviewing each response before it gets used, then the structure is worth it. The tags, the explicit schemas, the defined constraints, they exist to solve a reliability problem, not a quality problem.

If you're using AI to do your own work, spending an hour on prompt structure is probably not the best use of that hour. Be clear. Give context. Describe what you want. That's most of what matters.

The people selling magic templates have it backwards. The goal isn't to find the right words. The goal is to understand what you're actually trying to solve, and then use the right level of structure for that problem.

For most things, that level is lower than the internet would have you believe.

Better prompts. Better tools. Better workflows. The assumption is that if you can just squeeze more out of the model, you will stay ahead.

That is not the skill that matters.

Before We Get Into It

I have written about this shift before. About how the bottleneck moved from writing code to understanding systems. About how AI does not know your business context, and why that gap does not close no matter how good the models get.

That is all still true. But there is a layer underneath it that I did not get to, and it is the part that actually changes what a good engineer looks like day to day.

What Everyone Gets Wrong About Prompting

When something goes wrong with AI-generated code, the instinct is to blame the prompt. The logic makes sense: better input, better output. So developers iterate on their prompts, add more context, write more detailed instructions, and sometimes it helps.

But there is a category of failure that prompting cannot fix. And it is the most common one.

AI works within a context window. It sees what you give it in that moment, and nothing else. It does not see the file you did not include. It does not see the service that runs in a separate repository. It does not see the architectural decision from eight months ago that constrained everything built after it. It generates something coherent based on what is in front of it, which can look exactly right while being completely wrong for the system it lives in.

This is not a knowledge problem you can solve by writing a better prompt. It is a structural limitation. The model is not missing information you forgot to provide. It is missing information that cannot be put into a prompt because it is distributed across your entire codebase, your team's history, and decisions that were never written down.

What Validation Actually Requires

Take a concrete example. You ask AI to build authentication for an app where users can be logged in across multiple devices. It produces token expiry logic, a refresh flow, tests that pass. Everything looks correct, because at the level the AI can see, it is.

What it cannot see is that this app handles financial data, and the business requirement is that changing a password must immediately invalidate every active session everywhere. That rule exists because of a specific incident that shaped how the team thinks about security. It is not in any file. It is in the institutional memory of the people who were there.

The AI built something that works. It did not build what the system needs. And nothing about the prompt would have changed that, because the person writing the prompt did not think to include it either.

This is where validation becomes something other than reviewing output. It is the act of bringing everything the AI cannot see into contact with everything it produced. Not skimming for syntax errors. Not checking whether the tests pass. Asking whether this code, in this system, with this history, actually does the right thing.

That requires knowing the system at a level that lives outside any single file or conversation. It requires knowing which decisions were made under constraint, which parts of the codebase are fragile for reasons that are not obvious, and which requirements look stable but are not. None of that is in the prompt. All of it determines whether the output is correct.

The Skill Nobody Is Training For

Most AI workflow advice focuses on the generation side. How to structure prompts. How to break down tasks. How to get better output faster.

The validation side gets treated as a review step. Read the code, check the tests, ship it.

But validation in the way I am describing is not a review step. It is the part of the job that requires the deepest understanding of the system. And it is the part that AI makes harder, not easier, because the volume of code being generated has outpaced the instincts most developers have built for evaluating it.

The engineers who will struggle are not the ones who prompt badly. They are the ones who can generate quickly but cannot hold the whole system in their head. Who can review a function but cannot see how it fits into something larger. Who treat a passing test suite as the end of the question rather than the beginning of it.

The engineers who will not are the ones who understand that generating the code was never the hard part. Knowing whether it belongs in the system is.

Coding Still Matters

None of this means writing code stops mattering. Reading a diff, tracing logic, understanding what a piece of code actually does, that is still the foundation.

But it is no longer where the difficulty lives.

The difficulty is in carrying the system in your head clearly enough to know when something generated fits and when it only looks like it does. That is not a skill you can prompt your way into. It is built from time spent understanding how things connect, why decisions were made, and what the codebase is actually trying to do.

The developers who will matter are not the ones who generate the most. They are the ones who understand enough to know when to trust what was generated, and when to push back on it.

That has always been the job. It is just more visible now.

Then I looked more carefully at what I was actually producing.

The Good Part Is Real

I want to be honest about this part, because the rest of this article will not make sense without it.

AI genuinely changed the pace of my work. Scaffolding a new feature used to take time — now it takes minutes. Boilerplate code is mostly gone, and when I hit an error, I get an explanation immediately instead of spending twenty minutes reading documentation I half-understand.

The speed is not hype. If you use these tools every day, you feel it.

And that is exactly where the problem starts.

How I Actually Used to Work

Before AI, I was a "paint on canvas" developer. I didn't fully plan features before writing them. I liked to throw something quick and dirty at the wall to get a base layer down, something that roughly worked, and let the shape of the feature emerge as I went. Messy, hacked together, but complete. Once the whole thing was working end to end, I'd step back.

Now I had full context and I could see exactly how the feature fit into the app, what was redundant, what needed cleaning up. That's when I'd refactor.

That allowed me to be fast, because I wasn’t overthinking the feature: get it working first, then refactor it all. Simple.

The messy first pass wasn't a problem to fix, it was the method. Explore fast, understand fully, then clean. That two-stage process was doing most of the real work, and I didn't even realize it until AI quietly erased half of it.

Then AI Broke the Loop

Here's what I didn't expect: AI didn't improve that process. It disrupted the part that made it work.

The first stage, fast and dirty exploration, got even faster with AI, and that part felt great. But the second stage quietly disappeared, and the reason is sneakier than you'd think. AI-generated code looks clean. It's formatted, it's structured, it doesn't scream "this needs another pass."

So I stopped doing the refactor… not consciously, there was no moment where I decided to skip it. The code just looked finished, so my brain treated it as finished.

The problem is that looking clean and being well-thought-through are not the same thing. The messy draft is supposed to be a phase. AI turned it into the final product.

The Prompt Loop Trap

Here is a scenario most developers will recognize.

You have a problem. You write a prompt. The output is almost right, but not quite, so you prompt again with a small correction. Still off. You try a different angle, add more context, rephrase. Fifteen minutes later, you are still working on a problem you could have solved in two minutes if you had just opened the file and fixed it yourself.

At some point, you are no longer solving the problem, you are negotiating with the model. This happens because prompting feels like progress. Every response is something, you are moving. But sometimes the fastest path is to stop prompting, close the chat, and just think.

AI was faster, until I used it to avoid thinking and became lazy. Then it was just slower in disguise.

The Hidden Cost: Thinking Less

This is the part that is hard to see while it is happening.

I started reviewing AI output the same way I skim a news article: looking for obvious problems, checking that it roughly matched what I asked for, then moving on. What I stopped doing was asking harder questions. Not "does it work?" but "is this actually right?"

The code was not obviously bad. It worked, tests passed. But "works right now" is not the same as “clean and maintainable”. I was accepting outputs I would have pushed back on before, because the output was good enough and moving on was easy. Standards do not drop all at once, they slip one small acceptance at a time.

AI Didn't Skip Steps. I Did.

The development process has not changed. You still need to understand the problem before you build, think about the architecture before you write code, refactor the output into clean and maintainable code, and review it all carefully before you ship.

AI does not skip those steps, it only does what you ask, making it way too easy to get complacent. No friction, no obvious cost. The cost shows up later, when something breaks in a way you do not understand, or when you have to modify code you never actually knew.

The Fix Is Not a Tool

When I recognized what was happening, my first instinct was to find a better workflow: a smarter way to prompt, a tool that would catch what I was missing. That was the wrong instinct.

The problem was not the tool. The problem was that I had let the tool collapse a two-stage process into one, without noticing. The fix had to happen at the same level. Not a new tool, but a clearer mental model for how to work.

A few things that actually helped:

I kept the two stages explicit. Fast and dirty with AI is still fine, but I now treat that output the same way I used to treat my own messy first pass. It's a base layer, not a finished product.

I still do the refactor pass. Once the feature is working end to end, I step back and ask: now that I can see the whole thing, what would I actually do differently? That question used to come naturally. Now I have to be deliberate about it. I’ll tell Claude or Codex exactly how I want things to be refactored until I’m satisfied.

When I find myself reprompting the same thing more than twice, I stop. That is a signal that I need to think, not prompt. Sometimes, clearing the context and starting fresh also helps.

When I already know the answer, I just write the code. Not everything needs AI. Knowing when not to reach for the tool is as important as knowing how to use it.

The Real Skill

The developers I see getting the most out of AI are not the ones with the best prompts: they are the ones who know what their process actually is and protect the parts that matter.

For me, the first pass was never where the real work happened. The value was in the second pass, when I had full context and could see clearly. AI made me think I could skip it, but really, I couldn't.

Tools will change and the specific model you use today will look different in a year, but knowing which stages of your process are doing the real work, and refusing to let a tool quietly erase them, that is the skill that does not get replaced. It gets more important.

AI made me faster. It also made me worse, for a while. The difference between those two outcomes was not the tool. It was whether I still did the second pass.

Last week, I wrote maybe 10 lines myself, and I shipped more than I usually do.

It’s not a flex, you’re probably doing the same thing. But it took me a while to get comfortable with it because writing was always the part that felt like real work to me.

Something has shifted though, and I think a lot of experienced developers are feeling it without quite knowing what to do with it.

The Role Has Changed.

There is a version of this conversation that goes: "AI writes code now, so developers are done." That is not what I am seeing.

What I am actually seeing is that the work itself has moved.

For a long time, writing software was the hard part. That is why you spent years getting good at your language, your stack, your mental models. Execution was where most of the effort went. That is no longer true.

And when execution stops being the constraint, everything that used to wait behind it becomes visible. Understanding the actual problem. Defining what the system should look like before a line gets written. Knowing which shortcuts will cost you six months from now. That stuff does not get easier just because the code writes itself. If anything, it matters more.

The job did not disappear. It just sits at a different point in the process now.

My days look different because of it. Less time writing, more time managing what AI produces. It feels less like craftsmanship and more like technical direction. And the catch with that is: a fast, capable system that makes mistakes in subtle ways requires more attention, not less. You still have to know enough to catch what it gets wrong.

What I Actually Do Now

Before I touch any AI tool, I think through what I am building. Not at the line level, but at the system level.

• What are the components?
• How does data move between them?
• What are the constraints?
• What should this thing never do?

This is the part that AI cannot do for you. Not because the models are not capable, but because the answers live in your head and in the business context around the project.

Then, I ask Claude to generate an implementation plan for the feature. I will review that part thoroughly, before asking for a list of TDD-style tests to be generated before any code gets written.

Starting with that allows me to define what “done” looks like for the current feature.

If you skip these steps, you end up reviewing code against a vague idea of what you wanted. That is where AI slop comes from, not from bad models, but from unclear input.

Once I’ve reviewed the tests, the implementation work can start. I’ll usually try to do it step by step, with smaller chunks of the feature that I can review as I go.

This matters more than people realize. When you let AI generate a large chunk at once, reviewing it becomes overwhelming. You end up skimming and you end up missing things. Breaking it down forces both the AI and you to think in sequence, and it keeps each review focused enough to actually catch problems.

Then a second AI reviews the output, then I review it myself one more time.

There is also something worth saying about the speed. I will be honest: there is something genuinely satisfying about watching an idea become working software faster than it used to.

Getting to the built thing faster just means more time for the parts that actually require a human.

What You Still Have to Bring

That last review step is where experience earns its place.

I am not only checking syntax. I am also asking whether this approach makes sense for the business and whether we are solving the right problem at all.

This is where AI has a specific blind spot worth understanding. It is very good at producing code that looks functional. Tests pass. The feature works. But "works right now" and "holds up over time" are different things. AI does not naturally think about what happens when requirements shift, when the codebase grows, or when another developer has to modify this six months from now. It optimizes for the output in front of it, not for the system around it. That gap is exactly where experienced judgment lives.

A junior developer might see the same output and think it looks fine, because it does look fine. What they cannot always see yet is how it will behave when something changes around it. That judgment is not something you can prompt your way into. It comes from having seen enough things break.

If you are earlier in your career, this is not a reason to panic, but it is a reason to be intentional. The repetitive work that used to teach you how things connect is being automated, which means you have to find other ways to build that understanding deliberately. The good news is that learning has also gotten easier. You can take a well-known open source project, something like Rails or Linux, and ask AI to walk you through how a specific part works. When you do, push further than the answer. Ask why it was built that way, not just how it works. That habit is what separates developers who are actually learning from the ones who are just collecting answers.

The developers who will grow in this environment are the ones who use AI to understand systems faster, not to avoid understanding them at all.

What This Means

I did not stop being an engineer.

I stopped being a typist.

The craft is still there. It just looks different now. Less time at the keyboard, more time thinking about systems. Less writing, more reviewing. Less implementation, more direction.

If anything, the parts of the job I find most interesting, the architecture decisions, the problem framing, the moments where you push back and say "I think we are solving the wrong problem", those parts have more space now.

The 10 lines I wrote last week? Those were the lines that actually needed a human.