In the summer of 2019, I was an Associate Scrum Master, and I found myself alone in the office, standing on a chair to tape long printouts of screens and modals from my development team’s application onto the wall. I was preparing a game in which team members would be given objectives and take turns navigating the website to complete them. Every time they achieved their goal, they would win points. Every time they hit a user error, they would lose points, and their turn would pass to the next player. The developers and product manager weren't prioritizing usability issues in the development backlog, so I devised this board game to make them feel the impact of poor UX. I was desperate to make our users’ pain a reality for them. The thought 'maybe I'm in the wrong role' did not even cross my mind.

The Job I Thought I Loved

I loved being a Scrum Master. I found the organizing principles behind Agile sensible and helpful in making work more efficient and valuable. I believed in technical excellence, sustainable development, self-organizing teams, and a cyclical process of examination and improvement. But most of all, I loved the focus on people. Individuals and interactions over processes and tools. Customer collaboration over contract negotiation. At its heart, Agile aims to put real humans at the center of the development process, and I loved the idea of a role whose purpose was to coach that principle, ask hard questions, and make sure teams were building the right thing to solve a real user problem.

But the longer I was a Scrum Master, the more the role drifted from that ideal. I won't add to the pile of "death of Agile" think pieces — but what I lived through was a slow reduction of something principled into something purely mechanical. Story points reported to leadership. Consequences for missing velocity goals set by people outside the development team. KPIs and features handed down from internal roles miles away from our actual users. Questions like, "Is this feature actually valuable to our users?" became unwelcome. Leadership didn't want user-centered thinking. They wanted more code, faster.

I started missing the days when I'd been allowed to do the real work — an afternoon user discovery workshop, a ride-along with the drivers we were building an app for, or yes, the day I turned our application into a game board so my developers could finally feel what they were putting our users through.

The Accidental Researcher 

I had always described myself as a Scrum Master who was “UX curious.” Even as an Administrative Assistant back in 2016, I had devised a way to get involved in a UX project, improving our employee intranet. But I thought actually holding a UX role required a fancy degree and experience I didn’t have. Instead, I thought I could lean into the people-first aspect of the Scrum Master role. I sought to partner with UX teams at every point, looking to ensure my development teams were engaging with UX research, testing, and best practices.

Looking back, I realize I was already playing the user researcher: synthesizing information and patterns across retrospectives, designing discovery workshops, and asking, “Why?” so many times in a root cause analysis, one leader joked we were going to get to the bottom of all human weakness. 

I thought I wasn’t qualified for a UX role, but I could be a Scrum Master who championed UX and coached my development teams to center the user in everything they did. 

The “Death” of Agile

I was a Scrum Master for six years, working my way into a Senior role at a large, well-respected company. I thought I had made it. And then in the spring of 2024, my entire department was cut overnight without warning. It was a complete surprise, and I was devastated. I had thrived as a Scrum Master, producing strong outcomes and growth for my teams and winning awards as a result. I thought excelling at my job would save me from the layoffs sweeping the industry. But the profound misunderstanding of Agile as a shortcut to high output and low costs, and the overly high investment in undertrained, untenured Scrum Masters had caught up with Agile as an industry. If Scrum Masters were just glorified note takers and story point counters, were they really necessary? Companies were abandoning the Agile ship right and left, and mine had finally followed suit. My love for Agile principles and my above-and-beyond work to teach those principles to guide development hadn’t saved me. 

Suddenly, I found myself with no obligation to my current role, and I started to dream. What if I could find a role that truly did seek to understand and represent user needs in the technology sector? What if my role was seen and respected as one that could help prioritize features based on actual research and help ensure designs were based on real humans and the way they interact with technology? What if I could practice UX?

Even after working around development teams for six years, helping facilitate UX workshops and user interviews, supporting project and product managers, coordinating and wrangling stakeholders, and running design and prioritization workshops, I didn’t think I could make the leap. Did I really know enough?   

Conquering Doubt

I started by talking with UX practitioners I had worked with in the past and quickly gained confidence. The resounding feedback was “you’ve been doing this all along” and “I’m surprised you didn’t transition into UX sooner.”

I realized I had a lot of the skills and experience to become a UX Researcher. Six years of facilitation — running retrospectives, designing discovery sessions, wrangling stakeholders through collaborative prioritization — translated almost directly into the mechanics of UX research. Moderated user interviews, it turns out, are not so different from a well-run retro. Both require enough psychological safety that people will tell you something true, and enough structure that the conversation stays purposeful without shutting down room for surprise.

The analytical muscle was there, too. I had spent years tracing patterns across retrospective data and running root cause analyses. Synthesizing research findings and turning them into something a product team could act on? I had been doing a version of that every time I helped a team define and prioritize a backlog. And the cross-disciplinary collaboration — the constant negotiation between developers, product managers, designers, and stakeholders — which was a prerequisite for surviving as a Scrum Master, turned out to be equally essential in research. Most practically, the project management habits that had kept sprints on track and backlogs groomed turned out to be exactly what's needed to plan and execute a research project. Scoping a research plan, recruiting participants, keeping a study on schedule — it's a different kind of work, but the organizational instincts are the same.

Uncertain of my next steps, I sat down with a UX designer I admired and had worked with in the past. “Oh yeah!” she said, “you’d make an amazing UX Researcher!” I talked with her about the possibilities of a boot camp, which many had warned me against. “Oh no, do it,” she said. We talked about it, and both agreed a program would help solidify the foundational knowledge behind my experience and position me perfectly for the role I wanted. As long as I chose a program that would help me develop a portfolio, I had nothing to lose. Within days, I enrolled in a boot camp. Two years later, I’m a practicing UX Researcher with a range of experience behind me that has only made me stronger in the role. I have no regrets for having made the leap.

Agile, Done Right, Should Produce Great UX 

Sometimes I think the decision to transition to UX took me so long, not simply because of self-doubt, but also because of my sense of hope in Agile’s intentions. The Agile Manifesto, the document on which Agile frameworks and practices are based, explicitly values customer collaboration over contract negotiation, and individuals and interactions over processes and tools. The very first of the 12 principles states that the highest priority is to satisfy the customer through early and continuous delivery of valuable software. So the intent to center human users and their needs is there. If I was a good Scrum Master, shouldn't I be able to be a good UX advocate?

However, the problem lies not in Agile’s intentions, but in how Agile is so often misunderstood in practice. Let’s take Scrum, the most popular Agile framework, as an example. UX Researchers don't formally exist in Scrum. The framework only recognizes three roles: Scrum Master, Product Owner, and Development Team member. That means user advocacy gets diffused across the whole team rather than owned by anyone, which in practice usually means no one owns it at all.

Many argue that the prescribed practice of user story formatting for describing work to be done helps ensure the team thinks from the user’s standpoint. Though admirable in intention, this makes the grave error of mistaking Scrum Team members as stand-ins for the user. Finally, sprint timelines and a culture of code releases seen as the only valuable output to the customer means that UX research and other deliverables don’t fit neatly into a sprint plan, goal, or timeline. When is UX research and design supposed to happen? And how can the UX team member fit into the Scrum Team? None of these questions has been answered neatly or satisfactorily by Agile frameworks. 

Ideally, the Scrum Master should help the team learn to center the user, but most Scrum Masters are trained to optimize process, not to ask uncomfortable questions about whether the right thing is being built or if we’re truly designing something with a real user in mind. In addition, the Agile certificate culture actively selects against curiosity. Someone drawn to measuring success according to ticket completion and velocity metrics is never going to become a user advocate — but I’m wired a little differently, drawn more to the people-first aspects of the role and the use of facilitation and coaching to help a team wade through ambiguity and uncertainty. In other words, the Scrum Masters best positioned to become UX advocates are the ones who probably aren’t quite comfortable with what Scrum and other Agile frameworks have become. Which makes my own transition out of the Agile space less of a leap and more of an inevitability.

What I'd Tell a Scrum Master (or Anyone) Considering a Transition to UX

Though I fully believe Scrum Masters are uniquely poised to make the transition to UX roles, I also know I’ve been lucky in doing so. I have made this transition when both the Agile and UX industries are experiencing profound disruption due to AI and an oversaturation of undertrained professionals. But I’ve been asked what I would say to anyone considering a similar move, and here it is:

Be honest with yourself. 

If you’re looking to make this move because you think UX roles mean automatic riches, you’re about eight years too late. You need to be making this move because you love understanding how and why users interact with technology, you love solving interesting problems, and you love the challenge of making technology more human-focused.

Don’t assume a boot camp is your next step.

Don’t automatically sign up for a boot camp and expect a miracle. A boot camp happened to be a perfect fit for me, but most boot camps cover a lot of material very lightly and result in very generic portfolios. 

Find ways to practice UX now.

Find ways to expose yourself to UX experience in your current role. Scrum Masters have access to so many different disciplines that contribute to technical output. If you’re cooling on Scrum Mastery like I was, find what interests you and get involved.

Recognize that it will be an uphill battle.

The UX hiring landscape is particularly tough right now. This is especially true for entry-level positions. Call me an optimist, but I think there is reason to hope, especially as the AI boom reveals that good tools must first be grounded in real user problems and respond to real user needs. Our roles aren’t going anywhere; just know it won’t be easy. 

Large companies will likely ignore your resume.

No matter what you do to make your resume stand out or demonstrate your experience, any automated resume scanning program will likely reject you outright. Either use your network to get introductions or find a company that can value your unique experience and that cares about hiring enough to have their applications evaluated by a human who can see the nuance and value in your varied background.

No Regrets

It may have taken me six years to figure out that what I really wanted was to be a UX Researcher. But standing on that chair in 2019, taping screenshots to the wall, I was already doing it — I just didn't know it yet. And I don't regret the detour. Being a Scrum Master gave me the skills, the instincts, and the drive to do this work well.

Today I'm a UX Researcher at Viget, which means I spend my days diving into ambiguous problem spaces, untangling what users actually need from what businesses assume they need, and asking the question: what do we really need to build here? Right now, that includes helping ensure AI tools are grounded in real user workflows rather than impressive-looking features that nobody actually wanted. And the best part is, I’m working with teams that are agile in spirit – curious, iterative, and user-focused – without being overly framework-dependent.

The UX field is facing real challenges, and I won't pretend otherwise. But I believe the researchers who will thrive are the ones who can move past simply providing deliverables and offer something harder to come by: genuine insight into what makes technology useful to the humans who have to live with it. That, it turns out, is what I always wanted to do. I just needed six years and one very memorable game board taped to a wall to figure it out.

