# ma-x.im — Maksym Kuzmitskyi

> Maksym Kuzmitskyi’s work and writing on software development: complex interfaces, frontend architecture, testing and service integration. Based in Kraków.

## Profile and pages
- [Maksym Kuzmitskyi — Senior Software Developer](https://ma-x.im): Maksym Kuzmitskyi’s work and writing on software development: complex interfaces, frontend architecture, testing and service integration. Based in Kraków.
- [About Maksym Kuzmitskyi](https://ma-x.im/about): The experience and engineering approach of Maksym Kuzmitskyi: software development, frontend architecture, testing, accessibility and connected systems.
- [Selected experience](https://ma-x.im/case-studies): Four selected projects across frontend architecture, shared React components, enterprise applications and customer-facing quoting and checkout.
- [Writing](https://ma-x.im/blog): Notes on frontend development, software design and the practical details of building applications.
- [Get in touch](https://ma-x.im/contact): Get in touch with Maksym Kuzmitskyi about software, frontend architecture, a project or an engineering role.
- [Frontend Architecture Review](https://ma-x.im/frontend-architecture-review): A focused architecture review for React and TypeScript products that are hard to change. Contact me to discuss the codebase, review scope, deliverables and pricing.

## Selected experience
- [Procter & Gamble · via Luxoft / DXC — Promotion planning with spreadsheet and timeline interfaces](https://ma-x.im/case-studies/pg-promotion-planning): I authored the frontend low-level design and helped deliver an internal promotion-planning application with linked spreadsheet editing, business-rule validation and a draggable campaign timeline.
- [Honda Canada · via Assembly Canada — Shared React components for multiple brands](https://ma-x.im/case-studies/honda-multi-brand-components): I reworked shared React components for brand-specific layouts, improved local state isolation and worked extensively with Cypress and Cucumber in a test-first workflow.
- [Motorola Solutions — Enterprise applications, reusable UI and frontend delivery](https://ma-x.im/case-studies/motorola-enterprise-ui): I developed React and Node.js functionality with PostgreSQL-backed middleware, contributed to shared UI and accessibility, and later led frontend delivery for the corporate web platform.
- [Liberty Mutual Insurance — Direct Sales quoting and checkout](https://ma-x.im/case-studies/liberty-mutual-direct-sales): I build React and TypeScript quoting and checkout flows connected to federated GraphQL services, with a focus on maintainable UI, service contracts and reliable delivery.

## The React Playbook
A 56-part series on building serious React applications with the TanStack stack — from project setup through architecture at scale and component patterns. Best read in order.
- [The React Playbook index](https://ma-x.im/playbook): The full path, grouped into phases.
- [01 · Starting a New React Project in 2026-2027: The Stack I Keep Coming Back To](https://ma-x.im/blog/react-playbook-starting-new-project): Every new React project starts with the same question: which tools? After years of watching teams assemble mismatched libraries that fight each other, I stopped choosing independently. This is the coherent stack I now use by default — and why.
- [02 · TypeScript in React: Patterns That Actually Matter](https://ma-x.im/blog/react-playbook-typescript-patterns): Not a TypeScript tutorial. A focused look at the patterns that eliminate real production bugs in React + TanStack apps — typed API layers, discriminated unions for async state, route param inference, and generic components done right.
- [03 · Code Structure in React: The FSD Version I Actually Use](https://ma-x.im/blog/react-playbook-code-structure): Flat folders are fine until every feature starts touching routes, queries, forms, permissions, and UI state. Here's the React structure I use when a TanStack app grows past the simple stage without turning FSD into folder theater.
- [04 · Error Handling in React: What Users Should See When Things Break](https://ma-x.im/blog/react-playbook-error-handling): Error handling is not a catch block sprinkled at the end. In a React + TanStack app, it is a product decision: what fails locally, what fails at the route level, what can retry, and what the user needs to do next.
- [05 · React Data Fetching with TanStack Query: The Patterns That Keep Apps Calm](https://ma-x.im/blog/react-playbook-data-fetching): TanStack Query is not just a better useEffect. It is the server-state layer of your React app. The hard part is not fetching data — it is designing keys, freshness, invalidation, pagination, and prefetching so the UI stays predictable.
- [06 · Routing with TanStack Router: Treat the URL Like Application State](https://ma-x.im/blog/react-playbook-tanstack-router): Routing is not just rendering a page for a path. In serious React apps, the URL carries product state: filters, tabs, pagination, selected records, redirects, and preload decisions. TanStack Router makes that state typed instead of hopeful.
- [07 · React State Management with Reatom: When useState Stops Being Enough](https://ma-x.im/blog/react-playbook-reatom-state-management): Most React state doesn't need a library. Then one workflow grows into drafts, derived values, undo, optimistic steps, and cross-component coordination. This is where I reach for Reatom instead of turning TanStack Query into a client-state store.
- [08 · Immutable Data in React: The Rule I Stopped Arguing About](https://ma-x.im/blog/react-playbook-immutable-data-structures): A module I was told not to over-engineer grew into an entire application. Most of what let it survive was boring — and one of the most boring rules was never mutating state in place. Here's how immutability actually works in React, when I reach for Immer, and why I skip Immutable.js.
- [09 · Styling React in 2026: How I Actually Choose](https://ma-x.im/blog/react-playbook-css-styling): Styling is the most argued-about, least reasoned-about decision in a React app. The real question isn't which library looks nicest in a demo — it's which one survives a growing codebase. Here's how I weigh Tailwind, CSS Modules, CSS-in-JS, and zero-runtime options, and where each one earns its place.
- [10 · React UI Libraries: Who Owns the Styling Decides Everything](https://ma-x.im/blog/react-playbook-ui-libraries): Picking a component library feels like picking buttons and modals. It isn't. You're deciding who controls your styling — you or the library — and that single choice shapes how much you'll fight it for years. Here's how I weigh MUI, Ant Design, Radix, and shadcn/ui.
- [11 · Forms in React: Where TanStack Form Earns Its Place](https://ma-x.im/blog/react-playbook-form-libraries): Forms are where clean React apps quietly fall apart. Conditional fields, async validation, a submit button that has to know about everything — it adds up fast. Here's why I reach for TanStack Form, where it beats Formik and React Hook Form, and where a form library still can't save you.
- [12 · Charts in React: Who Renders the Pixels](https://ma-x.im/blog/react-playbook-chart-libraries): "Just use a chart library" hides a real decision. Do you want charts handed to you, or do you want to control every pixel? That choice — and your data size — decides between Recharts, visx, and raw D3. Here's how I pick, and where charts actually get hard.
- [13 · Authentication in React: Buy It, and Where the Line Really Is](https://ma-x.im/blog/react-playbook-authentication): Auth looks like a login form and turns out to be an architecture decision. Where do tokens live, who guards a route, what happens when the session dies mid-request? Here's why I buy auth instead of building it, and the parts that stay yours no matter what you buy.
- [14 · The Backend a React Developer Actually Needs to Understand](https://ma-x.im/blog/react-playbook-backend): You don't have to write the server. But the shape of the contract between your React app and the backend — REST, tRPC, or a BFF — decides how much of your frontend is real work versus glue code. Here's the part of the backend that's actually yours.
- [15 · SSR in React: What TanStack Start Actually Changes](https://ma-x.im/blog/react-playbook-ssr-tanstack-start): Server rendering isn't a performance checkbox — it collapses the wall between frontend and backend into one framework. Here's what SSR really buys you, why the client/server line stops being where you think it is, and where TanStack Start fits next to Next.js.
- [16 · Databases for React Developers: What Serverless Actually Changed](https://ma-x.im/blog/react-playbook-database-turso): "Add a database" used to mean provisioning a server, managing connections, and running migrations by hand. Serverless quietly rewrote that whole sentence. Here's what a React developer actually needs to know about picking and using a database in 2026.
- [17 · Hosting a React App in 2026: From DevOps Project to Git Push](https://ma-x.im/blog/react-playbook-hosting-railway): Deployment used to be a separate discipline — servers, pipelines, a person whose whole job was getting code to production. Modern platforms compressed it into a git push. Here's how to think about hosting a React app, what the tiers actually mean, and where the magic stops.
- [18 · Testing React Without Drowning: What Each Test Actually Buys You](https://ma-x.im/blog/react-playbook-testing): Most testing advice is either "100% coverage" zealotry or "tests slow you down" cynicism. Both miss the point. A test is a trade — effort now for confidence later — and the skill is knowing which trades pay off. Here's how I test React without a brittle suite that everyone hates.
- [19 · AI in a React App: Past the Demo, Into the Product](https://ma-x.im/blog/react-playbook-ai): The demos are intoxicating — a chat box, a streaming response, thirty lines of code and it feels like magic. Then you try to ship it and the hard parts show up all at once: streaming UI, structured output you can trust, state that doesn't fight you. Here's what building AI into a real React app actually takes.
- [20 · Real-Time React: When the Server Has Something to Say](https://ma-x.im/blog/react-playbook-websockets): Every data pattern so far has the client asking and the server answering. Real-time inverts that — the server speaks first, and your UI has to be listening. The mistake is treating that live connection as a second, parallel source of truth. Here's how I keep a React app live without ending up with two states that disagree.
- [21 · Internationalization Isn't Translation: What Actually Breaks](https://ma-x.im/blog/react-playbook-i18n): Everyone thinks i18n means swapping English strings for a dictionary lookup. That's the 10% that's easy. The 90% is formatting, pluralization, text that changes direction, and language data you can't afford to ship all at once. Here's what internationalizing a React app actually involves once you get past the word 'translation'.
- [22 · Payments in React: The Client Never Decides You Got Paid](https://ma-x.im/blog/react-playbook-payments): Taking a payment looks like a form submission and is nothing like one. The card number is radioactive, the confirmation is asynchronous, and the one thing your React app must never do is believe it got paid because a callback said so. Here's where the real line sits between the browser, your server, and Stripe.
- [23 · Time in React: The Bugs That Only Show Up at 2 AM](https://ma-x.im/blog/react-playbook-time): Dates look like the most boring data type in your app. They are also the source of the subtlest, most embarrassing bugs — the meeting that shows an hour off, the 'today' that's tomorrow in Tokyo, the date that shifts a day every time you save it. Here's how I stop time from quietly breaking a React app.
- [24 · File Upload in React: The Input Is Easy, the File Is Not](https://ma-x.im/blog/react-playbook-file-upload): An upload looks like a one-liner — a file input, a POST, done. Then someone uploads a two-gigabyte video on hotel wifi and the whole illusion collapses. The hard part was never the input. It's moving a large, unreliable blob of bytes from a browser to somewhere it can live. Here's how I actually handle it.
- [25 · Sending Email from a React App: A Backend Problem in Disguise](https://ma-x.im/blog/react-playbook-mails): "Just send them an email" is one of those sentences that sounds like a five-minute task and turns into a week. The React part is trivial. The hard part is that email is a deceptively deep backend system with deliverability, templates, and reputation — and none of it belongs in your frontend. Here's where the real work actually is.
- [26 · Design Prototyping for React: Where the Architecture Actually Starts](https://ma-x.im/blog/react-playbook-design-prototyping): Most engineers treat the Figma file as a picture to reproduce. That framing is why so many handoffs go badly. A good design isn't a picture — it's the first draft of your component architecture, and the decisions that decide whether your codebase stays sane are made before a single line of React is written.
- [27 · Documenting Components: The Only Docs That Don't Rot](https://ma-x.im/blog/react-playbook-component-documentation): Every team writes component docs the same way — a wiki page, a screenshot, a table of props — and every team watches them go stale within a month. The problem isn't discipline. It's that the docs live in a different place than the code. The fix is docs that can't drift because they're generated from the component itself.
- [28 · React on the Desktop: When a Window Beats a Tab](https://ma-x.im/blog/react-playbook-desktop): The pitch is irresistible — ship your React app as a real desktop program, same code, native icon in the dock. Electron and Tauri both promise it. But the interesting question isn't 'can I,' it's 'what do I actually gain that a browser tab can't give me,' and the answer decides which tool, and whether you should bother at all.
- [29 · React Native: What 'Learn Once, Write Anywhere' Really Means](https://ma-x.im/blog/react-playbook-react-native): React Native's promise gets misremembered as 'write once, run everywhere' — and that misremembering is why so many web developers hit a wall. The knowledge transfers; the code and the instincts often don't. Here's the honest line between what your React experience buys you on mobile and what it quietly doesn't.
- [30 · React in 3D: When <div> Becomes <mesh>](https://ma-x.im/blog/react-playbook-vr-ar): The idea that React could render a 3D scene sounds like a stretch — React is for interfaces, 3D is a different universe. Except it isn't a stretch at all, and understanding why closes out this whole series with its central idea: React was never really about the DOM. This is where that finally becomes obvious.
- [31 · The shared/ Folder Is Not a Place, It's a Promise](https://ma-x.im/blog/react-playbook-shared-code): Every codebase grows a shared/ folder, and given enough time every shared/ folder becomes a junk drawer. Not because the team got lazy — because the folder was never given a rule. Here's why it rots, and how to keep it boring.
- [32 · Barrel Files: The Import You Love and the Bundle You Hate](https://ma-x.im/blog/react-playbook-barrel-files): A barrel file makes imports look beautiful and can quietly drag half your app into a bundle that only needed one function. Here's what index.ts actually does, when it earns its place, and when it's a trap wearing a clean interface.
- [33 · The Direction of the Arrows: Dependencies Are Your Real Architecture](https://ma-x.im/blog/react-playbook-module-dependencies): You can draw whatever folder diagram you like. The honest picture of your app is which module imports which — the direction of the arrows. Get that wrong and no folder structure will save you.
- [34 · How Big Should a Component Be? Composition, Decomposition, and Handing Over Dependencies](https://ma-x.im/blog/react-playbook-composition-and-di): Split a component too early and you get a maze of tiny files. Split too late and you get a 600-line monster. The real question isn't size — it's who owns which dependency, and whether the component reaches for it or is handed it.
- [35 · Is Container vs Presentational Dead? What Survived the Hooks Era](https://ma-x.im/blog/react-playbook-container-presentational): The pattern that taught a generation to split 'smart' from 'dumb' components got quietly declared obsolete when hooks arrived. It wasn't. The folder convention died. The idea underneath it is more useful now than ever — including in Server Components.
- [36 · Compound Components: Designing an API, Not Just a Component](https://ma-x.im/blog/react-playbook-compound-components): The moment a component grows past a handful of props, you're not writing a component anymore — you're designing an API. Compound components are how you keep that API flexible without drowning it in configuration props.
- [37 · Headless Components: Give Away the Behavior, Keep None of the Markup](https://ma-x.im/blog/react-playbook-headless-components): The most reusable UI code I write renders nothing at all. Headless components, render props, and hooks-as-API are three names for one idea: separate what a component does from how it looks — and hand over the behavior without a single opinion about the markup.
- [38 · Changing a Component Everyone Uses: Deprecation, Codemods, and No Big-Bang Rewrites](https://ma-x.im/blog/react-playbook-changing-shared-components): Writing the new version of a shared component is the easy 10%. The other 90% is the hundred call sites that already depend on the old one — and the fear of touching them. Here's how I change a component everyone uses without a month-long rewrite that breaks the day it lands.
- [39 · Keeping a UI Kit Updated Across Apps: Versioning, Contracts, and Trust](https://ma-x.im/blog/react-playbook-ui-kit-versioning): A shared UI kit does not fail because the button component is hard to write. It fails when five applications are afraid to upgrade it. Versioning, contract tests, release channels, and migration paths are what turn a component library from a dependency into a product people can trust.
- [40 · localStorage Is Not State: Persistence, Hydration, and Tabs That Fight Each Other](https://ma-x.im/blog/react-playbook-local-storage-and-state): localStorage looks like a global variable that survives a refresh. That framing is the bug. Treat it as a persistence layer that mirrors your state — not as the state itself — and the hydration mismatches, stale tabs, and schema breakages mostly disappear.
- [41 · Server State Is a Cache: Normalization, Duplicates, and Invalidation You Can Trust](https://ma-x.im/blog/react-playbook-data-normalization): The same customer shows up in a list, a detail page, and a header badge — three copies of one truth you don't own. Edit one and the others go stale. Here's when to normalize server data into one source of truth, when the query cache is enough, and how to invalidate without nuking everything.
- [42 · Optimistic UI: Updating Before the Server Says Yes](https://ma-x.im/blog/react-playbook-optimistic-ui): Optimistic UI is a small lie: you show the result before the server confirms it. Done right, the app feels instant. Done wrong, the UI quietly tells the user something that never happened. The difference is entirely in how you roll back.
- [43 · Undo/Redo Without Losing Your Mind: The Command Pattern in React](https://ma-x.im/blog/react-playbook-undo-redo): The instinct is to snapshot your whole state on every change and step backward through the copies. It works until it doesn't. A history of reversible commands scales further, describes what actually changed, and survives contact with a server. Here's how I build undo/redo that doesn't fall apart.
- [44 · State Machines in React: When Booleans Start Lying to You](https://ma-x.im/blog/react-playbook-state-machines): isLoading, isError, isSuccess, isEditing — five booleans give you thirty-two combinations, and most of them are impossible states your code still has to survive. A state machine makes the impossible ones unrepresentable. Here's when to hand-roll one and when to reach for XState.
- [45 · The Event Bus: Great for Decoupling, Great for Making a Mess](https://ma-x.im/blog/react-playbook-event-bus): An event bus feels like the cure for prop drilling and tangled dependencies — anything can talk to anything, and nothing is wired together. That's exactly the problem. It doesn't remove the coupling, it hides it. Here's where a bus genuinely helps and where it quietly turns your app into action-at-a-distance.
- [46 · Feature Flags: Every Flag Is a Branch You Promised to Delete](https://ma-x.im/blog/react-playbook-feature-flags): Feature flags decouple deploy from release, and that's genuinely powerful. But every flag is a fork in your code, forks multiply, and the ones nobody deletes quietly become the most dangerous debt in the codebase. The architecture isn't the flag — it's how you evaluate, type, and eventually kill it.
- [47 · Analytics Is Architecture: Stop Sprinkling track() Everywhere](https://ma-x.im/blog/react-playbook-analytics-as-a-layer): Most analytics code is a scatter of track('button_click') calls with drifting names, mystery payloads, and three vendor SDKs called inline. Analytics is a cross-cutting concern, and it belongs in a layer with a typed event catalog — not smeared through your components. Here's how I structure it.
- [48 · Re-Renders Are React's Superpower, Not a Disease to Cure](https://ma-x.im/blog/react-playbook-rerenders-and-architecture): There's a particular panic I keep running into: a component re-rendered, someone saw it in the profiler, and now they're tearing the architecture apart to stop it. But rendering isn't React's flaw — it's the whole idea. The word you want is optimize, not minimize, and the difference decides whether your app stays maintainable.
- [49 · Theming and Dark Mode Without the Flash: A Systems Problem in CSS Clothing](https://ma-x.im/blog/react-playbook-theming-dark-mode): Dark mode looks like a class you toggle. Then you meet the flash of the wrong theme on load, colors that drift because every component hardcodes its own, and a theme context that re-renders the whole app. Theming done right is tokens, one switch point, and a boundary — and it barely touches React at all.
- [50 · The Command Palette Is an Architecture, Not a Widget](https://ma-x.im/blog/react-playbook-command-palette): Cmd+K looks like a fuzzy-search modal you bolt on at the end. Build it that way and it immediately drifts out of sync with the buttons and menus it duplicates. The real thing is a command registry: one typed source of truth for everything the app can do, feeding the palette, the shortcuts, and the menus at once.
- [51 · Code-Splitting Is a Boundary Decision, Not a Bundle Trick](https://ma-x.im/blog/react-playbook-code-splitting): Every performance guide tells you to lazy-load. Almost none tell you where to stop. Split on your file tree and you trade one big bundle for a hundred tiny chunks and a waterfall of spinners. The real question isn't how to split — it's finding the seams in the user's journey and cutting there.
- [52 · React Gives You the Loading State. It Does Not Give You Cancellation.](https://ma-x.im/blog/react-playbook-abort-controller): React 19 hands you pending state for free, and that's genuinely nice. But a finished spinner is not a finished request. AbortController is the piece almost nobody reaches for — not because it's hard, but because it looks scarier than it is. Here's the small, boring version that covers most of what you need.
- [53 · Most Advanced TypeScript Isn't Worth What It Costs](https://ma-x.im/blog/react-playbook-types-that-earn-their-keep): There's a point where a type stops protecting you and starts being a puzzle you have to solve again every time you touch it. I'm not a type wizard and I've stopped trying to be one — because on real React codebases, the complexity that pays for itself is a much shorter list than the internet suggests.
- [54 · What FSD Actually Fixed (and What It Didn't)](https://ma-x.im/blog/react-playbook-what-fsd-actually-fixed): Feature-Sliced Design got popular because frontend spent years being treated as the part of the codebase that didn't need real architecture. It fixed that perception. It did not fix cohesion, and pretending it did is how you end up with a button smeared across ten folders.
- [55 · Layered vs Feature-Sliced: Two Ways to Cut the Same App](https://ma-x.im/blog/react-playbook-layered-vs-feature-sliced): Every frontend architecture is really just a decision about which axis you slice the app along — by technical kind, or by feature. Both are correct. Both eventually hurt. The question worth asking isn't which one is better, it's which one is cheaper to be wrong about later.
- [56 · Micro-Frontends Are an Org Chart Decision, Not a Technical One](https://ma-x.im/blog/react-playbook-micro-frontends-org-chart): Every micro-frontends pitch I've seen leads with the technical benefits — independent deploys, framework isolation, smaller bundles per team. Almost none of it holds up unless the real problem was organizational to begin with. Conway's Law isn't a fun fact here. It's the actual justification.

## The Agent Playbook
A 11-part series on working with AI coding agents sensibly — cost, control, context, and judgment, not orchestras of agents.
- [The Agent Playbook index](https://ma-x.im/agent-playbook): The full path, grouped into waves.
- [01 · You Probably Don't Need Multi-Agents](https://ma-x.im/blog/agent-playbook-you-dont-need-multi-agents): Open almost any "how I use AI" post and you'll find an orchestra: a planner agent, a coder agent, a reviewer agent, a tester agent, all pinging each other. It looks impressive. It's also the most expensive, most fragile way to get worse results than one agent you actually taught to do the job.
- [02 · Do It As Usual: Teaching One Agent Your Whole Workflow](https://ma-x.im/blog/agent-playbook-do-it-as-usual): I can open a fresh session, type "take ticket 123 and do it as usual," and the agent runs the entire routine — assign, sprint, branch, commit, PR, pipeline. People assume that's a clever prompt. It isn't. It's months of small corrections turned into rules the agent never forgets.
- [03 · The Token Bill Is Part of the Architecture](https://ma-x.im/blog/agent-playbook-token-bill): A story made the rounds: someone put an agent on a schedule to keep checking their environment, it got stuck in a loop one night, and instead of a couple of hours it burned through a fortune in tokens by morning. The lesson isn't "watch your usage." It's that cost is a design constraint, and most agent setups treat it as a footnote.
- [04 · Test on Change, Not on a Timer](https://ma-x.im/blog/agent-playbook-test-on-change): The instinct is to put the agent on a schedule: every few minutes, wake up and check the environment. That instinct is where a lot of runaway costs and pointless runs come from. An agent should be woken by a reason — a commit, a deploy, a failing check — not by a clock ticking over whether or not anything happened.
- [05 · Guardrails for a Runaway Agent](https://ma-x.im/blog/agent-playbook-guardrails): An agent is stateful, and its errors compound: one wrong step sends it down an entirely different path, and it can't tell that it's lost. Autonomy without guardrails isn't trust — it's hoping. The job isn't to make the agent never fail. It's to make sure that when it does, the blast radius is small.
- [06 · The Context Is the Product](https://ma-x.im/blog/agent-playbook-context-is-the-product): A capable model with the wrong context is still a bad agent. The useful part of an agent is not the model in isolation, but the project knowledge, rules, tools, and decisions that shape what it can see before it acts.
- [07 · Tools Are Part of the Agent's Intelligence](https://ma-x.im/blog/agent-playbook-tools-are-intelligence): An agent cannot reason about information it cannot reach, and a vague tool description turns a precise capability into a guessing game. Tool design is not plumbing around the model. It is part of how the agent thinks.
- [08 · When an Agent Should Ask Instead of Acting](https://ma-x.im/blog/agent-playbook-when-to-ask): Autonomy is not a single setting to turn up. A useful agent knows which decisions it owns, which ones it can reverse, and which moments need a human before the next step.
- [09 · Memory Is Not a Bigger Context Window](https://ma-x.im/blog/agent-playbook-memory-vs-context): A long transcript can remember everything and still help with almost nothing. Durable agent memory is the small set of current facts, decisions, and lessons that makes the next run start from a better baseline.
- [10 · Evaluation Is the Missing Loop in Agent Workflows](https://ma-x.im/blog/agent-playbook-evaluation-is-the-missing-loop): An agent that feels better after a prompt change may still be getting worse. Without a small set of realistic tasks, explicit expectations, and recorded failures, agent improvement is just a sequence of impressions.
- [11 · Your Agent Instructions Are Rotting Right Now](https://ma-x.im/blog/agent-playbook-instructions-rot): Nobody writes agent rules once and walks away — they write them, then keep adding. A line here after a bad run, a paragraph there after a near-miss. Six months later the file contradicts itself, and the agent is following the version of your project that stopped existing in March.

## The Architecture Playbook
A curated cross-section of the architecture-focused articles above (React Playbook and standalone), regrouped around the decisions themselves rather than the series they were written for.
- [The Architecture Playbook index](https://ma-x.im/architecture-playbook): The curated path, grouped by concern.

## Other writing
- [The Request Ended. The Work Did Not.](https://ma-x.im/blog/full-stack-background-jobs): Emails, exports, webhooks, and slow integrations should not keep an HTTP request open. A queue helps only when retries, duplicate delivery, job state, and the database handoff are designed explicitly.
- [Redis Is Fast. Your Data Can Still Be Wrong.](https://ma-x.im/blog/full-stack-redis-without-magic): Redis can make an application feel dramatically faster, but speed is only useful when ownership, expiration, invalidation, and failure behavior are explicit. Otherwise the cache becomes a second truth nobody can explain.
- [The Database Changed Before the Deployment Finished](https://ma-x.im/blog/full-stack-zero-downtime-migrations): A schema migration and an application deployment do not happen at one instant. Zero-downtime changes work when old code, new code, and the database are allowed to coexist for a while.
- [SQL for Frontend Engineers: Model the Relationship First](https://ma-x.im/blog/full-stack-relational-database): SQL becomes much easier when you stop thinking in tables and start thinking in facts that must remain true. A checkout model shows where keys, JOINs, transactions, and indexes actually earn their place.
- [An API Is a Boundary, Not a URL](https://ma-x.im/blog/full-stack-api-contracts): A working endpoint is not yet a reliable API. The real contract includes validation, errors, retries, idempotency, and a way to evolve without making yesterday’s frontend fail tomorrow.
- [What Actually Happens After fetch()](https://ma-x.im/blog/full-stack-after-fetch): A frontend request does not jump straight from the browser into your backend. It crosses DNS, encrypted connections, edge infrastructure, application code, and a database before the UI sees a result.
- [AI Code Review Should Sound Like a Careful Engineer](https://ma-x.im/blog/github-ai-pr-reviewer): I built a personal AI reviewer for GitHub Pull Requests, not as a cold rule bot, but as a local and observable tool that checks known risk patterns and turns them into useful engineering conversation.
- [The Columns Hidden Inside Your Customer Reviews](https://ma-x.im/blog/jev-human-text-to-data): What interests me about TypeSafe's Jev is turning human language into data we can query. Restaurant reviews, product complaints, and Reddit discussions make the idea much more concrete than another chatbot benchmark.
- [Earned Autonomy: Comparing My Agent Workflow with a Corporate Experiment](https://ma-x.im/blog/agentic-development-at-work): I arrived at Liberty with a working model for agentic development. Now the company is exploring a more formal approach built around reusable agent skills. I don't know which model will prove better yet, and that uncertainty is the interesting part.
- [The Cart Was Not the Product: Building a HoReCa Procurement Agent for Silpo AI Factory](https://ma-x.im/blog/silpo-ai-factory-horeca-procurement-agent): For the Silpo AI Factory hackathon, the interesting problem was not building another AI shopping chat. It was figuring out where AI should stop, where deterministic procurement logic should begin, and how MCP could execute a controlled supplier workflow at the end.
- [Nivra: Turning a Hackathon Idea into a WebMCP Architecture Workspace](https://ma-x.im/blog/nivra-webmcp-challenge): How Nivra went from a vague hackathon direction to a tested WebMCP workspace: choosing the right idea, making architecture the shared context, and proving that human UI, agent tools, and deterministic validation could work from the same model.
- [Checkout Isn't a Form. It's the Only Part of the App Where Architecture Has a Stopwatch on It](https://ma-x.im/blog/checkout-architecture-time-to-goal): Most of an app can afford to be a little slow, a little clunky, and still get forgiven. Checkout can't. What you're actually selling in that flow isn't a UI — it's time-to-goal. Every architectural choice in there either protects that number or quietly taxes it.
- [They Asked Me to Build a Slider. It Was a Much Better Question Than I Thought.](https://ma-x.im/blog/the-slider-interview): A carousel with next, previous, and a row of dots. No animation. I remember thinking: is this it? Then I watched my own first thirty seconds of typing and realized the task wasn't measuring whether I could build a slider. It was measuring the order I do things in.
- [You Only Get to See It From the Outside Once](https://ma-x.im/blog/the-outside-view): The most valuable thing an experienced engineer brings to a new project isn't a skill — it's a vantage point. For a short window, you can still see the thing from the outside, the way a user or a newcomer does. Six months in, that view is gone. And most teams burn it in the first week without noticing.
- [The Smeared Component: When Architecture Scatters What Should Stay Together](https://ma-x.im/blog/smeared-component): FSD is one of the best frontend methodologies out there. Used without thinking, it turns a complex component into a scavenger hunt across eight folders. Here's what I learned.
- [The AI Agent Memory System I Built Was Broken — Here Is the Redesign](https://ma-x.im/blog/ai-agent-memory-redesign): Append-only markdown memory works great — until it doesn't. After watching the system degrade in production, our team redesigned it from scratch with strict principles: small, high-signal, controlled, and self-maintaining.
- [Give Your AI Agent a Memory — It Will Stop Disappointing You](https://ma-x.im/blog/give-your-ai-agent-a-memory): A simple file-based memory system that turns AI agents from forgetful interns into reliable collaborators. Works for engineers, designers, writers, and anyone who uses AI tools daily.
- [Stop Quizzing Senior Engineers — Start Talking to Them (TL;DR)](https://ma-x.im/blog/interviewing-senior-engineers-short): The condensed version: why conversational interviews beat trivia quizzes for senior roles, with practical examples and actionable advice.
- [Stop Quizzing Senior Engineers — Start Talking to Them](https://ma-x.im/blog/interviewing-senior-engineers): Why conversational interviews produce better hiring signal than algorithmic puzzles and API trivia — and how one interview with a guy named John changed how I think about hiring.
- [Designing Project Documentation for AI Coding Agents](https://ma-x.im/blog/ai-agent-project-context): How structured documentation dramatically improves AI-generated code quality by giving agents the context they need.
- [Next.js Static Export to GitHub Pages: A Production Setup Guide](https://ma-x.im/blog/nextjs-ssg-github-pages): How to configure Next.js 15 static export and deploy to GitHub Pages with a custom domain. Covers App Router, basePath, react-markdown blog pipeline, GitHub Actions CI/CD, and common pitfalls.
- [Building Design Systems That Scale](https://ma-x.im/blog/building-design-systems-that-scale): How to build component libraries that teams actually want to use.
- [Type-Safe React Architecture](https://ma-x.im/blog/type-safe-react-architecture): Leveraging TypeScript for better developer experience and fewer runtime errors.
- [Complex Forms Done Right](https://ma-x.im/blog/complex-forms-done-right): Patterns for managing complex form state, validation, and user experience.
- [React Performance Optimization](https://ma-x.im/blog/react-performance-optimization): Practical techniques for building fast React applications at scale.
- [Monorepo Best Practices](https://ma-x.im/blog/monorepo-best-practices): How to structure and manage large-scale monorepo projects effectively.

## Feeds
- [RSS feed](https://ma-x.im/feed.xml): Full post feed.
- [Sitemap](https://ma-x.im/sitemap.xml): All indexable URLs.
- [Public text export](https://ma-x.im/llms-full.txt): Profile, case studies and published articles.