DEV Community: Forrester Terry

Before You Build Anything With A.I., Write Down What Right Looks Like

Forrester Terry — Tue, 29 Sep 2026 16:30:00 +0000

The team meets. Everyone is excited. Someone opens a chat window and types "build us a dashboard that tracks our renewals." Twenty minutes later there is a dashboard. It has charts. It has a dark mode. It looks amazing.

Then the person who actually handles renewals every month looks at it and says, "That number is wrong."

Nobody can say why and nobody wrote down what right was supposed to be.

Why this step matters so much

A.I. is really good at making things that look finished. That's the magic, and it's also the trap.

What it can't do is know what "right" means for your work. It doesn't know that a charge on the 3rd is normal but a charge on the 30th means someone forgot to cancel. It doesn't know which column in the export can't be trusted. You know that, or someone on your team does.

That knowledge is the most valuable thing your team brings. Getting it out of people's heads and onto the page before anything gets built is where most of the win comes from.

What it looks like in practice

Say the project is tracking software subscriptions. You have a list of what your team pays for, and a card statement of what actually got charged. The goal is to catch surprises.

Before anybody prompts anything, write three examples by hand.

A normal one. "Design tool, $15 a month, charged on the 5th, matches the list. Nothing to flag."

A wrong one. "Survey tool. The list says $20 a month. The card says $340. It renewed annually at a new price. Flag it."

A weird one. "A $9 charge from a vendor nobody recognizes. Not on the list at all. Flag it and find out who owns it."

Three examples, ten minutes. Now you have something to hand the A.I., and something to check its work against. When the tool says "everything looks good," you can run your three and know whether that's true.

The weird one is usually the most useful. It's where the real work lives, and it's the case the A.I. may quietly skip.

Tips for getting started

1. Start with a small slice of real data. Twenty rows beats twenty thousand. You can read twenty rows yourself and spot what the A.I. gets wrong. Stick to data and tools you're allowed to use, and leave out anything sensitive you don't need.

2. Write your examples before you prompt. One normal, one wrong, one weird. If you have issues here, you may need to spend more time sorting your data and approach. That's a great thing to find out on day one instead of week three.

3. Decide what "wrong" looks like. One sentence is enough: "This is wrong if a charge shows up that isn't on the list." I wrote more about this in Checking A.I. Work is Hard. If you can't name what broken looks like, you'll end up with misleading results.

4. Pick the smallest version that helps someone next week. Skip the full vision for now. Find the one piece that would save somebody real time on Monday. A spreadsheet of flagged charges is a win. The dashboard can come afterwards.

5. Let the person who knows the work be the judge. On a mixed team, the most important person in week one often isn't the one writing code. It's the person who can look at an output and say "that's wrong, and here's why." If that's you, everyone on the team will need you.

6. Make the A.I. ask questions first. Give it your sample and your examples, and tell it not to build anything yet. Let it interview you. The questions it asks will show you what your team hasn't decided.

Tips particularly for developers

Turn the examples into tests. Your team's hand-written cases can become your first test fixtures. Every change then gets checked against what the team said right looks like.

Don't let the agent edit the examples. Keep them in their own file and mark it read only. If a test fails, the code is likely wrong, not the example. Agents love to "fix" a failing test by changing what it expects.

Add an example every time something surprises you. Every bug the domain expert catches becomes a new case. By the end of the project you have a real test suite written by the people who know the work best.

Prove the logic before the interface. A small script that reads the sample and prints the flags is a great first deliverable. Once the flags are right, the UI is the easy part.

Wrapping up

The tools keep getting faster at building. Knowing what right looks like is still on us, and it's the part that makes everything else worth building.

So before your team opens a chat window this week, grab a whiteboard, pull twenty rows, and write down three examples. It takes 10 minutes, and will be very worth it.

Good luck to everyone kicking off something new.

Example prompts

Before you start

Here is a small sample of our data and three examples of what correct
output looks like, including one that should be flagged. Do not build
anything yet. Read everything, then ask me the questions you need
answered to get this right. Ask them one at a time.

Here is what we want to build: <one or two sentences>. What is the
smallest version of this that would still be useful to someone next
week? What would we leave out, and what would we lose by leaving it out?

Writing your examples

Here is a sample of our data. Help me write examples of correct output:
one normal case, one that is clearly wrong, and one edge case that is
easy to miss. Don't guess at our rules. If you are not sure how a case
should be handled, ask me.

Before it builds

Before you build anything, restate in plain language what "done" means
for this project, and list how each of my examples should come out. If
anything I've told you conflicts, point it out.

After it says it’s done

Run my examples through what you built and show me the result for each
one next to what I said it should be. Do not change the examples. If
any don't match, tell me which ones and why.

What kinds of cases did my examples NOT cover? Give me three new
examples I should add, and tell me how you currently handle each one.

For developers

Turn examples.md into test fixtures. Treat examples.md as read only.
If a test fails, fix the code, never the expected result. If you think
an example itself is wrong, tell me instead of changing it.

26 Ways to Use Coding Agents for Non-Coding Tasks

Forrester Terry — Tue, 15 Sep 2026 16:56:03 +0000

Most people think of coding agents as tools for just writing code. But they can be effective for a lot more than that! If it has a command line, an API, or a screen, a coding agent can usually operate it.

For this post I figured folks could jump around and look at what they find interesting. There is a quick table of contents below to let you select what you want.

In this post

How I found these examples
- 1. Digging through my own agent history
Cloud, money, and store ops
- 2. The cloud spend report
- 3. Publishing a game to the App Store and Google Play
- 4. Setting up subscriptions through admin APIs
- 5. A cost-per-user model
Media production
- 6. A marketing kit for my food tracker
- 7. A demo video set, rendered around midnight
- 8. A commercial from six clips and a jingle
- 9. A band that doesn’t exist
- 10. Recording gameplay with OBS
Eyes on the screen
- 11. An unattended UX review
- 12. Vision-driven testing
The manager’s copilot
- 13. Launches: before, day-of, and after
- 14. How our team’s work actually flows
- 15. The stray K
- 16. A kernel vulnerability, checked and patched
- 17. Planning a team event
Home lab and personal IT
- 18. “Is something jamming my audio card?”
- 19. A home lab, set up over SSH
- 20. A VPN on my Raspberry Pi
- 21. Rescuing a new inference server
Life
- 22. A road-trip playlist for my mom
- 23. 11 years of my Spotify data
- 24. Reading my old Facebook data
- 25. Kitchen timers and a meal plan
- 26. An AI phone receptionist
When it goes sideways
Patterns that worked
Try it

How I found these examples

1. Digging through my own agent history

To write this post, I asked Claude Code to go find the examples for me. Seven agents ran in parallel and swept 356 project folders, 6,818 of my past prompts, and the job history from FOREMAN, a tool I built to run coding agents unattended. They came back with about 80 examples.

This post counts as example 1, haha! Here are the other 25 worth sharing.

Cloud, money, and store ops

2. The cloud spend report