Most people who try Claude Code start the same way: open a terminal, describe a problem, watch it generate some files, feel vaguely impressed, then slowly drift back to their old workflow because it doesn't quite fit into how they actually work. The problem isn't really Claude Code itself. It's that we treat it like a smarter ai chat - something you prompt when you're stuck - rather than a collaborator you set up to work with your project, your conventions, and your process.

This article is about the setup - the effort you can put in that gets you big returns. Specifically, the handful of things that changed how I use Claude Code from "occasionally useful" to "runs in the background while I do something else." I'll use a small demo project throughout - a Node.js CLI task manager called task-pilot to make the ideas concrete.

---

The core insight: context is a resource #

Claude Code's context window isn't infinite. Every session starts fresh. Every sub-agent spawned during a run starts fresh. If you treat context like an unlimited whiteboard, you'll constantly be re-explaining your project, your conventions, and what you're trying to do.

The developers getting the most out of Claude Code aren't the ones writing the most clever prompts. They're the ones who invest in the environment — the files, structures, and tools that mean Claude always has what it needs without you having to provide it manually every time.

Think of context as infrastructure. The sections below are the specific pieces of that infrastructure: a project memory file, a pattern for externalizing plans and artifacts to disk, skills that encode repeatable expertise, hooks that connect Claude to your existing workflow, and a few features that change the practical experience of longer tasks.

---

Start with CLAUDE.md — but write it properly #

CLAUDE.md is the first file Claude Code reads when it opens your project. Most people treat it like a system prompt. Maybe a few sentences describing what the project does. That's underselling it significantly.

A better mental model: CLAUDE.md is an onboarding document for a smart new hire who forgets everything between shifts. It should answer the questions you'd answer in a first day walkthrough: project structure, naming conventions, patterns to follow, things not to touch, how tests are run and written, what the exit codes mean.

For task-pilot, the thin CLAUDE.md we started with looked like this:

# task-pilot
A CLI tool for managing local tasks in a JSON file.

## Conventions
<!-- TODO: fill this out — naming, error handling patterns, test approach -->

After asking Claude Code to interview the codebase and improve it, we got a full document covering the task schema, storage conventions, test patterns, CLI command structure, and more.

The interesting thing: it documented saveTasks() normalizes every task on write — a behavior buried in storage.js that you'd only know from reading the code carefully. Which it did.

That CLAUDE.md now means every new session (and every parallel instance) starts with a complete picture of the project. You write it once and it will remember the important details you need it to across all future sessions.

One sibling worth knowing about: nested CLAUDE.md files. Where your root CLAUDE.md acts as onboarding docs for a new hire, a subdirectory CLAUDE.md is like a laminated instruction sheet bolted to a specific machine; explicit guidance for anyone working in that exact spot. Drop one into a directory with legacy code, sensitive security implications, or just any area that needs a little extra explanation. It's useful documentation for both humans and ai agents. An added benefit: Claude Code will only pull it in when it actually needs to work there – keeping your context as clear as possible.

---

.claudeignore: what Claude doesn't see matters too #

This one is easy to overlook. Claude Code respects a .claudeignore file structured exactly like .gitignore. Excluding node_modules, build artifacts, generated files, and data directories keeps context clean and focused.

For task-pilot we excluded the data/ directory entirely. The actual task data is user-specific and irrelevant to any coding task. A comment in the .claudeignore explains why, which is useful both for humans and for Claude when it reads the project:

# We exclude /data because task data is user-specific and
# not relevant context for code tasks

What Claude doesn't see is as important as what it does. Context hygiene isn't just a performance concern, it also shapes what Claude focuses on.

---

Externalizing artifacts: context that outlives the session #

Before getting into specific tools and skills, there's a pattern worth understanding that makes everything else work better: writing important outputs to disk rather than leaving them in the conversation.

Claude Code's context window resets between sessions. In a long agentic run it can also fill up mid-task, forcing Claude to summarize and compress earlier parts of the conversation. If your plan, your decisions, and your progress state only exist in chat history, they're fragile — subject to compression, loss, and the hard limit of the window itself.

The alternative is to treat files as your persistent memory layer. Any artifact worth referencing later: a plan, a product requirements document (PRD), a spike document, a decision log, a progress checkpoint - they get written to disk immediately. The next session reads the file, not the chat history. Parallel sessions read the same file simultaneously. Sub-agents get pointed at the file directly. Nothing important lives only in the conversation.

---

Skills: packaging your expertise #

This is the one that changed my workflow most meaningfully.

Skills are markdown files that define a repeatable, invocable process. It's like packaging up your expertise (or lack of) and saving it to distribute to your agent. You store them in .claude/skills/, each in its own folder with a SKILL.md. The frontmatter gives Claude Code the metadata it needs: name, description, argument hint, allowed tools.

The right question when building a skill: what do I keep re-explaining to Claude? That is your candidate for a skill.

I'll walk through two that I used in the task-pilot demo.

The prd skill #

Sometimes you leave a placeholder for yourself to come back to later. You create a feature request with no acceptance criteria, no data model, no edge cases. The code Claude writes based on it will be underspecified. The prd skill bridges that gap. Running /prd #1 against task-pilot's placeholder issue fetches it via the GitHub CLI, reads the codebase, and produces a full product requirements document: problem statement, goals and non-goals, user flows, data model, open questions.

The more interesting result: the generated PRD included a "Current State" note at the bottom catching that basic priority support was already implemented in the app. It cross-referenced the issue against the code rather than just filling a template. Output is written to docs/prds/ — immediately available as input for the actual implementation session.

The debug skill #

task-pilot has a bug: storage.js silently truncates any task description over 200 characters on every save. No error thrown, operation looks successful, data loss only visible by inspecting the JSON file directly. Issue #3 describes the symptom with no debug, logging, or line numbers to go off.

Running /debug #3 produces a structured diagnostic report before touching any code and ranked hypotheses.

This is not a Claude Code issue — it's a bug in the project code. No relevant errors in the debug log.             
                                                                                                                                     
  Root cause: storage.js:24 — entry.description = entry.description.slice(0, 200) runs on every save, not just on creation. When     
  completeTask() calls saveTasks(), all existing descriptions get re-truncated to 200 chars, silently corrupting any longer
  description.                                                                                                                       
                                                                                                                                     
  The fix: remove the truncation from saveTasks() and validate at input time in addTask() instead — or remove the 200-char limit     
  entirely. Want me to implement the fix?  

It then stops and asks whether to implement the fix. That pause is intentional — diagnosis and implementation are separate decisions, and seeing the reasoning before approving it is the point.

Skills compound — and so does the library you build #

These are just two examples. The real power is what happens as you accumulate them — each skill is a process you never have to re-explain, each one increasing your effectiveness.

Over time your skills directory stops looking like a collection of prompts and starts looking like a team's knowledge, bottled. A new developer joining a project can run /prd, /debug, and /spike on day one and immediately work at the level it took you months to reach. That's the compounding effect of skills done well — not just that you get faster, but that the expertise becomes transferable.

---

Connecting to your tools: CLI integration and MCP #

Claude Code can call any CLI tool available in your terminal, which makes the GitHub CLI (gh) a natural starting point. You can point Claude at an issue, let it read the spec, implement against it, and open a PR — all in one prompt, all without leaving the terminal.

For task-pilot's Issue #2 — a feature request with acceptance criteria, data model changes, CLI flag specs, and backward compatibility requirements — the prompt was:

Read GitHub issue #2 using the gh cli, then implement everything described.
Make all necessary changes to tasks.js, storage.js, cli.js and format.js,
write tests covering the acceptance criteria, then open a PR against main.

It fetched the issue, read the codebase, touched four files, and wrote 17 new tests covering the new feature addition, overdue detection edge cases. All 27 tests passed — 17 new, 10 existing. The acceptance criteria in the issue drove the test coverage directly.

That said, CLI integration via gh is really the floor, not the ceiling. The more powerful version of this is MCP — Model Context Protocol.

Where the GitHub CLI lets Claude run shell commands against GitHub, an MCP server gives Claude structured, authenticated access to an external system as a set of typed tools it can call directly. The difference matters: typed inputs, scoped permissions, consistent interfaces, and no reliance on parsing CLI output. Claude isn't shelling out and hoping, it's calling a well-defined API.

For a project management workflow, the benefits are significant. With the GitHub MCP server, Claude can read issues, fetch file contents at a specific ref, check PR review status, and reason about the state of your repository. It's not just executing git commands.

MCP Servers work with the tools your team already uses — Slack for async context, Notion for documentation, GitHub for tickets, or even your own internal APIs. MCP is the mechanism by which Claude Code stops being a smart terminal assistant and becomes an agent with actual access to your working environment. The developers investing in MCP integrations now are building something that will compound as the ecosystem grows; every major tool will have an MCP server eventually, and knowing how to wire them together is increasingly a core skill.

---

Hooks: participating in your existing workflow #

Hooks are shell commands that Claude Code fires automatically at defined points in its lifecycle. Most people don't know they exist.

The most immediately useful pattern: a post-task hook that runs your test suite automatically every time Claude finishes editing code. If tests fail, Claude sees the output and knows to fix before considering the task done. You don't have to tell it to run tests and try again when they fail — it just happens.

Other practical uses: auto-committing to a working branch after each completed subtask (giving you a clean git history of what Claude did and when) or running a lint check before Claude starts work to ensure the environment is clean.

Hooks are how Claude Code participates in your existing workflow rather than sitting beside it. It stops being a separate ai tool and starts being a step in your pipeline.

---

Remote control and model switching #

Two features worth mentioning that change the experience of longer running tasks.

claude rc (remote control) lets you start an agentic run on your machine and supervise it from your phone via the Claude app. It's easily my favorite new feature. You're not babysitting Claude; you're checking in. It keeps running while you're away. This changes your relationship with long-running tasks in a meaningful way: you can kick off a substantial job, step away, and get notified when it's done.

A few weeks ago, we paused client work for Pointless Palooza, our internal hackathon. It was our largest and most successful Palooza to date! Eight teams shipped projects, prototypes, and explorations in roughly 48 hours. 

It was 9AM on the first day of Pointless Palooza 2026. A product manager, a client strategist, and a JavaScript developer had a raw concept and 12 hours blocked out to create something usable. Think of a reality competition cooking show, but for an app.

By 5PM, we had a working prototype for our core concept: a map showing where people have lived over time, with a slider that lets you drag through the years and watch locations appear and disappear. When two people were in the same place at the same time, you'd see it. The ultimate goal was to identify these overlaps quickly, spark connections, and inspire conversations.

