<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Scott Hatfield on Medium]]></title>
        <description><![CDATA[Stories by Scott Hatfield on Medium]]></description>
        <link>https://medium.com/@Toglefritz?source=rss-c0985f54a96e------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*KhlaRzdhcNfjpXjVh2wY5Q.png</url>
            <title>Stories by Scott Hatfield on Medium</title>
            <link>https://medium.com/@Toglefritz?source=rss-c0985f54a96e------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 05:09:10 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@Toglefritz/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Prompt Engineering Will Look Ridiculous Someday]]></title>
            <link>https://medium.com/@Toglefritz/prompt-engineering-will-look-ridiculous-someday-d83d1b0aafee?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/d83d1b0aafee</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Fri, 28 Aug 2026 19:32:45 GMT</pubDate>
            <atom:updated>2026-08-28T19:32:45.133Z</atom:updated>
            <content:encoded><![CDATA[<h4>Why AI agents should learn their jobs instead of being told how to do them</h4><p>I am just old enough to remember learning how to search the Internet.</p><p>And I mean actually <em>learning</em> how to search. We had lessons about this in school. There were operators to remember, special punctuation to use, exact-match syntax, and various ways to combine search terms. Finding information online was a skill in itself because you needed to understand how the information retrieval system worked to use it effectively. In retrospect, searching the Internet sometimes felt less like asking a question and more like writing a database query.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*d3GvLIFwYlJtQR_Rbusrcw.png" /><figcaption>Before Google, finding things on the Internet was a bona fide skill.</figcaption></figure><p>Today, I can type a vaguely formed thought into a Google search box, with spelling mistakes and half the relevant information missing, and there is a remarkably good chance that what I wanted will appear somewhere near the top of the results. The enormously complicated machinery required to search billions of pages has not disappeared. In fact, it has become vastly more complicated. But I no longer need to understand very much about that machinery to use it.</p><p>I think about those school library lessons surprisingly often when I use AI.</p><p>There is now an entire culture devoted to figuring out how to talk to AI systems correctly. We have prompt engineering. We have rules, hooks, skills, shared prompts, steering documents, context files, and increasingly elaborate collections of instructions explaining exactly how an AI agent should behave. Software repositories that once contained a README for humans now accumulate Markdown documents written primarily for machines. Never has Markdown been so popular.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g0547f1vtZM2YkAZn89-4w.png" /><figcaption>Markdown has gone from a tool for READMEs to a fundamental piece of software architecture.</figcaption></figure><p>None of this is silly or useless. In fact, much of it works remarkably well. Carefully providing an AI agent with the right context and instructions can make an enormous difference in the quality of its work. The problem is that <strong>we have once again placed much of the burden on the human to learn how the machine wants to work</strong>.</p><p>I suspect this will eventually seem quaint. We will still need to tell AI systems what we want (probably). But I think the increasingly elaborate practice of explaining <em>how to do the job</em> every time we ask an AI agent to do something will eventually become an artifact of this particular stage in the development of AI.</p><h4>Imagine If Humans Worked This Way</h4><p>Consider what this would look like with a human engineer. Imagine that a new engineer joins your team. During the first few weeks, they read the documentation, explore the codebase, attend meetings, ask questions, make some mistakes, and gradually learn how the team works. Perhaps it takes a few months before they become truly effective. This is normal. Learning the job is part of the job.</p><p>Now imagine that six months later, the engineer arrives at work on Monday morning having forgotten everything. Before they can begin, you hand them hundreds of pages of documentation explaining the architecture, coding standards, team structure, current projects, past decisions, and all the other information they need to function. They read it all, do some useful work, and then go home.</p><p>On Tuesday, they have forgotten everything again.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rFfiY2tXkDn8E0NRplZHNw.png" /><figcaption>AI agents can feel like the meme about goldfish having super-short memories.</figcaption></figure><p>This would be an absurd way to run an engineering organization. Yet it is surprisingly close to how we work with AI agents today. The obvious solution is not simply to write better documentation. Nor is it to discover the perfect prompt, or to keep adding more instructions to an ever-growing context window. What we actually want is something much more fundamental.</p><h4>AI Agents Should Learn Their Jobs</h4><p>An effective engineer does not become valuable because they can repeatedly reread every piece of information the organization has ever produced. They become valuable because they gradually construct an understanding of the world in which they work. They learn how the pieces of a system fit together, which parts are fragile, why certain decisions were made, which approaches have failed before, what their teammates care about, and how all of this changes over time.</p><p>In other words, they build a <strong>model of their world</strong>. What would happen if AI agents could do the same?</p><h3>Remembering Is Not the Same as Learning</h3><p>There is an obvious answer to some of this: give the AI agent a memory. If our hypothetical engineer keeps forgetting everything at the end of the day, perhaps we simply need to give them a notebook.</p><p>There is already plenty of work, not to mention tens of billions of dollars, happening in this direction. AI systems can preserve conversations, retrieve relevant information from previous interactions, and search through increasingly large collections of documents when they need additional context. These capabilities are enormously useful, and better memory will almost certainly be part of making AI agents more effective over long periods of time. But I think memory, by itself, is an incomplete solution.</p><p>Consider our human engineer again. An experienced engineer is not effective because they perfectly remember every meeting they have ever attended, every bug they have ever fixed, or every pull request they have ever reviewed. In fact, they have probably forgotten most of them. What matters is that those experiences changed what they <em>know</em> about the system.</p><p>Perhaps they have fixed six bugs in the same subsystem over the last two years. They probably cannot describe each bug from memory. But they may have learned that this subsystem is unusually fragile and that seemingly harmless changes tend to have unexpected consequences. <strong>The individual experiences fade while the lesson remains</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*l0Fcamiz0FyV7uARYeYpQg.png" /><figcaption>Experiences are not perfectly recorded. Instead, they are distilled into key concepts that may become useful in the future.</figcaption></figure><p>The same thing happens with less concrete knowledge. An engineer might see the same architectural pattern proposed several times and watch it get rejected each time. Eventually, they learn something that may never appear in any architecture document: the approach technically works, but it does not fit the way this team wants to build software. The next time the idea comes up, <strong>the engineer does not need to search through two years of meeting transcripts</strong> to discover that fact again.</p><p>This distinction seems important for AI agents. Saving every conversation an agent has ever participated in gives it a <em>history</em>. Giving it the ability to search that history gives it useful <em>memory</em>. Neither necessarily means the agent has learned anything from those experiences.</p><p>Learning implies that experience changes the agent’s understanding of the environment in which it operates. New information might strengthen something it already believes, contradict something it previously believed, reveal a relationship it had not noticed, or cause some old piece of knowledge to become less relevant. <strong>The important artifact is not a perfect record of everything that happened. It is the understanding that remains afterward.</strong></p><p>We might call that understanding a <strong>world model</strong>: a representation of the environment the agent believes it is operating within. For a software engineering agent, that world might include the codebase, its architecture, the people working on it, the decisions they have made, the conventions they follow, and all the strange little lessons accumulated through the experience of actually working on the project.</p><p>Memory can help build that model, but memory is not the model itself. <strong>Memory preserves experiences. Learning changes your model of the world because of those experiences.</strong></p><h3>What If the Agent Could Learn the Project?</h3><p>After six months, our hypothetical AI engineer should know more than what is written in the documentation. It should understand how the major pieces of the system fit together, but it should also know which parts are fragile, why certain architectural decisions were made, which solutions have already been tried and abandoned, and which conventions actually matter to the team. It should recognize when the project is changing and, ideally, have some sense of where its own understanding might be incomplete or out of date.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-HVUEkmRnwd1EFkPKC7ANg.png" /><figcaption>Rather than being like a goldfish, we want our AI agents to be like an animal known for their excellent memory.</figcaption></figure><p>Where would it learn all of this? The same places a human engineer does. Some of it comes from source code and documentation, but much of it comes from experience: commits, pull requests, issue trackers, tests, meetings, messages, and the results of its own previous work. Taken together, these are not simply sources of context to retrieve later. They are observations about the world in which the agent works.</p><p>This suggests a fairly simple loop: <strong>observe, reason, update</strong>. A commit changes the repository, so the agent observes what changed. It reasons about whether that change affects its existing understanding of the project. If it does, the agent updates its world model. The same process could happen when documentation changes, a decision is made in a meeting, a test fails, or an approach is repeatedly rejected during code review.</p><p>This is the question that led me to build <a href="https://github.com/Toglefritz/Thicket"><strong>Thicket</strong></a>.</p><p>Thicket is a platform for giving AI agents persistent, evolving world models of the environments in which they work. Instead of beginning every task with a carefully assembled pile of context, an agent can accumulate an understanding of the project over time and bring that understanding with it to the next task.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2791rFdzRyZGsanHs7ASgA.png" /><figcaption>Without a world model, agents spend a great deal of time gathering and re-gathering the same context about a project over and over.</figcaption></figure><p>Importantly, I don’t even think we necessarily know what the right world model looks like. Different agents working in different environments may need to represent very different kinds of knowledge. That raises another interesting possibility: perhaps agents should be able to help determine not only what their world models contain, but how those models are structured.</p><p>There are a lot of unanswered questions here, and that is rather the point. Thicket is not an attempt to prescribe the correct world model for an AI agent. It is a system allowing us to stop treating context as something that must be reconstructed for every interaction and start asking whether an agent can develop an understanding of its environment through the experience of working within it.</p><h3>Maybe Markdown Is Our Card Catalog</h3><p>None of this means that prompt engineering, agent instructions, rules files, or carefully managed context are bad ideas. The complicated search syntax I learned in school wasn’t bad either. Neither were card catalogs. These were useful tools built around the capabilities of the technology we had at the time.</p><p>I suspect the same is true of the increasingly elaborate infrastructure we build around AI agents today. We are learning how to make extraordinarily capable new machines useful, and right now that means spending a surprising amount of effort explaining to them how we want them to work. Perhaps that is simply where we are in the evolution of this technology.</p><p>But I don’t particularly want to get better at writing instructions that explain my project to an AI agent. I want the agent to learn the project. I want it to develop the kind of accumulated understanding that we expect from a human who has spent months or years working in the same environment.</p><p>That’s the experiment behind Thicket.</p><p>Maybe someday repositories filled with Markdown files explaining how an AI agent should behave will look a little like those search lessons from my childhood: not foolish or pointless, but a perfectly reasonable solution to a problem we eventually learned how to solve better.</p><p><em>Disclosure: I created this article, and the Thicket project discussed within it, as part of my entry in the </em><a href="https://allthingsagentichackathon.devpost.com/"><em>All Things Agentic Hackathon</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d83d1b0aafee" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Who Actually Built This App?]]></title>
            <link>https://medium.com/@Toglefritz/who-actually-built-this-app-c8ade036972a?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/c8ade036972a</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Mon, 13 Jul 2026 11:33:43 GMT</pubDate>
            <atom:updated>2026-07-13T11:33:43.002Z</atom:updated>
            <content:encoded><![CDATA[<h4>AI app builders may be challenging an assumption hidden inside modern software distribution.</h4><p>If you maintain a public presence as a software developer, you have likely received a variation of a highly specific, out-of-the-blue email. The message usually offers a remarkably straightforward business proposition: a company wants to pay you, sometimes hundreds of dollars, simply to publish an application under your personal Apple or Google developer account. The pitch emphasizes that you do not have to write a single line of code or perform any active maintenance. You merely upload their completed binary, sit back, and collect passive income.</p><figure><img alt="A software engineer sits on the beach. A tropical drink sits next to their laptop. The laptop has just one button, with the text “free money.”" src="https://cdn-images-1.medium.com/max/1024/1*yVbjVG2bifkyMB4MJh0cEg.png" /><figcaption>Everybody loves free money!</figcaption></figure><p>For anyone who understands the economics of software development, this proposition immediately raises a glaring question. A developer account costs less than a hundred dollars a year, and the registration process is open to almost anyone. Why would a company pay a stranger many hundreds or even thousands of dollars to perform a task they could easily execute themselves for a fraction of the cost?</p><p>The answer lies in the fact that they are not buying your administrative labor. <strong>They are buying your digital identity</strong>. Modern operating systems rely on robust gatekeeping ecosystems to protect users from malicious software. To pass through these gates, an application must be digitally signed by a verified creator. Establishing that verified identity requires passing regulatory hurdles, proving your physical location, submitting tax documentation, and linking a valid credit card. Scammers and malware authors are locked out of this ecosystem by design. By purchasing access to your established developer account, <strong>they are purchasing a clean reputation</strong> that allows them to bypass these defensive perimeters entirely.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C69RAqqIw2oibkwwTST6ig.png" /><figcaption>Sadly, the cost of free money can sometimes be very high.</figcaption></figure><h4>The Social Contract of Code Ownership</h4><p>This scam exposes the fundamental, implicit trust model upon which all modern software distribution is built. The pipeline relies on a chain of custody that moves from a developer’s verified identity to their cryptographic signing credentials, then to the application binary, and finally to the user’s device. Security mechanisms like code signing do not actually prove that a piece of software is safe or well-written. Instead, they prove a structural relationship, guaranteeing that a specific, legally accountable individual or entity assumes responsibility for the behavior of that artifact. The developer-account scam is an intentional, malicious attempt to break that relationship by turning an honest creator into an unwitting proxy shield.</p><p>Historically, distributing software implied an intimate, structural understanding of how that code functioned. A publisher was responsible not just for the initial release, but for ongoing maintenance, security triaging, and downstream stability. This dynamic highlights the profound difference between simply creating software and actively owning it.</p><blockquote>True ownership requires the capacity to audit dependencies, patch vulnerabilities, and stand behind the product over its entire lifecycle.</blockquote><h3>Enter the AI App Builder</h3><p>The transition from traditional software development to the era of generative artificial intelligence has fundamentally altered the paradigm of creation. Today, a new wave of AI app builders promises a reality that once sounded like science fiction. Through a conversational interface, an individual with absolutely no programming experience can describe a desired application in plain English. Within minutes, the platform processes the natural language prompt, generates the necessary source code, manages the compilation process, and delivers a fully functional executable file ready for distribution. The magic of this pitch lies in the absolute elimination of technical friction, turning pure intent into working software almost instantaneously.</p><p>As a software engineer who integrates AI tools into my daily development workflow, I find this democratization of technology incredibly exciting. Lowering the barrier to entry means that specialized, creative, or deeply niche ideas can be realized by the people who understand the problems best, even if they cannot write code. However, professional engineering experience inevitably changes how a person evaluates a digital black box.</p><p>While a non-technical user sees a polished interface that functions exactly as described, an engineer instinctively looks for things that are not immediately visible. We evaluate software for structural integrity, hunt for hidden dependencies, and consider long-term lifecycle management. A non-programmer looks at a generated application and sees a completed product, whereas an engineer sees a complex web of potential vulnerabilities and unverified logic.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6ijQ6wxwtS3-OWd7LhkpmA.png" /><figcaption>Non-technical builders and engineers view the same software through entirely different lenses.</figcaption></figure><p>When we view these no-coding app builders alongside the mechanics of the developer account scam, a worrying connection begins to surface. Both scenarios involve a human being placing their personal reputation behind a collection of compiled code that they did not write and cannot fully verify. The frictionless nature of modern AI tooling obscures this reality, wrapping a profound shift in software provenance inside an experience of pure creative empowerment. This friction brings us directly to the central question that modern operating systems and distribution networks are completely unprepared to answer: <strong>what exactly does it mean to publish, sign, and distribute software that you cannot inspect, cannot maintain, and do not understand?</strong></p><h3>Code Signing Makes an Assumption</h3><p>To truly comprehend how this scales into a systemic vulnerability, we must zoom out from the mechanics of generative platforms and look closely at the underlying philosophy of modern security infrastructure. Cryptographically speaking, a digital signature proves something exceptionally narrow and precise. It validates exactly one mathematical fact: a specific cryptographic key was utilized to sign a specific binary artifact, and that artifact has not been altered since the signature was applied. The math makes no promises about intent, quality, or safety; it merely guarantees authenticity and integrity.</p><figure><img alt="A person signs a document not with a signature containing their name but with a hexadecimal string." src="https://cdn-images-1.medium.com/max/1024/1*DuKmEhnh2yU7xKZd_bFbAw.png" /><figcaption>Cryptographic signatures are a bit like human signatures. They guarantee the identity of the person signing but not the content of the document. They also assume that the person signing understands the content of the document.</figcaption></figure><p>Despite the rigid technical boundaries of cryptography, humans routinely project a massive social contract onto that mathematical foundation. When an operating system allows an application to run because it possesses a valid developer signature, we implicitly assume a complex baseline of human agency and oversight. We assume that the publisher deliberately chose to distribute exactly this logic, that they exercise active control over the application’s behavior, and that they possess the technical capacity to triage and patch the software if a vulnerability is discovered down the line. For decades, this interpretive leap was perfectly reasonable, because generating an executable required a level of technical proximity to the code that naturally aligned with these assumptions.</p><p>The arrival of frictionless AI app builders thoroughly dismantles this alignment. Consider the user journey in a generative ecosystem: an individual inputs a text description, watches the application appear on their screen, tests that the user interface works, and clicks a button marked “publish.” In this highly compressed workflow, the person signing the binary may never see a single line of source code. In many cases, they would not be able to read or comprehend the source code even if it were explicitly shown to them.</p><p>Consequently, it is inaccurate to claim that code signing is broken because the underlying mathematics remain completely intact. The reality is far more subtle and interesting. Rather than breaking cryptography, AI is rapidly widening the gap between what a digital signature technically proves and what human society assumes it means. <strong>When the developer signature carries the weight of a legal and ethical guarantee, but the developer cannot explain what the application actually does under the hood, the entire foundation of ecosystem trust begins to fracture.</strong></p><h3>The Platform Doesn’t Even Need to Be Malicious</h3><p>It is remarkably easy to jump straight to the malware-related implications of this architectural shift. When considering a world where developers distribute code they did not write, the mind naturally wanders toward bad actors, keyloggers, and deliberate deception. Yet focusing exclusively on deliberate malice misses the far more realistic, subtle, and systemic threat. Malicious intent is not required for this paradigm to trigger an ecosystem crisis. The more pressing danger is born from pure, well-intentioned routine engineering failures colliding with an unequipped distribution model.</p><p>Consider an entirely well-meaning grade school teacher who decides to use a generative AI platform to build a custom math practice application for their students. This is a fantastic use case for generative technology. By bypassing the traditional barriers of software engineering, the teacher rapidly unlocks an incredibly powerful, hyper-localized tool for learning. The platform they use is equally well-meaning. It is built by a dedicated team working hard to lower technical barriers and democratize creation. The teacher describes the app, tests it, signs it with their personal developer certificate, and proudly distributes it to the class.</p><p>The arrangement functions beautifully until a critical security vulnerability is discovered deep within an underlying framework used by the AI platform’s generation engine. In the professional software supply chain, a vulnerability of this scale triggers an automated cascade of security advisories, patch releases, and dependency updates. But what happens in our classroom scenario?</p><p>Does this grade school teacher receive a Common Vulnerabilities and Exposures (CVE) notification? If they do, would they even understand what the advisory means, let alone possess the technical capacity to fix the underlying code? The lifecycle chaos deepens if the teacher has since canceled their platform subscription, or if the startup that generated the application went out of business or was acquired. Suddenly, a group of students has a vulnerable piece of software running on their personal machines.</p><p>The platform engineers might patch the flaw in their generator today, meaning every app built tomorrow will be secure. But absolutely nothing happens to the fifty thousand apps generated over the previous six months. Nobody is responsible for pushing the updates, the ecosystem has no automated mechanism to track which signed applications share this vulnerable lineage, and the creators themselves are entirely unequipped to act as a security response team.</p><h3>The Hijacking of Communal Trust</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WscLJe9zTHbDn2ZCykikdw.png" /><figcaption>Code generation can create a mismatch between the person vouching for software and the system that actually created the software.</figcaption></figure><p>This breakdown becomes even more troubling when we look past the technical vulnerability and examine the human relationship at stake. Teachers are among the most genuinely well-meaning people in our society, and they naturally carry an exceptional amount of communal responsibility. Because parents and school systems deeply trust a teacher’s judgment, they will unhesitatingly install a math practice tool that the teacher explicitly vouches for and distributes.</p><p>If we allow our minds to wander back toward the more malicious implications of this systemic gap, a deeply insidious realization emerges. The threat here is not merely that an automated platform can hijack or exploit a developer’s digital signature. The deeper danger is that the profound, hard-won trust an individual has established with their local community can be hijacked as well.</p><p>When a trusted community figure publishes an application, their reputation acts as the ultimate endorsement. Under the current software distribution model, clicking “Publish” signs a digital guarantee that the creator stands behind the artifact. But when that creator is completely blind to the inner workings of the software, their genuine goodwill is effectively weaponized. The ecosystem accepts the app because it trusts the teacher, the community installs the app because it trusts the teacher, but the teacher is ultimately nothing more than an unwitting conduit for software they can neither verify nor control.</p><h3>People Should Not Stop Building Apps</h3><p>Emphasizing these systemic infrastructure gaps should not be mistaken for a call to restrict who gets to build software. The democratization of technology remains one of the most profoundly exciting shifts of modern computing. The fact that a grade school teacher can manifest a highly effective, deeply empathetic educational tool simply by describing it in plain language is an undeniable net positive for human creativity. We should actively resist the temptation to retreat into new forms of gatekeeping, and the solution to this paradigm shift is certainly not a rule requiring a computer science degree before a user is allowed to click publish.</p><p>Instead, the challenge we face is one of architectural legacy. Our current security infrastructure and software distribution networks were architected for a world where generating a native executable required an intimate, high level of technical proximity to the construction of that code. For decades, the ability to compile a binary and navigate the deployment process served as a natural proxy for technical comprehension. Today, that proximity has entirely evaporated. The tools have evolved to separate execution from understanding, leaving our validation systems stranded on an assumption that is no longer true.</p><p>Ultimately, this structural disconnect leaves us with an open paradox that the software industry must deliberately resolve. For decades, we have built software trust systems entirely around the identity of the person who signs the application. Generative AI is rapidly pushing us into a world where the more interesting, protective, and vital question is no longer <em>who</em> signed the code, but <em>what</em> actually built it.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c8ade036972a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Valuable but Un-flashy Ways to Use AI in Software Engineering]]></title>
            <link>https://medium.com/@Toglefritz/the-valuable-but-un-flashy-ways-to-use-ai-in-software-engineering-cbc6612eab59?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/cbc6612eab59</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[coding]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Sat, 30 May 2026 02:49:38 GMT</pubDate>
            <atom:updated>2026-05-30T02:49:38.081Z</atom:updated>
            <content:encoded><![CDATA[<h4>Three constructive ways software engineers can use AI to think, build, and learn</h4><p>The least satisfying way to use AI in software engineering is often to ask it to be the software engineer.</p><p>That may sound strange, given how much of the conversation around AI-assisted development focuses on code generation. But in practice, asking an AI system to take over too much of the work can quickly become frustrating. The first result may look impressive. It may produce files, functions, tests, interfaces, or even an entire prototype. Then the real work begins.</p><p>You have to inspect the assumptions. You have to find the places where the architecture does not quite fit. You have to notice the edge cases it missed, the dependencies it invented, the abstractions it overcomplicated, and the ways the solution fails to match the actual problem. At some point, the experience can stop feeling like software engineering and start feeling like supervising a very fast, very confident junior developer who does not fully understand the system and who refuses to ever adapt their thinking.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Zcg5_4lkU9QyPlCLnr0j7g.png" /><figcaption>AI systems allow developers to replicate the same mistakes across a codebase faster than ever before.</figcaption></figure><p>That does not mean AI is useless for software engineering. It means the most constructive uses of AI are often more focused, more deliberate, and less glamorous than the headlines suggest. <strong>AI systems are most useful when they help engineers do what engineers already need to do: think through designs, move faster through tedious work, and learn new skills.</strong> Used this way, AI is a tool for sharpening that judgment, reducing friction, and expanding what an engineer can reasonably take on.</p><p>There are three especially constructive ways to use AI in software engineering: as a sounding board, as a targeted productivity tool, and as a way to accelerate learning.</p><h3>Use AI to Improve Your Thinking, Not Replace It</h3><p>One of the most constructive ways to use AI in software engineering is as a sounding board for ideas, like a turbocharged rubber duck.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PeOLbf5RsXolSN_aIEzhBA.png" /><figcaption>AI is like the most useful tool in software engineering evolving to its next, more powerful, form.</figcaption></figure><p><strong>Having a sounding board for thinking about system design is valuable because a great deal of software engineering happens before code is written.</strong> The important work is often not choosing the exact syntax for a function or filling in the body of a method. It is deciding what should exist in the first place. Should this behavior live in a service, a package, a module, or a single function? Should the system be split into separate components, or would that create unnecessary complexity? Is the design flexible in a useful way, or merely abstract?</p><p>These are not questions with simple, universal answers. They are tradeoff questions. They depend on the shape of the system, the constraints of the team, the expected rate of change, the operational environment, and the cost of being wrong. In this context, AI is useful in a different way than simple code generation. <strong>A good AI interaction can create friction against an engineer’s first idea</strong>. It can surface assumptions that were implicit. It can point out failure modes that are easy to miss when a design still feels clean and elegant in the abstract. It can help compare several approaches before any one of them becomes expensive to change.</p><p>For example, an engineer might ask:</p><ul><li>Should this be a service, package, module, or just a function?</li><li>What are the failure modes of this architecture?</li><li>On what assumptions does this design depend?</li><li>Argue against this approach.</li><li>What would make this hard to maintain?</li></ul><p>The value of these questions is not that the AI system can act like a design review partner that is always available, even when another engineer is not.</p><p>However, this only works if the AI system is not treated as a source of validation. If the interaction becomes a search for agreement, it is much less useful. AI systems are often quite willing to affirm a proposed design, especially when the prompt implies that the user already prefers it. In fact, <strong>the tendency towards sycophancy is a dangerous characteristic of many AI tools because it makes them simultaneously more alluring and less useful.</strong> It can make the tool feel helpful while quietly making the engineering process worse.</p><p>The better approach is to ask for resistance. Ask the system to identify weak points. Ask it to explain what would go wrong. Ask it to compare the preferred approach against alternatives. Ask it to challenge the design from the perspective of maintainability, testing, onboarding, performance, security, and future change.</p><p><a href="https://github.com/Toglefritz/ai_steering/blob/main/docs/design-discussion.md">ai_steering/docs/design-discussion.md at main · Toglefritz/ai_steering</a></p><p>In that role, AI does not replace engineering judgment. It gives that judgment more material with which to work. The engineer still owns the decision. The engineer still understands the system, the team, and the consequences. But the AI system can help make the thinking more explicit before the design hardens into code.</p><p>Used this way, AI is not doing the engineering. It is improving the conditions under which engineering decisions are made.</p><h3>Use AI Where the Work Is Tedious, Not Where the Judgment Is Critical</h3><p>Every software project contains work that needs to be done, but does not necessarily deserve an engineer’s full creative attention. Unit tests need repetitive setup code. Data transfer objects need to be mapped from one shape to another. Example code needs to be converted among API styles. Test data, fixtures, and mock objects need to exist before the more meaningful testing work can begin.</p><p>None of this work is unimportant. A project still needs tests, documentation, scripts, configuration, and clean data mapping. But writing every line of that material by hand is not always the best use of an engineer’s time. Chores are necessary, but not typically very exciting.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cYXPW6Q7btWr2iJa4OD7PA.png" /><figcaption>Some parts of building a system are necessary but also tedious and time-consuming. Delegating these low-leverage tasks to AI systems can save time and improve morale.</figcaption></figure><p>This is where AI can produce real productivity gains without turning the development process into a frustrating exercise in supervising generated code. The engineer can define the task, provide the relevant context, and ask the AI system to produce a first pass. Then the engineer reviews, edits, and integrates the result.</p><p>The common thread in tasks that are good candidates to delegation to AI agents is that these tasks are bounded. They have clear inputs and outputs. They do not require the AI system to understand the entire business domain, own the architecture, or make subtle product decisions. They are useful precisely because they are limited.</p><p>That distinction matters because not all AI-assisted development produces the same kind of productivity gain. Asking an AI system to build an entire feature, design a whole application, or take ownership of a complicated technical decision can become expensive, frustrating, and counterproductive. The more responsibility the AI system is given, the more time the engineer may need to spend reviewing, correcting, reshaping, and sometimes discarding the result.</p><p>A more practical approach is to use AI for work that is necessary but not especially valuable as a thinking exercise.</p><p>This also helps avoid one of the risks of overusing AI: skill atrophy. If an engineer constantly delegates the parts of the work that require judgment, design, debugging, and deep understanding, the tool can start to weaken the very skills that make the engineer valuable. But delegating low-leverage work is different. It preserves attention for the parts of software engineering where human judgment matters most.</p><p>Used this way, AI represents a way to spend less time on mechanical work and more time on the work that actually benefits from experience. The productivity gain is not magic. It comes from being selective about what the AI system is asked to do.</p><h3>Use AI to Expand Your Range as an Engineer</h3><p>One of the more interesting uses of AI is not productivity at all. It is education. Software engineering is a broad discipline and most engineers spend the majority of their careers developing expertise in only a small portion of it. A mobile developer may know very little about embedded firmware. A cloud engineer may have limited experience with frontend frameworks. A backend developer may rarely interact with infrastructure, networking, or hardware. Expanding into adjacent disciplines has traditionally required a significant investment of time, as engineers work through unfamiliar terminology, tools, documentation, and conventions before they can even begin solving real problems.</p><p>AI does not eliminate this learning process, but it can make it substantially more efficient. An engineer can ask questions as they arise, request explanations at different levels of detail, compare alternative approaches, and quickly fill gaps in their understanding. Instead of spending hours searching for the right documentation page or tutorial, it becomes possible to have an interactive conversation about a topic while actively working through it.</p><p>The key, however, is to treat the AI system as a teacher rather than a substitute. <strong>An engineer who asks an AI system to generate a solution and immediately ships the result has learned very little.</strong> An engineer who asks why the solution works, what alternatives exist, and what tradeoffs were made is using the same tool in a completely different way. The goal is not to obtain a finished solution. The goal is to build a mental model that makes future problems easier to solve independently.</p><p>This is where AI begins to resemble tools used in other disciplines. Strong chess players often study games with engines such as Stockfish. The engine may identify stronger moves than the player would have found independently, but the value comes from understanding why those moves are stronger. The objective is not simply to reach a better position on the board. The objective is to become a better player.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dZkn6rEqmKLlaqp-KKrLug.png" /><figcaption>Chess players often use AI systems to develop their skills and software engineers can use the technology in a similar way.</figcaption></figure><p>AI can serve a similar role in software engineering. An engineer might ask the system to review a piece of code and then investigate the feedback. They might compare several implementations of the same feature and analyze the tradeoffs among them. They might generate an initial solution and then rewrite it from scratch to verify their understanding. They might ask the system to explain a design pattern, identify weaknesses in an implementation, or justify a recommendation in detail. In each case, the output itself is less important than the understanding gained by studying it.</p><p>These activities are forms of deliberate practice. The engineer is not outsourcing understanding. Instead, the AI system is being used to accelerate the process of building understanding. This can be especially valuable when exploring adjacent technical domains, where many of the core engineering skills already exist and the primary challenge is learning the vocabulary, conventions, tools, and constraints that are unique to a particular field.</p><p>Used this way, AI becomes more than a productivity tool. It becomes a force multiplier for professional growth. The engineer still has to do the work of learning, practicing, and developing intuition, but the feedback loop becomes much shorter. With the right approach, AI can help engineers expand their range more quickly than would otherwise be possible, allowing them to move into unfamiliar territory with greater confidence and competence.</p><h3>Conclusion</h3><p>Much of the discussion around AI in software engineering focuses on code generation. While that can certainly be useful in some situations, it is often not where AI provides the greatest value.</p><p>Used as a sounding board, AI can help engineers think through tradeoffs, challenge assumptions, and identify weaknesses in a design before those decisions become expensive to change. Used as a productivity tool, AI can reduce the cost of repetitive, low-leverage work, allowing engineers to spend more time on the parts of software development that require judgment and experience. Used as a learning tool, AI can accelerate deliberate practice, helping engineers build new skills and expand into unfamiliar technical domains.</p><p>None of these uses are particularly flashy, but that is precisely what makes them valuable. They fit naturally into the work that software engineers are already doing rather than attempting to replace it with an entirely different workflow. Like any tool, the value of AI depends on how it is used. When applied deliberately, it can help engineers make better decisions, spend more time on meaningful work, and continue expanding their skills throughout their careers.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cbc6612eab59" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Not All Engineers Do the Same Job]]></title>
            <link>https://medium.com/@Toglefritz/not-all-engineers-do-the-same-job-45939b2fef14?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/45939b2fef14</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[career-development]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Wed, 22 Apr 2026 02:25:53 GMT</pubDate>
            <atom:updated>2026-04-22T02:25:53.317Z</atom:updated>
            <content:encoded><![CDATA[<h4>How Two Definitions of Engineering Shape the Systems We Build</h4><p>“Software engineer” is usually treated as if it were a well-defined role. The title shows up on job descriptions, org charts, and performance reviews with an implied shared understanding of what the work entails.</p><p>But two engineers with the same title can be doing fundamentally different jobs depending on where they work. In one organization, an engineer may spend most of their time translating detailed specifications into code, with decisions made elsewhere. In another, that same title may carry responsibility for shaping systems, making tradeoffs, and guiding how a product evolves over time. The title is the same, but the expectations, the scope, and the nature of the work are not.</p><p><a href="https://medium.com/@Toglefritz/code-is-not-the-job-90f9df16b849">In a previous article</a>, I argued that code is not the job. The point was not to diminish the importance of code, but to reframe it as one part of a broader responsibility. Software engineering, in that view, is centered on designing systems that operate under real-world constraints, balancing competing priorities, and making decisions that affect long-term reliability and maintainability. Writing code is necessary, but it is not the defining characteristic of the role.</p><p>That perspective, however, is not universal. In many organizations, engineering is defined in a much narrower way. The responsibility of the engineer is to take a set of requirements or designs and translate them into working software. The decisions have already been made elsewhere. The role is to implement those decisions as accurately and efficiently as possible</p><p>That difference is easy to overlook because it is rarely made explicit. Organizations do not usually define engineering in these terms. Instead, the definition emerges through how decisions are made, who is involved in making them, and where accountability ultimately sits. Over time, that implicit definition becomes the operating model for the team.</p><p>The important point is that this is not just a difference in how work is distributed. It directly shapes the systems that get built. The way an organization defines the role of engineering determines how technical decisions are made, how tradeoffs are evaluated, and how systems respond to change over time. Those factors, in turn, influence the quality, reliability, and longevity of the software itself.</p><p>There are many variations in how engineering can be structured, but most tend to fall into one of two broad definitions. Both are real, both are common; and while they may appear similar at a glance, they lead to very different outcomes.</p><h3>The First Definition: Engineering as Implementation</h3><p>One of the most common ways engineering is defined in practice is far more constrained than the version many of us like to describe. In this model, the primary responsibility of the engineer is to take an existing set of requirements or designs and translate them into working software. The scope of the role is not centered on deciding what should be built or how a system should evolve over time, but on executing against a plan that has already been established.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*I7tmNLqSWw9-kYJhq2AAsg.png" /><figcaption>In the first definition, engineers are part of an essentially linear flow in which decisions are made up front and the engineer is responsible only for implementing those designs.</figcaption></figure><p>That plan may come from a variety of sources. In some organizations, it originates with product management. In others, design teams produce detailed specifications that extend well beyond visual layout into interaction patterns and system behavior. In more mature environments, the inputs may include formalized requirements, acceptance criteria, and pre-defined architectural constraints. Regardless of the source, the defining characteristic is that the core decisions have already been made by the time the work reaches engineering.</p><p>Within that context, the work of the engineer becomes a process of translation. Requirements are interpreted, edge cases are identified, and those ideas are expressed in code that can be executed by a machine. There is still skill involved in doing this well. Correctness matters. Attention to detail matters. The ability to navigate a large codebase and implement changes without introducing regressions is not trivial. In many cases, engineers operating in this model are also responsible for ensuring that their implementations align precisely with the intended behavior, even when that behavior is defined outside of engineering.</p><p>Performance in this role is typically evaluated along dimensions that reflect this focus. How quickly can a set of requirements be implemented? How accurately does the delivered software match the specification? How reliably can changes be made without breaking existing functionality? These are all reasonable measures when the primary objective is faithful execution.</p><p>It is important to be clear about something that often gets lost in these discussions. This model of engineering is not hypothetical, and it is not rare. A significant number of organizations are structured this way, either by design or as a result of how responsibilities have evolved over time. For teams operating under tight deadlines or in highly regulated environments, separating decision-making from implementation can even feel necessary. It creates clear boundaries and, at least in theory, predictable outcomes.</p><p>The tradeoff is that decision-making authority sits somewhere else. Engineers may surface issues or raise concerns, but they are not the ones ultimately responsible for determining the direction of the system. Their role is to carry decisions forward into implementation, not to shape those decisions at their source.</p><p>When engineering is defined this way, it produces a very specific picture of the work. It is structured, bounded, and largely driven by inputs that originate outside of the engineering function. That picture becomes especially important when we start to ask what parts of the role can be automated, and what parts cannot.</p><h3>The Second Definition: Engineering as System Design</h3><p>There is another way to define engineering, and it leads to a very different understanding of the work. In this model, the engineer is not positioned at the end of a pipeline of decisions, but embedded within it. The responsibility is not limited to implementing a plan. It includes helping to determine what that plan should be in the first place.</p><p>Engineers operating in this space participate directly in shaping systems. They evaluate multiple approaches, weigh constraints, and make tradeoffs that rarely have a single correct answer. Questions of performance, scalability, maintainability, and cost are not abstract concerns that show up after implementation. They are central to the decision-making process from the beginning, and they often compete with one another in ways that require careful judgment.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7_A9lYicwzJ1gy1v6hiG0g.png" /><figcaption>The second definition is much more dynamic, in which engineers collaborate with other disciplies to build the system dynamically and iteratively.</figcaption></figure><p>This shifts the nature of the work in a fundamental way. The problem is no longer defined purely by a set of requirements handed down from elsewhere. Instead, the problem itself is often ambiguous, and part of the engineer’s role is to help clarify it. That may involve pushing back on assumptions, identifying risks that are not immediately visible, or proposing alternative approaches that better align with long-term system behavior.</p><p>Accountability follows those decisions. When engineers help shape the system, they are also responsible for how that system performs over time. Reliability, maintainability, and the ability to evolve without accumulating unsustainable complexity are not secondary concerns. They are part of the outcome the engineer is expected to deliver. The consequences of earlier decisions tend to surface later, often under load, at scale, or during periods of change, and those consequences become part of the engineering responsibility.</p><p>Code is still an essential part of this work, but it occupies a different position. It is the mechanism through which decisions are realized, not the primary objective of the role. Writing code remains necessary, but it is not the center of gravity. The more defining aspect is the set of decisions that the code represents and the system behavior that emerges from those decisions over time.</p><p>The distinguishing characteristic of this model is that engineers are treated as decision-makers. They are expected to bring technical perspective into conversations that shape the system, not just to execute on outcomes defined elsewhere. When engineering is defined this way, the role expands beyond implementation into something closer to stewardship of the system itself.</p><h3>How These Definitions Shape Outcomes</h3><p>Once the role is defined, even implicitly, the downstream effects are not subtle. The way engineering is positioned within an organization determines how decisions are made, how systems evolve, and how problems are handled when reality inevitably diverges from the plan. The differences between the two models are not just philosophical. They show up in the software itself.</p><p>Under the first definition, where engineering is primarily an implementation function, systems tend to reflect decisions made outside of engineering. Requirements are translated into code as faithfully as possible, and success is measured by how accurately that translation occurs. This creates a strong bias toward short-term delivery and feature completeness. The goal is to implement what was asked for, on time, and without defects relative to the specification.</p><p>That approach can work, especially in environments where requirements are stable and well-understood. The challenge is that software systems rarely operate under those conditions for long. As complexity grows and edge cases emerge, the separation between decision-making and implementation starts to matter. Tradeoffs that were not fully explored earlier begin to surface in the form of performance issues, brittle abstractions, or difficulty making changes without unintended side effects. Technical debt accumulates not necessarily because engineers are careless, but because the decisions that drive the system were made without full visibility into their long-term impact.</p><p>When those issues arise, engineers often have limited ability to correct course. The same structure that separates them from decision-making on the front end also limits their influence when problems become visible. Changes require revisiting the same external decision-making processes, which can slow down or prevent necessary adjustments. Over time, this creates systems that are increasingly difficult to evolve, even if they were delivered efficiently at the outset.</p><p>Under the second definition, the system tends to reflect a different kind of process. Because engineers are involved in shaping decisions, technical and business considerations are evaluated together rather than sequentially. Tradeoffs around scalability, maintainability, and cost are not deferred until after implementation. They are part of the initial design of the system.</p><p>This does not eliminate complexity, but it changes how that complexity is managed. Constraints are more likely to be surfaced early, when they can still influence the direction of the system. Decisions are made with a clearer understanding of their downstream effects, which reduces the likelihood of large, unexpected issues emerging later. When those issues do occur, engineers are in a position to respond, because they have both the context and the authority to adjust the system as needed.</p><p>The result is not necessarily a perfect system, but a more adaptable one. Systems built under this model tend to evolve more deliberately, with changes informed by both technical realities and business needs. Engineers are able to revisit earlier decisions, refine them, and guide the system through periods of growth and change without accumulating the same level of friction.</p><p>It is important to acknowledge that neither model guarantees success or failure. There are organizations operating under both definitions that deliver high-quality products, and others that struggle. The difference is in the default trajectory. One model tends to optimize for execution against a predefined plan, often at the expense of long-term flexibility. The other aligns decision-making with implementation, which makes it easier to manage complexity as the system evolves.</p><p>Over time, those differences compound. The way engineering is defined at the outset quietly shapes how the system behaves months or years later, long after the original decisions have been made.</p><h3>The Tradeoff Organizations Are Making (Whether They Realize It or Not)</h3><p>Most organizations do not set out to define engineering in explicit terms, but the structure they choose makes that definition unavoidable. When engineering is positioned primarily as an implementation function, the underlying priorities are usually control, predictability, and speed. Decisions are centralized, plans are established up front, and execution is expected to follow a defined path. That model can create clarity and momentum, especially in the short term.</p><p>Shifting toward the second definition reflects a different set of priorities. It assumes that the complexity of software systems cannot be fully managed through upfront specification alone, and that technical expertise needs to be part of the decision-making process. This model places more emphasis on judgment, tradeoffs, and the ability to adapt as new information emerges. It is less about enforcing a plan and more about navigating uncertainty.</p><p>The important point is that this is not just a question of how work is distributed. Organizations are making a deeper choice about how decisions get made and who is responsible for the results of those decisions. That choice shapes not only the role of the engineer, but the behavior of the system over time.</p><h3>A Clear Position</h3><p>If the goal is to build systems that hold up over time, the second definition is the more effective model. Not because it is more idealistic, but because it aligns decision-making with accountability in a way that reflects how software actually behaves in the real world.</p><p><strong>Software systems do not fail because code was typed incorrectly. They fail because of decisions.</strong> Decisions about how data flows through the system, how components are coupled, how performance is traded against cost, and how the system is expected to evolve under changing requirements. Those decisions often look reasonable in isolation, especially early on. Their impact only becomes visible later, when the system is under load, when new features are introduced, or when assumptions no longer hold.</p><p>When engineering is treated primarily as an implementation function, there is a structural gap between the people making those decisions and the people responsible for living with their consequences. That gap does not eliminate responsibility, but it diffuses it. Engineers are expected to deliver working software, but not necessarily to shape the decisions that determine whether that software will remain viable over time. When problems emerge, they are often addressed reactively, within the constraints of decisions that are difficult to revisit.</p><p>The second model closes that gap. By involving engineers directly in the decision-making process, it ties responsibility for implementation to responsibility for outcomes. <strong>The same people who write the code are also accountable for how the system behaves as it grows and changes.</strong> That does not guarantee perfect decisions, but it does create a feedback loop where decisions are informed by the realities of implementation, and implementation is guided by an understanding of long-term consequences.</p><p>This is a practical advantage, not a philosophical one. Systems that are designed with an awareness of their constraints tend to degrade more gracefully under pressure. They are easier to extend, easier to reason about, and more resilient when assumptions change. When issues arise, they can be addressed by people who understand both the intent behind the system and the tradeoffs that shaped it.</p><p>None of this suggests that implementation-focused roles are without value. They are necessary, and in many contexts they are the most efficient way to deliver defined functionality. But when that model becomes the dominant definition of engineering, it limits an organization’s ability to manage complexity over time.</p><p><strong>If the objective is long-term system quality, the deciding factor is not how efficiently code is produced.</strong> It is how well decisions are made, and whether the people responsible for those decisions are equipped to understand their consequences. The second definition of engineering is more effective because it treats those responsibilities as inseparable.</p><h3>The Title Is the Same, the Job Is Not</h3><p>“Software engineer” is a familiar title, but it does not describe a single, consistent role. It is a label applied to very different kinds of work, depending on how an organization chooses to structure decision-making and responsibility. Two engineers can share the same title and operate under entirely different expectations, with very different levels of influence over the systems they build.</p><p>That difference is easy to ignore because it is rarely stated outright. It shows up indirectly, in who makes decisions, how tradeoffs are evaluated, and where accountability ultimately resides. Over time, those patterns define the role more clearly than any job description.</p><p>If the goal is to build systems that remain reliable, adaptable, and maintainable over the long term, the definition of engineering cannot be left to emerge by accident. It needs to be intentional. Organizations have to decide whether engineers are there to implement decisions or to participate in making them, and they have to align responsibility and accountability accordingly.</p><p>That choice does not just shape the experience of the engineers. It shapes the behavior of the system itself. The quality of a software system is not only a reflection of how well it was implemented. It is a reflection of the decisions that guided its design, and of the people who were empowered to make those decisions.</p><p>The title may be the same, but the job is not. And the way we choose to define that job quietly determines everything that follows.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=45939b2fef14" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Fast Code, Slow Integration]]></title>
            <link>https://medium.com/@Toglefritz/fast-code-slow-integration-0e9e2b63668b?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/0e9e2b63668b</guid>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Tue, 21 Apr 2026 22:38:41 GMT</pubDate>
            <atom:updated>2026-04-21T22:38:41.177Z</atom:updated>
            <content:encoded><![CDATA[<h4>Using steering documents to turn generic output into code that belongs in your project</h4><p>The primary challenge when using AI-assisted development is not generating code, but making that code align with the standards of a real system.</p><p><strong>The output produced by AI tools is often close enough to be useful, but rarely close enough to use as-is</strong>. When that code is introduced into an existing project, it needs to be adjusted before it fits. Naming does not quite match established conventions. Structure is slightly out of step with how similar problems are solved elsewhere in the codebase. Comments describe behavior, but not in the way the rest of the system communicates intent.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7fB9JRCxfuL0fZDTxxnBIQ.png" /><figcaption>Code generated by AI systems can often feel wrong and out of place in a larger project.</figcaption></figure><p>None of these issues are particularly difficult to fix, but they are consistent. Each piece of generated code requires a round of refinement before it can be considered part of the system.</p><p>That refinement is not especially interesting work. It is mostly mechanical, tedious, and boring. Rename a few things. Adjust the structure. Rewrite comments. Align it with patterns that already exist. It is the kind of work that engineers would prefer to avoid, and it directly offsets some of the productivity gains that AI tools are meant to provide.</p><p>Every project is shaped by a set of standards. Some are explicit, such as formatting rules or architectural boundaries. Others are implicit, reflected in how engineers name things, structure code, and explain decisions. These standards are what make a codebase coherent. They allow multiple contributors to work within the same system without it feeling fragmented.</p><p><strong>AI systems do not have access to those standards unless they are made explicit</strong>. As a result, they produce output that is valid, but not integrated.</p><p>This article focuses on that gap. Not how to generate code, but how to reduce the amount of refinement required by ensuring that generated output already fits the system to which it is being added.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7ppZwPKQkG-0nu7HdCD3Cw.png" /><figcaption>Fixing the same issues in AI generated code over and over and over is simply not an engaging thing to do.</figcaption></figure><h3>Why This Matters More Than It Seems</h3><p>The standards that shape a codebase are more than a checklist of rules. They define how decisions are expressed in code.</p><p>At the team level, this includes things like naming conventions, architectural boundaries, and documentation patterns. These are usually visible if you look closely enough. But a large portion of what makes a system feel consistent is not written down in a single place. It is reflected in how similar problems are approached, how responsibilities are divided, and how intent is communicated through code. A lot of the stylistic and architectural patterns in a codebase are created through in-person discussions among engineers and during pair programming sessions.</p><p>Over time, this creates a kind of internal language and culture, a set of expectations about how things should look and behave that allows new code to fit naturally into what already exists. <strong>AI-generated code does not operate within that language.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1QZRZ3G-2CJDXUsYiBvTfA.png" /><figcaption>AI generated output often just feels like it doesn’t belong in a codebase.</figcaption></figure><p>AI systems produce implementations that are reasonable in isolation, but unaware of the specific patterns that have been established in the system. This shows up in ways that are easy to recognize but difficult to describe precisely. A function might solve the right problem, but do so using a structure that is inconsistent with the surrounding code. A class might introduce an extra layer of abstraction that the rest of the system avoids. Documentation might be technically correct, but written in a tone or structure that does not match anything else in the project.</p><p>These are not violations of correctness necessarily. Intead, they are deviations from consistency. And the more often generated code diverges from established patterns, the more time is spent interpreting, adjusting, and reconciling it with the rest of the system. Review cycles become heavier. Changes that should be straightforward require more discussion. Engineers become more cautious about trusting generated output, not because it is incorrect, but because it is unpredictable in how it fits.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*v8XaU9TK3oKAmfWGee0ffQ.png" /><figcaption>It is a lot of work to patch up and fix all the inconsitencies created by AI tooling.</figcaption></figure><p><strong>Generated code already requires adjustment before it fits into a real system</strong>. Even when the implementation is correct, it needs to be brought into alignment with the conventions, structure, and tone of the codebase. That work is part of maintaining a coherent system, and it would exist regardless of how the code was produced. Comments are rewritten to reflect the tone of the codebase. Structure is adjusted to better match how similar problems are solved elsewhere. Naming is iterated on until it feels native to the system.</p><p>In practice, though, the effort often goes beyond pure alignment out of professionalism. The use of AI in development is still unsettled, and in many environments it carries a degree of stigma. Engineers are aware that generated code can stand out, and that it may be judged differently during review. As a result, the refinement process expands. The code is not only updated to match established patterns, <strong>it is also shaped to feel less identifiable as generated output</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9FXYqS8l4nRKN8l5aMJ9_w.png" /><figcaption>Engineers often spend a lot of time erasing the footprints of AI output in their codebases because of the stigma that surrounds AI technologies in many contexts.</figcaption></figure><p>AI is effective at producing implementations. It does not, by default, account for the conventions that make those implementations feel like part of a cohesive system.</p><h3>Steering Documents as a Missing Layer</h3><p>The gap between generation and integration exists because the standards that shape a system are rarely made explicit in a way that can be reused.</p><p>Engineers learn those standards over time. Engineers have memory — not like computer memory but actual human memory — that they build over time as they gain experience. That process is cumulative. It builds a mental model of how the system works and how new code should fit into it.</p><p>AI systems do not have that advantage.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*h6T9B1FGRrG8sdmCUh7d6Q.png" /><figcaption>AI agents are like if a goldfish got really, really good at generating text but still forgot everything past a 30-second window.</figcaption></figure><p>Each interaction starts from a relatively blank slate. Even when some context is provided, it is limited to what is included in that specific request, or, at best, within the past half a dozen requests. There is no continuity from one session to the next. There is no accumulated understanding of how this particular codebase tends to solve problems, or how its conventions differ from the general patterns on which the model was trained.</p><p><strong>This is where steering documents become useful. </strong>A steering document is a way of making those implicit standards explicit and persistent. It defines how code should be written in the context of a specific system. That includes structural decisions, naming conventions, documentation style, and the boundaries that shape how components interact. These are not instructions for solving a single problem. They are constraints that apply across problems.</p><p>A prompt is temporary. It exists for the duration of a single interaction and then disappears. It can guide the generation of a specific piece of code, but it does not carry forward. The next time the tool is used, the same guidance has to be restated or inferred again.</p><p>A steering document, by contrast, is part of the project. It can be referenced consistently, reused across sessions, and updated as the system evolves. It gives the AI system a stable point of reference for how code in a project is expected to look and behave.</p><p>In practice, this changes the role of AI in the workflow. Instead of generating code that must be reshaped after the fact, the goal becomes generating code that already reflects the decisions that define the codebase.</p><h3>Introducing the System</h3><p>The approach implied so far depends on one key idea: <strong>the standards that shape a system need to be made explicit in a form that can be reused</strong>.</p><p><a href="https://github.com/Toglefritz/ai_steering">GitHub - Toglefritz/ai_steering: A central, version-controlled repository for AI agent steering documents.</a></p><p>The <a href="https://github.com/Toglefritz/ai_steering"><strong>ai_steering</strong></a> project is built around that idea, but it is not simply a collection of documents. It is a system for managing how those documents are applied across projects. At its core, it provides a centralized, version-controlled repository of steering documents, but the more important piece is the tooling that allows those documents to be selected, installed, and kept in sync over time.</p><p>In most codebases, standards like these exist, but they are distributed. Some are reflected in the code itself. Others show up in past pull requests, review comments, or team habits. When they are formalized, they are often copied into individual repositories as Markdown files. From that point forward, they begin to drift. Updates made in one place do not propagate to others, and over time, the idea of a shared standard becomes less meaningful.</p><p>The <em>ai_steering</em> tool is designed to avoid that outcome by treating steering documents as something that can be deployed and maintained, rather than copied.</p><p>The repository acts as a single source of truth, and the CLI provides a way to apply that source to a specific project. During setup, you select the target project, choose your IDE, and then choose which documents are relevant. The tool handles placing those documents in the correct location for that environment, whether that means a directory of rules or a single aggregated file.</p><p>At the same time, it writes a manifest that records what was installed. This manifest is what makes the system practical over time. When the steering documents in the central repository are updated, those changes can be pushed back into any project that uses them. Running a sync operation reads the manifest and re-applies the latest versions of the selected documents. This allows standards to evolve without requiring manual updates across every codebase that depends on them.</p><p>Not every document is relevant to every project, and the system accounts for that. A steering library can include documents that are specific to a particular language or framework alongside more general guidance. A Flutter-specific document can live next to a writing style guide or documentation standard, but only the relevant subset needs to be installed in a given project. Each project ends up with a tailored set of steering documents, while still remaining connected to the same central source.</p><p>The documents themselves are not introducing new ideas. They capture decisions that engineers already make, often without writing them down in one place. How code is structured, how responsibilities are divided, how documentation is written, and how tools are used within the workflow. These patterns already exist in a mature codebase, but they are rarely collected in a way that makes them reusable.</p><p>This system makes those decisions explicit and durable. Instead of copying guidance from project to project or restating it in prompts, the same set of standards can be applied wherever they are needed and updated in one place when they change.</p><h3>Using the Tool</h3><h4>Creating Steering Documents</h4><p>The CLI is designed to remove friction from the process of managing steering documents and to make updating steering documents across projects as seamless as possible.</p><p>The entry point is the init command. This is an interactive flow that walks through three decisions:</p><ul><li>Where the target project lives</li><li>Which IDE or environment the project uses</li><li>Which steering documents should be applied</li></ul><p>The first step is selecting the project location. This is the directory into which the steering documents should be inserted.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lMMqBouSNZhm5N34wxHJlQ.png" /><figcaption>First, select the directory for your project. This is where the steering documents will be created.</figcaption></figure><p>The next step is to select the IDE that will be used for the project. The IDE selection matters because different tools expect steering in different formats and locations. Some rely on a directory of rule files. Others expect a single aggregated document. The CLI handles those differences so the documents end up where the agent will actually read them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Pnv4Nx3RB85glPOAeUL_hA.png" /><figcaption>Second, select the IDE you will be using. This allows the tool to create the steering documents with the correct structure and organization.</figcaption></figure><p>Next up, the tool will present a list of steering documents from which you can choose. The document selection step is where the system becomes useful. Instead of copying a generic set of guidelines into every repository, you choose the subset that reflects how that specific project should operate. A backend service, a Flutter app, and a documentation-heavy repo can all draw from the same source while ending up with different installed guidance.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1pOw2NP1ZCZMyxrBi2pITw.png" /><figcaption>Third, select which steering documents are needed for the project.</figcaption></figure><p>Once this process completes, the tool writes the selected documents into the project and creates a .steering-manifest.json file. That file is the contract between the project and the central repository.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7CRztqKrCPSQReArVYZTSA.png" /><figcaption>The tool creates the selected steering documents in the target directory, along with a manifest file.</figcaption></figure><h4>Syncing Changes</h4><p>Over time, the steering documents evolve. Maybe a coding standard is refined. Maybe a new pattern replaces an old one. Maybe a new AI model exhibits new behaviors and requires updated instructions. The question is how those changes reach existing projects.</p><p>That is the role of the sync command.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VSe1tzCvPRp-1ta22NQVvw.png" /><figcaption>The `sync` command can be used to pull changes to the steering documents into a project.</figcaption></figure><p>Rather than asking developers to manually track changes and re-copy files, the CLI reads the manifest and re-applies the current versions of the selected documents. The project stays aligned with the source of truth without needing to re-run the full setup process.</p><p>This is the difference between a static document and a maintained system. The documents are no longer snapshots. They are dependencies.</p><h4>Adjusting a Project</h4><p>Projects are not static either. As they evolve, the set of relevant steering documents can change.</p><p>The select command allows the installed set of documents to be modified without starting over. You can add new documents, remove ones that are no longer relevant, or adjust the balance between general guidance and project-specific rules.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CmWRjMpnTakfPAIrrPS3hg.png" /><figcaption>The `select` command can be used to add new steering documents to a project.</figcaption></figure><p>This keeps the system flexible without breaking the connection to the central repository.</p><h3>Parting Thoughts</h3><p>AI can produce working code quickly, but that code still has to be shaped to fit a real system. The friction comes from the gap between what the model knows and how a specific codebase actually works in practice. That gap shows up as small, repetitive adjustments. At its core, this is a context problem. A codebase is not just a collection of files, it is a set of decisions that have accumulated over time. Those decisions define how problems are approached and how solutions are expressed. Engineers internalize that context gradually through experience. AI systems do not. Without access to it, they produce code that is valid in isolation (ideally) but misaligned with the system to which it is being added.</p><p>Steering documents address that gap by making those decisions explicit and reusable. They do not make the model smarter, but they make the system more legible. Once the standards that shape a codebase are written down and consistently applied, generated code starts closer to where it needs to be. The refinement step does not disappear, but it becomes smaller, more predictable, and less of a constant tax on the workflow.</p><p>The <a href="https://github.com/Toglefritz/ai_steering"><strong>ai_steering</strong></a> tool exists to make that approach sustainable. Without some way to manage and distribute these documents, they fall back into the same pattern as any other piece of documentation. They are copied, modified, and eventually drift. Treating them as something that can be installed, tracked, and updated changes that dynamic. They become part of the system itself, evolving in one place and propagating outward to the projects that depend on them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cDcCf3HEFdXASdQd2OwESA.png" /><figcaption>With the correct steering documents and a way to manage them, AI agents and human engineers can work together in perfect harmony. Or at least with less friction.</figcaption></figure><p>The goal is not to generate more code. The goal is to produce code that already belongs to the system in which it lives.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0e9e2b63668b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Code Is Not the Job]]></title>
            <link>https://medium.com/@Toglefritz/code-is-not-the-job-90f9df16b849?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/90f9df16b849</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Tue, 20 Jan 2026 00:58:00 GMT</pubDate>
            <atom:updated>2026-02-02T19:27:17.811Z</atom:updated>
            <content:encoded><![CDATA[<h4><strong><em>Why does AI-generated code keep getting mistaken for software engineering?</em></strong></h4><p>Conversations about AI-assisted software development tend to collapse into two very loud positions. One treats AI as nothing more than a hype bubble built to impress investors, with no real value for people building serious software. The other leaps to the opposite conclusion, insisting that the ability to generate working code is proof that software engineering itself is on the verge of extinction. These extremes make for dramatic headlines, and they both miss the underlying point.</p><figure><img alt="Two people argue about whether “AI is worthless” or if “AI will replace all of you.” In the background, a software engineer sits quietly, creating software products." src="https://cdn-images-1.medium.com/max/1024/1*QlGBJH5_8GeKrndOug80tw.png" /><figcaption>It’s the engineer in the middle who has the correct view in this debate.</figcaption></figure><p>What AI has actually done is expose a misunderstanding that has existed for as long as software has been written: <strong>the belief that coding and software engineering are the same thing</strong>. They are not. Code is an artifact. Engineering is a discipline. When AI systems produce code quickly and convincingly, it becomes tempting to assume that the hard part of software creation has been solved. In reality, the part that AI accelerates is the part that was never the core of the job in the first place.</p><blockquote><em>The leap from “AI can generate code” to “software engineering is obsolete” is not optimism, it’s a category error.</em></blockquote><p>This article is not an argument for or against AI. It is an attempt to clarify what software engineering actually is and, just as importantly, what it is not. AI tools can be powerful, useful, and occasionally delightful. They can also be unreliable, opaque, and frustrating. But none of those traits are especially novel. We have always worked with tools that amplify our abilities without replacing our judgment. AI simply makes the distinction harder to ignore.</p><figure><img alt="A circular saw wonders if it is a woodworker because it can cut wood. This is not the job of a woodworker and the saw is not a woodworker." src="https://cdn-images-1.medium.com/max/1024/1*S8RdR9Fly0txJMSAr-4LiQ.png" /><figcaption>A circular saw allows people to cut wood far faster than even the strongest person with a manual saw. That does not mean that a circular saw will replace woodworkers. The important part is actually the measurements on the board, the cutting plan on the wall, and the experience and skill needed to operate the tool and build the project.</figcaption></figure><p>Software engineering has never been about fluency in a programming language or the mechanical act of producing code. It is about making decisions under constraints: decisions about performance, security, maintainability, risk, cost, and long-term ownership. Those decisions live above the code. They are informed by context, history, organizational goals, and an evolving understanding of the system as a whole. Code is how those decisions are expressed, not where they are made.</p><p>The confusion arises when successful code generation is mistaken for successful engineering. <strong>A working artifact is not the same thing as a resilient system</strong>. Shipping something is not the same thing as owning it. AI is very good at helping people create artifacts. Software engineers are hired to take responsibility for systems that must survive real-world conditions over time.</p><figure><img alt="A judge in a courtroom asks the plaintiff’s lawyer a question. But there is no lawyer, just a piece of paper generated by AI." src="https://cdn-images-1.medium.com/max/1024/1*EZD8uHPfwPyzuXhbDv2Qvg.png" /><figcaption>The same thing is happening to lawyers. Just because AI can generate legal text does not mean it can balance risk exposure against business goals, interpret unspoken intent, or be accountable in court.</figcaption></figure><p>That distinction is the focus of this article. Not whether AI can write code — it clearly can — but why that fact tells us far less about the future of software engineering than many people assume.</p><h3>Software Engineering Is Not a Language Problem</h3><p>A recurring theme in this article is that <strong>software engineering is not primarily about writing lines of code</strong>. Code is simply the medium we use to express decisions. The real work happens in the engineer’s internal model of the system. This is a model that AI does not possess and cannot maintain. This section explores that contrast and why it matters.</p><h4>How Human Engineers Think</h4><p>Human engineers do not think in terms of syntax. They work with a mental model made of structures, relationships, flows, constraints, risks, and goals. It is not a code-first mindset. It is a system-first way of reasoning.</p><p>Navigating a large codebase feels closer to navigating a familiar city than to typing instructions into a text editor. Engineers can move from one part of the system to another because they understand how everything fits together in an almost tactile way that goes far beyond just reading code files. Engineers know where the traffic tends to form because they understand how data moves. They know which parts of the system influence each other, which long-standing decisions create bottlenecks, and which parts carry historical context that cannot be disturbed without consequences. This internal map is not written down anywhere. It evolves continuously.</p><figure><img alt="References to entities shown as if on the map of a city, representing the way software engineers form mental models of codebases while they work." src="https://cdn-images-1.medium.com/max/1024/1*WMBGCtucnaL4-KlKUcEnvg.png" /><figcaption>Software engineers think about codebases in a physical, tactile way. They don’t show up to work each morning and re-read each file in the codebase to understand it.</figcaption></figure><p>This ability to hold a living model of the system is what gives engineers their real advantage. They can foresee how a small change in one corner will affect performance, reliability, user experience, and even team workflows months down the line.</p><h4>What AI Actually Does</h4><p>AI systems, even very capable ones, do not maintain anything like that persistent internal map. They do not navigate a system. They generate text. Each response is a fresh attempt that depends only on a limited window of context. There is no durable memory of project history, architectural decisions, past tradeoffs, or organizational priorities.</p><p>Large language models operate in isolated fragments. They do not carry forward a stable sense of state. They can improve local areas of a problem by suggesting a function, transforming a file, summarizing a diff, or outlining an approach. They cannot maintain the continuous mental model that real engineering requires.</p><h4>Why This Does Not Make AI Useless, It Makes It a Tool</h4><p>These limitations do not diminish the value of AI. They define where AI fits in the engineering workflow. You would not expect your IDE to understand your company’s quarterly goals. You would not expect Git to write a product requirements document. Likewise, you should not expect an AI system to design your architecture or preserve conceptual continuity across a long-lived codebase.</p><figure><img alt="A software engineer thinks about the best “tool” for their software engineering task. All of the “tools” are logos for common software engineering tools." src="https://cdn-images-1.medium.com/max/1024/1*ed0oHicvY6UgV7vnKUv2Lg.png" /><figcaption>AI agents are just one tool out of many in the software engineer’s toolbox.</figcaption></figure><p>You <em>can</em>, however, expect targeted value. You expect your IDE to accelerate specific tasks. You expect Git to protect your work and make collaboration possible. In the same way, you can expect an AI system to assist with focused, well-scoped work: generating boilerplate, rewriting patterns, exploring alternatives, or helping you reason through a narrow technical problem.</p><p>The right way to think about AI in engineering is not as a replacement, nor as something irrelevant. It is a tool, one that becomes powerful only when human judgment determines <em>where</em> it is applied, <em>why</em> it is being used, and <em>who</em> is responsible for the outcome.</p><p>The distinction between producing code and taking responsibility for a system is where most of the current confusion begins.</p><h3>When Code Generation Gets Mistaken for Engineering</h3><p>A recent and widely discussed example of this confusion appeared on the podcast <a href="https://www.nytimes.com/column/hard-fork"><strong>Hard Fork</strong></a>, hosted by <a href="https://kevinroose.com/"><strong>Kevin Roose</strong></a> and <a href="https://cnewton.org/"><strong>Casey Newton</strong></a>. In a recent episode, the hosts described using AI tools, specifically Claude Code,<strong> </strong>to build new personal portfolio websites for themselves.</p><p>This is, unambiguously, a success story.</p><p>Kevin and Casey were able to create custom sites that reflect their personal brands and personalities, iterate quickly on design and content, and dramatically reduce ongoing hosting and maintenance costs compared to their previous solutions. Just as importantly, they did so without needing prior software engineering experience. That outcome is not only reasonable, it is exactly the kind of problem modern AI tools are well suited to solve.</p><p>This is what effective tooling looks like: lowering barriers, expanding creative control, and making small, self-contained projects accessible to people who would otherwise need outside help.</p><p>Where the confusion begins is not with the success of these portfolio sites, but with how that success was framed. At one point in the episode, the experience is summarized this way:</p><blockquote><em>“I was able to, in a matter of hours, build and release a working software product. […] I have no idea how any of this works. […] And yet I was able to conduct an act of software engineering that now other people are downloading and using for themselves.”</em></blockquote><p>Building a personal portfolio site on a static hosting platform is almost entirely unrelated to enterprise software engineering. The two activities share a surface resemblance, both involve code, but they differ in every dimension that actually defines engineering work.</p><p>Kevin and Casey’s portfolio sites do not need to ladder up to business KPIs or drive shareholder value. They did not require cross-functional planning sessions, legal review, threat modeling, or formal requirements gathering in tools like Jama. There was no need to design for multi-region failover, data residency constraints, or long-term operational ownership. If either host were to step away from their site tomorrow, the consequences would be minimal. If two million people happened to visit the site at once, the worst-case outcome would likely be a temporary outage, not an incident review.</p><p>None of this diminishes the accomplishment. It clarifies it.</p><p>What AI enabled in this case was the creation of an artifact that met a clearly bounded personal need. That is a win. But software engineers are hired for a very different reason. They are paid not to produce code, but to make decisions about systems that must operate under uncertainty, scale under load, comply with legal and security constraints, and remain understandable and maintainable long after their original authors have moved on.</p><blockquote>Releasing a software product without understanding how it works is not an act of software engineering; it is the absence of it.</blockquote><p>This is why the quoted claim is internally contradictory. Releasing a software product without understanding how it works is not an act of software engineering; it is the absence of it. In any serious organizational context, ignorance of system behavior is not a badge of innovation, it is negligence. If a CTO of a public company shipped a product that resulted in a massive data breach and then admitted that the engineering team had “no idea how any of it works,” the outcome would not be admiration for speed. It would be lawsuits, termination, and potentially jail time.</p><p>The danger is not that AI tools can generate working software. They clearly can. The danger is mistaking that capability for evidence that the discipline of software engineering, responsibility, judgment, and long-term ownership, has somehow been automated away.</p><p>The Hard Fork example doesn’t signal the end of software engineering. It highlights, in a very public way, the difference between <em>making something that works</em> and <em>being accountable for a system that must continue to work</em>.</p><h3>The Job Was Never to Write Code</h3><p>AI systems can generate code. They can do so quickly, convincingly, and often correctly. What they produce are artifacts: files, functions, pages, and prototypes that work in isolation. That capability is real, and it is useful. But it is not the job of a software engineer.</p><p>Software engineering is about outcomes, not outputs. It is about whether a system remains secure under pressure, understandable over time, compliant with evolving constraints, and resilient in the face of growth, failure, and change. It is the difference between local correctness and systemic reliability. Between something that runs and something that can be trusted.</p><p>The value of an engineer does not come from typing speed or language fluency. It comes from judgment: deciding which tradeoffs to make, which risks to accept, which complexity to absorb, and which to avoid. It comes from continuity, ensuring that systems can outlive their original authors, and from accountability for the consequences of those decisions.</p><p>AI can assist in many parts of this process. It can accelerate work, explore alternatives, and reduce friction. What it cannot do is take responsibility. It cannot own a system, defend its design, or be accountable when reality pushes back.</p><p>The job of a software engineer has never been to write code. It is to design, steward, and sustain systems that support the long-term prosperity of an organization. Code is just how those decisions are expressed.</p><p><strong>AI can produce code. Software engineers produce systems that survive contact with reality.</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=90f9df16b849" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building Rich Notifications on Android]]></title>
            <link>https://medium.com/@Toglefritz/building-rich-notifications-on-android-6c1d534bbeb0?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/6c1d534bbeb0</guid>
            <category><![CDATA[mobile-app-development]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[flutter]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Fri, 12 Dec 2025 00:04:16 GMT</pubDate>
            <atom:updated>2025-12-12T00:07:11.133Z</atom:updated>
            <content:encoded><![CDATA[<h4>Creating polished, media-enhanced notifications on Android using Flutter and native tooling</h4><h3>💬 Introduction</h3><p>In the earlier parts of this series, we explored how clean, structured FCM payloads form the foundation for meaningful notifications and how Apple platforms rely on extensions to enrich and render those experiences. Now we turn our attention to Android, an ecosystem with its own strengths, conventions, and tools for creating polished, interactive, and media-rich notifications.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FDavYs1qvfB0%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DDavYs1qvfB0&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FDavYs1qvfB0%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/04cc9fff40ebc294cb2d964eca918022/href">https://medium.com/media/04cc9fff40ebc294cb2d964eca918022/href</a></iframe><p>Unlike Apple’s platforms, Android places nearly the entire workflow inside your app process. When an FCM message arrives, your background handler or messaging service receives the payload directly, constructs a notification using the system’s notification APIs, and hands it off to the Android NotificationManager for display.</p><figure><img alt="An example of a rich push notification experience on Android." src="https://cdn-images-1.medium.com/max/1024/1*1rvoLX1hSTyhN6ociimT3g.png" /><figcaption>Android supports rich notifications with custom titles and messages, multimedia, and custom actions.</figcaption></figure><p>This workflow gives developers a remarkable amount of flexibility. Rich notifications on Android can include remote images, progress indicators, grouped updates, inline action buttons, media-style controls, and even fully customized layouts built with RemoteViews. Many of the experiential elements we implemented on Apple platforms, like dynamic information, media attachments, or action control, can be rendered with equal sophistication on Android, just using a different set of primitives.</p><p>In this article, you’ll learn how to interpret structured payloads, fetch images, build advanced NotificationCompat layouts, wire up action handlers, and route user interactions back into Flutter. By the end, you’ll be able to recreate rich, dynamic push notification experiences on Android within a Flutter project.</p><h4>Series Table of Contents</h4><p>Part 1: <a href="https://medium.com/@Toglefritz/better-user-experiences-with-rich-notifications-in-flutter-3ed2d003d26f"><strong>Introduction + Architecture</strong></a></p><p>Part 2: <a href="https://medium.com/@Toglefritz/designing-fcm-payloads-for-rich-notifications-in-flutter-ac1bfba5b42c"><strong>Designing Notification Payloads</strong> (Cloud Side)</a></p><p>Part 3: <a href="https://medium.com/@Toglefritz/building-rich-notifications-on-ios-macos-f84025f396a4"><strong>iOS/macOS</strong></a></p><p>Part 4: <strong>Android </strong><em>👈 You are here</em></p><h3>📦 Android Notification Architecture for Flutter Developers</h3><p>Before diving into custom layouts or background enrichment, it helps to understand how Android structures its notification system. Android centralizes almost all of that work inside your app. Once you see how the pieces fit together, the rest of the workflow becomes much easier to reason about.</p><h4>Notifications in the Android System</h4><p>On Android, the system UI (often called the “notification shade”) is the final destination for all notifications your app posts. Everything flows through the NotificationManager, which is responsible for displaying notifications, updating them, grouping them, and respecting user preferences.</p><h4>Notification Channels</h4><p>Beginning with Android 8.0 (API 26), every notification must belong to a notification channel. This requirement exists so users can manage notification behavior at a more granular level. The can decide which categories should alert loudly and which should remain quiet.</p><p>Each channel defines:</p><ul><li><strong>Importance level</strong> (determines whether a notification appears silently or as a heads-up alert)</li><li><strong>Sound and vibration patterns</strong></li><li><strong>Visibility settings</strong></li><li><strong>Badge behavior</strong></li></ul><p>Because users can change these settings at any time, channels should be treated as stable identifiers. Create them once, keep their IDs consistent, and design your notification categories with user experience in mind.</p><h4>Collapsed vs. Expanded Views</h4><p>Notifications render differently depending on how much screen space the user gives them:</p><ul><li><strong>Collapsed</strong>: a compact, one-line or two-line preview</li><li><strong>Expanded (“big”) view</strong>: more room for images, long text, progress bars, or additional controls</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ChQysjgwu_ogz98UeX0PiA.png" /><figcaption>Notifications on Android can display in collapsed (left) or expanded (right) sizes.</figcaption></figure><p>Most rich notification features, such as a large image or multiple lines of text, appear only in the expanded layout using NotificationCompat styles (e.g., BigPictureStyle, BigTextStyle).</p><h3>🔥 How FCM Delivers Data to an Android + Flutter App</h3><p>Firebase Cloud Messaging (FCM) delivers messages to your Android app in two broad categories: <strong>notification messages</strong> and <strong>data messages</strong>. This article focuses on data messages because they give you complete control over how your notification looks, behaves, and is enriched.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_gOcsn1BexFNgSb1I7kKRQ.png" /></figure><h4>Notification Messages vs. Data Messages</h4><ul><li><strong>Notification messages: </strong>Let the system draw a default notification using fields like title and body. Your app may not receive these messages if it is in the background or killed.</li><li><strong>Data messages: </strong>Delivered directly to your app, regardless of whether it’s in the foreground, background, or terminated. Ideal for building rich, dynamic notifications.</li></ul><p>Because data messages give you both flexibility and reliability, they are the recommended choice when designing custom notification flows.</p><h3>📪 How Android Handles “Extension-Like” Notification Logic</h3><p>Android does not use separate extension targets or sandboxed processes to prepare or display rich notifications. Instead, everything related to notification enrichment and UI construction happens inside your app itself, either in Dart code or in a lightweight Android service. This model is simpler to set up than the actual extensions used on Apple platforms but still offers a large amount of flexibility for building advanced notification experiences.</p><h4>Where Notification Logic Runs on Android</h4><p>When a data message arrives from FCM, Android delivers it directly to one of two places:</p><ol><li><strong>A Dart background handler</strong> (provided by <em>firebase_messaging</em>)<br>○ Runs inside a background isolate<br>○ Ideal for most apps<br>○ Allows you to parse the payload, download small media files, build the notification content, and display it</li><li><strong>A native FirebaseMessagingService</strong> (written in Kotlin or Java)<br>○ Runs even when the Flutter engine is not initialized<br>○ Useful for more advanced behaviors like large-image downloading, custom background work, or integration with WorkManager</li></ol><p>Both entry points give you access to the entire FCM payload, which makes them suitable for enriching notifications before they’re displayed.</p><h4>Preparing the Notification Before Display</h4><p>Because there are no external extension bundles, all pre-display work happens in your app’s background execution path. Typical tasks include:</p><ul><li>Extracting values from the payload</li><li>Computing dynamic text (e.g., elapsed time or progress)</li><li>Downloading images to be shown in the expanded view</li><li>Building structured notification content with NotificationCompat</li><li>Selecting the appropriate style (BigPicture, BigText, Messaging, etc.)</li><li>Attaching action buttons and deep links</li></ul><p>Once this preparation is complete, you create the final NotificationCompat.Builder and post it through NotificationManager, which displays it in the system UI.</p><h4>Rendering the Expanded Notification UI</h4><p>Android offers two approaches for rich interfaces:</p><ol><li><strong>Built-in NotificationCompat styles<br></strong>○ BigPictureStyle for remote images<br>○ BigTextStyle for longer descriptions<br>○ MediaStyle for playback-like controls<br>○ MessagingStyle for conversational layouts</li><li><strong>Custom RemoteViews layouts<br></strong>○ Allows you to build a miniature UI using a subset of Android’s view toolkit<br>○ Great for progress indicators, grids, or stat blocks<br>○ Supports buttons, images, and basic view bindings</li></ol><p>These layouts expand when the user pulls down on a notification, giving you room to present more information or additional controls.</p><h4>The Overall Flow</h4><p>Although the terminology and architecture differ from other platforms, the conceptual flow on Android is straightforward:</p><ol><li>Receive FCM data</li><li>Process or enrich the data (Dart isolate or native service)</li><li>Construct the notification, including any media or custom layouts</li><li>Post it to the system using NotificationManager</li><li>The system renders the collapsed and expanded UI for the user</li></ol><p>This unified, in-app approach keeps all the logic in one place and gives Flutter developers full control over both the data-handling pipeline and the final notification UI.</p><h3>🎨 Building Rich Notification Content</h3><p>Let’s build something. The NotificationCompat library (part of <em>AndroidX</em>) is the foundation of modern Android notifications. It provides backward-compatible versions of Android’s notification APIs, ensuring your rich notifications work consistently across a wide range of devices and OS versions.</p><p>A typical rich notification includes:</p><ul><li><strong>Images</strong> (e.g., thumbnails, hero images, procedural snapshots)</li><li><strong>Progress indicators</strong> (indeterminate or percentage-based)</li><li><strong>Expanded text blocks</strong> (for detailed messages, status reports, or summaries)</li><li><strong>Inline actions</strong> (buttons for quick responses)</li></ul><p>A basic example using NotificationCompat.Builder might look like this:</p><pre>val builder = NotificationCompat.Builder(context, CHANNEL_ID)<br>    .setSmallIcon(R.drawable.ic_notification)<br>    .setContentTitle(title)<br>    .setContentText(summary)<br>    .setPriority(NotificationCompat.PRIORITY_HIGH)</pre><p>From here, you can add styles to enrich the presentation.</p><h4>Working with Built-In Notification Styles</h4><p>Android provides several high-level styles designed for richer layouts without requiring full customization.</p><p><strong>BigPictureStyle</strong></p><p>Best for hero images or snapshots. Ideal when your notification includes a remote image downloaded in a background handler.</p><pre>builder.setStyle(<br>    NotificationCompat.BigPictureStyle()<br>        .bigPicture(bitmap)<br>        .bigLargeIcon(null)<br>)</pre><p><strong>BigTextStyle</strong></p><p>Perfect for longer descriptions, multi-line summaries, or detailed updates.</p><pre>builder.setStyle(<br>    NotificationCompat.BigTextStyle()<br>        .bigText(longDescription)<br>)</pre><p><strong>MessagingStyle</strong></p><p>Used for chat or multi-message interactions. It automatically handles ordering, sender names, and message bubbles in the expanded view.</p><p><strong>MediaStyle</strong></p><p>Provides playback controls for media apps — but is also useful when your notification resembles a timeline or a live process, because it supports up to five action buttons in a compact layout.</p><p>These styles are often enough to produce a polished, high-quality experience without building a custom layout.</p><h4>Adding Interactive Actions and Routing Them Back Into Flutter</h4><p>Rich notifications gain much of their power from <strong>actions</strong>, which are buttons that let users respond or take control without opening the full app.</p><p><strong>Defining Actions</strong></p><p>To add an action, you attach a PendingIntent to the notification:</p><pre>val actionIntent = PendingIntent.getBroadcast(<br>    context,<br>    0,<br>    Intent(context, NotificationActionReceiver::class.java).apply {<br>        action = &quot;app.ACTION_DO_SOMETHING&quot;<br>    },<br>    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE<br>)<br><br>builder.addAction(R.drawable.ic_action, &quot;Do Something&quot;, actionIntent)</pre><p>Actions can:</p><ul><li>Trigger a background task</li><li>Update local state</li><li>Open a specific screen in Flutter</li><li>Perform network calls when appropriate</li></ul><h3>Routing Actions Back Into Flutter</h3><p>There are three typical patterns:</p><ol><li><strong>Deep Link Into Flutter<br></strong>Use an activity PendingIntent that opens your Flutter app at a specific route. Ideal for interactive or stateful tasks.</li><li><strong>BroadcastReceiver + MethodChannel<br></strong>The receiver handles the action immediately and, if the app is running, communicates with Flutter using a method channel.</li><li><strong>BroadcastReceiver + WorkManager<br></strong>Useful for actions that need reliable background execution (e.g., sending a quick API call).</li></ol><p><strong>Choosing an Approach</strong></p><ul><li>Use <strong>deep links</strong> when the user needs to see something in the app</li><li>Use a <strong>broadcast receiver</strong> for simple, instantaneous actions</li><li>Use <strong>WorkManager</strong> for background-safe, retryable tasks</li></ul><p>By combining these patterns with rich content and styles, you can build notifications that feel integrated, responsive, and truly helpful.</p><h3>👋 Wrapping Up</h3><p>Android offers a powerful, flexible model for building rich notifications, and integrating these capabilities into a Flutter app is far more approachable than it might seem at first glance. Instead of relying on separate system extensions or multiple native targets, Android centralizes all notification logic inside your app process. This gives you a single place to receive FCM data messages, prepare content, attach media, construct layouts, and present interactive controls.</p><p>In this article, you learned how Android’s notification system fits together, from NotificationManager and notification channels to the ways data messages flow through Dart background handlers or native services. You saw how NotificationCompat can produce polished layouts with images, progress indicators, and large-format text. You also explored how to add interactive action buttons and route those actions safely back into Flutter, whether through deep links, broadcast receivers, or background work.</p><p>By combining structured FCM payloads, lightweight background enrichment, and the rich layout tools available on Android, you can create notifications that not only inform users but provide them with meaningful, immediate control. Whether your app needs media snapshots, status dashboards, inline actions, or custom UI blocks, the Android notification APIs give you the building blocks to design an experience that feels polished and intentionally crafted.</p><p>Bringing all of this together completes the picture started earlier in the series: a robust, cross-platform approach to building high-quality push notification experiences. With the tools covered here, you’re ready to design rich, responsive notifications tailored to the unique workflows and interactions in your own Flutter app.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6c1d534bbeb0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building Rich Notifications on iOS & macOS]]></title>
            <link>https://medium.com/@Toglefritz/building-rich-notifications-on-ios-macos-f84025f396a4?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/f84025f396a4</guid>
            <category><![CDATA[flutter]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[firebase]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Fri, 12 Dec 2025 00:02:24 GMT</pubDate>
            <atom:updated>2025-12-12T00:06:31.799Z</atom:updated>
            <content:encoded><![CDATA[<h4><em>A Flutter developer’s guide to Notification Service Extensions and Notification Content Extensions</em></h4><h3>💬 Introduction</h3><p>In the last article, we designed the cloud-side structure that drives rich push notifications. We focused on building clean, intent-driven FCM payloads. These messages describe <em>what is happening</em> in your app and <em>what the user can do about it</em>. Now it’s time to look at how those payloads are transformed into real, interactive notifications on Apple platforms.</p><figure><img alt="A screenshot showing a rich notification on iOS." src="https://cdn-images-1.medium.com/max/1024/1*Qvq0GSC7kcVMkeNN9U_0AA.png" /><figcaption>Rich notifications on iOS and macOS can contain data from your system, media, and/or buttons.</figcaption></figure><p>iOS and macOS offer powerful notification capabilities, but they also require a different mental model than the standard Flutter development flow. Flutter developers rarely touch Xcode targets, native Swift files, or extension bundles. Yet these pieces are exactly what enable the kinds of experiences users associate with high-quality apps: dynamic content, images downloaded at delivery time, interactive controls, and fully custom layouts in the expanded notification view.</p><p>This article serves as a practical guide for Flutter developers who want to add those capabilities to their apps. We will walk step-by-step through creating two types of Apple extensions:</p><ul><li><strong>Notification Service Extension:</strong> intercepts incoming notifications and enriches them by rewriting text or downloading media</li><li><strong>Notification Content Extension:</strong> provides a custom interactive interface when the user expands a notification</li></ul><figure><img alt="A screenshot showing the Notification Content Extension and Notification Service Extension targets in Xcode." src="https://cdn-images-1.medium.com/max/548/1*uZdu7oEIjYmaOB1eU60PYA.png" /><figcaption>The main focus of this article will be adding notification extensions to iOS/macOS.</figcaption></figure><p>You do not need to be an expert in Swift or UIKit to follow along. The goal here is to keep things approachable while still showing how these pieces fit into the larger Flutter architecture. By the end of this article, you will be able to:</p><ul><li>add both extensions to a Flutter project</li><li>read and interpret FCM payloads inside native code</li><li>attach images, show progress, and update content dynamically</li><li>render a custom UI for your notification</li><li>route user actions (like “Stop shot” or “Extend pre-infusion”) back into Flutter</li></ul><p>In short, this article takes the structured payloads from Part 2 and shows how to turn them into the rich, polished notifications.</p><h4>Series Table of Contents</h4><p>Part 1: <a href="https://medium.com/@Toglefritz/better-user-experiences-with-rich-notifications-in-flutter-3ed2d003d26f"><strong>Introduction + Architecture</strong></a></p><p>Part 2: <a href="https://medium.com/@Toglefritz/designing-fcm-payloads-for-rich-notifications-in-flutter-ac1bfba5b42c"><strong>Designing Notification Payloads</strong> (Cloud Side)</a></p><p>Part 3: <strong>iOS/macOS</strong> <em>👈 You are here</em></p><p>Part 4: <a href="https://medium.com/@Toglefritz/building-rich-notifications-on-android-6c1d534bbeb0"><strong>Android</strong></a></p><h3>🍎 Understanding the Role of Extensions on Apple Platforms</h3><p>Before we start building anything in Xcode, it’s important to understand <em>why</em> Apple uses extensions for rich notifications and what each one is responsible for. Flutter does not expose these pieces directly because they belong to the system layer beneath your Flutter app. Once you know how they fit into the bigger picture, the rest of the workflow starts to make sense.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*O--T0vayUdGM8ivX7L4OXg.png" /><figcaption>Notifications are triggered by backed processes, delivered by Firebase Cloud messaging, enriched by the Notification Service Extension, and delivered by the Notification Content Extension.</figcaption></figure><h4>The Notification Service Extension (NSE)</h4><p>A Notification Service Extension is the part of the system that runs <strong>before</strong> a notification appears to the user. When a remote notification arrives with mutable-content: 1 in the APNs payload, iOS or macOS hands it to the NSE first. This gives your app a short window (generally a few seconds and not more than 30 seconds) to modify or enrich the incoming content.</p><p>The NSE can:</p><ul><li>rewrite titles, subtitles, and bodies</li><li>attach images or other media downloaded from URLs in the payload</li><li>compute dynamic strings (like elapsed time or remaining time)</li><li>assign categories that determine which action buttons appear</li><li>choose which Content Extension should render the expanded UI</li></ul><p>The NSE does <em>not</em> display UI. It simply prepares the final version of the notification that the system will present. This is the perfect place to use the structured FCM payload from Part 2, because the NSE has access to the complete userInfo dictionary and can transform that data into meaningful display content.</p><h4>The Notification Content Extension (NCE)</h4><p>If the Notification Service Extension prepares the notification, the Notification Content Extension is responsible for <strong>displaying custom UI when the user expands it</strong>. This is where Apple gives you control over the appearance and layout. Instead of the default expanded notification, your extension can show:</p><ul><li>images or live snapshots</li><li>progress indicators</li><li>grids of stats</li><li>timers</li><li>action buttons</li></ul><p>The NCE runs in its own small sandboxed view controller. When the user expands a notification belonging to one of its categories, the system loads this view instead of the default system UI.</p><p>For Flutter developers, the key point is that the Content Extension’s UI is written in Swift, either with UIKit or SwiftUI. It does <em>not</em> run Flutter code directly. Your extension reads whatever values the NSE placed in the final notification content and uses them to populate the interface.</p><h4>How the Two Extensions Work Together</h4><p>You can think of the NSE and NCE as two halves of a pipeline:</p><ol><li><strong>FCM → Notification Service Extension <br></strong>○ The NSE receives the raw payload <br>○ It transforms text, attaches images, selects categories <br>○ It hands back a polished notification ready for display</li><li><strong>User Expands Notification → Notification Content Extension <br></strong>○ The NCE receives the enriched UNNotificationContent <br>○ It builds a custom interactive interface based on that data <br>○ It handles user interaction and routes actions back into your app</li></ol><h3>📲 Adding the Notification Service Extension to a Flutter App</h3><p>The NSE lives entirely on the native side and doesn’t require changes to any Dart code. Its only job is to intercept incoming notifications and enrich them using the FCM payload we designed in the previous part of this series.</p><p>Let’s walk through the setup step-by-step.</p><h4>Creating the Notification Service Extension Target</h4><p>To begin, open the iOS portion of your Flutter project in Xcode:</p><ol><li>Navigate to the root of your Flutter project.</li><li>Open the workspace file at <em>ios/Runner.xcworkspace.</em></li><li>In Xcode, go to:<br><strong>File → New → Target…</strong></li><li>Choose <strong>Notification Service Extension</strong> from the list of iOS/macOS templates.</li><li>Give it a name. A clean, descriptive example is <strong>FirstCrackNotificationServiceExtension</strong></li><li>For most projects, the default settings are fine. If your app uses an App Group (for shared storage between Flutter and the extension), select it here as well.</li></ol><p>When you finish, Xcode will create a new folder under the iOS project with a template Swift file called <em>NotificationService.swift</em>. This file contains the NSE’s core entry point.</p><figure><img alt="A screenshot from Xcode showing the Notification Service Extension codebase." src="https://cdn-images-1.medium.com/max/786/1*UVUL-chH_zWK9e2u0BsCHQ.png" /></figure><p>Because the NSE is code-only and uses Apple system frameworks, it rarely needs additional dependencies meaning <strong>Swift Package Manager (SPM) is typically enough</strong> and no Podfile edits are required.</p><blockquote><strong>Runner.xcworkspace → Package Dependencies → +</strong></blockquote><p>Xcode will manage them for both the main app and the extension.</p><h4>Implementing the Notification Service Extension</h4><p>Open <em>FirstCrackNotificationServiceExtension/NotificationService.swift</em>.</p><p>You’ll see the template:</p><ul><li>didReceive(_:withContentHandler:)</li><li>serviceExtensionTimeWillExpire()</li></ul><p>This is the entry point for rewriting and enriching the notification.</p><p><strong>Parsing Incoming FCM Data</strong></p><p>Everything you attached in the cloud payload (Part 2) arrives in the userInfo dictionary. The NSE can extract information from this dictionary to make decisions about enchring the notification text, fetching and attaching images, and selects. categories. For example,</p><pre>let userInfo = bestAttemptContent.userInfo<br><br>let stage       = userInfo[&quot;event&quot;] as? String ?? &quot;&quot;<br>let brewType    = userInfo[&quot;brewType&quot;] as? String ?? &quot;Espresso&quot;<br>let dose        = userInfo[&quot;dose&quot;] as? String ?? &quot;18&quot;<br>let targetTemp  = userInfo[&quot;targetTemp&quot;] as? String ?? &quot;93&quot;<br>let imageUrl    = userInfo[&quot;imageUrl&quot;] as? String</pre><p>These values are strings because FCM transports only stringified data.</p><p><strong>Building Titles and Subtitles Based on Brew Stage</strong></p><p>A simple switch lets you generate consistent, user-friendly text. For example,</p><pre>switch stage {<br>case &quot;heating&quot;:<br>    bestAttemptContent.title = &quot;Heating water for espresso&quot;<br>case &quot;preinfusion&quot;:<br>    bestAttemptContent.title = &quot;Pre-infusion in progress&quot;<br>case &quot;brewing&quot;:<br>    bestAttemptContent.title = &quot;Extraction in progress&quot;<br>case &quot;complete&quot;:<br>    bestAttemptContent.title = &quot;Shot complete&quot;<br>default:<br>    break<br>}<br><br>bestAttemptContent.subtitle = &quot;\(brewType) • \(dose)g @ \(targetTemp)°C&quot;</pre><p><strong>Downloading and Attaching Images</strong></p><p>For stages that support images (grinding, brewing, complete), attach media:</p><pre>if let urlString = imageUrl, let url = URL(string: urlString) {<br>    URLSession.shared.dataTask(with: url) { data, _, _ in<br>        defer { contentHandler(bestAttemptContent) }<br><br>        guard let data = data else { return }<br><br>        let tempFile = URL(fileURLWithPath: NSTemporaryDirectory())<br>            .appendingPathComponent(UUID().uuidString + &quot;.jpg&quot;)<br><br>        try? data.write(to: tempFile)<br><br>        if let attachment = try? UNNotificationAttachment(<br>            identifier: &quot;image&quot;,<br>            url: tempFile,<br>            options: nil<br>        ) {<br>            bestAttemptContent.attachments = [attachment]<br>        }<br>    }.resume()<br><br>    return // Prevent double-calling the handler<br>}</pre><p><strong>Assigning Notification Categories</strong></p><p>The NSE chooses which action buttons and which Notification Content Extension UI appear:</p><pre>switch stage {<br>case &quot;heating&quot;:<br>    bestAttemptContent.categoryIdentifier = &quot;BREW_HEATING&quot;<br>case &quot;grinding&quot;:<br>    bestAttemptContent.categoryIdentifier = &quot;BREW_GRINDING&quot;<br>case &quot;preinfusion&quot;:<br>    bestAttemptContent.categoryIdentifier = &quot;BREW_PREINFUSION&quot;<br>case &quot;brewing&quot;:<br>    bestAttemptContent.categoryIdentifier = &quot;BREW_EXTRACTION&quot;<br>case &quot;complete&quot;:<br>    bestAttemptContent.categoryIdentifier = &quot;BREW_COMPLETE&quot;<br>default:<br>    break<br>}</pre><p>These identifiers correspond to categories registered in the app delegate or Notification Content Extension (more on that later).</p><h4>Error Handling Best Practices</h4><p>Notification Service Extensions run under tight time limits imposed by the operating systems. Good rules include:</p><ul><li><strong>Always</strong> call the content handler, even on failure.</li><li>Default to a simple text-only notification if enrichment fails.</li><li>Avoid large downloads or complex JSON parsing.</li><li>If a timeout is imminent, fall back to the original content.</li></ul><p>If you structure your code defensively, your notification will <em>always</em> appear, even if the enrichment step runs out of time.</p><p>With the NSE created and configured, your Flutter app now has the foundation for rich, dynamic notifications. In the next section, you’ll build the Notification Content Extension, the piece responsible for displaying custom, interactive UI when the user expands a brew notification.</p><h3>🖌 Adding the Notification Content Extension to a Flutter App</h3><p>If the Notification Service Extension prepares the data for a rich notification, the Notification Content Extension is the part that actually <em>brings it to life</em>. This extension controls the expanded view that appears when the user long-presses or clicks a notification on iOS or macOS. It gives you full UI control including layouts, images, metrics, buttons, sliders, and any other interactive elements your workflow needs.</p><p>For Flutter developers, this is the point where the native integration becomes visible. While the main app continues to run in Flutter, your Content Extension runs as a lightweight Swift-based view controller that renders UI based entirely on the enriched notification content. You can think of it as a miniature companion interface whose only purpose is to give the user immediate, contextual control without requiring them to open the full app.</p><h4>Creating the Notification Content Extension Target</h4><p>The process for adding the NCE to your project looks almost the same as the process for adding the Notification Service Extension:</p><p>To begin, open the iOS portion of your Flutter project in Xcode:</p><ol><li>Navigate to the root of your Flutter project.</li><li>Open the workspace file at <em>ios/Runner.xcworkspace.</em></li><li>In Xcode, go to:<br><strong>File → New → Target…</strong></li><li>Choose <strong>Notification Content Extension</strong> from the list of iOS/macOS templates.</li><li>Give it a name. A clean, descriptive example is <strong>FirstCrackNotificationContentExtension</strong></li><li>Use Swift as the language.</li><li>For most projects, the default settings are fine. If your app uses an App Group (for shared storage between Flutter and the extension), select it here as well.</li></ol><p>Xcode will generate:</p><pre>FirstCrackNotificationContentExtension/<br>    NotificationViewController.swift<br>    MainInterface.storyboard  (or SwiftUI file if chosen)<br>    Info.plist</pre><figure><img alt="A screenshot from Xcode showing the Notification Content Extension codebase." src="https://cdn-images-1.medium.com/max/782/1*msnU1wjNUCvxxFhJpSoklQ.png" /></figure><p>This extension contains a full, sandboxed view controller dedicated to rendering the expanded notification UI.</p><h4>Implementing the Content Extension</h4><p>Open the generated <em>NotificationViewController.swift</em>. This view controller receives a UNNotification and gives you full control over the appearance of the expanded notification.</p><p><strong>Receiving the Notification Content</strong></p><p>I receive the content of the notification from FCM, override:</p><pre>override func didReceive(_ notification: UNNotification)</pre><p>This method gives you the enriched <em>UNNotificationContent</em> produced by your NSE.</p><p>For example,</p><pre>override func didReceive(_ notification: UNNotification) {<br>    let content = notification.request.content<br>    let userInfo = content.userInfo<br><br>    let stage = userInfo[&quot;event&quot;] as? String ?? &quot;&quot;<br>    let brewType = userInfo[&quot;brewType&quot;] as? String ?? &quot;Espresso&quot;<br>    let dose = userInfo[&quot;dose&quot;] as? String ?? &quot;18&quot;<br>    let elapsed = userInfo[&quot;elapsedTime&quot;] as? String ?? &quot;0&quot;<br>    <br>    titleLabel.text = content.title<br>    subtitleLabel.text = content.subtitle<br>}</pre><p>At this point, all the structured data designed in Part 2 , and all the text/media enrichment performed by the NSE , are available for display.</p><p><strong>Building the Custom UI</strong></p><p>Depending on whether you chose <strong>Storyboard</strong> or <strong>SwiftUI</strong>, you’ll populate your controls accordingly.</p><p>Typical UI elements for notifications could include:</p><ul><li>an image view for content related to the notification</li><li>a progress bar for ongoing processes</li><li>labels containing data from your system</li><li>buttons allowing users to perform actions directly from the notification</li></ul><p>Storyboard example:</p><pre>@IBOutlet weak var imageView: UIImageView!<br>@IBOutlet weak var progressView: UIProgressView!<br>@IBOutlet weak var statsStack: UIStackView!</pre><p>SwiftUI example:</p><pre>struct NotificationView: View {<br>    var content: UNNotificationContent<br>    var body: some View {<br>        VStack {<br>            Text(content.title).font(.headline)<br>            Text(content.subtitle).font(.subheadline)<br>            // other UI<br>        }<br>    }<br>}</pre><p><strong>Handling User Interactions</strong></p><p>Custom actions are defined at the <strong>category level</strong>. For example, the First Crack demo app uses identifiers like:</p><ul><li>“STOP_SHOT”</li><li>“SKIP_PREFUSION”</li><li>“EXTEND_PREFUSION”</li><li>“BREW_AGAIN”</li></ul><p>When the user taps an action:</p><ul><li>macOS or iOS calls your app delegate</li><li>You forward the action to Flutter using a MethodChannel or background handler</li><li>If necessary, perform background network requests (e.g., stopping the shot)</li></ul><p>In your Content Extension, you do <strong>not</strong> execute the action directly.</p><p>You simply call:</p><pre>self.extensionContext?.performNotificationDefaultAction()</pre><p>or dismiss:</p><pre>self.extensionContext?.dismissNotificationContentExtension()</pre><p><strong>Error Handling and Fallbacks</strong></p><p>Because the NCE is purely UI-driven, failure modes are simple:</p><ul><li>If image attachments are missing → hide the image container</li><li>If data fields are missing → show defaults</li><li>If parsing fails → stick to the system-provided title/body</li></ul><p>Unlike the NSE, there are no timeouts here. The UI is rendered when the user expands the notification.</p><h3>🤝 Sharing Data Between Flutter and Extensions</h3><p>Notification extensions run in a completely separate process from your Flutter app. This separation is intentional: extensions must be lightweight, sandboxed, and allowed to run even when your main app isn’t. Because of this, they <strong>cannot access your Flutter runtime</strong>, your Dart objects, or even your app’s normal sandboxed file system.</p><p>That means if your extension needs to show live timer values, system states, or user preferences, or if it needs access to authentication tokens, you need a safe, system-approved way to share data.</p><p>Apple provides exactly one mechanism for this: <strong>App Groups</strong>.</p><p>This section explains how App Groups work, when to use them, and how to share data cleanly between the Flutter layer and your extensions.</p><h4>Using App Groups</h4><p><strong>Why extensions can’t see Flutter’s sandbox</strong></p><p>Your Flutter iOS app writes files in its own sandbox, typically under:</p><pre>/Containers/Data/Application/&lt;UUID&gt;/</pre><p>But your Notification Service Extension (NSE) and Notification Content Extension (NCE) each run inside <em>their own</em> container:</p><pre>/Containers/Data/PlugIns/&lt;Extension&gt;/&lt;UUID&gt;/</pre><p>These containers cannot read or write to one another. So, if your Flutter code writes a timer value to local storage, your NCE won’t see it.</p><p><strong>App Groups solve this</strong></p><p>App Groups create a <strong>shared container</strong> that multiple processes can read and write. All targets that belong to the App Group can access the same:</p><ul><li>shared UserDefaults</li><li>shared file directory</li><li>(optionally) shared Keychain entries</li></ul><h4>Creating an App Group</h4><p>In Xcode:</p><ol><li>Select the <strong>Runner</strong> target → <strong>Signing &amp; Capabilities</strong>.</li><li>Click <strong>+ Capability</strong> → choose <strong>App Groups</strong>.</li><li>Create a new group, for example: <em>group.com.example.appname</em></li><li>Enable the same App Group for:</li></ol><ul><li>Runner</li><li>your Notification Service Extension</li><li>your Notification Content Extension</li></ul><h4>Reading and writing shared data</h4><p>Once the group exists, you can access a shared store.</p><p>Flutter cannot write to an App Group by default. To access the shared container from Dart, you need either:</p><ol><li>a plugin that supports App Groups, or</li><li>a simple platform channel that writes to UserDefaults(suiteName:).</li></ol><p>Here’s what it looks like using a <strong>MethodChannel</strong> to bridge from Flutter to Swift:</p><p><strong>Dart side (Flutter)</strong></p><pre>static const _channel = MethodChannel(&#39;first_crack/app_group&#39;);<br><br>Future&lt;void&gt; saveBrewState(String state, int elapsed) async {<br>  await _channel.invokeMethod(&#39;saveBrewState&#39;, {<br>    &#39;state&#39;: state,<br>    &#39;elapsed&#39;: elapsed,<br>  });<br>}</pre><p>This sends a message to the iOS host code.</p><p><strong>Swift side (Runner target)</strong></p><p>In <em>AppDelegate.swift</em> or a dedicated Swift file registered with Flutter:</p><pre>let CHANNEL_NAME = &quot;first_crack/app_group&quot;<br><br>func application(<br>    _ application: UIApplication,<br>    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil<br>) -&gt; Bool {<br><br>    let controller = window?.rootViewController as! FlutterViewController<br>    let channel = FlutterMethodChannel(name: CHANNEL_NAME, binaryMessenger: controller.binaryMessenger)<br><br>    channel.setMethodCallHandler { call, result in<br>        if call.method == &quot;saveBrewState&quot;,<br>           let args = call.arguments as? [String: Any] {<br><br>            let state = args[&quot;state&quot;] as? String ?? &quot;&quot;<br>            let elapsed = args[&quot;elapsed&quot;] as? Int ?? 0<br><br>            let defaults = UserDefaults(suiteName: &quot;group.com.example.firstcrack&quot;)<br>            defaults?.set(state, forKey: &quot;brew_state&quot;)<br>            defaults?.set(elapsed, forKey: &quot;brew_elapsed&quot;)<br>            defaults?.synchronize()<br><br>            result(nil)<br>        } else {<br>            result(FlutterMethodNotImplemented)<br>        }<br>    }<br><br>    return super.application(application, didFinishLaunchingWithOptions: launchOptions)<br>}</pre><p>This writes the state information into the <strong>shared App Group container</strong>, where your extensions can read it.</p><p><strong>How the Notification Extensions read this shared data</strong></p><p>In the NSE or NCE:</p><pre>let defaults = UserDefaults(suiteName: &quot;group.com.example.firstcrack&quot;)<br><br>let brewState = defaults?.string(forKey: &quot;brew_state&quot;)<br>let elapsed = defaults?.integer(forKey: &quot;brew_elapsed&quot;)</pre><p>This gives the extensions the latest brew state written by the Flutter app.</p><h4>What data is appropriate to store in the App Group?</h4><p><strong>Good candidates:</strong></p><ul><li>current system state identifiers (e.g., heating, preinfusion, etc. in the First Crack example)</li><li>a running timer value</li><li>last known values from an external system, like an IoT device</li><li>user preferences</li></ul><p><strong>Avoid storing:</strong></p><ul><li>large images</li><li>encrypted blobs</li><li>complex serialized models</li><li>rapidly changing, high-frequency values</li></ul><p>Extensions run briefly and intermittently. Store only what they need to render a meaningful snapshot of state.</p><h4>Passing Auth Tokens to the Extension</h4><p>Some extensions need access to authentication credentials. For example, a notification extension might need to send an API call in response to a user action like tapping a button in the notification. Since extensions cannot access Flutter’s usual secure storage, you need something else.</p><p><strong>Using a shared Keychain access group</strong></p><p>Apple allows a Keychain item to be shared across targets via an <strong>Access Group</strong>, which is configured similarly to App Groups.</p><p>Steps:</p><ol><li>Enable <strong>Keychain Sharing</strong> in the Runner target.</li><li>Add a new access group: <em>com.example.appname.sharedkeychain.</em></li><li>Enable the same group for your extension targets.</li></ol><p>When the user logs in on the Flutter side, store the token using a plugin like:</p><ul><li><a href="https://pub.dev/packages/flutter_secure_storage"><em>flutter_secure_storage</em></a> with iOS access group support</li><li>a custom method channel</li></ul><p><strong>Reading the token in the extension</strong></p><pre>let query: [String: Any] = [<br>    kSecClass as String: kSecClassGenericPassword,<br>    kSecAttrAccount as String: &quot;auth_token&quot;,<br>    kSecAttrAccessGroup as String: &quot;com.example.firstcrack.sharedkeychain&quot;,<br>    kSecReturnData as String: true<br>]<br><br>var item: CFTypeRef?<br>let status = SecItemCopyMatching(query as CFDictionary, &amp;item)<br><br>if status == errSecSuccess, let data = item as? Data {<br>    let token = String(decoding: data, as: UTF8.self)<br>}</pre><p><strong>When is it appropriate for an extension to make API calls?</strong></p><p>Extensions can make network calls, but with <strong>important constraints</strong>:</p><ul><li>The NSE has a strict execution limit (about 30 seconds).</li><li>The NCE should avoid long-running operations since it is UI-focused.</li><li>Extensions should not attempt large downloads except media images.</li><li>Authentication refresh flows should <em>not</em> run inside extensions.</li><li>Only simple, quick API calls (like “dismiss timer”) are appropriate.</li></ul><p><strong>Good uses:</strong></p><ul><li>Stop a shot</li><li>Skip pre-infusion</li><li>Acknowledge a timer</li></ul><p><strong>Bad uses:</strong></p><ul><li>Refresh OAuth tokens</li><li>Upload large images</li><li>Run a full brew synchronization</li></ul><h3>👋 Wrapping Up and Next Steps</h3><p>At this point in the series, you’ve built a complete understanding of how rich notifications work on Apple platforms and how to integrate them cleanly into a Flutter application. You now have the tools to:</p><ul><li>add both a <strong>Notification Service Extension</strong> and a <strong>Notification Content Extension</strong></li><li>interpret and enrich <strong>FCM payloads</strong> using native Swift code</li><li>attach media, rewrite text, and choose stage-specific <strong>categories</strong></li><li>build a custom expanded UI that renders timers, images, stats, and controls</li><li>handle user interactions and <strong>route actions back into Flutter</strong></li><li>share small pieces of state or tokens between the Flutter layer and extensions using <strong>App Groups</strong></li></ul><figure><img alt="An empty coffee cup and an apple core sitting on a small plate." src="https://cdn-images-1.medium.com/max/1024/1*P0XgKiQObfaUGoUJvBeFxg.png" /><figcaption>We’ve wrapped up our work on iOS and macOS and the next step will focus on Android.</figcaption></figure><p>At this point in the series, you’ve built a complete understanding of how rich notifications work on Apple platforms and how to integrate them cleanly into a Flutter application. You now have the tools to:</p><ul><li>add both a <strong>Notification Service Extension</strong> and a <strong>Notification Content Extension</strong></li><li>interpret and enrich <strong>FCM payloads</strong> using native Swift code</li><li>attach media, rewrite text, and choose stage-specific <strong>categories</strong></li><li>build a custom expanded UI that renders timers, images, stats, and controls</li><li>handle user interactions and <strong>route actions back into Flutter</strong></li><li>share small pieces of state or tokens between the Flutter layer and extensions using <strong>App Groups</strong></li></ul><h3>🔗 Continue Learning</h3><p>▶ Next: <a href="https://medium.com/@Toglefritz/building-rich-notifications-on-android-6c1d534bbeb0"><strong>Building Rich Notifications on Android</strong></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f84025f396a4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Designing FCM Payloads for Rich Notifications in Flutter]]></title>
            <link>https://medium.com/@Toglefritz/designing-fcm-payloads-for-rich-notifications-in-flutter-ac1bfba5b42c?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/ac1bfba5b42c</guid>
            <category><![CDATA[flutter]]></category>
            <category><![CDATA[firebase]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[mobile-app-development]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Wed, 10 Dec 2025 03:45:56 GMT</pubDate>
            <atom:updated>2025-12-12T00:05:06.352Z</atom:updated>
            <content:encoded><![CDATA[<h4>How to structure backend messages that drive media, actions, and interactive UIs.</h4><h3>☁️ Introduction</h3><p>In the first part of this series, we looked at the core idea behind rich notifications in Flutter: <strong>Firebase Cloud Messaging delivers data and the native operating system renders the notification</strong>. Flutter sits above both pieces, orchestrating logic, state, and navigation. Once you understand that separation you gain the freedom to build far more capable notification workflows than the default Flutter tooling exposes.</p><p>This second article shifts focus to the other half of the system: the <strong>cloud side</strong>.</p><figure><img alt="A woman sipping coffee while looking up at the clouds. Some blue birds fly overhead." src="https://cdn-images-1.medium.com/max/1024/1*FsD9uw9VxQkkc_xqHOzhEg.png" /><figcaption>The cloud side can be beautiful, as long as it is not the type of cloud that produces tornados.</figcaption></figure><p>Before iOS, Android, or macOS can display rich, interactive notifications, the backend must send the right kind of data. That means designing a clean, well-structured payload schema that describes each notification event and gives every platform enough information to produce a meaningful user experience.</p><p>This article walks through how to:</p><ul><li>design a data model for rich, interactive notifications</li><li>structure FCM data messages so each platform can render custom UI</li><li>support actions, media, progress indicators, and routing</li><li>generate payloads dynamically</li></ul><p>Although the examples use Firebase Functions, none of the content depends on that specific choice. You can use any backend system that can generate FCM data messages. The important part is the <strong>payload structure</strong>, not the cloud provider.</p><p>By the end of this article, you’ll have a clear blueprint for modeling notification events in a way that scales, remains easy to extend, and gives your native layers everything they need to present rich, high-value push notifications in your Flutter application.</p><h4>Series Table of Contents</h4><p>Part 1: <a href="https://medium.com/@Toglefritz/better-user-experiences-with-rich-notifications-in-flutter-3ed2d003d26f"><strong>Introduction + Architecture</strong></a></p><p>Part 2: <strong>Designing Notification Payloads</strong> (Cloud Side) <em>👈 You are here</em></p><p>Part 3: <a href="https://medium.com/@Toglefritz/building-rich-notifications-on-ios-macos-f84025f396a4"><strong>iOS/macOS</strong></a></p><p>Part 4: <a href="https://medium.com/@Toglefritz/building-rich-notifications-on-android-6c1d534bbeb0"><strong>Android</strong></a></p><h3>🎨 Start From the Experience, Not the Payload</h3><p>Before you write a single line of backend code or JSON, it helps to pause and design the experience you want your users to have. The payload is only a description of that experience. If you start with key names and field types, you tend to end up with a structure that mirrors your database instead of something that supports a great notification workflow.</p><p>A good first step is to sketch the notification journey in plain language. This does not have to be fancy. It might be a Markdown document in your repository, written in the same style as a technical spec, listing what happens at each stage of your workflow.</p><pre>### Stage 1: Heating<br><br>**Goal**: Efficiently communicate water heating progress to the user.<br><br>#### Collapsed Notification<br><br>**Title**: `Heating water for espresso`<br><br>**Subtitle**: `Espresso • 18g @ 93°C`<br>- Dynamically constructed by NSE from brew profile data<br>- Format: `{brewType} • {dose}g @ {temperature}°C`<br><br>**Body**: `Your First Crack machine is heating water to the target brewing temperature.`<br>- Static descriptive text explaining the current stage<br>- Optional enhancement: `About 20 seconds remaining.` (if time estimate available)<br><br>**Media**: None (text-only notification for simplicity)</pre><p>It might be a set of simple frames in Figma that show the collapsed and expanded states of a notification.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MKyXcyXmmY2awWN-NmFMeg.png" /><figcaption>A simple, low-fidelity Figma design can guide the design of the FCM payload.</figcaption></figure><p>The important part is that you are describing what the user sees and what they can do, not which JSON keys exist.</p><p>For each notification, answer two questions:</p><ol><li><strong>What should the user see at this moment<br></strong>What status information is actually useful here? What context do they need so they can make a decision without opening the app?</li><li><strong>What should the user be able to do from the notification<br></strong>Is this stage purely informational, or should it offer controls? If there are actions, what are they, and what should happen when the user taps them?</li></ol><p>Using First Crack as an example, this might look like:</p><ul><li><strong>Heating<br></strong>○ The user sees the brew profile summary and a simple sense of progress. For example: espresso, 18 g dose, 200 °F target temperature, and a progress indicator that shows how close the machine is to that target.<br>○ The only meaningful control at this point might be the ability to cancel the brew.</li><li><strong>Pre-infusion<br></strong>○ The user sees that water is being applied gently to the coffee puck, along with the current pre-infusion time and target time.<br>○ They might be allowed to skip ahead to full pressure or extend the pre-infusion window if they want a longer bloom.</li><li><strong>Brewing (extraction)<br></strong>○ The user sees live stats: elapsed time, dose, current ratio, pressure, and possibly an image of the shot in progress.<br>○ Controls here might include stopping the shot early, extending the target ratio, or jumping into a live view inside the app.</li><li><strong>Complete<br></strong>○ The user sees a summary of the shot: final ratio, total time, dose, and a small hero image of the finished espresso.<br>○ They can repeat the same profile, open the app to tweak it, or dismiss the notification once they acknowledge the result.</li></ul><p>A short description like this, even written as a few bullet lists in a Markdown document, is enough to guide your payload design. By working from the experience back to the data, you end up with a payload schema that exists to serve the notifications, not the other way around. The sketch in your Markdown spec or Figma board becomes the source of truth. The JSON is simply the structured representation of that design.</p><h3>✉️ Data Messages Instead of Notification Messages</h3><p>Now that we have a picture of the experience we want to deliver, we need to choose the right kind of FCM message to carry the data that powers it. Firebase gives you two broad options: <strong>notification messages</strong> and <strong>data messages</strong>. At a glance they look similar, but they behave very differently, and that difference matters a lot for rich notifications.</p><h4>Notification messages</h4><p>Notification messages are the simplest form of FCM message. They contain fields like:</p><pre>{<br>  &quot;notification&quot;: {<br>    &quot;title&quot;: &quot;Brew complete&quot;,<br>    &quot;body&quot;: &quot;Your espresso is ready.&quot;<br>  }<br>}</pre><p>On many platforms, FCM (or the OS) can display these messages with almost no code on your side. That makes them attractive for quick announcements or simple updates. The trade-off is that you get very little control:</p><ul><li>Titles and bodies are rendered by the system.</li><li>Native extensions may not run at all, depending on platform and configuration.</li><li>You do not have a structured payload that describes the system state, the available actions, or media to attach.</li></ul><p>Notification messages are perfect for a “blog post published” alert. They are not enough for a live, interactive experience in the notification shade.</p><h4>Data messages</h4><p>Data messages are the more flexible format. Instead of a fixed notification block, they contain arbitrary key–value pairs under data:</p><pre>{<br>  &quot;data&quot;: {<br>    &quot;event&quot;: &quot;brewing&quot;,<br>    &quot;brewId&quot;: &quot;brew_123&quot;,<br>    &quot;dose&quot;: &quot;18&quot;,<br>    &quot;targetTemp&quot;: &quot;93&quot;,<br>    &quot;elapsedTime&quot;: &quot;19&quot;,<br>    &quot;imageUrl&quot;: &quot;https://example.com/extraction.jpg&quot;<br>  }<br>}</pre><p>These values are delivered to your app, service worker, Notification Service Extension, or background handler. Your code decides:</p><ul><li>how to interpret the fields</li><li>how to compose titles and subtitles</li><li>which image to download and attach</li><li>which buttons to show</li><li>which actions those buttons trigger</li></ul><p>In other words, data messages give native code full access to the payload. That access is exactly what you need for rich notifications.</p><h3>📁 Understanding Notification Categories on iOS &amp; macOS</h3><p>Before designing the full FCM payload, it helps to understand one of the most important concepts in the Apple notification system: <strong>notification categories</strong>. Categories determine which buttons appear in a notification and which custom UI (if any) should be displayed when the user expands it.</p><p>On iOS and macOS, categories do two things:</p><p>① <strong>They define the interactive actions available for a notification</strong></p><p>A category is essentially a named group of actions. Each action corresponds to a button the user can tap when they long-press or expand the notification.</p><p>For example:</p><pre>let stopAction = UNNotificationAction(<br>    identifier: &quot;STOP_SHOT&quot;,<br>    title: &quot;Stop Shot&quot;,<br>    options: []<br>)<br><br>let brewCategory = UNNotificationCategory(<br>    identifier: &quot;BREW_EXTRACTION&quot;,<br>    actions: [stopAction],<br>    intentIdentifiers: [],<br>    options: []<br>)</pre><p>Any notification whose categoryIdentifier is “BREW_EXTRACTION” will display the <strong>Stop Shot</strong> button when expanded.</p><p>② <strong>They determine which Notification Content Extension handles the UI</strong></p><p>If your app includes a Notification Content Extension (a custom interface displayed when expanding the notification), it must declare which categories it handles:</p><pre>&lt;key&gt;UNNotificationExtensionCategory&lt;/key&gt;<br>&lt;array&gt;<br>    &lt;string&gt;BREW_EXTRACTION&lt;/string&gt;<br>&lt;/array&gt;</pre><p>When a notification arrives with that category identifier, the system routes it to your custom UI.</p><p>This is how the First Crack demo is able to show different notification layouts for:</p><ul><li>Heating</li><li>Grinding</li><li>Pre-infusion</li><li>Brewing</li><li>Completion</li></ul><p>Each stage maps to a category, and each category maps to the appropriate buttons and content UI.</p><h4>How Categories Fit Into the Cloud Payload</h4><p>Apple platforms cannot guess which actions you want. They rely on the notification to include a category value. FCM allows you to embed this in the APNs portion of the payload:</p><pre>{<br>  &quot;apns&quot;: {<br>    &quot;payload&quot;: {<br>      &quot;aps&quot;: {<br>        &quot;mutable-content&quot;: 1,<br>        &quot;category&quot;: &quot;BREW_EXTRACTION&quot;<br>      }<br>    }<br>  }<br>}</pre><p>In your Notification Service Extension, you can also override or dynamically assign a category based on the payload contents:</p><pre>bestAttemptContent.categoryIdentifier = userInfo[&quot;category&quot;] as? String ?? &quot;BREW_EXTRACTION&quot;</pre><p>This flexibility is important because:</p><ul><li>You may want different buttons for heating vs pre-infusion.</li><li>You may want to disable actions entirely for certain stages.</li><li>You may want the Content Extension to display different layouts based on the stage.</li></ul><p>The category is what ties the data message from your backend to the native UI on the device.</p><h3>🔥 Generating FCM Payloads in Firebase Functions</h3><p>Once you know the structure of the payload you want to send, the next step is turning that structure into a real FCM data message generated by your backend. In the First Crack demo, Firebase Functions serves as the backend because it is simple to deploy, easy to integrate with Firestore, and already has built-in support for sending FCM messages through the Admin SDK. But the ideas here apply to <em>any</em> backend technology or environment.</p><p>In a Firebase Function, the workflow looks like this:</p><ol><li>Your backend observes a change in, in this example, brew state. There are many different ways your backend infrastructure might be notified about changes in your system that might trigger notifications.</li><li>The Function converts that state into a structured payload following the schema you designed.</li><li>The Function sends that payload as a <strong>data-only</strong> FCM message to the user’s device.</li></ol><p>Functions do not determine the UI. They simply translate machine state into a clear set of fields that your Notification Service Extension or Android handler can interpret.</p><p>A simplified Cloud Function might look like this:</p><pre>exports.onBrewStageChange = functions.firestore<br>  .document(&quot;brews/{brewId}&quot;)<br>  .onUpdate(async (change, context) =&gt; {<br>    const before = change.before.data();<br>    const after = change.after.data();<br><br>    // Determine the event type (heating, preinfusion, brewing, complete)<br>    const stage = after.stage;<br><br>    // Build the structured payload<br>    const payload = {<br>      data: {<br>        schemaVersion: &quot;1&quot;,<br>        event: stage,<br>        brewId: context.params.brewId,<br>        brewType: after.profile.brewType,<br>        dose: String(after.profile.dose),<br>        targetTemp: String(after.profile.temperature),<br>        elapsedTime: String(after.metrics.elapsedTime ?? 0),<br>        imageUrl: after.media?.imageUrl ?? &quot;&quot;,<br>        actions: JSON.stringify(after.availableActions),<br>        route: `brew/${context.params.brewId}`<br>      }<br>    };<br><br>    // Send the message<br>    await admin.messaging().sendToDevice(after.deviceToken, payload);<br>  });</pre><p>A few key points:</p><ul><li>All values must be strings because of FCM’s data-message constraints.</li><li>Complex values like arrays should be JSON-encoded.</li><li>The payload contains only <strong>data</strong>, not a notification block. This ensures that native extensions run and can take full control.</li></ul><p>With this approach, you can attach as much (or as little) contextual data as you want. Your FCM payload becomes the authoritative source of information for the product’s notification system.</p><h3>👋 Wrapping Up</h3><p>By the time your backend is generating structured, intent-driven FCM data messages, you’ve built the foundation for all the rich notification experiences coming later in this series. Native layers now receive enough information to:</p><ul><li>construct dynamic titles</li><li>attach media</li><li>display progress</li><li>show interactive buttons</li><li>route actions back to Flutter</li></ul><p>The next articles in the series will take these payloads and walk through how the iOS/macOS <strong>Notification Service Extension</strong> and <strong>Notification Content Extension</strong> use them to render the full experience.</p><h3>🔗 Continue Learning</h3><p>▶ Next: <a href="https://medium.com/@Toglefritz/building-rich-notifications-on-ios-macos-f84025f396a4"><strong>Building Rich Notifications on iOS &amp; macOS</strong></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ac1bfba5b42c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Better User Experiences With Rich Notifications in Flutter]]></title>
            <link>https://medium.com/@Toglefritz/better-user-experiences-with-rich-notifications-in-flutter-3ed2d003d26f?source=rss-c0985f54a96e------2</link>
            <guid isPermaLink="false">https://medium.com/p/3ed2d003d26f</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[flutter]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[mobile-app-development]]></category>
            <category><![CDATA[firebase]]></category>
            <dc:creator><![CDATA[Scott Hatfield]]></dc:creator>
            <pubDate>Wed, 10 Dec 2025 03:45:31 GMT</pubDate>
            <atom:updated>2025-12-12T00:04:51.941Z</atom:updated>
            <content:encoded><![CDATA[<h4>Using iOS and Android features to build actionable, high-value notification workflows for Flutter apps.</h4><h3>💬 Rich, Interactive Notifications</h3><p>Push notifications play a much bigger role in mobile apps than most people realize. They are often the first interaction a user has with an app in a given day, and in many cases they are the place where meaningful work actually begins. Despite that importance, many apps still rely on the bare minimum: just a title and a short message.</p><figure><img alt="A very boring cup of coffee in a boring styrofoam cup in a boring setting." src="https://cdn-images-1.medium.com/max/1024/1*9PTr8_58mmfpxzSFnt75vQ.png" /><figcaption>This is like the coffee equivalent of the default push notifications used in most Flutter apps.</figcaption></figure><p>But modern mobile operating systems offer far more than that. Users are already accustomed to notifications that contain media, status indicators, progress displays, and context-aware action buttons. These richer experiences feel more natural and allow users to move through tasks without opening the app at all. Not to mention, offering compelling push notification experiences will help drive app usage and satisfaction.</p><p>Flutter developers can build this level of experience too, but it requires going beyond the default Firebase Cloud Messaging setup. <strong>Firebase handles transport, not presentation</strong>. The moment you need interactive controls, dynamic media, or a custom interface, you step into the native notification systems that power iOS, Android, and macOS.</p><p>This series explains how to build those experiences in a clean, consistent way.</p><figure><img alt="An example of a push notification enhanced to include an image and data from the app." src="https://cdn-images-1.medium.com/max/1024/1*Cft1CYoD2fXdnHviR2viYw.png" /><figcaption>This notification is not just a message, it also include data from a (fake) IoT device, an image, and buttons for performing different actions.</figcaption></figure><h4>Series Table of Contents</h4><p>Part 1: <strong>Introduction + Architecture</strong> <em>👈 You are here</em></p><p>Part 2: <a href="https://medium.com/@Toglefritz/designing-fcm-payloads-for-rich-notifications-in-flutter-ac1bfba5b42c?postPublishedType=initial"><strong>Designing Notification Payloads</strong> (Cloud Side)</a></p><p>Part 3: <a href="https://medium.com/@Toglefritz/building-rich-notifications-on-ios-macos-f84025f396a4"><strong>iOS/macOS</strong></a></p><p>Part 4: <a href="https://medium.com/@Toglefritz/building-rich-notifications-on-android-6c1d534bbeb0"><strong>Android</strong></a></p><h4>Example Project: First Crack</h4><p>To make things concrete, we will use a small demo app called First Crack. It simulates a smart espresso machine and uses rich notifications to guide the user through the brewing process. The app triggers events like water heating, pre-infusion, and extraction, and each of these events can display a custom notification with controls, media, or status updates.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Xf88Zi3hzXeGYKzoOKoHQw.png" /><figcaption>This coffee represents the rich notification experience we will be building in this article series. It is not overpowering, but it does have some tasteful additions that make the whole experience more polished.</figcaption></figure><p>By the end of this article you will understand how to combine Flutter with native notification extensions, how to pass information between layers, and how to design a workflow that feels smooth across platforms. More importantly, you will have a practical example you can use as a starting point in your own applications.</p><figure><img alt="A rich notification on Android." src="https://cdn-images-1.medium.com/max/1024/1*Tscco2P0B35MAcMsyAJ2tw.png" /><figcaption>I’ll be right back. I suddenly need another cup of coffee.</figcaption></figure><p>If you have been wanting to build more capable notifications in Flutter but have not been sure where to begin, this guide is written for you. ☕</p><h3>📓 Why Rich Notifications Are Not Built Into Flutter</h3><p>Most Flutter apps that support push notifications rely on Firebase Cloud Messaging. This article has sort of assumed this is the case for your app so far. It is a familiar tool, it integrates well with Dart, and it works reliably across platforms. FCM, however, has a clear scope. It delivers messages. It does not determine how those messages are presented to the user.</p><blockquote><strong>FCM ≠ Notification UI</strong></blockquote><blockquote><strong>FCM = delivery mechanism</strong></blockquote><p>This is an important distinction because the default integration that most developers use only exposes the simplest form of notification UI. You get a title, some text, and a data payload. That is enough for basic announcements or simple updates, but it does not provide the building blocks needed for the kinds of rich, interactive experiences that users encounter in modern operating systems.</p><p>At this level there are several key limitations:</p><ul><li>You cannot create custom layouts.</li><li>You cannot add buttons that perform stateful actions or communicate results back to the system.</li><li>You cannot attach dynamic media such as images fetched at delivery time.</li><li>You cannot use platform-specific notification extensions to modify or enhance the content.</li></ul><p>None of these limitations come from Flutter itself. They are a result of treating Firebase Messaging as both the transport and the renderer of the notification. FCM does not try to solve the UI layer, and that is by design. Its job is to route structured information from your backend to the device. <strong>What happens after the payload arrives is entirely up to the platform.</strong></p><figure><img alt="A woman taking an envelope out of a mailbox while holding a cup of coffee. A blue bird sits atop the mailbox, a true sign of an article about Flutter." src="https://cdn-images-1.medium.com/max/1024/1*izKQ8__3LXCPrlwCt55lTg.png" /><figcaption>Firebase Cloud Messaging is like the postal service. It just delivers messages; it does not determine how the letters are designed.</figcaption></figure><p>In other words, FCM is the delivery mechanism. It gets the notification to the device. The notification UI is a different layer altogether, and that layer belongs to the operating system. Understanding this separation is the first step toward building the kinds of rich, interactive experiences that make notifications genuinely useful.</p><h3>🚧 Understanding the Architecture of Rich Notifications</h3><p>Once you understand that Firebase Cloud Messaging is responsible for delivering data rather than rendering a visual interface, the next step is to look at what a complete notification architecture actually involves. Rich notifications are the result of several layers working together, and each layer plays a distinct role.</p><p>A useful way to think about this is as a simple flow:</p><blockquote><strong>FCM → Platform Message Handler → Native Notification Renderer → Flutter App Callback</strong></blockquote><p>The message begins as structured data sent through FCM. After the payload reaches the device, the platform decides how to handle it. iOS, Android, and macOS each have their own message handlers that receive the payload and then pass it to the native notification system. <strong>This is the point where you have full control </strong>over layout, media, buttons, and interactions. Once the user interacts with the notification, the result can be routed back into the Flutter layer.</p><p>You are not replacing Firebase when you build rich notifications. You are overriding the UI layer that sits below it. FCM still handles device routing, topic management, and delivery. Native APIs control the look and feel.</p><ul><li><strong>iOS and macOS</strong> use a <em>Notification Service Extension</em> and a <em>Notification Content Extension</em>. The service extension allows the app to modify the content as it arrives, such as downloading a preview image or rewriting the title based on brew status. The content extension provides a custom interface where users can interact with controls like buttons or progress indicators.</li><li><strong>Android</strong> uses a background service to receive data messages and <em>NotificationCompat</em> to construct a custom layout. This layout can contain actions, progress indicators, or images fetched from the network.</li></ul><p>Across all platforms, the principle is the same: <strong>platform-native rendering and Flutter-driven orchestration.</strong></p><p>Flutter handles the logic, the models, and the state of the app. The native layers handle the visuals and interactivity of the notifications themselves.</p><h3>☕️ The First Crack Demo App</h3><p>To make these ideas concrete, this article uses a small demo application called <strong>First Crack</strong>. The app simulates a smart espresso machine that can send status updates and accept remote commands. It includes live brew notifications, timers, and even simulated images from a camera mounted above the portafilter. Users can interact with notifications directly by starting a brew, adjusting temperature, pausing the process, or acknowledging a completed shot.</p><p><a href="https://github.com/Toglefritz/First_Crack">GitHub - Toglefritz/First_Crack: Demonstration application showing how to build rich push notification experiences</a></p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FDavYs1qvfB0%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DDavYs1qvfB0&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FDavYs1qvfB0%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/04cc9fff40ebc294cb2d964eca918022/href">https://medium.com/media/04cc9fff40ebc294cb2d964eca918022/href</a></iframe><p>The goal of First Crack is not to recreate a full-featured coffee machine or build a production-level IoT system. Instead, it provides a clean and understandable example of how to structure a Flutter app that works with rich, interactive notifications across multiple platforms. The app is intentionally focused so that the architectural patterns remain clear, and the notification workflows are easy to follow and adapt to your own projects.</p><h3>➡️ What Comes Next</h3><p>This article sets the foundation for the rest of the series. Before diving into platform-specific implementation, the next article focuses on the cloud side of the system. It explains how to design the FCM payload structure that drives all of the rich interactions shown throughout this project.</p><ul><li><strong>Designing the Cloud Payload: </strong>How to model your notification events, design a clean JSON schema, and structure FCM data messages to support rich, interactive notifications across all platforms.</li></ul><p>After that, you can continue to the platform-specific guides:</p><ul><li><strong>iOS &amp; macOS: </strong>Implementing Notification Service Extensions and Notification Content Extensions.</li><li><strong>Android: </strong>Creating custom layouts, buttons, and background media loaders with NotificationCompat.</li></ul><p>Each platform has its own quirks and capabilities, but the underlying architecture stays the same. After covering payload design in the next article, we’ll begin exploring the rich capabilities of the Apple notification system on iOS and macOS.</p><h3>🔗 Continue Learning</h3><p>▶ Next: <a href="https://medium.com/@Toglefritz/designing-fcm-payloads-for-rich-notifications-in-flutter-ac1bfba5b42c?postPublishedType=initial"><strong>Designing Notification Payloads</strong> (Cloud Side)</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3ed2d003d26f" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>