I asked for an expense report across all of my team's Google Cloud projects: what we aren't using that still costs money, what we could scale down, and what is expensive but actually used. I told it to use the gcloud CLI and to MAKE NO CHANGES. It swept every project my account could see, read-only, and wrote it up. The headline: about 59% of the spend it could identify was Cloud Run instances kept online 24/7 and sitting almost entirely idle. I then had it rewrite the report for leadership and link it from the ticket. (NOTE: using a Read Only Service Account and env isolation is best when allowing an LLM to drive your cloud infra. We don't want boo-boos...)

3. Publishing a game to the App Store and Google Play

For my game MagLava, the agent found the store credentials I had staged in Keychain, filled in the store listings in seven languages, uploaded builds to TestFlight and Google Play testing, and pushed the signing certificates into CI. It also rendered 126 localized screenshot cards, a trailer, and an App Store preview. The release notes it keeps are nice.

4. Setting up subscriptions through admin APIs

For my food tracker app, it used the RevenueCat and Google Play admin APIs to create the subscription plans: monthly and annual, with a 7-day trial. It did a dry run first, because Play base-plan IDs can never be reused once created. Along the way it noticed RevenueCat was still on sample settings, which would have made Pro silently fail.

5. A cost-per-user model

For the same food tracker app, it built a cost-per-user model from real usage, noticed billing export had never been turned on, and changed one Cloud Run setting that took the idle cost from about $37 a month to about $0.05.

Media production

6. A marketing kit for my food tracker

A hero video, three short clips, captions, 23 generated food photos, Play Store screenshots, and a feature graphic. The pipeline writes the narration first (Gemini text-to-speech), so every on-screen action is held exactly as long as its voice-over. Playwright drives the app at phone size, Remotion puts the footage in a phone frame, and ffmpeg mixes in a music bed. Everything is captured from a seeded demo account, so no real user data shows up anywhere. It did however use a really old TTS model, so it sounds bad.

7. A demo video set, rendered around midnight

For FoFo Care, a Mac help app I built a while ago, the agent recorded the real packaged app, generated narration, captioned it with Whisper, composited it in Remotion, added music, and checked its own output. It even left notes on bugs it ran into while recording. OBS was installed, but it chose not to use it. It captured the app window through Chrome DevTools instead, which needs no screen recording permission and keeps desktop clutter out of the shot.

8. A commercial from six clips and a jingle

For "Robots Save The Call," it mapped the song's beat (120.96 BPM) and cut on it, generated four voiceover takes and checked each one by transcribing it back, then rendered nine versions across aspect ratios. Here is the full ad.

9. A band that doesn’t exist

One FOREMAN job, $3.90: a made-up band called Saltline with a persona, lyrics, four songs, cover art, and a website.

A note on the music: the four tracks on that site are 30-second instrumental clips from Google's Lyria model, and honestly they are... not the best yet (getting there). The good stuff came later. Here is "Super Quick," a full song I made for the band with Suno:

Listen: Super Quick, a song made with Suno for the Saltline band, about 2 minutes.

10. Recording gameplay with OBS

I made a StepMania song pack out of my own songs using A.I. and wanted a gameplay video for each one. I asked if it could automate it: open the game, play each song on Hard, and have OBS record. I set up the OBS scene, told it to go, and 13 videos landed about two minutes apart, each chart played by the game's AutoPlay.

Eyes on the screen

11. An unattended UX review

I told the agent I needed a general test and UX review of my app's pilot build, to work as autonomously as possible, and that OBS was set up if it wanted to record. It drove the real packaged app with Playwright over six passes and came back with a prioritized bug list, 14 annotated screenshots, and a two-minute walkthrough video. A couple of the finds I would not have caught quickly: the chat invented a fake technical reason when a tool was behind the paywall, and a confirmation dialog showed text that was written for the LLM, not the user.

The OBS part: it tried OBS first. OBS pulled in desktop clutter and audio, and one of its automation calls crashed OBS outright. So it switched to recording the app window through Chrome DevTools, on its own. The same tool that worked great for gameplay was the wrong tool here, and the agent figured that out without me.

12. Vision-driven testing

This one has been a long time coming. I have been chasing vision-driven testing for a while: started as a screen-grid experiment with a local vision model, now an auto-tester that screenshots the screen, lets Gemini pick the next click, and handles native macOS dialogs a browser driver cannot see. The goal every time has been the same: download one of our work apps and run it to completion.

The manager’s copilot

13. Launches: before, day-of, and after

I have started using agents at all three points of a launch.

Before: For my food tracker, I asked "am I actually ready to launch this thing?" and had it check the marketing site, app, backend, security, payments, and deployment, then save findings to a file. My favorite part: it later corrected one of its own findings ("My original finding was wrong on the facts") after checking the actual database.
Day-of: At work, the morning we rolled out a new feature, I asked it to check recent logs and tell me how it was going for folks. READ ONLY. It queried the logs and database, built an HTML report, and screenshotted it so I could share it.
After: When one of my side projects hit v1, I asked it to look at all my git commits and all my Claude chats for the project and figure out how much development time went into it.

14. How our team’s work actually flows

I asked it to use six months of git and Jira history to answer three questions: how long does it take us to get work done, how much carries over from sprint to sprint, and is our pace sustainable? It built an HTML report. I cannot show the real one, so the chart below uses made-up numbers for what most teams see: most of a ticket's life is spent waiting, not being worked on.

15. The stray K

We started getting alerts that users were having issues. On day one, the agent traced it to a vendor service being down. On day two, the same alerts came back. I asked it to check if the vendor endpoint was up, without posting to it or authenticating. It was healthy. So it pulled the deployed source from the storage bucket and found a single stray K character in one file. That threw an error inside a success handler, the error handler swallowed it and reported failure, and the vendor call had actually succeeded the whole time. It was live for about 12 minutes. I had it write up the incident for our lead developer.

16. A kernel vulnerability, checked and patched

When a Linux kernel vulnerability was announced, I asked if it affected any of our stuff, read-only. It checked across our projects, identified already patched VMs over SSH one at a time, and wrote a Slack summary I could send my boss.

17. Planning a team event

My agent also helped plan our team event: a participant journey, an agenda, a dry run against a fake team, and a live site.

Home lab and personal IT

18. “Is something jamming my audio card?”

My Mac would start playing audio and then immediately stop. I asked the agent in the middle of a video project. It checked audio processes, virtual audio drivers, and system logs, and found the real problem: my JBL headset was stuck in hands-free mode, the 16 kHz mono mode meant for calls, instead of stereo playback. Nothing to do with code at all. So turned off headphones and things worked again!

19. A home lab, set up over SSH

I have four machines at home for running local models. Agents did the setup over SSH: firewall rules, a scheduled task to keep WSL running on the Windows box, text-to-speech, speech recognition, and local model servers, a LiteLLM proxy, SearXNG search, and Langfuse tracing. Every service has a check script it can rerun. Now all of it is saved as a skill, so any future session already knows the boxes and the traps we have already hit.

20. A VPN on my Raspberry Pi

My agent set up a VPN on my Raspberry Pi with an auto-rollback timer, so if the VPN cut off SSH, the change would undo itself.

21. Rescuing a new inference server

At work, a brand new server came up with a (too) bare-minimum install (no sudo, no DNS). The agent got the machine working over SSH.

Life

22. A road-trip playlist for my mom

I was going to San Francisco with my mom (likes 70s, R&B, soul) and my brothers (video game music, electronic). I asked for a playlist called "SanFranTripping," at least 30 tracks, with a good mix of what we all like, saved straight to my Spotify. It used my listening history and my Spotify connection and came back with 60 songs.

23. 11 years of my Spotify data

I requested my full streaming history from Spotify and had an agent turn it into a single-page HTML report: 11 years, 394,588 streams, 17,332 hours. It was research for FoFo Radio, an AI radio station idea, so the agent went well past totals.

It ranked my top artists and tracks. "Pogo" by Digitalism wins by a mile, with 1,289 plays.

It split out the songs I never skip, which it labeled as "A-list" rotation candidates for the station, from the ones I bail on within seconds.

And it found my longest "listening sessions," using a rule of no more than 10 minutes between tracks. The top one ran 47 hours and 741 tracks.

24. Reading my old Facebook data

I also exported my Facebook data and asked an agent to write about me from it, to "learn about myself from back in the day… the good moments, the sad moments." That one was a trip.

25. Kitchen timers and a meal plan

My self-hosted assistant, Hermes, has set a cookie timer and a muffin reminder, and made me a meal-prep plan in Google Sheets.

26. An AI phone receptionist

For an AI phone receptionist I set up, the agent configured Twilio, my router, and DNS. The receptionist answered my test call with "let me transfer you." My response: TRANSFER ME TO WHO????

When it goes sideways

It is not all smooth. A few of my favorite misses:

An agent running my art shop created about 800 Etsy draft listings I did not want.
I found out my assistant could reach my Mac directly casually via conversation: "you are not sandboxed??"
Deploying this blog, the agent would not listen to my upload instructions: "STOP IGNORING MY DIRECTIONS."

Patterns that worked

Say READ ONLY or MAKE NO CHANGES in the prompt. Scoped API Keys!!! Most of the examples above started this way.
Dry run first for anything that writes, creates, or can't be undone.
Auto-rollback timers for network changes, so a mistake can undo itself.
Disable, don't delete. You can turn something back on. You can't un-delete it.
Stage credentials in Keychain so you are not pasting secrets into the chat or storing in plaintext on disk.
Take a snapshot before admin changes, so you can restore.

More on this in Checking A.I. Work is Hard.

Try it

There is a lot you can do with an a.i. coding agent. In these examples, I typically used Claude Code via Max subscription -- but a lot of other setups work too.

Next time you wanna get a big task done, if you know the steps and can provide the APIs, see if A.I. can do it!

Checking A.I. Work is Hard: How I Handle It

Forrester Terry — Wed, 09 Sep 2026 17:18:52 +0000

You spent a few good cycles, did some troubleshooting, and finally, it works!

With A.I., "working" does not always mean "ready to go" though. Something can work but have:

Security issues
Resource and cost issues
Usability issues
Incomplete features

We are making way more code than we can reasonably review.

The takeaway is not that you should read harder. You cannot read your way out of this. The takeaway is that you have to move the checking somewhere it fits.

So what should we do to handle this?

Whether you are shipping code, a spreadsheet, a policy draft, or a slide deck the A.I. built for you, here are some things to try.

1. Check the plan first, not the output. The plan might be forty lines or so, compared to output that is three thousand. Before you prompt for what you want to build, ask for the approach first: read that carefully, approve it, and then let it build. Ask it to do some research before starting.

2. Define what "wrong" would look like before you start. Try writing out: "X is wrong if Y does not match Z." Then try reviewing the work afterwards against this list.

3. Ask it what it changed that you did not ask for. "List every change you made that was not required by what I asked. For each one, say why." A.I. tools quietly improve things. Renamed a field. Moved a file. Swapped a library. Individually reasonable, collectively how you end up somewhere you never chose.

4. Focus on consequence, not size. Careful not to spend too much time reading every change and line. For critical functionality, read more closely. For other things, read at a high level.

5. Do a security pass. Once the A.I. claims to be done, tell it to check the work it did for any security issues or gaps. I have seen the A.I. forget to implement authentication and basic security from time to time, especially while working on bigger tasks and prompts.

6. Ask the A.I. to explain what it did. Sometimes I ask my agent to give me a summary of what it did and why. You can also ask it to explain how to manually test components or chat through any questions you have.

A few bonus ones for developers

Commit often, not once per session. Be sure to do commits per milestone or feature. This makes things way easier to review ultimately, since you get smaller chunks of code changes.

Review the test, then lock it in. Have the A.I. write the test from the requirement before it writes the code. Then review the tests to ensure they evaluate what you need. From there, you can use these tests as your bar for the coder. Do not let the coder adjust the tests once locked in, this is key.

Some things are best for humans. If the risks are high, you should double check the work yourself. Do not let the automation handle critical actions like deletes or live data manipulation without supervision and review.

Commit before you start. Otherwise, you risk the coding agent wiping out your uncommitted changes. I had this happen to me once, so it is worth throwing out there.

You own it

Though we can move faster than ever, we need to make sure our workflows and processes for quality keep up.

By creating a process, and having some checks before and after you start, you can keep up with the new pace at which everyone is moving.

Example prompts

These are ones I have used, cleaned up so you can paste them as is.

Before you start

Get a plan you can read instead of output you cannot.

I have outlined the requirements and specs for this project in <FILE>.
Before we write any code, do the relevant research and read the whole
requirements file, then write a detailed design document that will guide
the implementation. Save it as design.plan.md in the docs/ directory.
I will review it before we start building.

Make every requirement fail-able.

Rewrite these requirements so each one has a stable ID (REQ-001, REQ-002)
and an "Acceptance:" line describing exactly what must be true for it to
count as done. If a requirement cannot be given a checkable acceptance
criterion, flag it instead of guessing.

Anything it flags is something you had not actually decided yet.

Confirm you have a clean starting point.

Before we begin, confirm the working tree is clean and everything is
committed. If it is not, stop and tell me what is uncommitted.

Guardrails to paste in every time

Stop it from acting before you have answered.

DO NOT MAKE CHANGES WITHOUT ASKING. First investigate and answer my
question. Do not touch the code until I say go.

Stop it from quietly editing the plan.

Do not change the scope of our work in PROGRESS.md. If work remains, we
handle it later. Never delete tasks.

Make the dry run mandatory for anything that touches real data.

Default to read-only. Before any action that writes, deletes, or changes
live data, show me the full plan of what you are about to do and wait for
me to say go. One plan at a time, no chaining. If any part of it cannot be
undone, say so explicitly at the top.

After it says it is done

Find out what it changed on its own.

List every change you made that was not required by what I asked.
For each one, say why you made it.

Run a security pass and send it somewhere you will actually read it.

Review this application and make sure it is secure, both when run as a
normal user and as an administrator. Include code snippets and links to
the relevant code so I can review each finding myself. Put everything in
an MD document in the docs folder rather than answering here.

Shorter version for a smaller project:

Do a security review of this entire app and repo. Identify anything that
needs to be addressed before it goes live.

Writing findings to a file instead of the chat window is a nice trick. When the chat is gone, the file is still there tomorrow.

Ask how to check it yourself.

How do I test this myself? Write a short guide covering how to manually
verify each piece, including anything I need to set up first.

Asking for testing instructions hands you something you can go check independent of the a.i. coder

For developers

Lock the tests before any code exists.

Write the tests from the spec first, before any implementation exists.
Once I approve them, they are locked: you write code to pass those tests
and you do not modify or weaken them. If you believe a test is wrong,
stop and tell me. That is a conversation, not an edit.

A.I. Made It… But Can You Explain It?

Forrester Terry — Tue, 01 Sep 2026 15:50:01 +0000

Imagine: You are in a meeting with a vendor. It is going fine. Then they ask a completely normal question:

"So, how exactly does X work?"

And you stall. Not because it is a hard question. Because you shipped X, you own X, and you did not actually write X. Your A.I. did, and you skimmed it, and it worked, and you moved on.

I had this happen to me. It was no big deal, I explained myself and found the answer, but I did not like the feeling of not knowing.

The worry is real, and it is not new

One of the big fears about A.I. is what it does to how much we learn, and how well.

We are already leaning on it hard. People get their news explained to them. Kids get their homework answered. We get our custom software written. These are genuinely great use cases.

The problems start when:

We read the A.I. summary and never look at the actual source.
We get the answer instead of doing the work, so we never actually learn much.
We accept the code without understanding it, and then something breaks and we have no idea where to even start looking.

For a developer or IT professional, the bill comes due in three ways. You learn less about how your own system works. Your troubleshooting gets slower and shallower. And your codebase quietly turns into a liability, because you are responsible for something you cannot explain.

None of that shows up on day one.

The Manager Parallel

I have kinda lived a version of this transition, and so has every manager reading this.

When you move from writing code all day to managing people who write code all day, you produce less. Way less. And you do lose a little of your edge. That is real.

But something else happens. You start exercising different skills, and they turn out to matter a lot: reading a system at the architecture level, asking the question that unblocks somebody, knowing which risk is actually the risk. You stop being the person who types the most and you become the person who understands more.

And honestly, your "old" skills become a foundation for those new skills. For non-technical folks, your expertise in your domain becomes incredibly useful for directing the output and checking the quality.

So the goal is not "use less A.I." The goal is to make sure the thing you traded away is the typing, and not the understanding and awareness.

How I Avoid This Issue

I let A.I. do nearly all of my coding, and I have not felt myself getting dull. Here is what that actually looks like for me:

General Tips

Make it explain itself, on purpose. I ask a lot of "why" out loud. Some prompts I use constantly:

"Explain this like I have to defend it in a design review tomorrow."
"What approaches did you consider and reject here, and why?"
"What is the riskiest part of this change?"
"What would break if traffic went up 10x?"

Any of those will teach you something or even catch real problems.

Stop on the words you do not know. A term goes by that you cannot define: so stop and ask, or go look it up. Small but fundamental and very powerful.

Recite it back before you ship it. For anything meaningful, I close my agent and try to explain the change or work to myself in my head. If I cannot get through it cleanly, I should review the work and plan again.

Keep building things that challenge you. Do it on your own time or as time allows, on something you actually care about. Run into the wall, get stuck, try again. Nobody is watching, there is no deadline, and it is still a quick way to learn anything.

Watch how other people use theirs. Everyone has worked out some workflow trick. Ask them.

Tips Particularly For Developers

Read the logs yourself, especially when the agent is circling. Let the A.I. read them first, absolutely. But the moment your agent takes its third swing at the same bug, that is your cue to open the logs personally. Nine times out of ten there is a line in there that it skipped right past, and you spotting it is what breaks the loop.

Use the design phase as your learning budget. Before anything gets built, I will have it lay out two or three approaches with real tradeoffs, and tell me who else does it that way. That is the requirements and design part of the SDLC. This is where most of my exposure to new frameworks and patterns comes from now.

Read the diff instead of the file. Telling yourself you will "skim the whole file later" can end up a daunting task. Reading the diff is easier and it is the difference between approving code and reading code. If something looks weird in there, stop and ask the bot about it before it merges.

So…

Like I said, I let A.I. write most of my code. But my role remains involved, I am just not doing the actual writing anymore. I'm still testing, still designing, still exploring and asking questions.

Next time you finish something, try asking this to yourself.

"If someone stopped you in a meeting and asked how it works, could you tell them?"

Not line by line. Just the shape of it, out loud, without opening your laptop or asking your agent.

If yes, you are fine. Go faster, fam!

If not, there is likely something new for you to learn.

Product Shipped! But Now What? The Part I Forgot About.

Forrester Terry — Wed, 15 Apr 2026 08:03:00 +0000

As a developer, I love to build.

Planning it out, picking the stack, getting into flow state, watching something go from nothing to a working product.

That part is fun. And with AI tools in the mix, that part is faster than ever.

But here's what I've been facing in reality: shipping the code is maybe 30% of the work. The other 70% is everything that comes after.

I want to walk through what that looked like in practice for my recent project. Not quite a tutorial or success story. Just an honest look at the messy middle.

The Build

A few months ago I built FoFoClip, a tool that takes a podcast episode and turns it into polished, ready-to-post video clips. You upload your audio, pick a style, and get clips delivered to your inbox. Supports 6+ languages.

The tech stack is my usual go-to: Vue 3, Quasar Framework, Firebase (Hosting, Auth, Cloud Functions, Storage, Tasks), with AI handling the heavy lifting on the backend for transcription, clip selection, and caption rendering.

I used AI pair programming for the entire build. Claude for architecture decisions and complex logic, Claude Code for fast iteration, and a workflow where I'd break things into focused prompts rather than trying to generate everything at once. If you've read my earlier posts, you know I'm a big believer in this approach.

The build took about a solid week of evening work. Prompting, testing, revising, prompting again. Security reviews. Edge case handling. Making sure the clip styles actually looked good across different types of content.

And then it was done and deployed! Real product offering, real Stripe integration, real pricing.

I felt great. I had built something real. Until haha...

The Silence

Here's the thing about launching a product as a solo developer: unless you built some hype or awareness... nobody is waiting for it.

There's no Product Hunt launch with 500 upvotes. No Twitter thread going viral, etc. I push to production, maybe tell a few people, and then... quiet.

I told my mom. I posted a bit on social media. And then I kind of waited for something to happen.

Nothing happened.

So I did what a lot of us do when things aren't moving. I went and worked on other projects. I had plenty of them. It felt productive. It felt like I was still shipping. But really, I was avoiding the harder work that FoFoClip needed.

The YouTube Ads Experiment

Eventually I came back to FoFoClip and decided to throw some money at it. I made a 30-second video ad, set up a YouTube campaign targeting podcast-related search terms, and put $50 behind it.

The results: 59 website visits. Zero conversions.

While I was proud some people were clicking (though honestly, they may have been ghost clicks...) not one person signed up. Not one person bought a DANG THING.

Now, $50 on YouTube ads is barely a test... but zero conversions out of 59 visits still stings. It made me look harder at the landing page, the messaging, the trust signals, all the stuff that has nothing to do with code quality.

A couple things I found:

Perhaps the pricing was too high?
Perhaps the brand was confusing. The product is "fofoclip," the domain is clip.fofo.dev, support emails come from sweetpapatechnologies.com. That's a lot of "who are these people?"
I had no analytics that actually worked. My cookie consent banner was so privacy-friendly that most visitors opted out and never got tracked. I literally could not see my own traffic.

None of this is a code problem. This was even bigger. It was a marketing problem!

Google Won't Index My Site

After the ads experiment, I noticed that searching for my site on Google returned nothing. I assumed it was a technical issue. Spent time making sure everything was statically rendered at build time. Checked my robots.txt. Checked my HTTP headers. Checked for noindex meta tags. Everything was clean.

Then I looked at Google Search Console and saw this status:

"Crawled - currently not indexed"

So... basically Google successfully crawled my site. It confirmed that indexing was allowed. It fetched the page without errors. And then it chose NOT to index it.

The reason likely: trust. My site has zero backlinks. No referring pages. No external mentions anywhere on the internet. Google looked at clip.fofo.dev and essentially said: "We see you. We just don't have a reason to care yet."

This was a humbling realization, because I have never had that happen before... You can have perfect headers, perfect SSG, perfect robots.txt, and Google will still shrug if you haven't done the non-technical work of building credibility on the web.

What I'm Learning

I don't have a framework for this or big tips. I'm still in the middle of it and still learning. But here's what's becoming clear:

Building can become the comfort zone. Developers default to solving problems with code because that's what we know. But sometimes the issue is much more about UX and non-architectural

Marketing is a skill, not a chore. I used to think of marketing as something you tack on after the real work is done. It's not, it is very much a big and standalone thing. Understanding why someone would trust a new product enough to pay for it, that's a design problem just as interesting as any architecture decision.

The build never really ends, but it needs to share bandwidth. I still have bugs to fix and features to add. But if I spend all my energy on code and none on outreach, content, and trust-building, I'll have a really well-engineered product that nobody uses.

Talk about what you're building. This is something I'm getting better at. Blog posts, Bluesky updates, dev.to articles. Every piece of content you put out there is a signal to both humans and search engines that you exist.

A.I. is super helpful for beyond just coding. I was able to make ad content, promotional material, and get all sorts of questions I had about marketing answered.

For a bootstrapped solo project, content might be the most cost-effective marketing channel there is.

Where I'm At Now

FoFoClip is still live at clip.fofo.dev. I'm still working on it.

I also have a bunch of other SPT projects in various stages. The temptation to go heads-down on those is real. But I know from experience that building another thing won't solve the problem that this thing has.

The code was the easy part. Of course there were challenges and headaches along the way, but getting people to find my service, trust it, and pay for it... that's the actual product work. And I'm just getting started on it.

It will be interesting to see if this app and service gets any use, and serves a purpose for someone.

That is what makes coding fun, is seeing the product come to life.

Your AI Coder Will Go Rogue If You Let It (Here's Some Tips to Stay in Control)

Forrester Terry — Thu, 22 Jan 2026 05:37:04 +0000

Lessons from Building with AI Coding Assistants

So I've been building a lot of stuff with AI coding assistants lately—like, a lot. And one thing I keep running into is this: the AI will just... make decisions for you if you're not paying attention. Sometimes good ones! But sometimes it'll confidently march you right off a cliff.

This isn't me hating on AI coding. I'm fully bought in at this point. But there's a difference between using an AI coder and actually directing one.

Here's some stuff I've learned that might save you some headaches.

Challenge It When It Changes Your Approach

AI coders have opinions. They'll make architecture decisions without asking you first, and if you're not watching closely, you might not even notice until way later.

The Websocket Ambush

I was building something using pipes—a deliberate choice for my use case. Somewhere mid-conversation, the AI just... switched to websockets. No "hey, should we consider this?" No discussion at all. It just started writing websocket code like we'd agreed on it.

We hadn't agreed on anything.

I had to stop and say "no, go back, I want pipes for this." And it did! Immediately! But if I hadn't caught it, I would've ended up with an architecture I didn't want.

The "Write Scripts to Disk" Thing

Same project, different issue. The AI started writing executable scripts to disk as part of its solution. Technically functional? Sure. A good idea in most production environments? Absolutely not—that's a security red flag in a lot of contexts.

I had to explicitly ban that approach before it became a problem.

The pattern: AI optimizes for "does it work." You have to optimize for "is this appropriate for my situation"—security, compliance, maintainability, all that stuff that AI doesn't naturally think about.

Tell It to Do Its Own Testing

This one saves me a bit of time: make the AI test its own code before giving it to you.

The Bad Command Loop

I kept getting commands and code that would fail. Copy, paste, error. Copy, paste, different error. Over and over. Basically the AI was using me as its test runner.

Then it clicked—the AI can execute commands itself. It can iterate on its own. It can figure out what actually works before handing me something.

So I told it: "Test this yourself first. Iterate until it works, then show me the solution."

It actually worked!

It ran through several failed attempts on its own, found something that actually worked, and gave me that. All that debugging time I would've spent? Gone. The AI did it for me.

The takeaway: If you're testing code that keeps failing, ask yourself—could the AI have tested this itself? If yes, just tell it to do that. You're the architect, not the test runner.

Sometimes You Need Research, Not Code

Sometimes the AI is stumbling because it doesn't have enough context. It's trying things, hitting walls, trying more things—and you're both stuck.

Using Another AI to Unblock the First One

I had my AI coder grinding through a problem, throwing idea after idea at it. Nothing was sticking. We were both frustrated (yes, I personify it, don't judge me haha).

Here's what I ended up doing: I opened a separate chat with Gemini Pro—not to write code, but just to talk through approaches. "Hey, I'm trying to do X. What are the proper patterns for this? What should I be thinking about?"

Gemini did research from the web and gave me a solid breakdown of the right approach. I took that conversation and fed it to my AI coder.

Instant clarity. It stopped flailing and just... did the thing.

Why this works: Your coding AI is optimized for implementation. Sometimes you need a "thinking" conversation before you can have a "building" conversation. Just like having your requirements figured out before you start designing or building.

If you have access to Deep Research tools, those work great for this. Let the research tool go deep on the problem, then bring those findings back to your coder.

AI-Generated Deployment Scripts (Carefully!)

Okay, this one needs a big warning label, but it's too useful not to mention.

You can have your AI write helper scripts for cloud CLI commands—deployments, configuration, infrastructure setup. This saves a ton of time. But you absolutely have to review everything before running it.

Terraform Became My Friend

I needed to set up a backend app—VM or Cloud Run, SSL certs, static IPs, load balancer stuff. Lots of moving pieces.

I used Deep Research first to figure out the best approach. What's the right pattern? What services do I need? What order should things happen?

Then I had the AI generate a Terraform script based on that research. The script pre-checked dependencies, let me input my variables cleanly, created everything in the right order, and actually worked on the first run.

Honestly, this whole experience made me fall in love with Terraform. AI generating infrastructure-as-code plus Terraform's built-in safety features (plan before apply) is a really nice combo.

The Giant Caveat

ALWAYS ALWAYS review deployment scripts before running them. Check for:

Destructive actions (destroy, delete, rm -rf anything)
Resource creation that might cost more than you expected
Security group or IAM changes that could open holes
Anything touching production data

The AI doesn't understand the blast radius of infrastructure changes the way you do. It will happily generate a script that nukes your database if that's technically what you asked for.

For bigger infrastructure stuff, Terraform is great specifically because it has built-in safety mechanisms. But even then—review the plan output before applying.

Always Review, Always Ask Why

This is kind of the meta-lesson that wraps everything else together.

AI coding assistants will give you code. Lots of it. Fast. The temptation is to just ship it and move on. Don't.

What reviewing actually means:

Actually read the code. Not skim—read. Does the logic make sense?
Ask for reasoning. "Why did you use this approach?" is totally valid. If the AI can't explain it well, that's a red flag.
Ask for documentation. Ask the AI to document how things work, or document design decisions etc. post development.
Give feedback. "This is too complex" or "Can we simplify?" pushes it toward better solutions.
Check the edges. AI is great at the happy path. It's often weak on error handling, edge cases, and security stuff.

Wrapping Up

After doing a lot of AI-assisted development, my productivity has genuinely gone way up. But not because the AI replaced my thinking—because it amplified it.

The pattern that works:

You decide the approach. AI implements it.
You validate the output. AI iterates based on your feedback.
You catch the context-specific stuff. AI doesn't know your infrastructure, your security requirements, or your users.
You stay curious. Ask why. Push back. Give direction.

We're the architects.

A.I. — The Amplifier: From Software Developer to Software Creator 🚀

Forrester Terry — Tue, 20 Jan 2026 16:00:00 +0000

A.I. will make the bad "badder", the rich richer, the poor poorer, the hopeful more hopeful, the doubtful more doubtful. It's given people the ability to do more with less—and less with more. It is the double-edged sword that is both blessing and curse.

The question isn't whether A.I. will be good or bad for humanity. It'll be both. We know this.

The real question is: How much of a force multiplier will it be on the things that matter most? And where will that take us?

What I'm Seeing Out There 📊

Let me be honest about what's happening in our industry right now.

Junior developer roles have collapsed. Entry-level tech postings fell 60% between 2022-2024, and Big Tech hired only 7% new grads in 2024. At the same time, the barrier to entry for creating has never been lower. Suno has 12+ million users making music. Over 15 billion AI images have been generated. GitHub Copilot users complete tasks 55% faster.

A.I. makes mistakes AND solves age-old math problems. It takes jobs and creates some. It's used to improve breast cancer detection throughput by 44%, and it's used in warfare and surveillance.

Among all this -- it is the end of software developers as we knew them—and the start of something new: The Software Creator.

❓ "Should I Still Learn Software Development?"

Short answer: Yes. These tools are not bulletproof. Not even close.

What I've Learned About A.I. Capabilities

I think of A.I. agents like employees I'm onboarding. Right now, A.I. performs at junior-to-mid level for routine, well-defined tasks—but falls well below junior on complex system changes and architectural decisions.

Task Type	AI Performance
Single functions (HumanEval)	90-96% ✅
Standard GitHub issues	70-76% 🟡
Complex real-world problems	17-23% ❌

The breadth of knowledge is WIDE, but not DEEP. I learned this the hard way building an AI-powered chatbot for my team—the thing could answer simple questions beautifully, but the moment someone asked something that required understanding our specific infrastructure (or a tool call gave bad info), it would confidently hallucinate an answer that sounded perfect but was completely wrong.

Additionally if you don't know how to ask, "WHY are you doing it that way?" or better yet, "WHOA, please don't do that, do this instead," you'll get taken down a rabbit hole of confident failure.

The Real Productivity Numbers (They're Messier Than You Think)

You've probably heard "AI gets you 80% there." The data tells a more honest story.

GitHub Copilot generates 46% of code for active users, but the acceptance rate averages only 30%—meaning 70% of suggestions get rejected. 66% of developers say their top frustration is "AI solutions that are almost right, but not quite." And here's the kicker: a METR randomized controlled trial found developers actually took 19% longer with AI—while believing they were 20% faster. 🤯

I've felt this myself. There's something intoxicating about watching code appear on your screen. You feel productive. But then you spend an hour debugging something the AI introduced three suggestions ago, and you realize your "80% there" was actually "60% there with new bugs."

Realistic ratio: 60/40 or 70/30. That "last mile" is longer than it looks.

🛠️ What Should You Actually Learn?

You don't need to know everything overnight. I didn't. I came into this field without a computer science degree and learned everything on the job over 11+ years. Buy tools for your garage as you need them—same principle here.

Start With the Foundations

Learn the basics first: variables, functions, classes. These are universal to any modern language. Here's my unpopular opinion: build something simple without A.I. first. That trial-and-error is what makes you stronger. It's what lets you recognize when the AI is leading you astray.

And learn Git. Non-negotiable. This will be important for keeping your code and the A.I.'s code on track.

Then Build Your Stack

Backend fundamentals matter—Firebase, Express/Node, Flask. Understand what an API is and how to stand one up. If you're working with AI agents, TypeScript + Zod (or Pydantic for Python folks) become critical. Type definitions and data validation are how you keep AI-generated code from doing something unexpected at runtime.

Pick up basic testing with Jest or pytest. Here's a common trick I practice: make the AI write tests, then make it run them. It's a forcing function for quality.

Security basics should be non-negotiable too. Don't put secrets in frontend code (I've seen this more than I'd like to admit). Understand OAuth and auth flows. Use a secret manager.

Level Up When You're Ready

Cross-platform frameworks like Electron, Capacitor, and Quasar open up new possibilities when you're ready for them. Docker is technically a "bonus" but honestly, just learn it. Your future self will thank you.

💼 "How Do I Get a Job?"

If You're Starting from Zero

The barrier for entry is higher now. I won't sugarcoat that. But I've hired people, and I can tell you what actually moves the needle.

First, build a real portfolio WITH A.I. Release software on GitHub that's actually useful. Demonstrate you can go from idea to reality. But here's the crucial part: understand it under the hood and be able to explain it. I've interviewed candidates who built impressive-looking projects but couldn't explain basic architectural decisions. That's a red flag.

Second, bring genuine enthusiasm. I'll take someone who's green but humble and eager over someone excellent but difficult to work with every single time. Your soft skills matter more than ever in a world where AI can write code. The human stuff—collaboration, communication, judgment—that's your edge.

Third, develop AI skills beyond basic prompting. Job postings for "prompt engineers" peaked in April 2023 and have plateaued since. Basic prompting is table stakes now. What employers actually want is system design and architecture, MLOps and production deployment, LLM fine-tuning and RAG development, and critical evaluation of AI outputs.

Jobs mentioning AI skills pay a 28% premium (~$18K/year), rising to 43% for multiple AI skills.

If You're Mid-Level or Beyond

~~Move into management because those jobs are safer. Right???~~

Nah. The data actually shows middle managers comprised 32% of 2023 layoffs, and companies like Microsoft, Amazon, and Meta are explicitly flattening org structures. "The Great Flattening" is real. I say this as someone in management—the title alone doesn't protect you.

What actually works is becoming a force multiplier. Use A.I. to do an amazing job at what your employer cares about. I've built reports and automations that would have taken weeks and compressed them into days. That's the kind of thing that gets noticed.

Learn the tools deeply. Explore, play around, but focus on what connects to your actual job. Build with A.I. agents—learn how to orchestrate them, multitask with them, and free up your time for the work that actually requires human judgment.

Lead without the title. Technical design, mentorship, and judgment are human superpowers. No AI is going to sit down with a frustrated junior dev and help them work through impostor syndrome.

This is what transforms you from Software Developer → Software Creator → A.I. Orchestrator.

🎮 How I Got Started with A.I.

Here's roughly how my journey went:

Phase	What I Learned
🎨 Image Gen	Started with Stable Diffusion. Check out Flux, Imagen, Midjourney
💬 Chatbots	ChatGPT, Claude, Gemini. Learned context windows, tokens, prompting
🤖 Coding Agents	Cursor, Windsurf, Claude Code—AI edits code locally
🔧 Building Agents	CrewAI, LangChain, MCP servers
🔬 Deep Research	Gemini Deep Research, NotebookLM for studying
🏠 Running Local	Ollama, vLLM, fine-tuning your own models, RAG

Take it one step at a time. I spent months in each phase before moving to the next. You don't need all of this at once.

⚠️ Real Talk: What's Coming

I'd be crazy to tell you not to be concerned. A lot is changing. But here's how I think about it:

A.I. amplifies what people already do—good and bad. People generally want everyone to be well off (so they can be well off too). And people don't like being squashed or oppressed.

We're going to figure things out, as we have before. But it'll take work.

What About "The Next Big Thing"?

You might hear about transformer alternatives, neurosymbolic AI, quantum computing integration. Here's my honest read on these:

Transformer alternatives like hybrid models exist (Jamba, Granite 4.0), but transformers remain central. We're seeing augmentation, not replacement. Neurosymbolic AI produced impressive results with AlphaGeometry, but no major LLM has shipped a general product yet. And quantum + AI? Jensen Huang estimates 15-30 years for "very useful" applications.

These are research directions to watch, not imminent paradigm shifts. Focus on what works today.

🎯 The Bottom Line

Yes, still learn software development. It's still worthwhile.

But understand this: the role is transforming. The developers who thrive will be the ones who become creators—people who can direct A.I. tools with expertise, know when to trust output and when to override, build entire systems (not just write code), and amplify their output through orchestration.

Be kind to each other, and be kind to yourself. Be curious.

The future will be great and problematic. You need to know how to spot deepfakes, understand security risks, and leverage the tools—otherwise you'll be pushed out.

But you've got this. 🤝

What's your experience with A.I. in your development workflow? Are you a skeptic, an enthusiast, or somewhere in between? Drop a comment below!

I Have Bipolar II and I'm a Software Engineering Manager. Here's What Actually Works.

Forrester Terry — Sun, 18 Jan 2026 17:00:00 +0000

I've been in higher education IT for over 11 years. I've gotten "Exceptional Year" ratings. I manage a team of four devs and a portfolio of 20+ apps.

I also have Bipolar II, diabetes, and I'm a recovering alcoholic — sober since 2020.

If you're a dev managing your own stuff, this is for you. Not quite the “inspirational” version, but real nonetheless.

The Real Version

The performance reviews say things like "force multiplier" and "technical backbone." What they don't capture: the hypomanic phases where I'd fire off more ideas than anyone could implement, followed by crashes where getting out of bed felt impossible. The time I sent an apology email to my entire IT org while manic, outing myself as bipolar to hundreds of people. The years I used alcohol to manage what my brain wouldn't.

When I got sober, I replaced drinking with work. Classic move, right? The dopamine hit of shipping code. The validation of being the guy who solves the "impossible" problems.

Then I lost my brother. And somewhere in the grief, I realized I was going to burn out completely if I didn't change how I thought about all of this.

Your Health Isn't a Side Quest

Here's what took me way too long to accept: managing my health isn't something I do around my job. It IS the job. Everything else comes after. Especially more so as I stepped into leadership and became responsible for others.

Bipolar and diabetes create this feedback loop — mood affects blood sugar, blood sugar wrecks mood, stress spikes everything. It's not a metaphor. It's just how the body works.

I tried to brute-force through it for years. Push harder, sleep less, prove I could keep up. You know where that leads.

Spoon Theory, Basically

If you don't know Spoon Theory: you start each day with limited "spoons" (energy units). Every task costs spoons. When they're gone, they're gone. Borrow from tomorrow and you pay interest in a crashed mood or spiked glucose.

So I stopped organizing work by priority and started organizing by energy cost:

High-energy stuff (architecture, hard conversations) → morning when I'm sharp
Medium stuff (code reviews, meetings) → afternoon
Low-energy stuff (email, docs) → the valleys

I built a hybrid system by literally just talking through my constraints with AI over a bunch of sessions. GTD for capturing everything, time blocking for structure, Pomodoro for pushing through fog. Nothing fancy. Just honest about what I'm actually working with.

The key insight: rest isn't the opposite of work. It's what makes work possible.

Making Myself Less Necessary

Here's the weird part: my limitations made me a better manager.

When you can't be the hero pulling all-nighters, you build systems that don't need heroes. When you know a depressive episode could knock you out for days, you write documentation and processes that let your team function without you.

Practically:

Reusable code libraries so we're not reinventing stuff
Documentation that's actually useful (AI memory, not bureaucracy)
Mentoring junior devs into mentors themselves
Automating the tedious stuff — CI/CD, release notes, deployments

The goal is to make myself progressively less necessary. Sounds bad for career advancement, but actually? The good orgs reward people who elevate everyone around them, not people who hoard knowledge.

The Humbling Part

I gotta be honest: I've watched people who output less than me get more recognition. And a lot of the time, they deserved it.

Because they were consistent. Reliable. They showed up steady every day.

When you're managing Bipolar, consistency is hard. Hypomania feels productive but creates chaos. Depression tanks your reliability. Boom-and-bust might average to high output, but it's not the same as being someone people can count on.

My work feedback survey shows I rate myself way harsher than my team does — like 2 out of 5 on stuff they score me 4.6. That gap is years of feeling like I had to compensate for my brain by being visibly exceptional.

The truth: sustainable and reliable beats exceptional and erratic. Every time.

Environment Matters More Than Salary

I work in higher ed, not FAANG. Not where the big money is. This is intentional.

I've had the same leadership for 11+ years and enjoy working with my directorl. When I've struggled — visibly — I wasn't managed out. I was supported. That kind of psychological safety is worth more than any salary bump I'd get jumping to a high-pressure gig.

If you're managing chronic stuff, environment isn't a perk. It's infrastructure. The right manager, the right culture, the right flexibility — that's what makes everything else possible.

The Short Version

If you're a dev fighting similar battles:

Don’t pretend that you have the same resources as everyone else. You don't. Build systems for your actual constraints.
Energy management > time management. Know your peaks and valleys.
Rest is productive. For real.
Make yourself less necessary. Document, automate, mentor.
Consistency beats intensity. 70% every day beats 150% half the time.
Environment is infrastructure. A good manager isn't a luxury.
Your inner critic lies. Get external feedback. Trust it more than the voice saying you're not enough.
Work can be an addiction too. Ask me how I know.

Work-life balance isn't a myth. For some of us, it's a survival strategy.

I'm not writing this from the other side, all figured out. I'm in the middle, still managing the loops, still learning what sustainable looks like.

But I'm still here doing my thing. Still shipping code. Still leading a team.

If you're fighting similar stuff — you can do this.

Not by pretending you don't have limits, but by building systems that work with them.

That's not settling. That's engineering.

If this resonates at all or made you think about something else, I'd love to hear from others.

Part 1 : Building a Game in 30 Hours Using AI — Here's the Actual Timeline

Forrester Terry — Fri, 16 Jan 2026 00:22:34 +0000

What happens when you treat AI as a development partner instead of an autocomplete tool?

I wanted to find out, so I ran an experiment: build a game as fast as possible, prioritizing speed and iteration over polish. No extensive planning phase. No detailed specs. Just prototyping at velocity to see what's actually possible.

The result is MagLava—a magnetic platformer where you swing between nodes to escape rising lava. Six development sessions. Roughly 30 hours of work. A published game with 25 levels, 7 language translations, and a desktop app.

To be clear: this approach was the point of the experiment. For production software or anything beyond rapid prototyping, proper planning and testing remain essential (I plan to make a post around that later).

But I wanted to stress-test the other extreme.

Here's exactly how that broke down.

The Commit Log

I commit frequently using an AI tool that generates summaries after each task, so commit clusters map well to actual work sessions. I went through my git history and reconstructed the timeline:

Date	Commits	Estimated Time	What Happened
Dec 18	2	~1.5 hours	Project scaffold, Vue + Phaser setup
Dec 19	3	~2-3 hours	Core magnetic polarity system
Dec 20	27	~8-12 hours	Complete movement redesign + 15 levels
Dec 21	9	~4-6 hours	Mobile controls, tutorials, PWA
Dec 30	13	~5-7 hours	Desktop app, music, polish
Jan 15	8	~3-5 hours	i18n (7 languages), expand to 25 levels

Total: ~25-35 hours across 6 sessions.

Notice the gaps. Nine days between Dec 21 and Dec 30. Sixteen days before the final session. The calendar says "one month of development." The reality is about a week of actual work, scattered across that month.

What "AI-Assisted" Actually Meant

The first day alone produced 6,555 lines of code—project structure, game config, menu systems, routing, storage services, the event bridge between Vue and Phaser. That's scaffolding I would have spent days on manually.

But the surprising part wasn't the code generation. It was what else came out of the process.

The promotional website with SEO, sitemaps, and structured data? AI-built. The full Electron desktop app with the level editor? Same story. The internationalization system supporting 7 languages? Implemented in a single session.

I didn't set out to have AI handle all of these. They emerged because once you're in a flow state with an AI partner, the friction for "one more feature" drops dramatically. Adding a desktop build went from "future roadmap item" to "let's just do it this session."

The Method Behind the Numbers

You might have heard the term "vibe coding"— in this case, staying in player mode and describing problems experientially rather than technically. That's what this looked like in practice. Here's an actual prompt from one of my sessions:

"game just freezes! I can't actually SEE the LAVA LINE!!! I WANA SEE THE LAVA line. And finally, we start way too close to the lava."

Typos, caps lock, frustration—all of it. I didn't calculate a pixel buffer. I expressed a feeling of unfairness. The AI translated "way too close" into a concrete fix: increasing the spawn buffer from 150 to 500 pixels above the lava line.

This only works because emotion is a valid technical spec when your goal is player experience. "This feels unfair" contains more design information than "adjust the Y-offset parameter."

Why the Timeline Matters

I'm not claiming 30 hours is fast or slow. Game complexity varies wildly. What I am claiming is that this timeline was possible because of how I worked, not just the tools I used.

The traditional solo dev pipeline looks like this: plan extensively, build the architecture, implement features, then test. You front-load decisions before you have information.

My pipeline inverted that. Build something immediately. Play it. Describe what feels wrong. Iterate. The AI handled the translation from "this sucks" to "here's the code change."

Every system stayed disposable. Every change stayed focused and modular. When something wasn't working, I didn't defend it—I described a different vision and let it get rebuilt. That's hard to do when you've personally written every line. It's easy when you're directing rather than typing.

What the Numbers Don't Show

The timeline looks clean in retrospect. It wasn't.

Day 3—that massive 27-commit session—included throwing away the entire movement system I'd built on Day 2. The original concept was polarity-based climbing: red platforms attract, blue platforms repel. I built the whole thing. Then I played it and it felt indirect, frustrating, disconnected from what I actually wanted.

So I described something different: "I want swinging. Like Spider-Man but with magnets."

Within hours, the game had a completely new identity.

That pivot—and one other major pivot that came later—are probably the reason MagLava works at all. But that's a longer story.

Next in this series: The two pivots that almost killed the project, and why emotional prompts caught problems that specs would have missed.

Play MagLava | itch.io page

Tech stack for the curious: Vue 3 + Vite, Phaser 3, TypeScript, Electron for desktop, Firebase + itch.io for hosting, Claude (Opus via Claude Code CLI) for AI assistance.

Supercharging Your AI Agents with Pydantic: A Developer's Guide 🚀

Forrester Terry — Fri, 28 Feb 2025 04:33:15 +0000

Introduction 👋
What is Pydantic and Why Should AI Developers Care? 🤔
- The AI Agent's Output Problem 🤖💬
How Pydantic Makes AI Agents More Reliable 🛡️
- 1. Automatic Type Conversion
- 2. Clear Error Messages
- 3. Schema Generation for Guiding AI Outputs
Real-World Use Cases 🌍
- OpenAI Function Calling + Pydantic
- Multi-Agent Systems (CrewAI)
Best Practices for Using Pydantic with AI Agents ✅
- 1. Start with a Clear Data Model
- 2. Handle Validation Errors Gracefully
- 3. Consider Re-Prompting When Validation Fails
A Simple Tutorial: Getting Started with Pydantic and AI 🏗️
- Step 1: Define Your Pydantic Model
- Step 2: Create a Function to Get Recommendations from an AI
- Step 3: Use the Recommendation in Your Application
Advanced Tips and Tricks 🧠
- Custom Validators for Domain-Specific Rules
- Nested Models for Complex Data
- Working with LangChain's Pydantic Output Parser
Conclusion 🎯

Introduction 👋

Have you ever built an AI agent that sometimes returns unpredictable data structures? Or perhaps you've dealt with the frustration of parsing JSON from a language model only to have your application crash because a field was missing or had the wrong type?

I've been there too! That's why today I want to talk about one of my favorite tools for taming the wild outputs of AI agents: Pydantic!

In this guide, I'll show you how Pydantic can transform your AI agent development from a game of chance into a reliable, robust process. Let's dive in! 🏊‍♂️

What is Pydantic and Why Should AI Developers Care? 🤔

Pydantic is a Python library for data validation that uses type annotations. Think of it as a bouncer for your data - it checks IDs (types) at the door and makes sure only the right data gets into your application.

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    is_active: bool

But why is this particularly useful for AI agents? Here's the thing:

AI models (especially LLMs) are amazing at generating content, but they're not always precise about formatting. They might return JSON where a number is accidentally a string ("42" instead of 42), or they might forget a field entirely. Without validation, these small inconsistencies can cause big problems downstream in your application.

The AI Agent's Output Problem 🤖💬

Imagine asking an AI agent to return information about a product:

{
  "name": "Super Widget",
  "price": "29.99",
  "in_stock": "true",
  "features": ["durable", "lightweight"]
}

Notice the issues? price is a string instead of a float, and in_stock is a string instead of a boolean. Your application might crash when it tries to do math with that price or make a decision based on the stock status.

Pydantic to the rescue! It can automatically convert these types for you, so "29.99" becomes 29.99 (float) and "true" becomes True (boolean).

How Pydantic Makes AI Agents More Reliable 🛡️

1. Automatic Type Conversion

Pydantic doesn't just validate - it tries to convert data to the right type when possible. This is perfect for AI outputs that are almost correct.

from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: float
    in_stock: bool
    features: list[str]

# Even though price and in_stock are strings, Pydantic will convert them
product = Product(
    name="Super Widget", 
    price="29.99", 
    in_stock="true",
    features=["durable", "lightweight"]
)

print(product)
# Product(name='Super Widget', price=29.99, in_stock=True, features=['durable', 'lightweight'])

2. Clear Error Messages

When validation fails, Pydantic tells you exactly what went wrong:

try:
    Product(name="Broken Widget", price="expensive", in_stock=True, features="strong")
except Exception as e:
    print(f"Error: {e}")

# Error: 2 validation errors for Product
# price
#   Input should be a valid number, unable to parse string as a number [type=float_parsing, input_value='expensive', input_type=str]
# features
#   Input should be a valid list [type=list_type, input_value='strong', input_type=str]

These detailed errors make debugging so much easier when your AI agent returns unexpected data.

3. Schema Generation for Guiding AI Outputs

One of my favorite Pydantic features for AI development is its ability to generate JSON schemas:

print(Product.model_json_schema())
# {
#   "title": "Product",
#   "type": "object",
#   "properties": {
#     "name": {"title": "Name", "type": "string"},
#     "price": {"title": "Price", "type": "number"},
#     "in_stock": {"title": "In Stock", "type": "boolean"},
#     "features": {
#       "title": "Features",
#       "type": "array",
#       "items": {"type": "string"}
#     }
#   },
#   "required": ["name", "price", "in_stock", "features"]
# }

You can use this schema to guide your AI model, especially if you're using function calling with OpenAI or similar features with other providers. This dramatically improves the chances of getting correctly formatted responses!

Real-World Use Cases 🌍

Let's look at how developers are using Pydantic with AI agents in the wild:

OpenAI Function Calling + Pydantic

from openai import OpenAI
from pydantic import BaseModel, Field

class WeatherInfo(BaseModel):
    location: str = Field(..., description="The city and state")
    temperature: float = Field(..., description="Current temperature in Celsius")
    condition: str = Field(..., description="Weather condition (sunny, cloudy, etc.)")

# Get the JSON schema for OpenAI
function_def = {
    "name": "get_weather",
    "description": "Get the current weather in a location",
    "parameters": WeatherInfo.model_json_schema()
}

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[
        {"role": "user", "content": "What's the weather like in Boston?"}
    ],
    functions=[function_def],
    function_call={"name": "get_weather"}
)

# Extract and validate the response
function_response = response.choices[0].message.function_call.arguments
weather = WeatherInfo.model_validate_json(function_response)
print(f"It's {weather.temperature}°C and {weather.condition} in {weather.location}")

This approach has two benefits:

The schema guides the AI to produce properly structured output
Pydantic validates that output as an extra safety measure

Multi-Agent Systems (CrewAI)

In systems where multiple AI agents collaborate, consistent data structures are critical. Frameworks like CrewAI use Pydantic to ensure agents communicate properly:

from pydantic import BaseModel
from crewai import Agent, Task, Crew

class ResearchReport(BaseModel):
    topic: str
    key_findings: list[str]
    sources: list[str]

# Define a task with a Pydantic output schema
research_task = Task(
    description="Research the latest advancements in quantum computing",
    expected_output="A structured research report with key findings and sources",
    output_pydantic=ResearchReport
)

# When the agent completes the task, CrewAI validates the output against the model

Best Practices for Using Pydantic with AI Agents ✅

After working with numerous AI projects, here are my top recommendations:

1. Start with a Clear Data Model

Define Pydantic models that capture exactly what you need from your AI agent. Be specific about types and constraints:

from typing import Optional, Literal
from pydantic import BaseModel, Field, conint

class ProductRecommendation(BaseModel):
    product_name: str
    price_range: str = Field(..., pattern=r"^\$\d+-\$\d+$")  # Ensure format like "$10-$20"
    rating: conint(ge=1, le=5)  # Integer between 1-5
    category: Literal["electronics", "clothing", "home", "books", "other"]
    features: list[str] = Field(..., min_items=2, max_items=5)
    in_stock: bool
    shipping_days: Optional[int] = None

This detailed model serves as documentation and validation in one package.

2. Handle Validation Errors Gracefully

Always wrap your Pydantic validation in try/except blocks:

try:
    recommendation = ProductRecommendation.model_validate_json(ai_response)
    # Use the structured data
except Exception as e:
    # Log the error
    print(f"AI output validation failed: {e}")

    # Possible strategies:
    # 1. Use a fallback approach
    # 2. Re-prompt the AI with the error details
    # 3. Apply some fixes and retry validation

3. Consider Re-Prompting When Validation Fails

One powerful approach is to tell the AI exactly what went wrong and ask it to fix the response:

def get_validated_response(prompt):
    for attempt in range(3):  # Try up to 3 times
        response = ai_model.generate(prompt)

        try:
            result = ProductRecommendation.model_validate_json(response)
            return result
        except Exception as e:
            if attempt < 2:  # Don't update prompt on the last attempt
                prompt += f"\nYour previous response had validation errors: {e}. Please fix them and try again."

    # If we get here, all attempts failed
    raise ValueError("Could not get valid response after multiple attempts")

This feedback loop helps the AI learn from its mistakes!

A Simple Tutorial: Getting Started with Pydantic and AI 🏗️

Let's bring everything together with a simple tutorial. We'll create a movie recommendation agent that returns properly structured data:

Step 1: Define Your Pydantic Model

from pydantic import BaseModel, Field
from typing import List, Optional

class MovieRecommendation(BaseModel):
    title: str
    year: int = Field(..., ge=1900, le=2030)
    genres: List[str] = Field(..., min_items=1)
    rating: float = Field(..., ge=0.0, le=10.0)
    director: str
    streaming_on: Optional[List[str]] = None
    description: str = Field(..., max_length=500)

Step 2: Create a Function to Get Recommendations from an AI

def get_movie_recommendation(genre_preference, mood, decade_preference=None):
    # Construct a prompt for the AI
    prompt = f"""
    Suggest a movie based on the following:
    Genre preference: {genre_preference}
    Mood: {mood}
    Decade preference: {decade_preference or 'any'}

    Return the recommendation as a JSON object with the following fields:
    - title: the movie title
    - year: the release year (1900-2030)
    - genres: list of genres
    - rating: rating out of 10
    - director: the director's name
    - streaming_on: list of streaming platforms (if known) or null
    - description: brief description (max 500 chars)
    """

    # In a real application, you'd call your AI model here
    # For demonstration, let's pretend we got this response:
    ai_response = """
    {
      "title": "The Grand Budapest Hotel",
      "year": 2014,
      "genres": ["Comedy", "Drama", "Adventure"],
      "rating": 8.1,
      "director": "Wes Anderson",
      "streaming_on": ["HBO Max", "Disney+"],
      "description": "A writer encounters the owner of an aging high-class hotel, who tells him of his early years serving as a lobby boy in the hotel's glorious years under an exceptional concierge."
    }
    """

    try:
        # Parse and validate the AI response
        recommendation = MovieRecommendation.model_validate_json(ai_response)
        return recommendation
    except Exception as e:
        print(f"Error validating AI response: {e}")
        # In a real application, you might implement retry logic here
        return None

Step 3: Use the Recommendation in Your Application

def display_recommendation(recommendation):
    if not recommendation:
        return "Sorry, couldn't generate a valid recommendation."

    return f"""
    🎬 {recommendation.title} ({recommendation.year}) - {recommendation.rating}/10

    Directed by: {recommendation.director}
    Genres: {', '.join(recommendation.genres)}

    {recommendation.description}

    {f"Available on: {', '.join(recommendation.streaming_on)}" if recommendation.streaming_on else "Streaming info not available"}
    """

# Get and display a recommendation
user_genre = "sci-fi"
user_mood = "thoughtful"
user_decade = "2010s"

movie = get_movie_recommendation(user_genre, user_mood, user_decade)
print(display_recommendation(movie))

Advanced Tips and Tricks 🧠

Want to take your Pydantic + AI game to the next level? Here are some advanced techniques:

Custom Validators for Domain-Specific Rules

from pydantic import BaseModel, Field, validator

class TravelRecommendation(BaseModel):
    destination: str
    best_months: list[str]
    budget_usd: int = Field(..., gt=0)

    @validator('best_months')
    def check_valid_months(cls, months):
        valid_months = ["January", "February", "March", "April", "May", "June", 
                      "July", "August", "September", "October", "November", "December"]

        for month in months:
            if month not in valid_months:
                raise ValueError(f"Invalid month: {month}")
        return months

Nested Models for Complex Data

class Address(BaseModel):
    street: str
    city: str
    state: str
    country: str
    postal_code: str

class Contact(BaseModel):
    name: str
    email: str
    phone: Optional[str] = None
    address: Address

class BusinessListing(BaseModel):
    name: str
    category: str
    rating: float
    contact: Contact
    hours: dict[str, str]

Working with LangChain's Pydantic Output Parser

from langchain.output_parsers import PydanticOutputParser
from langchain.prompts import PromptTemplate
from langchain.llms import OpenAI
from pydantic import BaseModel, Field

class AmazonProduct(BaseModel):
    name: str = Field(description="The product name")
    price: float = Field(description="The product price in USD")
    rating: float = Field(description="Rating from 1-5")
    reviews: int = Field(description="Number of reviews")

parser = PydanticOutputParser(pydantic_object=AmazonProduct)

prompt = PromptTemplate(
    template="Extract product information from this text:\n{text}\n{format_instructions}",
    input_variables=["text"],
    partial_variables={"format_instructions": parser.get_format_instructions()}
)

model = OpenAI()

input_text = """
This amazing laptop is the MacBook Pro 16-inch, priced at $2,399. It has received 
excellent feedback from customers, with a 4.8 star rating based on 3,842 reviews.
"""

output = model(prompt.format(text=input_text))
product = parser.parse(output)

Conclusion 🎯

Pydantic is more than just a validation library - it's your AI agent's best friend! By defining clear data models and validating inputs and outputs, you can:

Make your AI applications more reliable
Catch errors early before they cascade into bigger problems
Guide your models to produce better-structured outputs
Create self-documenting code that clearly specifies what data you expect

The next time you're building an AI agent, take the time to define your data models with Pydantic. Your future self (and your users) will thank you!

Have you used Pydantic with AI projects? Feel free to share your experiences in the comments!

TypeScript Fundamentals: A Beginner's Guide (2025) ✅

Forrester Terry — Tue, 07 Jan 2025 02:33:01 +0000

TypeScript has caused endless debates among developers. Some see it as a bureaucratic roadblock to the freedom of JavaScript, while others hail it as a beacon of light in the trenches of loosely typed code. Love it or hate it, TypeScript is here to stay — and once you get to know it, you might just find it’s not a burden but a blessing for your projects.

In this series we will explore TypeScript and cover the basics -- as well as some tricks and troubleshooting tips.

1. Introduction

What is TypeScript?

TypeScript is a statically typed superset of JavaScript that compiles to plain JavaScript. In simpler terms, it’s JavaScript with extra features that help you catch errors early and write better, more maintainable code.

Think of TypeScript as a friendly assistant who double-checks your work before you submit it. It lets you:

Spot errors while you’re coding, not after you’ve deployed.
Write code that’s easier to read and understand.
Scale your projects without losing track of how things connect.

Why Use TypeScript?

Let’s get practical. Why should you care about TypeScript when JavaScript already works?

Real Benefits:

Catch Errors Early: Avoid common pitfalls, like passing the wrong data type to a function.

   function greet(name: string) {
     return `Hello, ${name}!`;
   }
   greet(42); // Error: Argument of type 'number' is not assignable to parameter of type 'string'.

Autocompletion & Documentation: Modern editors (like VS Code) provide rich autocomplete suggestions and documentation as you type.
Code Scalability: TypeScript’s features shine in larger projects where maintaining consistency is key.
Improved Team Collaboration: Clear types make it easier for team members to understand your code at a glance.

I have found TypeScript to be particularly helpful for planning out bigger apps; understanding what types of data I will be dealing with and what data my functions take/return.

Prerequisites

Before diving in, ensure you have basic JavaScript knowledge. You should be familiar with:

Variables and data types (e.g., let, const, string, number)
Functions
Arrays and objects

If you’re not confident yet, take some time to review JavaScript basics.

2. Setting Up Your Environment

Installing TypeScript

TypeScript is a tool that requires installation to get started. With just a few steps, you can prepare your environment to begin coding in TypeScript. Here’s how to do it:

To start using TypeScript, you’ll need Node.js installed. Once you have that:

Install TypeScript globally:

   npm install -g typescript

Verify the installation:

   tsc --version

Setting Up VS Code

VS Code is one of the most popular editors for TypeScript development. It provides a range of features and extensions that make coding easier and more efficient. Let’s set it up:

VS Code is the go-to editor for TypeScript developers. Here’s how to set it up:

Install VS Code: Download here
Add these helpful extensions:
- ESLint: For linting your TypeScript code.
- Prettier: For consistent code formatting.
- TypeScript Hero: For improved productivity.

Creating Your First TypeScript Project

Getting hands-on is the best way to learn TypeScript. This section guides you through setting up your first project, from creating files to running your code.

Create a new folder for your project and navigate into it:

   mkdir typescript-starter
   cd typescript-starter

Initialize a new project:

   npm init -y

Add TypeScript:

   npm install --save-dev typescript

Create a tsconfig.json file:

   npx tsc --init

Write your first TypeScript file:

   echo "console.log('Hello, TypeScript!');" > index.ts

Compile and run:

   npx tsc index.ts
   node index.js

You’ve just written and compiled your first TypeScript program!

3. Basic Types Overview

TypeScript’s power lies in its type system. Let’s explore some basic types:

Primitive Types

Primitive types are the building blocks of TypeScript’s type system. They include basic data types like strings, numbers, and booleans. Here’s a quick look at how to use them:

string:

   let name: string = "Alice";

number:

   let age: number = 25;

boolean:

   let isStudent: boolean = true;

Advanced Types

In addition to primitives, TypeScript supports more complex types like arrays, tuples, and special types like any and unknown. These types make your code flexible while maintaining safety.

Arrays:

   let scores: number[] = [90, 85, 88];

Tuples:

   let user: [string, number] = ["Alice", 25];

any (use sparingly):

   let data: any = "Could be anything";

unknown (safer than any):

   let value: unknown = 10;

void (functions that return nothing):

   function logMessage(message: string): void {
     console.log(message);
   }

null and undefined:

   let something: null = null;
   let nothing: undefined = undefined;

4. First Steps with Type Annotations

Type Annotations in TypeScript allow developers to specify the type of a variable, parameter, or function return value. This ensures that the code adheres to a defined structure, making it easier to catch errors during development and maintain consistency throughout the project.

As you write your code as you normally do, take note of the features below that you can integrate

Basic Variable Typing

Set types for your variables so that they are always set to the right thing, and the rest of the app understands what they are.

let firstName: string = "Alice";
let age: number = 30;

Function Parameter Typing

Similarly, for functions you can define the types for the arguments, as well define the type for the return.

// Note the 'number' keywords for each param
function add(a: number, b: number): number { 
  return a + b;
}

Return Type Annotations

// Note the 'string' keyword at the end
function greet(name: string): string { 
  return `Hello, ${name}!`;
}

Practical Example: User Profile

TypeScript allows you to declare your own types to better structure and enforce rules in your code. By using type or interface, you can define custom types for objects, functions, or even unions. This not only makes your code more robust but also improves readability and consistency in larger projects.

interface UserProfile = {
  name: string;
  age: number;
  isActive: boolean;
};

const user: UserProfile = {
  name: "Alice",
  age: 25,
  isActive: true,
};

5. Quick Start with Interfaces

Basic Syntax

Interfaces in TypeScript define the structure of objects, ensuring they have specific properties and types. This section shows you how to create and use them:

interface User {
  name: string;
  age: number;
}

const user: User = {
  name: "Bob",
  age: 30,
};

Optional Properties

Sometimes, not all properties in an object are required. TypeScript lets you define optional properties in interfaces to handle such cases gracefully.

interface Product {
  name: string;
  price?: number;
}

const item: Product = { name: "Notebook" };

Readonly Properties

Readonly properties are useful when you want to ensure certain values cannot be changed after they are set. Here’s how to use them in interfaces:

interface Book {
  readonly title: string;
}

const myBook: Book = { title: "TypeScript Handbook" };
// myBook.title = "Another Title"; // Error: Cannot assign to 'title'.

Real-World Example: API Response

Using interfaces to type API responses ensures you handle data from servers safely and effectively. Here’s a practical example:

interface ApiResponse {
  data: unknown;
  status: number;
}

6. Practice Project: Building a Simple Todo List

Practice is key to mastering TypeScript. In this project, you’ll create a simple todo list application that leverages the features you’ve learned so far:

Create a Todo type:

   interface Todo {
     id: number;
     title: string;
     completed: boolean;
   }

Build a simple array of todos:

   const todos: Todo[] = [
     { id: 1, title: "Learn TypeScript", completed: false },
   ];

Add some functions to add todos and mark todos as complete:

   function markAsComplete(todo: Todo): Boolean {
        let bUpdated = false
        todos.map((td:Todo) => {
            if (td.id == todo.id){
                bUpdated = true
                td.completed = true
            }
        })
        return bUpdated
   }

   function addToDo(todo:Todo): Boolean{
        try {
            todos.push(todo)
            console.log(`Added "${todo.title}"" to list!`)
            return true
        } catch {
            console.log("Error adding to the todo object!")
            return false
        }
   }

7. Next Steps

That's it for now, hope you enjoyed this tutorial. I will be working on some additional tutorials to dig deeper into useful TypeScript features and use cases.

Coming Up Next: Deep dive into TypeScript functions and advanced types.
Resources:
- TypeScript Documentation
- CodeSandbox for practicing TypeScript online.
Challenge: Create a TypeScript interface for a blog post and use it to type-check a list of blog posts.

See you next time!

📦 How to Create, Publish, and Maintain a Node.js Package (in JavaScript and TypeScript)

Forrester Terry — Mon, 06 Jan 2025 03:59:40 +0000

Have you ever written a piece of code that could benefit other developers — or even your future self—over and over again? Perhaps it’s a utility function, a library, or a set of reusable tools you find yourself copying and pasting across multiple projects.

This might be the perfect candidate for an NPM package!

In this article, we’ll walk step-by-step through creating a simple Node.js package in both JavaScript and TypeScript, setting up best practices such as testing and versioning, and then publishing it to npmjs.com. 🚀

1. Setting Up Your Project

2. Writing Your Package Code

3. Testing Your Package

4. Versioning Best Practices

5. Publishing Your Package

6. Common Features and Best Practices

7. Use Cases

8. Creating Scripts to Automate Common Tasks

1. Setting Up Your Project

1.1 Prerequisites

Node.js (v22.12.0 LTS is recommended as of January 2025, v18 LTS is the oldest version that is still maintained).
npm (comes bundled with Node).
A npmjs.com account for publishing your package.

1.2 Initialize Your Project

Create a new directory for your package:

mkdir my-awesome-package
cd my-awesome-package

Initialize a new Node.js project:

npm init

This command will ask several questions to help create a package.json file, the heart of your Node.js package. Key fields to pay attention to:

name: The name of your package (must be unique in the npm registry).
version: The version of your package, often starting at 1.0.0.
description: A brief explanation of your package.
entry point: The main file (often index.js or dist/index.js).
author: Your name or organization.
license: The license type (e.g., MIT).

You can skip the Q&A by running npm init -y to get a default package.json file.

2. Writing Your Package Code

We’ll explore two approaches: plain JavaScript and TypeScript. Choose whichever suits your project needs—or maintain both if you like.

2.1 Plain JavaScript Version

Create a file named index.js in your project root:

// index.js

/**
 * Returns a greeting message
 * @param {string} name - The name to greet
 * @return {string} A greeting message
 */
function greet(name) {
  return `Hello, ${name}!`;
}

// Export the function as a module
module.exports = greet;

2.2 TypeScript Version

2.2.1 Install and Initialize TypeScript

Install Typescript as a development dependency:

npm install --save-dev typescript

Initialize a tsconfig.json:

npx tsc --init

2.2.2 A Recommended tsconfig.json

Replace the generated tsconfig.json with a configuration tailored for your needs, here we configure for modern Node.js (v22.12.0 LTS):

{
  "compilerOptions": {
    "target": "ES2020",                        // Modern JavaScript features
    "module": "CommonJS",                      // Node.js module system
    "rootDir": "src",                          // Source files directory
    "outDir": "dist",                          // Compiled output directory
    "strict": true,                            // Enable all strict type-checking options
    "esModuleInterop": true,                   // Better compatibility with CommonJS modules
    "skipLibCheck": true,                      // Skip type checking of declaration files for faster builds
    "forceConsistentCasingInFileNames": true,  // Enforce consistent file name casing
    "declaration": true,                       // Generate .d.ts files for type definitions
    "declarationMap": true                     // Generate source maps for declarations
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.test.ts"]
}

This ensures compatibility with modern JavaScript and enforces strict type-checking, improving code quality.

2.2.3 Create Your Source File

Create a src directory and add index.ts:

// src/index.ts

/**
 * Returns a greeting message
 * @param name - The name to greet
 * @returns A greeting message
 */
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

2.2.4 Update package.json

We need to point main at the compiled JavaScript file in dist, and also specify where the type definitions live via the "types" field. We’ll also add a build script:

{
  "name": "my-awesome-package",
  "version": "1.0.0",
  "description": "A package that greets the user.",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "test": "jest"
  },
  "author": "Your Name",
  "license": "MIT"
}

By specifying "types": "dist/index.d.ts", consumers of your package automatically get the TypeScript definitions.

Now, you can compile your TypeScript source by running:

npm run build

3. Testing Your Package

Testing is not mandatory for publishing but is highly recommended to ensure reliability. We’ll demonstrate using Jest for both JavaScript and TypeScript.

3.1 Install Jest

npm install --save-dev jest

For TypeScript, also install ts-jest and type definitions:

npm install --save-dev ts-jest @types/jest

3.2 Configure Jest (TypeScript Only)

Initialize Jest with TypeScript support:

npx ts-jest config:init

This creates a jest.config.js (or jest.config.ts) file tailored for TypeScript. Typically, it might look like:

// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node'
};

3.3 Write Your Tests

Create a test directory. Let’s name our test file greet.test.js or greet.test.ts, depending on your language choice.

3.3.1 JavaScript Test Example

// test/greet.test.js
const greet = require('../index'); // Using JavaScript's require

test('returns a greeting with the given name', () => {
  expect(greet('Alice')).toBe('Hello, Alice!');
});

3.3.2 TypeScript Test Example

// test/greet.test.ts
import { greet } from '../src/index'; // or '../dist/index' after build

test('returns a greeting with the given name', () => {
  expect(greet('Alice')).toBe('Hello, Alice!');
});

3.4 Update package.json for Testing

Ensure your package.json includes:

{
  "scripts": {
    "build": "tsc",
    "test": "jest"
  }
}

Now you can build and test your project via:

npm run build
npm test

4. Versioning Best Practices

Node packages typically follow SemVer (Semantic Versioning):

MAJOR for incompatible API changes.
MINOR for adding functionality in a backward-compatible manner.
PATCH for backward-compatible bug fixes.

Example: 1.0.0 (Major.Minor.Patch)

To increment your package version (and create a Git tag if you’re using Git):

npm version patch   # e.g., 1.0.0 -> 1.0.1
npm version minor   # e.g., 1.0.1 -> 1.1.0
npm version major   # e.g., 1.1.0 -> 2.0.0

5. Publishing Your Package

5.1 Log in to npm

Before you can publish, authenticate with npm:

npm login

Enter your credentials and/or token. If you haven’t created an account yet, sign up here.

Alternatively, you can setup your .npmrc to handle the authentications:

echo //registry.npmjs.org/:_authToken=MY_TOKEN > ~/.npmrc

You can change the registry path as needed, depending on your NPM repository instance. For instance, for GitHub you may do:

echo //npm.pkg.github.com/:_authToken=MY_TOKEN > ~/.npmrc

5.2 Publish

For a plain JavaScript package:

npm publish

For a TypeScript package, build your code before publishing:

npm run build
npm publish

Your package is now live on the npm registry, and anyone can install it with:

npm install my-awesome-package

If your package name is scoped (e.g., @your-scope/my-awesome-package), you might need:

npm publish --access public

(--access public is required for scoped packages to be publicly available.)

6. Common Features and Best Practices

6.1 README.md

A clear README.md is essential for explaining your package. Include:

Installation Instructions

  npm install my-awesome-package

Basic Usage

  // JavaScript:
  const greet = require('my-awesome-package');
  console.log(greet('Alice')); // Hello, Alice!

  // TypeScript:
  import { greet } from 'my-awesome-package';
  console.log(greet('Alice')); // Hello, Alice!

Advanced Examples: Show more use cases, configuration, or integration details.
API Documentation: If your package has multiple methods or classes, document them thoroughly.

6.2 LICENSE

Including a license clarifies how your package can be used. Define it in:

A LICENSE file at the root.
The license field in package.json.

6.3 GitHub Repository

While not strictly required, hosting your package on a platform like GitHub helps with:

Collaboration (issues, pull requests)
Version Control (Git tags, branches)
Automated CI (running tests on each commit)

6.4 Linting

Use a linter like ESLint for consistent coding standards.

npm install --save-dev eslint
npx eslint --init

Configure your lint rules, then run:

npm run lint

6.5 Continuous Integration (CI)

For open-source or team projects, consider GitHub Actions, Travis CI, or similar. This ensures tests run automatically on every commit, increasing confidence and catching issues early.

6.6 Adding Dependencies and Managing Dependency Files

As your package grows, you might need to incorporate other libraries or tools to enhance its functionality. Managing dependencies effectively ensures that your package remains robust, maintainable, and easy for others to use.

6.6.1. Adding Dependencies

Dependencies are packages required for your package to run correctly. DevDependencies are packages needed only during development, such as testing frameworks or build tools.

To add a runtime dependency:

  npm install lodash

This command adds the lodash library as a dependency and updates your package.json:

  {
    "dependencies": {
      "lodash": "^4.17.21"
    }
  }

To add a development dependency:

  npm install --save-dev eslint

This adds eslint as a devDependency:

  {
    "devDependencies": {
      "eslint": "^8.0.0"
    }
  }

6.6.2. Managing Dependency Files

package.json: This file lists all your dependencies and devDependencies. Ensure that all necessary packages are correctly listed to avoid missing dependencies during installation.
package-lock.json: Automatically generated when you install dependencies, this file locks the versions of your dependencies to ensure consistent installations across different environments. Do not manually edit this file; instead, let npm manage it.

6.6.3. Best Practices

Keep Dependencies Updated: Regularly update your dependencies to incorporate the latest features and security patches. You can use tools like npm-check-updates to assist with this.

  npm install -g npm-check-updates
  ncu -u
  npm install

Minimize Dependencies: Only include packages that are essential for your package’s functionality. Fewer dependencies reduce the risk of conflicts and vulnerabilities.
Use Peer Dependencies When Appropriate: If your package is a plugin or extension that relies on a host package (like React), specify it as a peer dependency to avoid version conflicts.

  npm install --save-peer react

Update your package.json:

  {
    "peerDependencies": {
      "react": "^17.0.0"
    }
  }

6.6.4. Example: Adding a Dependency

Suppose you want to use axios for making HTTP requests in your package.

Install axios as a dependency:

   npm install axios

Use axios in your code:

   // src/index.ts
   import axios from 'axios';

   /**
    * Fetches user data from an API
    * @param userId - The ID of the user
    * @returns User data
    */
   export async function fetchUserData(userId: number): Promise<any> {
     const response = await axios.get(`https://api.example.com/users/${userId}`);
     return response.data;
   }

7. Use Cases

Utility Packages
- E.g., date-formatting libraries to simplify working with dates.
UI Components
- E.g., a set of React or Vue components published as a standalone package.
CLI Tools
- E.g., command-line utilities for scaffolding projects or automating tasks.
Libraries for APIs
- E.g., wrappers for third-party APIs or microservices, making them easy to integrate with Node.js.

8. Creating Scripts to Automate Common Tasks

To streamline your development workflow, it's beneficial to define custom scripts in your package.json. These scripts can handle tasks like building, testing, deploying, and versioning your package with simple commands.

8.1. Benefits of Custom Scripts

Automation: Reduce manual steps by automating build and deployment processes.
Consistency: Ensure that tasks are performed the same way every time.
Modularity: Create reusable scripts that can be combined for complex workflows.
Efficiency: Save time by chaining multiple commands into a single script.

8.2. Example: Deploying to Development and Production

Let's create two deployment scripts: deploy:dev for development environments and deploy:prod for production. These scripts will handle tasks such as building the project, tagging the Git repository, versioning, and deploying the package.

8.2.1. Defining the Scripts in `package.json`

Open your package.json and add the following scripts under the "scripts" section:

{
  "scripts": {
    "build": "tsc",
    "test": "jest",
    "version": "npm version patch",
    "tag:dev": "git tag -a v$(node -p \"require('./package.json').version\") -m \"Dev deployment v$(node -p \"require('./package.json').version\")\"",
    "deploy:dev": "npm run build && npm run test && npm run version && npm run tag:dev && git push && git push --tags && npm publish --tag dev",
    "tag:prod": "git tag -a v$(node -p \"require('./package.json').version\") -m \"Production deployment v$(node -p \"require('./package.json').version\")\"",
    "deploy:prod": "npm run build && npm run test && npm run version && npm run tag:prod && git push && git push --tags && npm publish"
  }
}

8.2.2. Breakdown of the Scripts

build: Compiles the TypeScript code into JavaScript using the TypeScript compiler.
test: Runs the Jest test suite to ensure your package is working correctly.
version: Increments the patch version in package.json following Semantic Versioning.
tag:dev / tag:prod: Creates a Git tag corresponding to the current version for development or production deployments.
deploy:dev:
1. Builds the project.
2. Tests the build.
3. Versions the package.
4. Tags the commit for a development deployment.
5. Pushes the commits and tags to the remote repository.
6. Publishes the package to npm with the dev tag.
deploy:prod: Similar to deploy:dev but publishes the package without a tag, making it the latest stable release.

8.3. Running the Deployment Scripts

With the scripts defined, deploying becomes straightforward:

Deploy to Development:

  npm run deploy:dev

This command will build your project, run tests, increment the patch version, create a Git tag, push changes, and publish the package with the dev tag.

Deploy to Production:

  npm run deploy:prod

This command performs the same steps as deploy:dev but publishes the package as the latest stable version without an additional tag.

8.4. Making Scripts Modular

By breaking down tasks into smaller, reusable scripts (like build, test, version, and tagging), you can compose complex workflows easily. This modularity allows you to maintain and update individual steps without affecting the entire deployment process.

For example, if you need to change how the project is built, you only need to update the build script without modifying the deployment scripts.

8.5. Additional Automation Tips

Pre/Post Hooks: Utilize npm's pre and post script hooks to run tasks automatically before or after specific scripts. For instance, you can add a prepublishOnly script to ensure tests pass before publishing.

  {
    "scripts": {
      "prepublishOnly": "npm run test && npm run build"
    }
  }

Environment Variables: Manage different environments (development, staging, production) by using environment variables within your scripts or leveraging packages like cross-env for cross-platform compatibility.
Error Handling: Incorporate error handling in your scripts to halt the process if a critical step fails, ensuring that incomplete or faulty deployments do not occur.

In Review

Publishing an NPM package may feel daunting, but the fundamentals are straightforward:

Initialize your project with npm init.
Write your code in either JavaScript or TypeScript (v5.7.2 recommended).
Add tests to ensure your package remains reliable.
Follow SemVer for version management.
Publish your package with npm publish.

By following these best practices you’ll have a package that is reliable, easy to maintain, and simple for others to consume. 💻