This was Matt's and my first Palooza. Maria had participated before, but this was the first year where AI played such a big role. This is the story of building Wereabouts. The decisions we made, the problems we hit, and what we learned about the balance between AI assistance and human judgment.

<task>
Generate 20 creative, memorable, and marketable app names for my new product.
</task>

<description>
[Interactive timeline map that visualizes location histories and reveals serendipitous overlaps]
</description>

<keywords>
[serendipity, connections, timeline, travel, mapping, shared experiences, location history]
</keywords>

<target_audience>
[Frequent travelers, remote workers, expats, socially connected professionals]
</target_audience>

<brand_vibe>
[Minimalist, Friendly, Playful]
</brand_vibe>

The Pitch

Stuck grinding through grammar drills and decontextualized vocabulary lists with no easy way to just start speaking? That's where one of our Viget teammates found herself when trying to level up her K-Drama watching experience.

For Pointless, our internal Viget hackathon, UX Researcher Megan pitched a different approach: a language learning app that teaches the way children actually learn—through simple, high-frequency words in context, not endless grammar exercises. Start with common 1–3 syllable nouns and verbs, drop them into 3–5 word sentences, and let users hear proper pronunciation while quizzing themselves.

Fellow UX Researchers Laura and Liza were hooked. We dove into Pointless to see what the three of us could experiment with and build in 24 hours using AI, without developers. We all agreed to adopt a "throw spaghetti at the wall" approach—see how much we could experiment with an AI-forward approach. 

---

The Evening Before

We wanted the right setup so hackathon day would run smoothly. Megan turned to Claude as our technical advisor, who generated a project plan with detailed instructions on tools and how everything would connect.

Most people would rather be locked in a dark room with a poisonous snake dressed as an evil clown holding a giant spider than give a speech.

And yet, the ability to speak clearly, confidently, and thoughtfully in front of other people is one of the biggest career advantages a person can have. It doesn’t require unique talent, it takes practice. It’s something we’ve practiced at Viget for more than 25 years.

What’s a Labshare?

Every week, we gather for Free Lunch Friday (FLF), our weekly staff meeting. The schedule is simple: 15 minutes of unstructured social time, 30 minutes of company updates, ending with a 15-minute Labshare. That’s a full hour of otherwise billable time for the full team – an expensive investment that continues to be worth every penny.

Pre-Covid, FLF was mostly an in-office experience, so a presenter would enjoy a live studio audience of a dozen or two, with another 50 or so folks joining via video. 

Rethinking the concept of your to-do list and ever-growing checklists, our hack-a-thon team decided to flip the script. We didn't want to build another app that tells you what to do; we wanted to build one that rewards you for what you don't do.

Meet the To-Don’t List: Productivity’s mischievous twin. It’s a gamified habit tracker where "doing nothing" is the ultimate achievement. Instead of checking off tasks, you’re resisting temptations. Whether it's "Don’t check social media before noon" or "Don’t eat the whole cake," every moment of restraint earns you progress.

Design & Experience

We wanted the app to feel like a cozy garden, inspiring growth and mindful habits. We leaned heavily into an 8-bit pixel art aesthetic, drawing inspiration from Stardew Valley, Pokémon, and Tamagotchi. We crafted a logo with a pixel script font paired with a delicate plant sprout. Riffing on the garden elements, we included falling cherry blossom petals for a login transition. 

Pointless FLF is a Slack-first tool for coordinating our weekly internal live show called Free Lunch Friday (FLF). Think: recurring segments, rotating presenters, and a producer brain trying to keep the whole thing from going off the rails.

The product focus wasn’t “make the show better.” The show is already pretty good. The focus was everything around the show: the coordination overhead that repeats every week, like slot filling, gentle nudges, run-of-show drift, and the constant “wait, what’s the plan right now?” when state is distributed across humans and Slack scrollback.

This is the story of building the app and the workflow used to build it with agents: what worked, what didn’t, where tests helped (later), and what it feels like when your tools have an internal state you can’t inspect.

The problem: the uncertainty tax #

Most of the work isn’t “doing the show.” It’s maintaining shared state: who’s in, what’s next, what changed, and what’s still missing. When the shared state is implicit, the system generates extra traffic, pings, follow-ups, and duplicate questions just to keep reality synchronized.

Every week someone needs to:

• find people to fill “quickshare” slots
• nudge presenters through prep (opt-in, non-annoying… ideally)
• keep a run-of-show coherent as it changes
• handle last-minute swaps without melting the producer

In the baseline workflow, state lives in two places:

1. Slack messages (scattered, non-authoritative, and sometimes poetic)
2. people’s heads (authoritative, but not queryable)

This works until it doesn’t. The cost spikes right when you want stability: during the live show, when everyone’s attention is already spent.

So the goal was simple: reduce ongoing cognitive load and coordination labor without creating a new job titled “person who maintains the coordination tool.”

Product Philosophy: assist, don’t overwhelm #

I set constraints early and treated them like product requirements, not vibes:

• Assist, don’t enforce. No readiness policing. No mandatory status updates.
• Opt-in by default. It should help even if adoption is partial.
• Tolerate mess. Reordering, missing info, and late changes are all normal, not error states.
• Low-noise. If the tool spams the channel, congratulations: you made Slack worse.

Tools that try to do too much can become more of a hindrance than a help. The “feature ceiling” matters as much as the feature floor.

What I built: #

The system ended up as three pieces, intentionally biased toward Slack.

Slack bot (primary surface) #

Slack already held the social reality of coordination, so the bot needed to live there:

• one weekly anchor message
• the thread is the control plane
• updates via message edits (so the channel doesn’t become bot confetti)
• slot claim/unclaim + producer controls + live “what’s next” state

Web app (producer control + visibility) #

Slack is great for quick actions; it’s not great for “dense editing.” The web app is for:

• producer management
• schedule editing / reordering
• clearer overview of current state for contributors

Notion (optional, read-only archive) #

It’s very easy for a Notion integration to turn into “maintain the Notion integration,” which I expressly didn’t want so the rules were strict:

• read-only
• auto-generated from Slack-backed state
• no manual data entry required, ever
• tool works fully without Notion

The process: #

Agent workflows have a brutal property: they amplify whatever you give them. If the inputs are vague, you don’t get “a vague result”—you get a very confident, very detailed version of the wrong thing. Classic Garbage In, Garbage Out.

So I deliberately didn’t start by “letting the agent code.” I started by tightening the inputs: a PRD, explicit acceptance criteria, and a technical plan that forced decisions into daylight. That up-front definition work wasn’t process theater; it was how I kept the build from iterating quickly in the wrong direction.

ideas → specs → plans → milestones → tasks

This process should be familiar. It’s a pattern that already works outside of agentic workflows but it’s also a superpower. If you want agent-driven development to stay coherent, you need a pipeline that actually produces durable artifacts.

Here’s how I approached it.

1) Ideation → PRD + acceptance criteria (ChatGPT) #

I used ChatGPT early to convert a fuzzy idea into something testable:

• problem framing
• PRD draft
• acceptance criteria

Acceptance criteria are the difference between shipping vibes and shipping something that actually meets its goals.

2) PRD → technical implementation plan (Codex, Plan Mode) #

Next, those docs became inputs for GPT-5.2-Codex in Plan Mode. The job here was not “write code.” It was:

• propose architecture
• surface risks (Slack mechanics, state, integrations)
• iterate on decisions until the plan was coherent and sequenced

3) technical plan → milestones/scopes (Codex + a custom skill) #

I used Codex again for decomposition. I wrote a custom skill that turns the technical plan into milestone-shaped scopes of work.

The output wasn’t just a document. It became operational: epics and tasks, ready to execute.

4) milestones → execution (Beads) #

Those tasks were created in Beads, which gave me a real work graph. This mattered because:

• “what’s next?” stopped living in my skull
• tasks had acceptance targets, not just vague intent
• the agent loop stayed anchored to explicit outcomes

One of the problems I have as a romance novel enthusiast is finding my next favorite read. I have very specific book interests, but struggle to find exactly what I’m looking for. The book recommendations I get on Goodreads or Amazon don’t really help. Despite knowing what’s in my digital library, they often direct me to books I’ve already read or authors I keep rejecting. 

Like me, many Viget employees are passionate about books, and we even have a #books channel on Slack, a book club, summer books bingo, and an annual books roundup. With so many avid readers, I found it fitting to tackle a book-related challenge during Pointless Palooza and pitched a better book recommendation tool.

Tommy Rehnert and our top book lover, Laura Sweltz, joined me in the challenge of bringing Shelf Help to life during Viget's annual hackathon. Over the course of a few days, we had the opportunity to explore new tools, build something fun, and advance our personal skills. 

Remote work removed the need for a commute and allowed people to clock-in from anywhere, but it also blurred the boundaries between work and home life. For employees craving a separation, Abby Smith’s idea of Scooter Commuter is the answer. 

Abby pitched the idea of creating a ritual that makes the invisible commute visible by simulating the feeling of waking up, taking a yoga class, getting ready, grabbing a coffee, and commuting to the office while never leaving your house. Claire Atwell Eisinger, Jackie Yu, Sadie Finn, and Bre Corn joined the team and helped make the game come to life in 48 hours for our annual hackathon, Pointless Palooza. In this short time we went from idea to innovation as we explored new skills and tested new tools.

Scooter Commuter is a lightweight game played in the browser and designed to help remote workers mentally transition into their workday. Players move through a series of small, playful moments which creates the mood for intention, boundaries, and a healthier start to the day.

Game Inspiration

Before building, we tested some popular, nostalgic, and niche games to see what game style and elements we wanted to incorporate in Scooter Commuter.

• Pac Man
• Daily Dungeon
• NYT Wordle

We discussed core elements that make these games exciting for us to play and that we wanted to nail in our own project. These were our top 10:

1. Clear and simple rules
2. Meaningful user choices
3. A reasonable challenge curve
4. Consistent feedback loops
5. Intrinsic motivation
6. Accessibility
7. Curiosity gaps
8. Social connection & competition
9. Visual clarity
10. Reactive controls

Brainstorming

After nailing down our inspiration and requirements, we got to work on visualizing our ideas. We created shared Notion and Whimsical workspaces to individually think through our ideas before collectively deciding on a direction.

Sadie leveled up our conceptual Viget inspired commute by suggesting we help players jump start their day by using the game to prompt players in real life. They are encouraged to grab snacks, do sun salutations, hydrate, get dressed, and turn on their favorite playlist. 

Creating

With a solid idea, guidelines, and benchmarks, we got started bringing this idea to life. We created a version plan of the game that would lead to the best results before the deadline.

Abby completed the heavy lift of developing the entire game. She took a crash course on Phaser, handled repository setup, and refactored a 1000-line code base to help our vision come to life. Claire took on the work of not only containing this project but literally containing the game by converting the wall system from rectangles to individual tiles, using Copilot.

Their work resulted in a final tech stack of: JS / React, Phaser.js, and Vercel.

At Viget, we have a sizable group of Obsidian enthusiasts. During this year's Pointless Palooza hackathon, our three-person team of Natalie, Jackson, and Joshua (that's me!) explored ways to integrate LLM features into Obsidian and empower our coding agents to work within our content vaults. Each of us brought different experience levels and workflows to the table, but we shared two things: curiosity about pushing Claude Code to its limits and an Obsidian habit that keeps on growing.

Claude Code + Obsidian #

If you've never used it, Obsidian is a local-first, Markdown-based knowledge management app. It's flexible, extensible, and an excellent digital junk drawer. Obsidian vaults are just Markdown files and folders on your computer. It's the perfect fodder for an AI agent to churn through.

Tools like Claude Code are surprisingly effective as a general agent for knowledge work. Open it inside of an Obsidian folder and say: "You're in my Obsidian vault. Let's talk about it." It already knows what Obsidian is, how Markdown works, and what frontmatter means. For ad hoc queries, this requires zero setup. Being grounded in a local filesystem moves you from one-off chat threads to a durable workspace that evolves over time.

Here’s an example: Every Friday, I photograph my Analog to-do list cards and run a Claude skill. It asks me questions about my messy todo list, cross-references my yearly goals and past performance reviews to generate a weekly summary. You could do all these steps without AI, but automation eliminates all the busywork that killed my consistency. This context builds up over time and becomes more useful to Claude as it grows.

The Limits #

Despite their usefulness, an AI agent isn't a silver bullet. Naively pointing Claude Code at a raw vault has real limitations:

• Large vaults are slow. With 3,000-4,000 notes, Claude Code burns through tool calls and tokens just searching for relevant content.
• General-purpose means wasteful. Just now I asked Claude Code to summarize a YouTube video. It used yt-dlp to download a VTT transcript, wrote a Python script to parse the VTT, and finally summarized said transcript. Running ccusage shows this session took almost 500k tokens and would have cost $1.02 in API calls. Claude Code is powerful, but expensive for routine tasks.
• Token budgets disappear fast. A typical Claude Pro subscription can hit usage limits in a single ambitious session, leaving no budget for coding.

What if we could write an Obsidian plugin to help?

Our Pointless Pitch #

We wanted common LLM operations to be automatic and affordable. Summarizing clips, tagging notes, and synthesizing across files could happen inside Obsidian rather than through an expensive, general-purpose agent session.

No more copy-pasting YouTube transcripts. No more burning Claude Pro credits on tasks a $0.001 API call can handle.

What We Built #

We built an Obsidian plugin that connects your web clipper and file tree to cheap, targeted LLM calls. The following two user journeys nicely sum up our plugin's features.

Web Clipper: Auto-Summarize on Save #

At this point in your knowledge work adventure, you're browsing the web and gathering resources to read later or archive for future reference.

The Obsidian Web Clipper already lets you bookmark pages into your vault, but our plugin takes it further. The moment a clipped page lands in your vault, it auto-generates a structured summary and tags. If the clip is a YouTube video (or eventually a podcast URL), the plugin fetches the transcript, appends it to the note, and uses it to inform the summarization task.

Avid followers of the Viget blog may remember the announcement of a particularly exciting-sounding Viget intern project called Parakeet back in August, which came with the promise that “it’s going to be available for everybody to use… eventually.“ I’m very happy to report that “eventually” has finally come!

Next week, we’ll run our annual Pointless Palooza. As with many things in this age of AI, this one feels different.

Pointless Corp. is Viget’s innovation lab. Neither pointless nor a corporation, it’s been our long-standing answer to a simple question: how do we make space to build things without the constraints of client work? Things that aren’t revenue-driven, don’t need a business plan, and don’t even have to work to be considered a success. It’s how we try, fail, and try again in ways that make us better.

That mission hasn’t changed, but the tools we have to work with certainly have.

It was hard, in 2025, not to get overwhelmed by the near-daily news around large language models, chatbots, and everything else AI-powered. I try to stay a little skeptical of the new and shiny in the tech world, but even as an AI skeptic it seemed clear that these tools were approaching an inflection point from "cool in theory, busted in practice" to "actually pretty useful." I also realized that it might be existential for me, as a designer and leader at a digital agency, to not lose sight of where these tools are going.

Staying informed was my first goal. To stay in the loop, I started curating a list of people I thought were providing a clear-eyed view of the AI-powered future. For example:

• Jackie Liang who works in the AI tooling space, but is also building his own AI-powered side business.
• Simon Willison who dove into the AI world early and has maintained a nicely balanced perspective on the industry.

I get plenty of AI boosterism through LinkedIn and other mainstream sources, so I've tried to keep that perspective out of my curated feeds. I'm also trying to ground myself by following strong skeptics and no one is more skeptical of AI than your favorite author. I'm a book nerd, so I get strong AI opinions from many of the authors I follow in sci-fi, fantasy, and romance. Balancing these voices has helped me feel like I'm keeping up on the news of the day, without getting lost in the hype.

It also became clear to me that I needed more hands-on experience if I was going to have an informed opinion about how good (or not) these tools have become. I needed a project, but I wasn't comfortable throwing these tools into the mix on a client project just yet.

To get the experience I wanted, I decided to reboot my very neglected blog (most recently living on Tumblr, if that tells you just how neglected it was).

March 2025: A Blog Exists

One reason I enjoy having a blog is that I get to play with blogging software. I'm weird that way. I've used Wordpress, Movable Type, Blogger, Blosxom, Jekyll, Tumblr, and probably a couple others I've forgotten. I wanted a static site generator like Jekyll, but new! My co-worker David gave a great presentation at work about using Hugo, so that seemed like a good option to try.

To kick things off, I asked three different web-based AI dev tools—Lovable, Bolt, and Replit—to build me a Hugo-based blog. I gave them some design direction and a few posts to populate this new blog.

• Lovable: We're off to a rough start. I ran into technical issues, like the chat UI failing to load, on a regular basis. Then I found out Lovable didn't grok Go, so it built me a site using React, which wasn't really what I was aiming for. 
• Bolt: Bolt happily built me a site in Hugo! But I noticed there were a lot of errors cropping up in the console. Turns out Bolt didn’t actually support Hugo, or Go. Bolt offered to migrate the project to Astro.
• Replit: Replit was quick to note that it didn't support Go and also suggested I try Astro as another option. Which is fine, but not what I wanted. A few weeks later I tried again and Replit had added Go support and I finally had my Hugo blog!

While I came away with generally positive feelings for the potential of all 3 tools, my experience in March reinforced my perspective that these tools weren't yet delivering on the promises they were making.

July 2025: A Different Blog Exists

Then I got distracted for a few months. Summer rolled around and I had time to dive back in to this project. By July I had a Claude Pro account, so I rebooted the project and installed Claude Code. I had Claude spin up a new Hugo setup ... and it worked flawlessly. I got my theme tweaked, imported my starter posts, and then I had Claude help me add a few extra bits. The most notable is the following tab, which is built from my NetNewsWire OPML file.

Also, Claude helped me get Netlify auto-deploys working from Github. Thanks, Claude!

It was pretty remarkable how much better the experience was working with Claude Code in July compared to my experience in March. I suspect I would have had a similarly improved experience with Lovable, Bolt, or Replit had I given them another chance.

December 2025: Have Blog, But No Blog Posts

I had my blog. I wasn't writing in my blog. So I decided to try building something to make the writing process easier. If my experience over the Summer showed me that these tools could be useful, my experience at the end of year demonstrated just how powerful they could be. As I explored different ideas, I realized that I could actually make them happen. I really enjoyed being able to take a wild idea and quickly(ish) translate that idea into something I could test. Here's a subset of the tools I explored:

• The desktop app: I tried building an electron-based app that used AI to jumpstart the writing process. I could drop in some links and the AI would write a draft post on the connections between the articles. It was fun to play with some ideas on how AI can help with writing, but ultimately this felt too heavy.
• The menu bar tool: The desktop app was too much, so I pivoted to something very small. I built a small app that could live in the MacOS menubar that would make it easy to spin up a new blank post in my editor of choice. And that was it! The app itself was nice and small, but I had to install a whole lot of stuff to build it (xcode). Ultimately, I realized I just didn't want to blog in VS Code.
• The Obsidian blog: I had Claude help explore an integration between Hugo and (the note taking app) Obsidian. This seems like it could be a neat way to manage content, but I'm not super comfortable with Obsidian just yet. I might try this again later.
• The web app: Having realized I didn't want to use VS Code to write blog posts, I had Claude build me a web app that I could run locally to make the writing experience more pleasant. This tool started simple—it lets me create and update posts. I can commit changes and push them to Github to trigger Netlify builds. I like it a lot and I'm using it to write this post.

From Skeptical to Less Skeptical

In retrospect, this project tracked pretty closely with some important moments in the broader AI narrative of 2025. Those early experiments showed an ecosystem with more promise than delivery. By December, the foundational models like Claude and ChatGPT had improved dramatically as coding assistants.

I can now pretty clearly see the value of an AI-powered coding tool, at least for myself. And not just for coding things! I've got Claude Code open 24/7 in a terminal tab. I've used it to build tools, do data migration and cleanup, and help me see trends in performance review data. It's not suprising that Anthropic just launched "Claude Cowork," essentially Claude Code rebranded as a personal assistant.

I still don't see myself as an AI true believer. I think the AI bubble is real and 80% of the hype is hot air. I’m also not a full-on skeptic anymore. That said, there some areas where my skepticism is still high:

• I don't think we'll ever see a proper reckoning over the fact that all of the foundational models engaged in intellectual property theft to develop their models.
• I don't think these models can really think outside the box. They are, by nature, "average machines." That said, it turns out that being an infinitely patient average quality coding machine can be pretty darn useful.

I don't think I'll be any better at posting to this blog than I have been in the past, but one can always hope. At least I have a nice new web app to help me write posts thanks to the robots (and also nice human co-workers to proofread this post).

The lesson I take away from 2025, and this project specifically, is that we can’t wait around to see how our AI era will shake-out. It’s complicated and there’s a lot going on ALL THE TIME. It’s incumbent on us, as designers, as builders, to keep experimenting and look for the signal within the noise.

Every year, businesses set ambitious goals: growth targets, efficiency gains, cultural commitments. And every year, many of those goals quietly fade, not because they were wrong, but because there wasn’t enough operational structure behind them. The same dynamic plays out at the individual level with New Year’s resolutions. 

In January, I have clear eyes, a fresh outlook, and the urge to improve. It feels like I can’t lose, and this year is no different. Personally, I welcome the new year as a fresh start and a chance to reset on my priorities. Like so many other people, I set goals year after year to prioritize my health and reduce stress. 

Setting goals is the easy part, but keeping them? Nearly half of us are likely to abandon our resolutions by the end of January, and only 9% will complete them by year's end (Forbes).

This means that even the best laid plans and the purest intentions need operations, not just optimism to make it to the top 10%. Goal setting is a great start, especially well-defined ones, but once the excitement wears off, all that we’re left with is the real everyday work. 

On an individual level, abandoned resolutions sting but rarely have lasting consequences. For businesses, though, the stakes are higher. Deprioritizing your stated goals may enable short-term gains, but it risks long-term damage like diminished credibility, lack of alignment, and poor morale. At any scale - personal, team, or company - translating goals into action, momentum and success is enormously powerful.  

My position as a Business Development Operations Associate here at Viget is all about operationalizing success. My job is to build the systems that help Viget’s goals actually happen. Here’s how I do it:

1. Replace Motivation with Systems. Motivation fades, systems stay, and they simplify the work. In BD ops, I don’t rely on daily inspiration to track projects or follow up on tasks. Building infrastructure with automated reminders, templates, and consistent ways to analyze criteria, makes the right actions automatic and less chaotic. Setting up Slack Canvases, for example, helps reinforce that system by keeping key context, checklists, and decision notes in one living doc that the team can update over time.
2. Create More Checkpoints. Regular reviews beat year-end recaps. In operations and my personal life, I've learned that consistent check-ins catch issues early, which limits missed follow-ups and long stretches of misaligned priorities. Getting real-time feedback, even when it's uncomfortable, lets us actually improve instead of repeating the same mistakes. Short feedback loops also promote accountability; nothing falls off anyone’s radar for long.
3. Secure Small Wins. One improved process compounds over time. This month I might standardize agendas and call notes, which paves the way for next month’s focus on streamlined documentation and resource management. These aren't flashy; honestly, they are quite thankless— and I like them that way. However, they add up to  quicker responses, cleaner handoffs, and hopefully higher close rates. Small operational wins build the momentum that big goals require.

With that being said, resolutions can be rigid and binary; you make them or break them. But operations? Operations can bend, adapt, and build. That's how we end up in the 10%– not through willpower, but through systems that make success inevitable.

How is your company approaching 2026? 

Spooky Season in December?! #

I came across an image recently that really threw me for a loop. Before I show it, I wanted to note that I do not condone doing what the next image does. You have been warned.

[alias]
    addp = !git add -N . && git add -p

abbr -a -- gap 'git add -p'

abbr -a -- gap 'git addp'

git config --global core.pager delta
git config --global interactive.diffFilter 'delta --color-only'
git config --global delta.navigate true
git config --global merge.conflictStyle zdiff3

abbr -a -- gco 'git checkout'
abbr -a -- gcob 'git checkout -b'
abbr -a -- gpo 'git push origin'
abbr -a -- gap 'git addp'
abbr -a -- gst 'git status'
abbr -a -- gcm 'git commit -m'
abbr -a -- gpof 'git push origin --force-with-lease'
abbr -a -- gl 'git log --oneline'
abbr -a -- grc 'git rebase --continue'

Every quarter, our Design and UI Development teams meet to talk shop and see what everyone's been up to across our labs. This Q4, we shared our favorite finds—things that shaped our work or just sparked inspiration and joy. And since AI comes up in pretty much every conversation these days, we figured why not let Claude help us share them in a way that evokes the spirit of the holidays? Hope you enjoy!

---

'Twas the end of the year, and throughout our whole team,
 Not a pixel was moving, not even a meme.
 Our Figmas were closed with their booleans set right,
 In hopes that good workflows soon would take flight.

The designers were nestled, all snug at their desks,
 While visions of Tillamook danced in their heads.
 When out on our Slack there arose such a clatter,
 We sprang from our chairs to see what was the matter.

Away to our screens we flew like a flash,
 Opening channels and clearing the cache.
 When what to our wondering eyes did appear,
 But a list of the tools that had helped us this year.

With Claude and VSCode, so lively and quick,
 We knew in a moment prototyping's the trick.
 More rapid than sprints, our discoveries came,
 And we whistled and shouted and called them by name:

"Now Tillamook! Now Godly! Now Pudding and Jitter!
 On Affinity! On SVGOMG! On Focus Friend that glitters!
 From the top of localhost to our client call,
 Now optimize! Animate! Prototype all!"

The visual designers—how their eyes, they did twinkle!
 Using Jitter for Viget, without even a wrinkle!
 Their scroll-based prototypes, were no fuss to make,
 Showed developers motion for everyone's sake.

The product designers, with a wink of their eye,
 Built localhost examples (Claude didn't shy).
 For AI-native interfaces, this was the way—
 To play with ideas, not debate all the day.

The platform developers laid fingers to keys,
 Exporting WebP files with elegant ease.
 With SVGOMG they optimized fast,
 From one kilobyte saved to ninety percent!

We marveled at Pudding, their onions so fine,
 Where animation helped storytelling to shine.
 And Antlii's portfolio, patterns galore,
 Showed generative effects we couldn't ignore.

Then someone spoke up with a curious admission,
 About Character Quizzes and product positioning.
 We laughed at this wild card, so random yet true,
 How a personality quiz became part of our crew.

But the star of our year, our communal decree,
 Was Tillamook's website—what brilliance to see!
 With brand and with motion and function combined,
 "What would Tillamook do?" became our refrain defined.

And so as the year comes to a close,
 Our team had found tools that helped us compose
 Better handoffs, workflows, and collaborative might,
 We'd refined our whole process and gotten it right.

We sprang to our channels, to the team gave a cheer,
 "Here's to staying curious throughout the new year!
 May our prototypes render, our icons align,
 Happy 2026 to all, and to all a good design!"

On a recent TypeScript project, we ended up in a situation where editor performance had degraded and the TypeScript compiler (and language server) was increasingly struggling with some specific areas of the codebase resulting in sluggish intellisense, long type-checking times, occasional stale type information, and a lot of frustration.

This project is a monorepo with 7 TypeScript packages. To the credit of the original creators, it is already using project references (which requires the composite setting), and incremental compilation but it also has some heavy TypeScript dependencies like prisma, kysely, ts-pattern, and hotscript.

Diagnosing The Problem #

When doing any sort of troubleshooting, my first port of call is the docs. To my knowledge, there isn’t a dedicated page on https://www.typescriptlang.org/ for this, but a quick search leads to the GitHub wiki page on Performance which has a bunch of sage advice and useful suggestions.

It’s wise to begin with the usual suspects:

• make sure your editor is up to date including plugins and extensions
• disable all editor extensions to eliminate them from the list of suspects
• make sure no other processes are hogging system resources
• use the latest version of TypeScript that you can use (many releases include performance fixes and optimizations)
• update dependencies to the latest version whenever possible (including any @types declarations your dependencies need)
• use strict compilation unless you have a good reason not to and you know what you’re doing (it allows the compiler to check for more kinds of potential problems and also to use certain more performant algorithms like faster variance checks)

From there, you can start to dive into additional information that the TypeScript compiler can provide:

Validating Source Files Inclusion #

Ensure that only the minimal set of source files are being processed by the compiler.

$ tsc --listFilesOnly

Why?: fewer files = fewer types = less work for the compiler.

If you see files that you don’t expect in the compilation, you can ask the compiler to tell you why they are included:

$ tsc --explainFiles > explanations.txt

Tweak your tsconfig’s include/exclude/types/typeRoots/paths as necessary if adjustments are needed to omit unneeded files from the compilation

Performance Metrics and Measurement #

Performance tuning requires careful planning and execution. In order for two compilations to be meaningfully comparable, it’s important to make sure they’re run on the same hardware and under the same conditions (system load, battery/power, etc.). Even under carefully managed conditions, outliers can skew results so it’s wise to run the compilation several times in order to get a good sense of variance. A rigorous approach would be to use statistical analysis to calculate significance based on standard deviations, but if compilation times are long then that can be prohibitively time-consuming.

Establishing a baseline is crucial when doing any sort of optimization work in order to assess whether subsequent changes have a meaningful positive impact. To do this, the TypeScript compiler offers a flag that outputs detailed metrics about the compilation: tsc --extendedDiagnostics. When you run that command, you’ll get an output that looks like the following (you may see more than one such report if you have multiple TypeScript projects in your compilation):

Metric	Value
Files	6
Lines	24,906
Nodes	112,200
Identifiers	41,097
Symbols	27,972
Types	8,298
Memory used	77,984K
Assignability cache size:	33,123
Identity cache size	2
Subtype cache size	0
I/O Read time	0.01s
Parse time	0.44s
Program time	0.45s
Bind time	0.21s
Check time	1.07s
transformTime time	0.01s
commentTime time	0.00s
I/O Write time	0.00s
printTime time	0.01s
Emit time	0.01s
Total time	1.75s

Of the many data points this analysis reports, the most useful metrics to look at are the number of files and types, amount of memory used, and the amount of time spent doing I/O, parsing, and type-checking. If I/O times are high or the number of files/lines are high look at Validating Source Files Inclusion.

Deeper Insights with Compiler Traces #

If the compiler is spending a lot of time in the parse, bind, or check phases, then capturing a trace can help identify which parts of your program are contributing most to this expense. The compiler offers a flag that instruments everything it does which produces a dataset that can be mined for deeper insights: tsc --generateTrace <output_dir> (available since TypeScript 4.1). If this command is giving you trouble, make sure you’re not doing an incremental build by passing in the -f argument (for build mode) or --incremental false (for regular compilation).

Running this command will output some files into the given directory. The outputs will look a bit different depending whether you’re running tsc in build mode (-b) or not, but either way there will be one or more JSON files for types and trace. Look for the largest of these files as a starting point or check these docs for a more complete explanation.

These traces can be analyzed with Chrome’s trace viewer (which should be available at about://tracing in Chromium-based browsers including Arc). You can also try the newer Perfetto UI but I have had better luck with the older method.

Issues I ran into: #

tsc fails with a Heap Out of Memory error when running extended diagnostics and/or traces

By default node processes (since version 12) have a maximum heap size that depends on the system’s available memory. On many modern systems this defaults to ~2GB. If you run into errors related to memory, you can bump up the maximum allowed memory usage by passing a flag to node (note this command runs both the extended diagnostics and generates trace files during one compilation run):

$ node --max-old-space-size=8192 ./node_modules/.bin/tsc -b --extendedDiagnostics --generateTrace ./ts-trace

Trace Files can’t be analyzed by trace viewer

Trace files can be quite large — so much so that tools like about://tracing and Perfetto UI will refuse to process them. That was the case for some but not all of the trace files for me and I ended up relying on @typescript/analyze-trace to understand them.

The recommended process-tracing script outputs nothing

The Performance Tracing docs suggest using a process-tracing script to sample extra large traces in order to produce smaller traces that are easier to work with. In practice, this script just output empty files when I tried it. YMMV.

Identifying the Root Cause(s) #

In our specific case, @typescript/analyze-trace was the key to identify the most problematic application code. Because of the monorepo structure of this project, there were 6 or 7 trace files to consider. Not all of them contained obvious issues, but eventually I stumbled upon this one and was immediately intrigued.

$ npx analyze-trace ./ts-trace

Analyzed /<client>/<project>/packages/<package>/tsconfig.json (trace.12493-5.json)
Hot Spots
├─ Check file [35m/<client>/<project>/packages/<package>/src/tasks/extractions/common.ts (80609ms)
│  └─ Check deferred node from (line 10, char 10) to (line 29, char 4) (80608ms)
│     └─ Check expression from (line 11, char 12) to (line 28, char 7) (80607ms)
│        └─ Check expression from (line 11, char 15) to (line 28, char 6) (80607ms)
│           ├─ Check expression from (line 13, char 7) to (line 27, char 8) (51716ms)
│           │  └─ Check expression from (line 14, char 9) to (line 26, char 12) (51711ms)
│           │     ├─ Check expression from (line 24, char 18) to (line 25, char 69) (38423ms)
│           │     │  └─ Check expression from (line 25, char 13) to (line 25, char 69) (38422ms)
│           │     │     └─ Check expression from (line 25, char 44) to (line 25, char 68) (14922ms)
│           │     └─ Check expression from (line 14, char 9) to (line 24, char 17) (13287ms)
│           │        └─ Check expression from (line 14, char 9) to (line 23, char 12) (13287ms)
│           │           └─ Check expression from (line 14, char 9) to (line 17, char 21) (13262ms)
│           │              └─ Check expression from (line 14, char 9) to (line 16, char 42) (13261ms)
│           │                 └─ Check expression from (line 16, char 19) to (line 16, char 41) (4364ms)
│           └─ Check expression from (line 12, char 7) to (line 12, char 32) (28891ms)
└─ Check file /<client>/<project>/packages/<package>/src/tasks/transforms/operation.ts (712ms)
   └─ Check expression in /<client>/<project>/packages/<package>/src/tasks/extractions/operation.ts from (line 46, char 50) to (line 46, char 57) (611ms)
      └─ Check expression from (line 48, char 17) to (line 191, char 10) (502ms)
         └─ Check expression from (line 48, char 17) to (line 190, char 19) (502ms)
            └─ Check expression from (line 48, char 17) to (line 190, char 13) (500ms)
               └─ Check expression from (line 48, char 17) to (line 188, char 4) (500ms)
                  └─ Check expression from (line 168, char 10) to (line 187, char 6) (322ms)
                     └─ Check expression from (line 169, char 5) to (line 187, char 6) (322ms)
                        └─ Check expression from (line 169, char 15) to (line 186, char 59) (321ms)
                           └─ Check expression from (line 170, char 7) to (line 186, char 59) (321ms)
                              └─ Check expression from (line 170, char 7) to (line 186, char 18) (320ms)
                                 └─ Check expression from (line 170, char 7) to (line 185, char 63) (320ms)
                                    └─ Check expression from (line 170, char 7) to (line 185, char 18) (320ms)
                                       └─ Check expression from (line 170, char 7) to (line 184, char 10) (320ms)
                                          └─ Check expression from (line 170, char 7) to (line 180, char 18) (319ms)
                                             └─ Check expression from (line 170, char 7) to (line 179, char 10) (319ms)
                                                └─ Check expression from (line 170, char 7) to (line 174, char 18) (317ms)
                                                   └─ Check expression from (line 170, char 7) to (line 173, char 55) (317ms)
                                                      └─ Check expression from (line 170, char 7) to (line 173, char 18) (316ms)
                                                         └─ Check expression from (line 170, char 7) to (line 172, char 40) (316ms)

It’s not that easy to see but there is a file in this trace that took 80,609ms (80 seconds) to type-check. That’s a long time! Why did it take so long?

The next line shows that in this exceptional case, the top-level check is a deferred node Check deferred node from (line 10, char 10) to (line 29, char 4) (80608ms) which gives us some line and column numbers to check out. In this context deferred just means that the compiler does not have enough information yet to resolve the type and it must continue the compilation in order to gather more information (often other inferred types) so that it can fully resolve this deferred node.

Here’s what I discovered when I opened that file and looked at line 10, char 10 (the details here have been obfuscated):

import type { Db } from '@lib/kysely/db';
import type { ExpressionBuilder, ExpressionWrapper } from 'kysely';

export const existsValidThing = <
  const T extends keyof Db,
  EB extends ExpressionBuilder<Db, keyof Db>,
>(
  thingIdRef: ExpressionWrapper<Db, T, string | null>,
) => {
  return ({ eb, or, exists }: EB) => {
    return or([
      eb(thingIdRef, 'is', null),
      exists(
        eb
          .selectFrom('thing as t')
          .select(eb.lit(1).as('exists'))
          .innerJoin('category', 'category', 't.category_id')
          .where('t.id', '=', thingIdRef),
      ),
    ]);
  };
};

It’s a bit awkward, right? Line 10, char 10 is the beginning of the anonymous lambda function that is returned from this existsValidThing helper function. So why is the type of this helper function so difficult for TypeScript to resolve?

There are a few reasons but ultimately it comes down to:

1. Db is a large interface filled with a mapping of ~30 database tables and their many fields (dozens per table)
2. kysely is built in such a way that heavily relies on type inference and distributing across large unions (i.e. the tables in a database, or the fields in a table, one GitHub commenter casually floated the idea that the complexity was on the order of O(n^x) in some edge cases)

Even though there was an explicit type declared for the argument to the lambda (EB, coming from the generic), TypeScript still has to infer the return type of this lambda which is itself a complex series of nested function calls each requiring inference to determine their return types.

The things kysely lets you do with strong typing are fairly magical. However, trying to split those things off into re-usable helpers can produce unexpected type-checking bottlenecks with sufficiently large databases.

The Fix(es) #

There were a bunch of things we tweaked to improve performance but the largest gains came from just deleting these problematic kysely helper functions and inlining their queries where they were being used.

Other things we did that helped:

1. fixed circular dependencies (see madge)
2. removed unused types
   1. prisma-zod-generator generated types
   2. uninstalled unused dependencies
   3. deduplicated packages
3. clean up and removed barrel files
4. upgraded packages to newer versions
5. upgraded node and ensured everything was on the same version
6. added syncpack and set up monorepo linting rules

Results #

Performance matters. Many factors impact the developer experience. Even when a team’s values and culture place adequate importance on maintaining and improving performance, still other elements may conspire to threaten daily productivity.

The tale for this specific project is one of triumph. By the numbers it was a bloodbath.

Metric	Before	After	Change	% Change
Files	14,628	10,445	-4,183	-28.6%
Lines of Library	85,573	87,322	+1,749	+2.0%
Lines of Definitions	1,563,401	1,458,375	-105,026	-6.7%
Lines of TypeScript	205,561	89,162	-116,399	-56.6%
Lines of JavaScript	0	0	0	0.0%
Lines of JSON	197,264	197,258	-6	-0.0%
Lines of Other	0	0	0	0.0%
Identifiers	2,591,445	1,983,548	-607,897	-23.5%
Symbols	12,162,183	6,238,779	-5,923,404	-48.7%
Types	4,605,085	2,303,043	-2,302,042	-50.0%
Instantiations	41,244,435	25,282,289	-15,962,146	-38.7%
Memory used	7,065,937K	3,522,442K	-3,543,495K	-50.2%
Assignability cache size	7,530,942	989,151	-6,541,791	-86.9%
Identity cache size	36,263	41,336	+5,073	+14.0%
Subtype cache size	58,647	20,457	-38,190	-65.1%
Strict subtype cache size	111,640	147,930	+36,290	+32.5%
Tracing time	2.72s	0.46s	-2.26s	-83.1%
I/O Read time	1.30s	0.93s	-0.37s	-28.5%
Parse time	2.69s	1.56s	-1.13s	-42.0%
ResolveModule time	1.00s	0.66s	-0.34s	-34.0%
ResolveTypeReference time	0.03s	0.02s	-0.01s	-33.3%
ResolveLibrary time	0.02s	0.02s	0.00s	0.0%
Program time	6.59s	4.11s	-2.48s	-37.6%
Bind time	1.88s	0.97s	-0.91s	-48.4%
Check time	226.19s	38.23s	-187.96s	-83.1%
transformTime time	1.10s	0.24s	-0.86s	-78.2%
commentTime time	0.15s	0.02s	-0.13s	-86.7%
I/O Write time	0.40s	0.06s	-0.34s	-85.0%
printTime time	2.60s	0.51s	-2.09s	-80.4%
Emit time	2.61s	0.51s	-2.10s	-80.5%
Dump types time	132.73s	33.63s	-99.10s	-74.7%
Config file parsing time	0.08s	0.04s	-0.04s	-50.0%
Up-to-date check time	0.00s	0.00s	0.00s	0.0%
Build time	374.32s	78.55s	-295.77s	-79.0%

Most Significant Reductions: #

• I/O Write time: -85.0% (0.40s → 0.06s)
• Tracing time: -83.1% (2.72s → 0.46s)
• Check time: -83.1% (226.19s → 38.23s)
• Emit time: -80.5% (2.61s → 0.51s)
• Print time: -80.4% (2.60s → 0.51s)
• Build time: -79.0% (374.32s → 78.55s)

Resource Usage: #

• Memory usage: -50.2% (7.1GB → 3.5GB)
• Files processed: -28.6% (14,628 → 10,445)
• TypeScript lines: -56.6% (205K → 89K)

Overall Impact: #

The optimization reduced the total build time from 6.2 minutes to 1.3 minutes, representing a 79% improvement in compilation speed.

That’s nice and all but we’re rarely running a fresh, full compilation with no cache. The real impact is a responsive language server and instant intellisense.

If you know your tools, have a bit of time and patience, and are motivated to make things better there’s a lot you can do even when faced with what feels like an impossible task.

This might be shocking coming from a developer, but I like to write code. I usually spend a good chunk of my weekend tooling around with my home server set up or building side projects that will never see the light of day. My time is limited though, so if I really want a little app for my own personal use, I'll let Cursor or Claude Code (or whatever else new and shiny that week) write the code for me. This works really well... until I come back the next weekend and realize I have no idea where to start changing code to introduce new features. All of that code has now become legacy code.

What is legacy code and why do we care? Can't we just let the AI continue to work on the code?

Legacy code is code that you cannot comfortably change because either you don't understand why it was written the way it was or it's such a mess that it easier to code around it than to fix it.

On a little solo project, this is probably not a big deal — just keep letting the AI build more and more legacy code. Sure, you might never understand it, but you can always just put a TODO in the repo saying you'll rewrite it in Rust anyways.

When you start working with a team, that code that you're generating costs someone else time and maybe a little sanity. Your colleague who was told to change something in that vibe coded feature has to spend a potentially non-trivial amount of time trying to figure where they could even start to change something, and then they have to hope that they don't break something with their change.

Legacy code tends to "breed," generating more legacy code. There is nothing more permanent than a temporary fix. It's easy to layer on more and more workarounds, and each of those workarounds adds more tech debt and frustrates your colleagues. At some point, you'll hit a critical mass where the only reasonable way to add a new feature is a full rewrite, costing you time that could have been spent on new features, the chance for regressions, and good will from your client.

You might be thinking that this is just an issue if you don't write tests, but this isn't just about test coverage. It's about unclear abstractions, inconsistent patterns, and logic that made sense to the AI but not to humans. Tests tell you if something breaks, but they don't tell you where to make your change or why the code does what it does.

Let's take a look at how to go from "vibe coding" to engineering with AI-powered tools.

Own It #

One of my favorite ways to use AI tools — and the reason I haven't called any of this "agentic" yet — is to just ask it questions and write the code myself. For simple or repetitive things, I'll let the agent handle the coding, but we learn best by doing. Just the act of typing the code is going to help it stick in your head and is going to give you the chance to adjust the output to be more human-friendly. This isn't necessarily very efficient if only because I'm a slow and error-prone typist, but it does seem to help me learn about how to use a new package or pattern.

If that's not appealing to you, own something. Something that you write. Test driven development is a great pattern for this. Write the tests yourself and don't let the AI change them except small details like parameter names. You might be a level abstracted from the code, but you'll still have a good grasp on how it should work. Another good option is to manually write integration points. This could be defining the database or endpoint schemas, or, if you're using something like TypeScript, define the inputs and outputs of the function.

Regardless of how you choose to approach this, the point is for you to really think about the problem you're solving and get your hands a little dirty. Just a little bit of manual work will help the ideas stick around and give you better insight into what is good code and what is not.

Review Your Own PRs #

Whenever you finish a feature and put up your PR, the first person to review that code should be you. If you wrote all the code yourself, you might have some writer's blindness, but hopefully you can catch silly things so your teammates can focus on the meaningful code. If the code is generated, you should scrutinize it. Your name is on these commits. If something isn't right with the implementation or if someone has a question about the feature, they're going to come to you first. Make sure the code is code that you understand and that you are comfortable having your name on it. Saying "oh, I use Codex for this" isn't going to cut it when there's a bug in production.

Write Commits for Your Future Self #

Your commits are not just to make your contributions chart on Github look good. They are the roadmap that tells you how you got from point A to point B all the way to point 1c17df6. Some of the best tools you have for understanding a code base are things like git diff and git blame. Looking at the code as it currently is doesn't give you enough information to understand the "why" of the code. However, looking at change over time (especially with good commit messages), you can usually piece together the "why."

Whether or not you're using an AI tool, a good rule of thumb is "one logical change per commit." If you're using an AI tool, you might adapt this to "one (complete) prompt per commit". If you tell the AI to add a new function, once it's done and the functionality is right (which could take multiple prompts), write your commit. It's better to have too many commits than not enough (something I don't follow enough). You can always come back through and adjust or edit commits as you need.

Centralize Your Tooling #

Everyone on our team uses different tools — Windsurf, Cursor, Codex, Claude Code, and probably more. Each of those manages some form of rules differently. However, most tools do understand AGENTS.md. You can think of AGENTS.md as being the README.md for your AI tooling. It's not as powerful as tooling-specific rules, but it is a good place to drop repo-wide context. This can be things like basic scripts and commands, style guides for code and commits, and general context about the project. If you're a monorepo, you can even nest them so that each package has their own special context.

Getting everyone on the same tool is also great, but we're in period of exploration and invention right now. There's a lot of value in trying a bit of everything and using AGENTS.md still gives you a reasonable starting place for context and rules.

Wrap Up #

The genie is out of the bottle. Agentic coding and AI tooling are here to stay. These tools open all sorts of doors for us. Designers prototype their ideas without having to learn all of React, developers focus on the really tricky architectural problems, and everyone can get their weekend projects done (so that they can start another one).

Owning your code, reviewing your own PRs, committing frequently, and sharing knowledge with your team: none of this is exactly groundbreaking. That's because these principles are just best practices. Turns out that the practices our industry has been developing for decades just kind of work. We just need to update a few flows for the modern day.

None of us can really predict what software development is going to look like in five years or a decade, but I know I'm still going to be writing code. As these tools evolve, I'm not going to shy away from them. As long as we keep building on these principles, no matter what these tools become, we'll still be able to understand the code and get our hands dirty when we need to.

Another year, another favorite books roundup! These aren’t necessarily books published in 2025 — just books that we read and enjoyed this year. Without further ado, our 2025 favorites:

This was the year that I finally embraced AI. I was previously hesitant to use it for fear of what it would do to me as a writer, thinker, and doer. However, what I’ve realized is that it makes me stronger in those places. At first, I admit I was using Chatty McChatsBot more like a faster search engine or, occasionally, a sentence-polishing tool.

But over the past several months, that relationship changed.

What I learned wasn’t just how to write faster or generate ideas more quickly. I learned how an AI tool could support strategic thinking. In order to get the good stuff out of AI, you have to put good stuff in. You have to ask it specific questions, give it details, and follow up in the same fashion I did when I was a working journalist. The first answer rarely is the one that makes it on the air or in a presentation.

From only answers to thinking partner

Early on, my prompts were transactional: “Can you rephrase this?”, “Can you summarize that?”, “Can you define this term?”

Over time, I started using ChatGPT less as an answer machine and more as a thinking partner. I brought half-formed ideas, competing constraints, and messy drafts into the conversation. Instead of asking for “the right answer,” I asked for alternatives, implications, and framing.

The biggest shift was realizing that the quality of the output mirrored the clarity of the input. Better questions led to better thinking. This was true of Chatty and of me.

Strategy benefits from externalized thinking

Most strategic work happens invisibly. It’s in your head, between meetings, or in the margins of documents. ChatGPT gave me a place to externalize that thinking quickly.

I used it to:

• Pressure-test assumptions before sharing them
• Explore how a decision might land with different stakeholders
• Translate complex ideas into clearer language
• Sanity-check scope, tradeoffs, and tone

This didn’t replace judgment. It sharpened it. Seeing my own reasoning reflected back—sometimes challenged, sometimes clarified—made gaps more obvious and decisions more intentional.

Confidence came from iteration, not automation

One unexpected outcome this year was increased confidence. This wasn’t because ChatGPT told me what to do, but because it helped me iterate faster.

I could try multiple phrasings, explore different levels of directness, and sense-check decisions before putting them in front of clients or colleagues. That repetition made patterns visible: what I consistently believed, where I tended to hedge, and when I already knew the answer but needed to hear it reflected back.

Over time, I relied less on the tool for validation and more for refinement.

The human work stayed human

Despite the efficiency gains, the most important parts of my role didn’t change. Relationship-building, judgment calls, empathy, and accountability all remained firmly human responsibilities.

ChatGPT helped me prepare better, think more clearly, and communicate more effectively—but it didn’t make decisions for me. It didn’t replace experience. It didn’t remove responsibility.

If anything, it raised the bar for how intentional I needed to be.

My focus for 2026

Looking ahead to next year, I’ll spend less time asking for polish and more time inviting friction. This year, the moments where ChatGPT pushed back, reframed a question, or exposed a blind spot were far more valuable than the moments where it simply made something sound better.

The tool was most useful when I treated it like a collaborator who could challenge me, not a service that existed to agree.

But most of all

Using ChatGPT helped me learn more about myself – how I think, how I decide, and it helped to validate my knowledge.

The biggest lesson this year wasn’t that AI can do my job faster. It’s that, when used thoughtfully, it can make my thinking better.

And that’s a shift that deserves attention.

Screen readers are essential tools for people who are visually impaired. They help users interact with computers and mobile devices. Automated accessibility testing can find some issues, but only real testing with a screen reader reveals all the errors.

Screen reader testing ensures a site meets accessibility standards like WCAG and ADA. True accessibility comes from designing every detail of a digital experience with inclusivity in mind. It invites people of all abilities to engage with content smoothly. 

Testing with a screen reader is more than finding mistakes. It’s about understanding users as individuals. We need empathy to see their experience on a site. By doing this, we connect design and development, always keeping the user at the center.

Types of screen readers

There are three screen readers, VoiceOver, NVDA, and JAWS. JAWS runs on Windows and is paid software. NVDA is free and only runs on Windows, and VoiceOver comes with MacOS.

JAWS is the most advanced screen reader and has many features that the other two don’t have. For instance, JAWS can add in words and text to help with semantics on elements. But if you know what to look for and how to test a site, using VoiceOver or NVDA will be sufficient to find accessibility errors on a site.

.pipe(..) is much stricter #

If you make liberal use of .pipe() as a way to compose schemas then, like us, you might find yourself staring at an issue like:

The types of _zod.input are incompatible between these types: <T1, T2>

If you have code like:

const schema = z.object({
	q: z.string(),
	sort: z
		.string()
		.transform((value) => value.split(':'))
		.pipe(someOtherSchemaExpectingValidSortParam)
});

A few different folks have started up discussions around the change. As Colin points out, “Zod schemas aren't contravariant in their input type” which is an intentional choice but it does create some edge cases like this.

The change to make .pipe() stricter in v4 is “intentional to fix unsoundness in v3”. It should help us more easily discover if we’re creating pipelines that may not behave as expected but it also comes with the need for workarounds while we migrate our projects to v4.

⚠️ What does “Zod schemas aren't contravariant in their input type” mean?
That’s an entire other separate blog post, I’m afraid. If you’d like to explore further I’d start with the wikipedia article on Contravariance, brush up on your Liskov Substitution Principle, and then look back at the classic Animal > Dog example which should make a bit more sense.

Workaround 1: Return unknown from .transform(..) #

You can do this either by annotating the transform function’s return type or type casting the value and letting inference handle it.

const schema = z.object({
	q: z.string(),
	sort: z
		.string()
		.transform((value): unknown => value.split(':'))
		// Or ━┑
		// .transform((value) => value.split(':') as unknown)
		.pipe(someOtherSchemaExpectingValidSortParam)
});

Workaround 2: Use z.any() explicitly #

This essentially opts out of any kind of type checking at that particular interface which can be a good short-term solution if you need it but should be avoided if possible.

const schema = z.object({
	q: z.string(),
	sort: z
		.string()
		.transform((value) => value.split(':'))
		.pipe(z.any().pipe(someOtherSchemaExpectingValidSortParam))
});

.superRefine() is now .check() #

Allegedly check is just superRefine but with a “cleaner API”. No more return z.NEVER and z.ZodIssueCode.custom. Instead of ctx.addIssue() you just have to ctx.issues.push(..). Just kidding about z.NEVER by the way… apparently it’s still used in pipes and transforms to “exit the transform without impacting the inferred return type”.

This is an interesting choice. We can only speculate about the trade-offs that might have been considered when making this change. There are benefits to building APIs like .refine() by composing lower level and more versatile APIs (like .check()) for things like code simplicity, testability, and overall cohesiveness.

In terms of the user API, deciding to favor direct data manipulation (ctx.issues.push(..)) over function calls (ctx.addIssue(..)) seems like a step back in terms of level of abstraction. To use the API you need to know that “adding an issue” requires pushing a new issue value onto a list called ctx.issues. Those details leaking out may be a benefit if the goal is to add friction and discourage users from reaching for these specific escape hatches.

In practice, we only ever use .superRefine in a few spots and the migration was painless, so let’s all just agree to calm down and see how this one plays out, ok?

Working with ZodErrors is a bit different #

Instead of error.flatten() we now have z.flattenError(error). Instead of error.format() we now have z.treeifyError(error).

If you want a nice single string that captures all the problems on a schema you can now use z.prettifyError(error) and it will pretty-print a summary of all the (possibly nested) issues like this:

✖ Unrecognized key: "extraKey"
✖ Invalid input: expected string, received number
  → at username
✖ Invalid input: expected number, received string
  → at favoriteNumbers[1]

Migrating away from .merge()? Do this: #

The deprecation message on .merge() suggets replacing it with a.extend(b.shape). However, the zod 4 documentation for .extend() goes on to say that there is another form which has better tsc performance (using destructuring):

const foo = z.object({
	foo: z.string(),
});

const bar = z.object({
	bar: z.string(),
});

// zod 3
const fooBar = foo.merge(bar);

// zod 4 (based on deprecation message suggestion)
const fooBar = foo.extend(bar.shape);

// -- just do this instead: -v

// ✅ zod 4 (best performing, according to docs)
const fooBar = z.object({
	...foo.shape,
	...bar.shape,
});

z.string() refinement helpers promoted #

A bunch of helpers that were previously on ZodString (like z.string().email()) were promoted to top-level schema types (z.email()).

With that come a few adjustments to the level of strictness for these checks. z.uuid() will now validate more strictly against RFC 9562/4122 (specifically, the variant bits must be 10 per the spec). For something a little more “UUID-ish” you can use z.guid().

z.coerce input is now unknown #

z.coerce was changed so that the inferred input type is now unknown. This makes a lot of sense and in at least one case meant that we could remove a workaround that was put in place just so that we could get a correctly inferred input type that was accurate in how permissible it was.

Case Study: tsc metrics comparison #

After having gone through this migration on a fairly large project (~100k LoC) that makes significant use of zod schemas, here are the numbers:

Metric (agg)	Before	After	Change
Identifiers	3,534,744	3,373,893	-160,851 (-4.55%)
Symbols	4,486,388	4,364,030	-122,358 (-2.73%)
Types	1,193,186	1,028,579	-164,607 (-13.80%)
Instantiations	16,421,354	14,147,656	-2,273,698 (-13.85%)
Memory used	2,747,064K	2,630,832K	-116,232K (-4.23%)
Build time*	40.07s	37.50s	-2.57s (-6.41%)

Well we didn’t quite hit the 100x reduction in type instantiations claimed in the zod 4 introduction but a ~14% improvement is still significant.

For this project, the inciting incident that precipitated the need to urgently prioritize these updates was a problem with a few particularly deeply nested discriminated unions. We were hitting TS2589 errors (“Type instantiation is excessively deep and possibly infinite”) when trying to use the inferred zod schema types as generic parameters to react-hook-form’s useWatch (and useForm, although you can omit it and rely on inference if you like).

This isn’t the first time we’ve invested in improving the TypeScript performance on this project and I’m sure it won’t be the last. Every effort leaves a trail of lessons, frustrations, and small joys. Come back once in a while, and I’ll tell you another story.

For nearly all of my career, the web has been both my employer AND my teacher. Looking back, there are a handful of articles that weren’t just bookmarks or blog posts — they marked turning points. Little pushes from fellow web workers that helped move me to where I am today.

Join me for a quick romp through ye olde history as I revisit five articles that helped shape my career.

1. A ‘flexible foundation’ #

Responsive Web Design

I started my career in graphic design, and one of the biggest mental shifts in transitioning from print to web design was working with a ‘squishy’ canvas — you could never truly guarantee what size screen a user would view your design. Not like you could with paper.

Ethan Marcotte’s article on responsive design back in 2010 finally made it click how we could approach this new world of tiny screens. It reshaped how I thought about web design. I feverishly rewrote my portfolio using media queries — something that I was told later helped me land a job at an agency as a hybrid designer/developer. So in a way, this article helped me get my first web job! 😎

2. The problem with specificity and portability #

Object Oriented CSS

In the early days of CSS preprocessors, it was very common to see wild, zany selectors in a project’s CSS. Ultra-qualified selectors for avoiding unintentional side-effects, a mish-mash of IDs, classes, and element tags, or even unintentionally deeply nested selectors in a SCSS stylesheet. (Or maybe that was just my CSS 😅)

Several approaches came out during this time, like SMACSS, and later BEF, but the first one I really understood was OOCSS. It seems common sense now to ‘separate structure and skin’ and create styles that work the same everywhere, but it’s thanks to the work of Nicole Sullivan and others that these concepts are so deeply ingrained in our current approaches.

It was also OOCSS and its single-class approach that helped me understand the problem with CSS specificity and how to mitigate it. I started following OOCSS principles and watched my CSS become more durable, resilient, and portable. And waaaaaay fewer !important tags!

3. Vim once, Vim forever #

Vimcasts

Around this time, I also read a clickbait-y and unfortunately-named article (that I can no longer find) called “Real Developers Code with Vim”. I, of course, being a 100% authentically real developer, took the bait. I do not agree with the original premise, but that article started my journey into learning Vim.

If that article piqued my interest, it was Drew Neil and his Vimcast series that took me by the hand and let me through a world of custom config files, modal editing, and community plugins. Vim wound up being a gateway into the command line, and I started to understand how UNIX systems worked. Things like how to customize my bash prompt and set up custom aliases naturally flowed from what I learned in Vim and turned the command line from something weird and scary into something that felt like home.

I'm still using Vim today (Neovim specifically), and I can trace back my .vimrc all the way back to 2012. 13 years later, and I STILL feel like a wizard in the terminal. 🧙‍♂️

4. A new layout paradigm #

A Guide to Flexbox

Before flexbox landed in the early-to-mid 2010’s we were using CSS floats. Never heard of them? Good, let them rest quietly in the past. 🪦

Chris Coyier and his flexbox guide on CSS Tricks solidified my mental model of how flexbox worked and helped me start creating modern layouts. Things that were previously impossible, like re-ordering elements without altering their source order or even making items in a row the same height, were not just possible, but EASY.

5. Vanilla with sprinkles #

How does Viget JavaScript and Stimulus Controllers and Viget Modules

(This one is cheating a little, but the two articles go together.)

In 2022, I was hired at Viget, which marked the first time I was 100% a developer—my entire career had been in a hybrid role with a mix of designer/developer/director/manager.

This set of articles helped onboard me into a new way of thinking and writing JavaScript, and also marked my entrance into a new era of capability. Classes, modules, promises, async, destructuring, and so much more — the promise (ha, get it?) of ES6 all those years ago was not only fully realized but accelerating!

Honorable Mentions #

Before publishing this article, we talked about this topic as a team (UI Development) and there were a few articles we felt we’d be remiss to leave out:

The Front-End Split #

Brad Frost’s Front-of-the-front-end and Back-of-the-front-end, along with Chris Coyier’s The Great Divide helped us make sense of the diverging skill sets in front-end development. What we choose to call ourselves is important, and is part of why we reorganized the front-end development team here at Viget in 2022.

Componentized Design #

Brad Frost (again) with his Atomic Design helped us start thinking about componentized design and development. This had natural knock-on effects with future tools and techniques like design systems and component-driven development.

A Call to Share #

Looking back, I can see my career not as a straight path but as a breadcrumb trail left by generous strangers on the internet. Those articles weren’t just information — they were people, somewhere, deciding to hit “publish” instead of “maybe later.”

The web is funny that way. It’s not a library we visit; it’s a living garden we tend together. Every tutorial, every blog post, every half-baked gist is a seed. Some quickly grow and spread, others grow quietly in corners, but ALL of them matter more than the author probably realizes at the time.

If the web has fed you (and if you’re reading this, it almost certainly has), think about what you can share back. Share your messy notes, your weird bug fixes, your “I finally figured this out!” revelations. Someone, somewhere, is about to trip over the same obstacle you just climbed, and your breadcrumb might be the one that leads them out.

When Perfection Becomes the Problem