<?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 Ismael G Marin C on Medium]]></title>
        <description><![CDATA[Stories by Ismael G Marin C on Medium]]></description>
        <link>https://medium.com/@igmarin?source=rss-bfcd072d0964------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*nuwZWwUxfKo9RTe9mLYG9A.png</url>
            <title>Stories by Ismael G Marin C on Medium</title>
            <link>https://medium.com/@igmarin?source=rss-bfcd072d0964------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 18:08:54 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@igmarin/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[Beyond the Code: 3 The Lessons That Shaped My Engineering Journey]]></title>
            <link>https://medium.com/@igmarin/beyond-the-code-3-the-lessons-that-shaped-my-engineering-journey-1a36a257e540?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/1a36a257e540</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <category><![CDATA[tech-layoff]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Tue, 09 Jun 2026 04:03:22 GMT</pubDate>
            <atom:updated>2026-06-09T04:03:22.800Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BoNix2yQEDag3dXXZ5BOAg.png" /><figcaption><strong>Beyond the Code</strong></figcaption></figure><p>I joined my previous job back in <strong>September</strong> <strong>2020</strong> for what I can only describe as an embarrassingly romantic reason: I needed the income to qualify for a mortgage so I could buy a house for the woman I knew I was going to marry. I never expected to stay. I never expected to care. But for the first time in fifteen years as a contractor, someone — <strong>Hugo</strong> — actually asked for my opinion. He taught me what quality looked like, what mattered, and what was expected of me. Working alongside people I genuinely admired, I felt like I belonged.</p><p>Four years later, I left as the fourth all-time contributor to our core API, with <strong>475 merged pull requests, 505 Jira issues, and 49 Confluence pages authored.</strong> I also left during one of the hardest eras in tech. Two major layoffs reduced our engineering team to less than a third of its original size. I watched friends leave. I carried their work. I learned that &quot;<a href="https://lawsofsoftwareengineering.com/laws/bus-factor/"><strong>bus factor</strong></a>&quot; isn&#39;t an abstract concept when you&#39;re the one still on the bus.</p><p>Currently, I am interviewing for a Engineering openning role. One phase of this process requires walking through three foundational projects from my career, detailing:</p><ul><li><strong>The Challenge</strong></li><li><strong>The Approach</strong></li><li><strong>My Specific Role</strong></li><li><strong>The Impact</strong></li><li><strong>The Lessons Learned</strong></li></ul><p>Preparing for this conversation made me incredibly reflective. These milestones weren’t achieved in a vacuum; they were the result of tight-knit teamwork, late nights, and collective resilience.</p><p>I can&#39;t talk about these projects without talking about the people who were in the trenches with me. This wasn&#39;t a solo act. Every win was shared; every failure taught us something together. To anyone reading this who has been laid off, who is sending résumés into the void, who is questioning their worth after rejection number twenty: I see you. This is hard. But we do this work because we love it. You will land. Take the breath, sharpen your skills, and trust that the right door opens.</p><blockquote><em>Note: For NDA and privacy reasons, I&#39;ve anonymized specific client names and certain internal project titles. Any teammate names mentioned are already public in my farewell letter or used with permission.</em></blockquote><h3>Project 1: Building a New Business Workflow in Two Weeks</h3><h3>The Challenge</h3><p>For years, our platform was a straightforward <strong>B2B</strong> product with rigid, well-defined rules. Then a major client asked us to integrate their reservation flow into our system. On the surface, this looked easy — we already had reservations. But their requirements shattered our model. Our existing flow was three discrete endpoints: customer data, reservation data, then general client data. The client demanded a single endpoint that consumed all three at once, and they expected a specific response payload under their own rules. They were too big to adapt to us. We had two weeks.</p><h3>The Approach</h3><p>As the Tech Lead, I looked at our decoupled architecture and knew we couldn’t rewrite our core validation engine in 14 days without introducing catastrophic regression risks. Instead, I defined the integration strategy, split the execution with my teammate, and made the call to prioritize delivery and correctness over <a href="https://lawsofsoftwareengineering.com/laws/premature-optimization/"><strong>premature optimization</strong></a><strong> </strong>and the guiding principle was <a href="https://lawsofsoftwareengineering.com/laws/teslers-law/"><strong>Tesler’s Law</strong></a>: we had to absorb the complexity so that neither their users nor our internal business users felt the friction. The plan, which I executed with a trusted teammate, was fourfold:</p><ol><li>Speak the same language. We stood up an <a href="https://aws.amazon.com/api-gateway/"><strong>AWS API Gateway</strong></a> so we could receive their exact payload shape and respond under their rules without breaking our existing contracts.</li><li>Create a unified API. We built a new endpoint that handled the “all-in-one” requirement. If data was incomplete — which it often was — we explicitly marked the reservation as “<em>not confirmed</em>” rather than guessing. <a href="https://lawsofsoftwareengineering.com/laws/teslers-law/"><strong>Tesler’s Law</strong></a>, again: we owned the complexity of partial state.</li><li>Bidirectional sync. We added webhooks so that if a reservation changed state on our side, the client’s system stayed in sync.</li><li>Small, surgical changes. We introduced a new “<em>not confirmed</em>” status into our legacy system and documented the business rules explicitly. We did all of this pre-AI, which meant every line of code, every test, and every piece of documentation was written by hand under a deadline that refused to bend.</li></ol><h3>The Impact</h3><p>We shipped the integration completely on time, unblocking a foundational revenue channel for the business and deliberately documented the tech debt we accepted rather than hiding it, following Knuth’s Optimization Principle of <a href="https://lawsofsoftwareengineering.com/laws/premature-optimization/"><strong>premature optimization</strong></a> is the root of all evil. The system had room to breathe. But then <a href="https://lawsofsoftwareengineering.com/laws/hyrums-law/"><strong>Hyrum’s Law</strong></a> hit us. Another internal team saw our integration and adapted it for a <strong>B2C</strong> use case without understanding the original client constraints. They optimized prematurely, broke a rule we had explicitly designed around, and our implementation broke in production. The client became our tester. We fixed it fast, but it stung.</p><h3>Lessons Learned</h3><ul><li><a href="https://lawsofsoftwareengineering.com/laws/galls-law/"><strong>Gall’s Law</strong></a> and the <a href="https://lawsofsoftwareengineering.com/laws/law-of-unintended-consequences/"><strong>Law of Unintended Consequences</strong></a> are real. A working complex system is always built from a working simple system. We had a working system; someone else made it complex without understanding the invariants.</li><li>Tests that pass don’t mean the contract is honored. We had tests, but they were modified to match the new code rather than the original endpoint behavior.</li><li>Communication is a technical requirement, not a soft skill. When you build bridges between systems, you must over-communicate the constraints or someone will burn the bridge without knowing it.</li></ul><h3>Project 2: No Time, Too Many Responsibilities — Databricks + ThoughtSpot</h3><h3>The Challenge</h3><p>By this point, the team had been gutted by layoffs. We were operating under severe <a href="https://lawsofsoftwareengineering.com/laws/bus-factor/"><strong>bus factor</strong></a> conditions: too many responsibilities, not enough people, and zero margin for error. The challenge was to integrate <a href="https://www.databricks.com/">Databricks</a> and <a href="https://www.thoughtspot.com/">ThoughtSpot</a> to deprecate our legacy reporting stack. The catch? These were new technologies for everyone, requirements were fuzzy, and the business needed something “<em>viable to sell</em>” before we had clarity on what “<em>viable</em>” actually meant.</p><h3>The Approach</h3><p>We treated every initiative as an MVP (<a href="https://lawsofsoftwareengineering.com/laws/galls-law/"><strong>Gall’s Law</strong></a> again). If a requirement wasn’t clear, we marked it as <a href="https://lawsofsoftwareengineering.com/laws/yagni/"><strong>YAGNI</strong></a>. We lived by the <a href="https://lawsofsoftwareengineering.com/laws/ninety-ninety-rule/"><strong>Ninety-Ninety Rule</strong></a>: the first <strong>90% </strong>of the work takes <strong>90%</strong> of the time, and the remaining <strong>10%</strong> takes the other <strong>90%</strong>. That meant we scoped aggressively and refused to gold-plate. Because we knew requirements would shift, we held an unusually high bar for code quality:</p><ul><li><strong>TDD</strong> so changes were covered.</li><li><strong>Service Objects</strong> and tight encapsulation so business logic was isolated.</li><li><strong>YARD</strong> and <strong>OpenAPI</strong> documentation so the next person (likely us, three months later, at 2 a.m.) could understand the intent. I worked shoulder-to-shoulder with QA, Frontend, and the Data Team. The underlying principle was clear: we had to understand the business value perfectly, explain it to managers, and protect the product from our own exhaustion.</li></ul><h3>My Role</h3><p>Engineer, architect, and part-time PM. I translated ambiguity into implementable plans, defended time for quality, and built internal tooling to keep us moving without cutting corners.</p><h3>The Impact</h3><p>The migration completed seamlessly, successfully enabling enterprise reporting capabilities and corporate organization provisioning without causing production downtime — up to my last day. The time pressure also forced me to build a personal project, <a href="https://github.com/igmarin/rails-agent-skills">rails-agents-skills,</a> that let me accelerate development without sacrificing the standards we had set.</p><h3>Lessons Learned</h3><ul><li>When resources are scarce, clarity beats cleverness. <a href="https://lawsofsoftwareengineering.com/laws/yagni/"><strong>YAGNI</strong></a> isn’t laziness; it’s survival.</li><li>Quality standards (<strong>TDD</strong>, code documentation, encapsulation) are force multipliers when you’re underwater. They slow you down for a day and save you for a month.</li><li>You cannot outsource understanding the business value. If you can’t explain why a feature matters to the company’s bottom line, you don’t know what you’re building.</li></ul><h3>Project 3: The Hardest Lesson Was AI — But Not in the Way You Think</h3><h3>The Challenge</h3><p>In <strong>2024</strong>, we held a hackathon. GitHub was about to re-leased AI-powered code reviews, and we wanted to build something similar internally. I’m a “<em>learn by doing</em>” person — stubborn, hands-on, not great at reading manuals. So my teammate and I decided to wire OpenAI (GPT-3.5 or 4, I don’t recall) into our PR workflow. The challenge wasn’t the code. It was the organizational fear. Within hours of our demo, Legal knocked on our door. They were worried the AI would train on our proprietary code. We explained we were using deprecated repos and synthetic diffs, but the tension was instructive:</p><blockquote><strong>AI wasn’t just a technical shift; it was a cultural and legal one</strong>.</blockquote><h3>The Approach</h3><p>In 24 hours, we built a GitHub Action that sent a PR diff to the OpenAI API and returned a code review with suggestions. I learned about temperature, prompt engineering, and the simple truth that it was still just an API call: payload in, response out. We won the hackathon. A year later, another hackathon. This time we explored MCP (Model Context Protocol) to let engineers ask natural-language questions about business workflows. I was intrigued, but I was also exhausted. I ended my workdays drained and couldn’t muster the energy to sit at a computer and learn more. Then, right before I left the company, I started using Codex. I finally understood how it connected to GitHub (branch creation), Jira (ticket ingestion), and other services. And I realized my hardest lesson:</p><blockquote><strong>I had seen this wave coming two years ago, and I let fatigue stop me from riding it.</strong></blockquote><h3>The Impact</h3><ul><li>We won both hackathon and made enough noise that the company had to grapple with AI policy early.</li><li>I built <a href="https://github.com/igmarin/rails-ai-bridge">rails-ai-bridge</a>: a Ruby gem that adds enterprise-grade authentication to MCP servers, because every solution we saw lacked the security needed for real corporate use.</li><li>I built <a href="https://github.com/nebulaideas/rs-guard">rs-guard</a>: a Rust project that uses low-cost models (DeepSeek, Qwen, Kimi) to validate code changes cheaply.</li><li>I built <a href="https://github.com/igmarin/ruby-core-skills">ruby-core-skills</a> an evals project in Ruby to measure code quality systematically.</li><li>And finally <a href="https://github.com/igmarin/agnostic-planning-skills">agnostic-planning-skills</a>.</li></ul><h3>Lessons Learned</h3><ul><li><a href="https://lawsofsoftwareengineering.com/laws/boy-scout-rule/"><strong>The Boy Scout Rule</strong></a>: leave the code better than you found it. These personal projects are my way of doing that for the wider ecosystem.</li><li>Trust your intuition. If something tells you “<strong>this is the path</strong>,” listen. I knew AI was the path two years ago; I just didn’t have the bandwidth to walk it. I’m walking it now.</li><li>Fatigue is real, but so is regret. Give yourself rest, but don’t let rest become avoidance.</li></ul><h3>Closing</h3><p>My previous endeavour was never just a job to me. Every decision I made, no matter how small, I understood had consequences — for the product, for our clients, for my teammates, and for myself. That sense of ownership wasn’t assigned to me. I chose it. And I’d choose it again. To my former teammates — <strong>Mumo, Aleksandr, Callie, Lester, Victor, Bo </strong>and so many others — you made this hard to leave. Every one of these projects has your fingerprints on it, even if your name isn’t in the commit log. To anyone in the job market right now: the rejections hurt. The silence hurts. But you are not your last interview. You are the sum of the problems you’ve solved, the teams you’ve lifted, and the code you’ve left behind. Keep going. If you want to talk shop, compare notes on AI tooling, or just vent about the market, reach out.</p><p><em>Ismael Marín</em></p><p><a href="https://www.linkedin.com/in/ismaelmarin/">LinkedIn</a> | <a href="https://github.com/igmarin">GitHub</a> | <a href="/service/mailto:ismael.marin@gmail.com">ismael.marin@gmail.com</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1a36a257e540" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Skills vs. Evals: A Hard Architectural Lesson Tessl Forced Me to Learn]]></title>
            <link>https://medium.com/@igmarin/skills-vs-evals-a-hard-architectural-lesson-tessl-forced-me-to-learn-d891d0107308?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/d891d0107308</guid>
            <category><![CDATA[tessl]]></category>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[agentic-workflow]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Mon, 08 Jun 2026 00:45:50 GMT</pubDate>
            <atom:updated>2026-06-08T00:45:50.946Z</atom:updated>
            <content:encoded><![CDATA[<p>Not gonna lie — I’m the kind of person who starts building before reading the manual. I get an idea, I jump in, I see if it works, and I iterate until it doesn’t. Then, and only then, do I go back and check the references, blog posts, books, or whatever tells me how I was supposed to do it “the right way.” This is one of those stories.</p><p>A few months back I wrote about optimizing a single <a href="https://medium.com/@igmarin/from-static-prompts-to-production-agents-my-journey-with-tessl-and-ai-skills-138521d880da">Rails agent-skills library with Tessl</a>. One giant repo with 41+ skills, workflows, MCP integration, docs — the whole kitchen sink. I got it to 96.4% and thought I was done.</p><p>Nope. The real work started when I tore the whole thing apart.</p><h3>The Monolith Was a Trap</h3><p>That original repo had everything mushed together: Rails-specific skills, Ruby core patterns, Hanami/dry-rb conventions, planning workflows, ticket generation. It scored okay as a unit, but maintaining it was a mess. Every time I touched a Rails skill, I risked bleeding context into planning lanes. The evals were noisy because the tile was trying to be everything to everyone.</p><p>So I split it into four focused repos:</p><ul><li><a href="https://github.com/igmarin/rails-agent-skills">rails-agent-skills</a> — Rails-specific agent behaviors</li><li><a href="https://github.com/igmarin/ruby-core-skills">ruby-core-skills</a> — Pure Ruby patterns and process skills</li><li><a href="https://github.com/igmarin/hanakai-yaku">hanakai-yaku</a> — Hanami, dry-rb, and ROM conventions</li><li><a href="https://github.com/igmarin/agnostic-planning-skills">agnostic-planning-skills</a> — Project planning, ticket definition, feature breakdown</li></ul><p>This wasn’t just “organizational hygiene.” It completely changed how the skills behave in evals. When the agent loads a focused tile, it doesn’t get confused by overlapping contexts. The baseline scores stabilized because the first sentence of every description maps to a coherent domain.</p><h3>The First Sentence Is the Whole Game</h3><p>Here’s the thing nobody tells you when you start writing <a href="https://tessl.io/">Tessl</a> skills: in baseline eval mode, the agent only sees the first sentence of your description field. Full stop. The rest of your beautiful SKILL.md, your examples, your assets — invisible until the agent explicitly loads the skill.</p><p>The regex is /(?&lt;=[.!?])\s+/. It splits on the first period, exclamation, or question mark followed by whitespace. So if you write:</p><pre>description: &gt;<br>  Create service classes with .call pattern. Spec at spec/services/...</pre><p>The agent only sees: <em>“Create service classes with .call pattern.”</em> Everything after that first period? Gone. Not in the task prompt. Not part of the baseline signal.</p><p>This hit me hard. I had skills scoring 19% baseline that were actually well-written — the agent just didn’t know what game it was playing.</p><h3>The Fix: Before and After</h3><p>Here’s what my descriptions looked like when I was clueless:</p><p>Before (scoring 19% baseline):</p><pre>description: &gt;<br>  Use this skill when creating service objects in Ruby. <br>  Follows the .call pattern. Includes testing conventions.</pre><p>The agent sees: <em>“Use this skill when creating service objects in Ruby.”</em> That’s it. It doesn’t know about .call, doesn&#39;t know about test placement, doesn&#39;t know about the response contract.</p><p>After (scoring 85% baseline):</p><pre>description: &gt;<br>  Use when creating service classes with `self.call` entry point,<br>  `{success:, response:}` response contract, spec at `spec/services/...`,<br>  `UPPER_SNAKE_CASE` error constants, mandatory module README, and test BEFORE<br>  implementation. Covers 4 core patterns.</pre><p>One long sentence. Commas, colons, backticks. No period until the very end. The agent now gets the full algorithm in the task prompt.</p><h3>The Gotchas</h3><p>I burned myself a few times on details that seem trivial but break the whole sentence:</p><p>The ... trap: { ... } inside backticks looks fine, but the regex sees that third dot followed by a space as a sentence end. So { ... } }splits mid-expression. I now write {...} with no space.</p><p>Question marks in method names: should_calculate? is fine (no trailing space), but if you accidentally write should_calculate? with a space, it splits there.</p><p>The 1024-character wall: There’s a hard limit. Backtick-heavy descriptions burn through characters fast. I now use + instead of &quot;and,&quot; trim connectors, and keep trigger words <em>after</em> the first period where they don&#39;t consume task-prompt space.</p><p>The results were immediate. Across the repos, baseline averages jumped from <strong>54</strong>% to <strong>87</strong>%. Some skills went from <strong>20</strong>% to <strong>97</strong>%. It wasn’t about adding more knowledge to the body — it was about making sure the agent knew the rules before the clock started.</p><h3>Why Hanami/dry-rb Deserves Its Own Repo</h3><p>The Hanami stack is the reason I split the repos in the first place. Hanami, dry-rb, and ROM have completely different conventions from Rails, but they live in the same Ruby ecosystem. When they were mixed into a single tile, the agent would default to Rails patterns because those were more heavily represented in the context.</p><p>hanakai-yaku (the name is a play on “hanami” + “yaku” from Japanese role terminology) covers 37 skills specific to the dry ecosystem:</p><ul><li>dry-monads for result types (Success, Failure)</li><li>ROM repositories instead of ActiveRecord</li><li>dry-validation schemas for params</li><li>Hanami actions with dependency injection</li><li>Slice-based architecture and provider registration</li></ul><p>These aren’t just “Rails without Rails.” The patterns are fundamentally different. A Rails skill might say “use before_action for auth,&quot; but a Hanami action needs dependency injection of an authenticator: in the slice. A Rails model might use has_many, but ROM uses explicit relation definitions with custom mappers.</p><p>Having a dedicated tile means the baseline evals test the agent against the <em>correct</em> conventions. No more defaulting to ActiveRecord because it’s the loudest signal in a mixed context. The scores stabilized around 92%+ once the descriptions were tightened to mention dry-monads, ROM relations, and Hanami slices explicitly in that first sentence.</p><p>If you’re building skills for a non-dominant framework, this is the lesson: don’t let your skills compete with the default mental model. Give them their own tile and their own first sentence.</p><h3>The Iteration Protocol</h3><p>Once the repos were split and descriptions were tight, I needed a real system for iterating. I couldn’t just throw darts at low scores anymore.</p><p>I generate explicit iteration plans for each repo. Instead of “fix whatever scores lowest,” I look at stable anchors — skills that are consistently low across multiple 3-run Sonnet evals — and classify their failures:</p><ul><li><strong>Missing instruction in the first sentence? </strong>→ Fix description</li><li><strong>Missing output evidence the grader can see?</strong> → Fix Output Style contract</li><li><strong>Scenario-specific trap?</strong> → Deeper redesign, don’t just patch</li><li><strong>Bad eval criterion?</strong> → Fix the eval, not the skill</li></ul><p>Then I batch changes in groups of six. Big enough to move the aggregate, small enough to bisect if something regresses. I run single evals for fast iteration, but I never make release decisions without three Sonnet runs. Compare means, compare per-skill minimums, compare variance.</p><p>The key discipline: batch for signal, decide per skill. A batch can improve your overall score and still contain changes you should throw away immediately. I keep the winners, revert the losers, and re-evaluate the exact kept state. No guessing.</p><h3>Where Things Stand Now</h3><p>All four repos are sitting above 92%. But honestly, the percentage isn’t the interesting part anymore.</p><p>What’s actually cool is the lift — the gap between with-context and without-context scores. If a baseline model already knows how to do something, your skill isn’t adding value. It’s just documentation. The real win is when the model is lost without your skill and nails it with your skill.</p><p>You can see the actual registry entries on <a href="https://tessl.io/">Tessl.io</a>:</p><ul><li><a href="https://tessl.io/registry/igmarin/agnostic-planning-skills">agnostic-planning-skills</a></li><li><a href="https://tessl.io/registry/igmarin/rails-agent-skills">rails-agent-skills</a></li><li><a href="https://tessl.io/registry/igmarin/ruby-core-skills">ruby-core-skills</a></li><li><a href="https://tessl.io/registry/igmarin/hanakai-yaku">hanakai-yaku (aka Hanami ecosystem skills)</a></li></ul><p>That registry link matters because it’s not just me saying “<strong>trust me, it works.</strong>” It’s the actual eval results, public and reproducible.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gXLRiar9gaYgMuzCP5mKeQ.png" /><figcaption><a href="https://github.com/igmarin/ruby-core-skills/blob/main/docs/skill-description-strategy.md">Check the secret plan to improve skills using Tessl evals</a></figcaption></figure><h3>What I Actually Do Differently Now</h3><p>A few concrete habits that came out of this mess:</p><p>I don’t broad-refactor during eval work. Six skills at once is my max. More than that, and when the aggregate moves, you have no idea who to blame.</p><p>I optimize the receipt, not the essay. The skill body can be beautiful prose, but if the final artifact doesn’t show the grader visible proof — failing spec, command, expected error, passing rerun — it doesn’t matter what the model “knew internally.”</p><p>I keep hard gates in SKILL.md, not in support files. Progressive disclosure is great for reference material, but if the critical behavior lives only in an example file the agent might not load, you’re gambling.</p><p>I retire skills instead of endlessly optimizing them. I had a temporary build skill that was a bridge artifact from an old layout. It was scoring <strong>90%</strong>, but keeping it was cluttering the taxonomy. I killed it. The cleaned surface actually jumped because the remaining skills were coherent.</p><p>I validate descriptions with a Ruby one-liner before every eval. 1024-character limit, enforced at eval time. I check it every time:</p><pre>ruby -ryaml -e &#39;<br>md = File.read(&quot;skills/&lt;category&gt;/&lt;skill&gt;/SKILL.md&quot;)<br>_, yaml, _ = md.split(/^---\s*$/, 3)<br>puts YAML.safe_load(yaml)[&quot;description&quot;].length<br>&#39;</pre><p>I update companion files when I update SKILL.md. If the skill teaches the model to load assets/release_checklist.md, but that file still has old guidance, the agent follows the skill and then gets contradicted by the asset. I fix both.</p><h3>The Real Lesson</h3><p>The original article was about optimizing one repo. This phase taught me that skill libraries are products, not documents.</p><p>You need focused domains. You need ruthless first-sentence engineering. You need an iteration protocol — single runs for speed, triple runs for confidence, never mix the two when making decisions. And you need the discipline to revert things that don’t work, even if you spent two hours writing them.</p><p>Tessl forces you to stop writing skills for human readers and start writing them for agent behavior. The score is just the receipt that proves the behavior changed.</p><p><strong>Resources</strong></p><ul><li><strong>GitHub</strong>: <a href="https://github.com/igmarin">github.com/igmarin</a></li><li><strong>My Tessl skills</strong>: <a href="https://tessl.io/registry/igmarin">https://tessl.io/registry/igmarin</a></li><li>My secret plan to improve skills: <a href="https://github.com/igmarin/rails-agent-skills/blob/main/docs/skill-optimization-guide.md">skill-optimization-guide.md</a></li></ul><blockquote><em>all skills are MIT licensed. Built by </em><a href="https://ismaelmarin.dev/"><em>Ismael Marin.</em></a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d891d0107308" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your Rails App Finally Speaks AI: A Deep Dive into rails-ai-bridge]]></title>
            <link>https://medium.com/@igmarin/your-rails-app-finally-speaks-ai-a-deep-dive-into-rails-ai-bridge-051dbe728b1e?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/051dbe728b1e</guid>
            <category><![CDATA[mcp-server]]></category>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[rubygems]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Mon, 08 Jun 2026 00:06:09 GMT</pubDate>
            <atom:updated>2026-06-08T00:09:23.873Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Z8uDrao37JIosWTiSG0XGA.png" /></figure><blockquote><em>A practical guide to the gem that turns your Rails app into a first-class context source for Claude, Cursor, Devin, Copilot, Codex, and Gemini — from zero to the new 3.5.0 skill registry.</em></blockquote><h3>The problem nobody talks about enough</h3><p>You open your AI assistant, drop in a task, and it starts writing code. The code looks plausible. Then you actually read it: wrong column names, a route that doesn’t exist, a service object that duplicates one you already wrote. You spend the next ten minutes explaining your app instead of shipping a feature.</p><p>This is not a model intelligence problem. It is a context problem. The AI is smart. It just doesn’t know your app.</p><p>Dropping your entire schema.rb into the chat helps, sometimes. But it&#39;s clunky, it fills context fast, and the second you merge a migration it&#39;s already stale. What you actually want is an AI that walks into your codebase the way a good senior developer does: knowing the shape of the data, the conventions the team follows, where the busy controllers live, and which models are the real domain core.</p><p>That’s what rails-ai-bridge is.</p><h3>What it does, in plain language</h3><p>The gem has two jobs.</p><p><strong>First</strong>: it reads your Rails app and generates compact, structured files that each AI tool knows how to pick up automatically — CLAUDE.md for Claude Code, .cursor/rules/ for Cursor, AGENTS.md for Codex and Devin, .github/copilot-instructions.md for Copilot, and so on. One command, multiple formats, each one shaped around what that specific tool expects.</p><p><strong>Second:</strong> it runs a read-only MCP server that AI clients can query on demand. Instead of pasting your whole schema, the assistant calls rails_get_schema(table: &quot;orders&quot;) and gets exactly what it needs, right now, from your live app.</p><p>Together these two layers mean the assistant starts every session already knowing your app, and has a clean way to ask precise questions when it needs more detail.</p><h3>The timeline: how it grew</h3><p>Looking back at the commit history, the velocity of how this gem evolved surprised even me. It wasn’t designed in a vacuum; it was built live, in the open, driven entirely by the friction of trying to make AI agents actually useful on real-world Rails apps. Here is the arc of how a simple tool grew into an ecosystem.</p><p><strong>March 2026–0.1.0 through 0.6.0</strong>: The early days were absolute chaos — in a good way. The initial releases shipped fast, sometimes multiple versions in a single day, because I was actively using the gem in production projects and immediately fixing whatever broke. These early releases established the absolute core loop: schema introspection, model associations, basic routing tables, a handful of raw MCP tools, and rudimentary file generation for Claude and Cursor.</p><h3>Timeline Overview</h3><p>For a complete visual breakdown of our architectural progression from inception to our latest features, see the generated timeline figure below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3Jn9X28HL0PdmlxyZ8D8bA.png" /><figcaption>rails-ai-bridge histogram</figcaption></figure><p><strong>0.5.0</strong> — The First Clean: This was the first major inflection point where the internal mechanics had to catch up with the feature set. Two big architectural decisions happened here. First, I ripped out 47 explicit require_relative calls and dropped in standard Zeitwerk autoloading—meaning new introspectors just needed to exist in the right directory to work. Second, I introduced introspector presets: :standard (fast, 9 core components) and :full (all 26+). You pick the footprint based on how heavy your app is.</p><p><strong>1.0.0</strong> — A Pivot in Philosophy: This version came with a rebrand. I renamed the project from rails-ai-contextto rails-ai-bridge. It sounds subtle, but it marked a massive shift in my own philosophy: this tool wasn&#39;t just about dumping dead text context files anymore; it was about building a living, bidirectional bridge between Rails structures and AI reasoning.</p><p><strong>2.0.0</strong> — Moving to Production Grade: The MCP path over HTTP got serious security controls. I added proper bearer token authentication, rate limiting, structured JSON logging, and production boot guards. This was also the moment the internal code got a proper refactoring: the massive Configuration class was broken apart, becoming a clean facade over focused sub-objects like Config::Auth, Config::Server, and Config::Mcp.</p><p><strong>2.2.0</strong> — Surviving Large Codebases: If you throw alphabetical model context at an LLM, a minor join table like AdminRole gets prime real estate over your core Order model just because of the letter A. 2.2.0 introduced semantic model classification. Every model automatically gets assigned a tier (core_entity, rich_join, pure_join, or supporting) so the AI inherently understands your domain&#39;s real center of gravity.</p><p><strong>3.0.0</strong> — Streamlining the UX: I removed the standalone CLI binary entirely to keep things clean and leaned completely into native Rake tasks. Along with it came an interactive install generator with distinct environment profiles (minimal, full, custom, mcp).</p><p><strong>3.3.0</strong> — Concept over Text: Integration with rubydex. Regular text search fails when an AI is looking for patterns instead of exact strings. By embedding a semantic code graph on top of standard search, the assistant could finally look for code by concept (e.g., searching for &quot;<em>payment processing</em>&quot; and successfully surfacing controllers or webhooks that don&#39;t explicitly contain those exact words).</p><p><strong>3.4.0</strong> — Tuning the Engine: Performance work and freshness tracking. I moved the introspection engine to run in parallel, added SHA-256 freshness headers to stop Git noise from rewriting identical files on every save, and optimized rubydex to use incremental index caching based on file modifications.</p><p><strong>3.5.0</strong> (Current) — The Skill Registry: This brings us to where the project stands today. We built a whole new subsystem to handle structured AI skill packs—essentially turning the gem into a package manager for AI instructions.</p><h3>Installing it</h3><p>Getting up and running takes two commands:</p><pre>bundle add rails-ai-bridge<br>rails generate rails_ai_bridge:install</pre><p>The generator walks you through an install profile interface:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1006/1*p6anf_5NltiSnUqu4gdBmw.png" /><figcaption>rails generate rails_ai_bridge:install</figcaption></figure><p>The generator runs as an interactive prompt right in your terminal, letting you pick a profile that matches your workflow:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/747/1*gAqGhzQOgpJUC0GmXdypOA.png" /><figcaption>Installation options</figcaption></figure><p>Once the setup completes, your primary tool belt consists of three Rake tasks:</p><pre>rails ai:bridge      # generate all context files<br>rails ai:serve       # start the MCP stdio server<br>rails ai:doctor      # health check + readiness score</pre><h3><strong>What actually gets generated?</strong></h3><p>When you run rails ai:bridge, it compiles your Rails architecture into a highly predictable directory structure tailored to the strict limits and formatting quirks of each specific tool:</p><pre>your-rails-app/<br>├── CLAUDE.md                            ≤150 lines, Claude Code<br>├── .claude/rules/<br>│   ├── rails-context.md                 semantic model tier summary<br>│   ├── rails-schema.md                  table listing<br>│   ├── rails-models.md                  models with tiers<br>│   └── rails-mcp-tools.md               full tool reference<br>│<br>├── AGENTS.md                            Codex + Devin<br>├── .codex/README.md<br>│<br>├── .cursor/rules/<br>│   ├── rails-engineering.mdc            alwaysApply: true<br>│   ├── rails-project.mdc                alwaysApply: true<br>│   ├── rails-models.mdc                 globs: app/models/**<br>│   └── rails-controllers.mdc            globs: app/controllers/**<br>│<br>├── .devinrules                          ≤5,800 chars (Devin&#39;s 6K limit)<br>├── .devin/rules/<br>│<br>├── .github/copilot-instructions.md      ≤500 lines<br>├── .github/instructions/<br>│<br>├── GEMINI.md<br>│<br>└── .mcp.json                            MCP auto-discovery</pre><p>The gem handles all the individual tool constraints behind the scenes. For instance, Devin’s .devinrules is aggressively capped at 5,800 characters to stay safely inside Devin’s strict 6K rule ceiling. Anthropic recommends keeping CLAUDE.md short, so we force it under 150 lines. For Cursor, it outputs .mdc files complete with the correct YAML frontmatter and directory globs so rules only trigger when the AI enters a matching path.<br>The best practice here is simple: commit all of these files. By keeping them in version control, you ensure every single person on your team is working with the exact same AI context alignment.</p><h3>The two-layer model in practice</h3><p>This is the core mental model of how the system operates. It splits the workload into two completely separate layers to balance context window limits with perfect accuracy.</p><p><strong>Layer 1 — Static files (The Blueprint):</strong> Your assistant reads the generated markdown files (like CLAUDE.md or AGENTS.md) right at the start of the session. This provides instant grounding. The AI immediately understands the general schema layout, the core domain logic, and your code conventions without needing to explore.</p><p><strong>Layer 2 — Live MCP (The Microscope):</strong> When the AI is actually deep in the code and needs exact parameters, it makes a live, on-demand tool call through the Model Context Protocol. It queries your running app in real-time to fetch the exact schema of a single table, a specific controller’s routes, or a model’s validation rules.</p><pre># The assistant can call these tools on demand:<br>rails_get_schema(detail: &quot;summary&quot;)<br># → all tables with column counts, fast<br>rails_get_schema(table: &quot;orders&quot;)<br># → full schema for orders: columns, indexes, FK constraints<br>rails_get_routes(controller: &quot;users&quot;)<br># → every route that hits UsersController<br>rails_get_model_details(model: &quot;User&quot;)<br># → associations, validations, scopes, enums, semantic tier<br>rails_search_code(pattern: &quot;before_action :authenticate&quot;)<br># → ripgrep search across your codebase<br>rails_search_semantic(query: &quot;payment processing&quot;)<br># → semantic search via rubydex</pre><p>To prevent token bloating, all of these tools accept a detail flag (&quot;summary&quot;, &quot;standard&quot;, or &quot;full&quot;). If your schema is massive, the tools support pagination natively via limit and offset, and a hard limit (max_tool_response_chars, defaulting to 120K) acts as a safety valve against massive, runaway payloads.</p><h3>Interaction Flow</h3><p>The workflow operates via two distinct phases — initial bootstrap indexing followed by targeted execution calls:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VGeRZilIJTPln_SGAlUKfg.png" /><figcaption>Static files vs Static + MCP</figcaption></figure><h3>Model semantic tiers: finding the center of gravity</h3><p>This was one of the most satisfying features to build, introduced back in 2.2.0.</p><p>A standard Rails application might have 80 models (or a huge schema but it doesn’t really tell you the real picture of the app), but only 5 or 6 of them represent the actual core domain entities where the real business logic lives. The rest are join tables, auditing logs, or supporting setup.<br>If you feed models to an LLM alphabetically, it digests them with equal importance. To fix this, I built the ModelSemanticClassifier. It&#39;s a pure Ruby object that analyzes your associations, foreign keys, and table configurations to classify your codebase into explicit tiers:</p><p>Now each model gets a tier:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/763/1*CPv5PWDU2xzFESsj6D_z1Q.png" /><figcaption>Semantic Classifier</figcaption></figure><p>If the classifier misses an edge case, overriding it is trivial:</p><pre># config/initializers/rails_ai_bridge.rb<br>RailsAiBridge.configure do |config|<br>  config.core_models = %w[Order User Product]<br>end</pre><p>When the context files are compiled, the models are grouped and listed by tier. The AI sees your domain’s real center of gravity right at the top of the file, completely bypassing the noise of thirty minor supporting tables.</p><h4><strong>Introspector presets: optimizing the footprint</strong></h4><p>With more than 26 individual introspectors running under the hood, compiling everything blindly would slow down your boot times and pollute the context window. The preset system lets you choose your footprint explicitly:</p><pre>RailsAiBridge.configure do |config|<br>  config.preset = :standard  # default: 9 core introspectors<br>  # config.preset = :full    # all 26, thorough<br>end</pre><p>The :standard configuration covers the essentials—database schemas, routing tables, models, controllers, active gems, testing configurations, and migrations. For the vast majority of projects, this is your sweet spot. From there, you can opt into specific high-utility introspectors depending on your setup:</p><pre>config.introspectors += [:database_stats, :non_ar_models]</pre><p>For example, database_stats is completely opt-in because it runs live queries against pg_stat_user_tables (which you might want to avoid running in certain environments). Meanwhile, non_ar_models lets the engine sweep through app/models to find plain old Ruby objects (POROs) or service objects that don&#39;t inherit from ActiveRecord::Base, explicitly tagging them as [POJO/Service] in the final context map.</p><h3><strong>Solving performance in 3.4.0</strong></h3><p>As the project grew, running dozens of complex introspectors sequentially quickly became a bottleneck. The 3.4.0 release was entirely focused on engineering out those performance pain points.</p><p><strong>Parallel execution:</strong> Introspectors now run concurrently inside a Concurrent::FixedThreadPool. The pool size defaults to 4 (config.parallel_pool_size), and each introspector operates under a strict wall-clock timeout budget of 10 seconds (config.parallel_timeout_seconds). If a highly complex introspector stalls out, it won&#39;t block the rest of the application boot; it gracefully times out and logs an isolated error payload.</p><p><strong>Freshness tracking:</strong> To kill unnecessary Git diff noise, generated files now include a SHA-256 fingerprint generated from your db/schema.rb and config/routes.rb. When you trigger a build, if the underlying schema or routing state hasn&#39;t changed, the file write is skipped completely.</p><p><strong>Incremental indexing:</strong> Building semantic code indexes can be heavy. The rubydex integration uses strict file system mtime tracking to only re-index files that have been modified since the last execution. A full, heavy rebuild is only triggered if a major migration or branch switch touches more than 30% of the codebase at once.</p><p><strong>Cache warming:</strong> By setting config.cache_warm_on_boot = true, the entire internal introspection state is compiled and held in memory right when your Rails application boots. This completely eliminates the cold-start performance penalty on your very first live MCP request.</p><h3>Rubydex: d<strong>eep semantic code search</strong></h3><p>Integrated natively in 3.3.0 and optimized for incremental execution in 3.4.0, the rails_search_semantic tool uses the <a href="https://github.com/shopify/rubydex">rubydex</a> engine to build an in-memory conceptual graph of your Ruby source files.<br>Standard text search or grep lookups break down the moment an AI searches for a concept instead of an exact keyword. Semantic search resolves this by looking at programmatic intent:</p><pre>rails_search_semantic(query: &quot;payment processing&quot;)<br># Finds: PaymentService, ChargeProcessor, StripeWebhookController<br># This maps conceptual intent, not just string matches.<br><br>rails_search_semantic(query: &quot;user authentication&quot;)<br># Finds: SessionsController, AuthenticatesUser, Devise callbacks1</pre><p>If you want the indexing state to persist across separate runs or dev server restarts, you can lock it down via config.rubydex_persist_index = true.</p><h3><strong>3.5.0: the skill registry</strong></h3><p>The latest major addition to the gem is the Skill Registry. As development teams started writing highly custom prompt instructions and engineering patterns for their AIs, committing plain markdown text files into every single separate repo started feeling like an anti-pattern.<br>The Skill Registry solves this by acting like a dependency package manager, specifically built for AI prompt engineering and custom agent behaviors.</p><p><strong>The architecture<br></strong>Your application’s available skill packs are declared inside a central JSON manifest file located at config/rails_ai_bridge_registry.json:</p><pre>{<br>  &quot;version&quot;: &quot;1&quot;,<br>  &quot;packs&quot;: {<br>    &quot;rails-core&quot;: {<br>      &quot;source&quot;: &quot;https://github.com/your-org/rails-skills&quot;,<br>      &quot;always_loaded&quot;: true<br>    },<br>    &quot;payments&quot;: {<br>      &quot;source&quot;: &quot;https://github.com/your-org/payment-skills&quot;,<br>      &quot;depends_on&quot;: [&quot;rails-core&quot;]<br>    }<br>  }<br>}</pre><p>A skill pack is simply a Git repository containing a structural directory.json manifest alongside individual markdown instruction files. The engine pulls these remote packs down, manages the checkouts, and handles local file caching directly inside ~/.rails-ai-bridge/cache/. To prevent slowing down your local workflow, cached repositories are governed by a 24-hour time-to-live (config.registry.git_pull_ttl) before a new Git pull is ever attempted.</p><h3>P<strong>riority resolution and environment safety</strong></h3><p>When you have multiple custom packs defining instructions for the same technical concept, the registry uses an explicit priority resolver to decide which rule wins:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/746/1*f_ifgH-FjyUv4xCcxlGZoQ.png" /><figcaption>Skills priority order</figcaption></figure><p>The system includes a smart PackDetector that automatically parses your project&#39;s Gemfile. If it detects you&#39;re building a Hanami app versus a Rails app, it flips the framework flags and automatically resolves the correct structural packs.</p><p><strong>Daily execution tools</strong><br>The registry exposes a dedicated rails_list_registry tool straight to your MCP client:</p><pre>rails_list_registry(type: &quot;skills&quot;)<br># → returns a clean catalog of all loaded skills and descriptions<br><br>rails_list_registry(type: &quot;agents&quot;)<br># → maps out available autonomous agent profiles<br><br>rails_list_registry(type: &quot;packs&quot;)<br># → returns all active packs, their git sources, and priority states</pre><p><strong>Version control pinning</strong><br>You can pin a skill pack to an exact Git reference directly within your manifest file to prevent upstream updates from breaking your team’s prompt alignment:</p><pre>{<br>  &quot;packs&quot;: {<br>    &quot;payments&quot;: {<br>      &quot;source&quot;: &quot;github.com/your-org/payment-skills&quot;,<br>      &quot;ref&quot;: &quot;v2.1.0&quot;<br>    }<br>  }<br>}</pre><p>The internal resolver automatically executes a strict git checkout matching your tag, branch name, or raw commit SHA.</p><p><strong>Built-in security defaults</strong><br>Giving an automated AI tool deep access to a local codebase requires strict boundaries. The security model behind the gem was built to be completely defensive by default:</p><ul><li><strong>Strict Read-Only Execution:</strong> Every single native MCP tool exposed by the server is explicitly marked as non-destructive. The engine is architected purely for introspection; it does not contain code paths that write files, run migrations, or alter database states.</li><li><strong>Automated Secret Filtering:</strong> The serializers include a hardcoded regex block that automatically strips out sensitive files from ever reaching the context layer. It completely blocks .env variations, encrypted Rails credentials, master.key files, private SSH keys, and anything nested inside config/secrets. It explicitly allows config/database.yml since mapping the structural adapter type is highly useful for context alignment.</li><li><strong>Localhost Binding Safety:</strong> The HTTP server defaults strictly to 127.0.0.1. If you explicitly modify config.http_bind to expose the endpoint across an external network interface, the engine forces a strict production boot guard. It will actively refuse to initialize unless you have configured bearer tokens, custom JWT verification hooks, or an explicit authorization lambda.</li><li><strong>ReDoS Vulnerability Mitigations:</strong> The rails_search_code tool restricts lookups to a strict allowlist of development file extensions (.rb, .erb, .js, .ts, .yml). Following a vulnerability identified and closed in 3.4.0, the lookup engine places a strict character cap on incoming regex patterns to completely eliminate Regular Expression Denial of Service (ReDoS) vectors.</li><li><strong>Insecure HTTP Rejection:</strong> The 3.5.0 SourceParser enforces encryption across all remote skill registries. The engine explicitly drops and logs an error for any unencrypted http:// Git endpoints, requiring valid https:// or git@ targets.</li></ul><p><strong>Keeping context fresh in practice</strong><br>Once you have the gem configured, keeping your AI tools aligned with your development cycle comes down to a few basic workflow habits:<br>Regenerate after migrations: Make it a habit to trigger rails ai:bridge whenever you run database migrations or pull major routing updates.</p><p>Because the fingerprint system tracks files using SHA-256 hashes of schema.rb and routes.rb, unchanged context files are skipped, making the execution take fractions of a second. If you hate running things manually, you can leave rails ai:watch running in a background terminal tab to auto-compile on changes.</p><p>Write explicit local team overrides: The system automatically seeks out a local override file at config/rails_ai_bridge/overrides.md and appends its contents straight into your Copilot and Codex rules. This is the perfect spot to declare team specific design rules that can&#39;t be inferred programmatically (e.g., <em>&quot;We don&#39;t write vanilla callbacks here, use service objects&quot;</em>). Just make sure to remove the `` comment tag at the top to activate the file.</p><p>Lean on <strong>rails ai:doctor</strong>: If your AI client starts hallucinating or acting erratic, run the doctor task. It triggers 16 isolated diagnostic health checks across your environment, reports any stale context files where fingerprints don&#39;t match your live schema, and scores your project readiness on a clean 0-100 scale.</p><h3>A concrete example</h3><p>Let’s trace exactly what happens when you’re building a new checkout feature on an e-commerce platform with an open Claude Code session:</p><ol><li><strong>The Handshake:</strong> The second you open your terminal workspace, Claude boots up and instantly ingests your local CLAUDE.md. Before you type a single prompt, the AI already knows your primary core entities (Order, LineItem, User), knows you use Sidekiq for async workers, utilizes Pundit for authorization policies, and relies on Stripe for payments.</li><li><strong>The Prompt:</strong> You type: <em>“Add a refund action to the OrdersController.”</em></li><li><strong>The Live Inspection:</strong> Claude realizes it needs the structural details of your model. It instantly calls the MCP tool rails_get_model_details(model: &quot;Order&quot;), returning your exact validation rules, enum states, and through-associations in milliseconds.</li><li><strong>The Routing Verification:</strong> It calls rails_get_routes(controller: &quot;orders&quot;) to see your existing API endpoints and determines the exact HTTP verb structure needed for the new action.</li><li><strong>The Clean Code Write:</strong> It writes the controller action, appends the route, and hooks up the correct Pundit policy call perfectly on the first attempt — matching your codebase conventions without requiring a single conversational correction.</li></ol><p><strong>Who this tool is actually for</strong></p><ul><li><strong>Junior Engineers:</strong> It drastically flattens the architectural learning curve when onboarding onto a large codebase. It removes the guesswork out of <em>“where does this pattern live?”</em> and stops the AI from generating out-of-style code that violates existing design patterns.</li><li><strong>Senior Engineers:</strong> It eliminates context-bloat and manual copy-pasting. Instead of manually shoving huge snippets of schemas or routes into a chat window, the AI pulls highly isolated, atomic data points exactly when it needs them.</li><li><strong>Distributed Teams:</strong> It turns AI prompt context into a first-class engineering artifact. Your prompt rules live directly inside version control, keeping your entire engineering team perfectly in sync.</li></ul><p><strong>Resources</strong></p><ul><li>GitHub: <a href="https://github.com/igmarin/rails-ai-bridge">github.com/igmarin/rails-ai-bridge</a></li><li>RubyGems: <a href="https://www.google.com/search?q=https://rubygems.org/gems/rails-ai-bridge">rubygems.org/gems/rails-ai-bridge</a></li><li>Best practices guide: <a href="https://github.com/igmarin/rails-ai-bridge/blob/main/docs/BEST_PRACTICES.md">docs/BEST_PRACTICES.md</a> in the repo</li><li>MCP security: <a href="https://github.com/igmarin/rails-ai-bridge/blob/main/docs/mcp-security.md">docs/mcp-security.md</a></li><li>Skill registry guide: <a href="https://github.com/igmarin/rails-ai-bridge/blob/main/docs/skill-registry-guide.md">docs/skill-registry-guide.md</a></li></ul><p><em>rails-ai-bridge is MIT licensed. Built by </em><a href="https://ismaelmarin.dev/"><em>Ismael Marin.</em></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=051dbe728b1e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How I Built a Composable AI Skill Ecosystem for Ruby — With Help From 4 Different AI Agents]]></title>
            <link>https://medium.com/@igmarin/how-i-built-a-composable-ai-skill-ecosystem-for-ruby-with-help-from-4-different-ai-agents-009d72a9d179?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/009d72a9d179</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[rust]]></category>
            <category><![CDATA[mcp-server]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Tue, 26 May 2026 06:07:51 GMT</pubDate>
            <atom:updated>2026-05-26T06:07:51.049Z</atom:updated>
            <content:encoded><![CDATA[<p><em>A story about 85 skills, 6 repos, a Rust CLI, and the messy reality of making AI coding assistants actually useful.</em></p><p>I’ve been building something I call <strong>AI agent skills</strong> for about a year now. The idea is simple: instead of prompting an AI assistant with a generic “write me a Rails controller,” you hand it a structured <strong>skill</strong> — a detailed instruction set with hard gates, examples, and conventions. It forces the AI to write code <em>the way your team actually writes code</em>.</p><p>It started small. One repo. A dozen skills. Then it grew. And grew. Before I knew it, I was looking at 85 skills scattered across 3 repos, 23 agents, and a naming collision problem that was slowly eating my development environment alive.</p><p>This is the story of how I untangled that mess — and how I orchestrated <strong>four different AI agents</strong> working in parallel to do the heavy lifting.</p><h3>The Problem: Success Creates Chaos</h3><p>Here’s a snapshot of what my skill ecosystem looked like before the refactor:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UMgRZ_nVQefDQAfNGGgozA.png" /><figcaption>The Initial Mess</figcaption></figure><p>If you look closely, the cracks are obvious. <a href="https://github.com/igmarin/rails-agent-skills">rails-agent-skills</a> and <a href="https://github.com/igmarin/hanakai-yaku">hanakai-yaku</a> both had identical skills like <a href="https://github.com/igmarin/rails-agent-skills/tree/2fa8a2766cdc947b44402be196ffcf584ea03316/skills/code-quality/code-review">code-review</a>, <a href="https://github.com/igmarin/hanakai-yaku/tree/dc5b124f8905c60badb4f705856589f5659921d7/skills/refactor-code">refactor-code</a>, <a href="https://github.com/igmarin/rails-agent-skills/tree/2fa8a2766cdc947b44402be196ffcf584ea03316/skills/testing/plan-tests">plan-tests</a>, and <a href="https://github.com/igmarin/rails-agent-skills/tree/2fa8a2766cdc947b44402be196ffcf584ea03316/skills/testing/triage-bug">triage-bug</a>. These skills aren&#39;t Rails-specific or Hanami-specific—they&#39;re just foundational <em>Ruby</em>workflows. But they lived inside framework-specific repos because that&#39;s where they happened to be born.</p><p>This setup triggered three massive headaches:</p><ol><li><strong>Naming collisions:</strong> If I loaded both repos, I ended up with two competing code-review skills. Figuring out which one won was a coin toss.</li><li><strong>Divergent evolution:</strong> I’d fix a bug or improve triage-bug in the Rails repo, but forget to update the Hanami version. Suddenly, my workflows were drifting apart.</li><li><strong>Zero composition:</strong> The planning skills had no idea the framework skills existed. The framework repos were completely blind to each other. Everything was trapped in a silo.</li></ol><p>I needed a real architecture.</p><h3>The Approach: Plan Once, Execute in Parallel</h3><p>Let’s be real: token budgets aren’t infinite (even more if I am currently un-employed), but my ambitions are and you know when you have that plan in your head you need to make it real.</p><p>To pull this off without blowing a hole in my wallet, I came up with a pipeline strategy: use a high-tier agent as the architect (<a href="https://devin.ai/">https://devin.ai/</a>) and code reviewer (<a href="https://devin.ai/">https://devin.ai/</a> &amp; <a href="https://www.coderabbit.ai/">https://www.coderabbit.ai/</a>), then execute the grunt work in parallel using lighter, faster command-line agents working from standalone Markdown playbooks (<a href="https://antigravity.google/product/antigravity-cli">Gravity CLI aka Gemini</a>, <a href="https://deepseek.com/">DeepSeek</a> &amp; <a href="https://opencode.ai/go?ref=XWPTPPPRR6">Opencode Go</a>)</p><p>Here is how the workflow actually played out:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*29T5-45B6RJW4ICq3m5HYA.png" /><figcaption>Parallel Execution Loop</figcaption></figure><p>The secret sauce here was making <strong>each phase document completely self-contained</strong>. Every playbook had exact file paths, context snippet blocks, verification checklists, and strict “done” criteria baked right in. Any AI agent could pick up a playbook and execute it flawlessly without needing a massive, expensive conversation history to understand what was going on.</p><h3>The Architecture: 6 Repos, 1 Runtime</h3><p>After a lot of back-and-forth (and a few middle-of-the-night pivots), here is the architecture we landed on:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*A-chYU_fQ2QvcRPhv8HAww.png" /><figcaption>Target V3 Architecture</figcaption></figure><p>The magic lies in how seamlessly it all connects:</p><h3>1. The Runtime Auto-Detects Your Stack</h3><p>Instead of dealing with annoying configuration files or manual flags, you just pass your task straight to the terminal:</p><pre># Just tell it what to do. It figures out the rest.<br>agent-mcp-runtime --task &quot;Add full_name to User model&quot;</pre><p>The Rust runtime instantly parses your Gemfile. If it sees gem &#39;rails&#39;, it dynamically injects the Rails pack. If it detects gem &#39;hanami&#39;, it pulls in the Hanami pack. If you&#39;re crazy enough to run both, it loads both. Meanwhile, the <a href="https://github.com/igmarin/ruby-core-skills">ruby-core-skills</a> pack is <em>always</em> loaded as the baseline. No tedious flags required. It just works.</p><h3>2. Skills Compose Like LEGO</h3><p>Here is a look at how the Rails <a href="https://github.com/igmarin/ruby-core-skills/tree/main/skills/planning/generate-tdd-tasks">TDD</a> agent behaves under the hood:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Gmrz9dDekrL8WZ-tK7DClw.png" /><figcaption>Skill Composition Workflow</figcaption></figure><p>Notice how tdd-process (sourced straight from ruby-core-skills) slots smoothly into steps 4 and 6. That&#39;s the beauty of shared process discipline. The hard rule—<em>&quot;a test must exist and fail before you write a single line of implementation&quot;</em>—is identical whether you&#39;re writing Rails or Hanami. The <em>process</em> is completely shared; the <em>framework implementation quirks</em>stay isolated locally.</p><h3>3. Deprecation Aliases Protect Against Breaking Changes</h3><p>Moving triage-bug out of rails-agent-skills and into ruby-core-skills shouldn&#39;t mean breaking everyone&#39;s existing environments. We left a forwarding address in the configuration:</p><pre>{<br>  &quot;deprecated_skills&quot;: {<br>    &quot;triage-bug&quot;: {<br>      &quot;moved_to&quot;: &quot;igmarin/ruby-core-skills&quot;,<br>      &quot;message&quot;: &quot;Bug triage has moved to ruby-core-skills.&quot;,<br>      &quot;removed_in&quot;: &quot;7.0.0&quot;<br>    }<br>  }<br>}</pre><p>If an legacy agent tries to call the old location, the runtime quietly handles the redirect behind the scenes and prints a clear deprecation warning. Clean migration, zero friction.</p><h3>The Decisions That Mattered</h3><p>Building this ecosystem forced me to make a few non-obvious engineering trade-offs.</p><h3>Should auto-detect the framework or force users to flag it?</h3><p>I initially built the runtime expecting explicit --pack rails flags. It felt safe, explicit, and rigorous. But the moment I started dogfooding it, I realized it was pure friction. Your Gemfile isn&#39;t a guess—it’s an explicit project manifest. Reading it automatically is just as reliable as a manual CLI flag, but saves you from typing the same flag a hundred times a day.</p><p><strong>The takeaway:</strong> Sometimes what we call “engineering rigor” is just us being too lazy to automate the obvious.</p><h3>Should it be generic agents or generic skills?</h3><p>This was a massive fork in the road. The temptation to build a single, beautiful ruby-agents repo with a universal tdd agent was incredibly strong.</p><p>But consider what an active TDD agent actually needs to know to do its job:</p><ul><li>Which test runner are we using? (rspec or minitest?)</li><li>What setup conventions are we following? (FactoryBot or core fixtures?)</li><li>What commands do we run to verify? (bundle exec rspec?)</li></ul><p>A generic TDD agent without framework context is like a world-class chef dropped into an empty kitchen. They know <em>how</em> to cook conceptually, but they can’t actually feed anyone.</p><p><strong>The solution:</strong> Share the <em>discipline</em>, keep the <em>orchestration</em> local. tdd-process is an abstract skill that enforces the mindset. The Rails and Hanami agents inherit that core skill but wrap their own framework-specific tooling around it.</p><h3>Should it be a generic agents or generic skills?</h3><p>This was the absolute fork in the road for me. The temptation to build a single, beautiful, abstract ruby-agents repo with a universal tdd or code-review agent was incredibly strong. It sounds clean on paper, right? Clean boundaries, dry code, zero duplication.</p><p>But consider what an active TDD or code review agent actually needs to know to do its job effectively. A generic agent without framework context is like a world-class chef dropped into an empty kitchen. They know <em>how</em> to cook conceptually, but they can’t actually feed anyone.</p><p>To see exactly what I mean, look at how radically different the structural expectations are when an AI agent runs a code review in Hanami versus Rails or even a repo that it’s not Rails related in this case <a href="https://github.com/igmarin/agnostic-planning-skills">agnostic-planning-skills</a>, yes I have a repo and I wanted to include in the eco system that’s 100% different in terms of outcomes.</p><p>These are the actual underlying skill configurations from the ecosystem:</p><h4>The Hanami Flavor (review-code snippet)</h4><pre>---<br>name: review-code<br>description: &gt;<br>  Use when reviewing Hanami 2.x code, a Hanami app, or any hanami slice for quality<br>  and convention adherence. Covers single-responsibility Actions, dependency injection<br>  via Deps[], no direct container access, ROM query encapsulation in Repositories...<br>---<br>## Quick Reference</pre><pre>| Concern | Rule | Priority |<br>|---|---|---|<br>| Action responsibility | One Action = one endpoint. No business logic. ≤ ~10 lines of logic. | Blocker if logic leaks |<br>| Dependency injection | `include Deps[]` only. No `Hanami.app[&#39;key&#39;]` direct access. | Blocker |<br>| Query location | All DB queries in Repositories/Relations. No SQL in Actions or Views. | Blocker |</pre><h4>The Rails Flavor (code-review snippet)</h4><pre>---<br>name: code-review<br>description: &gt;<br>  Reviews Rails pull requests, focusing on controller/model conventions,<br>  migration safety, query performance, and Rails Way compliance.<br>---<br>## Quick Reference</pre><pre>| Area | Key Checks |<br>|------|------------|<br>| Routing | RESTful, shallow nesting, named routes |<br>| Controllers | Skinny, strong params, scoped `before_action` |<br>| Queries | N+1 prevention, `exists?`, `find_each` batches |</pre><p>Look at that contrast. If I’re reviewing Hanami, the AI needs to strictly police single-responsibility Actions, check for explicit dependency injection via include Deps[], and ensure zero direct container access. If it&#39;s reviewing Rails, it needs to scan for skinny controllers, strong parameters, and ActiveRecord N+1 query prevention.</p><p>If I tried to flatten this into a single “generic Ruby reviewer,” the context window would quickly devolve into a muddy soup of conditional statements: <em>“If Rails do X, if Hanami do Y.”</em> That is exactly how you get an AI agent that hallucinates framework conventions or entirely misses critical architectural violations.</p><p><strong>The solution:</strong> Share the <em>discipline</em>, keep the <em>orchestration</em> local.</p><p>Instead of generic agents, the framework packs inherit abstract process guardrails from ruby-core-skills. For instance, both the Hanami and Rails review skills leverage review-process under the hood. The core process dictates the engineering mindset: how to classify severity levels (Critical, Suggestion, Nice to Have), how to format structured findings, and what triggers a mandatory re-review.</p><p>The core tells the AI <em>how to behave like a disciplined engineer</em>, while the framework pack handles <em>what specific code patterns to look for</em>. It is textbook object-oriented design applied directly to LLM context engineering.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5V23vaM9EwzjmBM-b-kH3w.png" /><figcaption>The Interface Inheritance Pattern</figcaption></figure><h3>What I Learned Along the Way</h3><ul><li><strong>AI Agents thrive on isolated context:</strong> The only reason running 4 agents simultaneously didn’t devolve into utter chaos was the absolute isolation of the playbooks. Give an agent a narrow sandbox and a crisp checklist, and it will outperform a sprawling, unfocused context window every single time.</li><li><strong>Process discipline &gt; Framework knowledge:</strong> The most valuable assets in this entire ecosystem aren’t the ones that understand Rails controllers or routing tables. It’s the rigid process guidelines. Telling an agent <em>“Classify review findings as Critical, Major, or Minor”</em> completely transforms how it behaves, shifting it from an impressionable chatbot to a disciplined engineering collaborator.</li><li><strong>Version your breaking changes loudly:</strong> Moving skills around meant bumping rails-agent-skills from v5.x to v6.0.0 and shipping a thorough migration guide. It might feel like overkill for an internal toolset, but treating your own AI tools with production-level open-source respect prevents endless debugging headaches down the road.</li></ul><h3>Where It’s Going Next</h3><p>The core infrastructure is up, stable, and completely functional, but the roadmap is far from empty:</p><ol><li><strong>Live LLM Evaluation:</strong> The testing stubs are ready inside ruby-skill-bench. The next step is running live adversarial benchmarking to quantify exactly how much our tdd-process skill moves the needle on code generation quality.</li><li><strong>Deeper Project Introspection:</strong> Integrating rails-ai-bridge directly into the runtime context loop so the agents can automatically inspect active database schemas, live routes, and dependencies without any manual prompting.</li></ol><p><em>AI coding assistants are only as good as the guardrails and contexts you give them. Skills turn those loose instructions into versioned, composable engineering standards. If you’re building a similar setup for your development stack, let’s chat over on </em><a href="https://github.com/igmarin">GitHub</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=009d72a9d179" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From Static Prompts to Production Agents: My Journey with Tessl and AI Skills]]></title>
            <link>https://medium.com/@igmarin/from-static-prompts-to-production-agents-my-journey-with-tessl-and-ai-skills-138521d880da?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/138521d880da</guid>
            <category><![CDATA[ai-generated-content]]></category>
            <category><![CDATA[llm-evaluation]]></category>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[ai-skills]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Sat, 16 May 2026 15:21:55 GMT</pubDate>
            <atom:updated>2026-05-16T19:13:46.883Z</atom:updated>
            <content:encoded><![CDATA[<p>Over the last few months, my first attempts at building AI skills focused on improving my own development workflow using Cursor. At the beginning, I had around 14 highly specialized skills tailored to the work I was doing at the time. Those were my first real steps toward improving the quality of the software I was building.</p><p>Around that period, I knew a layoff was coming and that I would most likely be part of it. Because of that, I decided to focus my time on two things. The first was building <a href="https://github.com/igmarin/rails-ai-bridge">rails-ai-bridge</a>, a Ruby gem designed to spin up an MCP server capable of deeply parsing the Rails projects I worked on. My goal was to shift away from brittle, probabilistic prompt outputs and move toward a deterministic architecture. The second focus was continuing to scale and refine my skills system itself.</p><p>Once I realized I would soon be looking for a new job, I started thinking more seriously about market expectations for advanced, AI-assisted development workflows. I wanted to encode software engineering patterns I personally love, especially Domain-Driven Design (DDD) and Rails Engines — patterns I originally fell in love with while working on large-scale e-commerce systems built with Solidus and Spree Commerce.</p><p>However, getting dozens of skills to behave consistently became an uphill battle. By this point, my repository had scaled to around 30 unique skills, including specialized prompts for generating tasks, PRDs, and automated tests. The bottleneck was clear: manually evaluating whether the AI’s outputs matched my strict architectural guidelines was incredibly time-consuming and unreliable.</p><p>Fortunately, I discovered <a href="https://tessl.io/">Tessl.io</a>, which provided an empirical, automated environment to validate and stress-test my skills. I became obsessed with optimizing our evaluation scores. In isolation, every individual skill eventually hit a perfect 100% score. But I quickly realized a harsh truth: perfect isolated scores do not translate into strong results when skills are executed within real-world, complex codebase context.</p><p>This realization pushed me into the journey this article explores: finding the structural balance between individual skill performance, runtime context preservation, regression safety, and deterministic execution. Today, my ecosystem features 41 highly optimized skills and 9 complex workflows, serving as the blueprint for production-ready, fully autonomous agents.</p><h3>The Shape of the Repository</h3><p>To understand the evaluation journey, you have to understand the layout of the project. It is built as a unified, publishable Rails agent-skills library containing modular prompt configurations, automated workflows, MCP integrations, and dedicated evaluation suites.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8sGz8XntGUF8pgeONFtJsQ.png" /><figcaption><a href="https://github.com/igmarin/rails-agent-skills">https://github.com/igmarin/rails-agent-skills</a></figcaption></figure><p><strong>Tessl</strong> scores the publishable skills defined within <a href="https://github.com/igmarin/rails-agent-skills/blob/main/tile.json">tile.json</a>. A core engineering takeaway from this setup is that <em>“the repo is clean”</em> and <em>“the Tessl score is green”</em> are related but completely distinct claims. The public surface requires its own specialized evaluation lane.</p><h3><strong>The Metric That Matters: Context Lift</strong></h3><p>Before running automated evaluations, it is tempting to treat an AI skill as an interactive README — a clean set of markdown instructions that feels intuitive to a human reader. At runtime, that mental model breaks. A skill acts as an engineered product surface with activation curves, token constraints, and measurable lift over a baseline model.<br>When evaluating agent behaviors, the ultimate metric is Context Lift:</p><blockquote>Context Lift = ‭With-Context Score — Baseline Score</blockquote><p>‬‭‬‭‬<br>If a baseline LLM already scores a <strong>95%</strong> on a generic task without your skill, the skill isn’t providing much architectural value. True capability is proven when the baseline model scores poorly on complex engineering problems, but jumps significantly when your context-driven skill is injected.</p><h3><strong>The Context Gap: Pre-Optimization Snapshot</strong></h3><p>When tested in an empty prompt window, the model effortlessly hit top marks. But the moment we injected real framework context and messy dependencies, performance dipped significantly due to token confusion and conflicting rules:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zk8IQ7g-yiuuDl9DuUWWtQ.png" /></figure><p><strong>The Continuous Optimization Loop</strong></p><p>To systematically close this context gap, my custom-configured AI agent — Codex — and I established an empirical optimization loop. We treated single evaluation runs as unstable samples, using a disciplined batching and bisection workflow to guard against regressions.</p><figure><img alt="The infinite loop" src="https://cdn-images-1.medium.com/max/1024/1*Hjgo3FtsejbHyclgRwQHGA.jpeg" /></figure><p><strong>The Win: </strong>apply-code-conventions<strong> (Optimizing the Receipt)</strong><br>Our initial implementation of <a href="https://github.com/igmarin/rails-agent-skills/tree/main/skills/code-quality/apply-code-conventions">apply-code-conventions</a> contained excellent guidelines: check the active linter, enforce strict area isolation, and avoid let_it_be specs unless test-prof is explicitly loaded in the Gemfile.lock. Yet, the evaluation scores remained low.<br>The problem wasn&#39;t a lack of technical knowledge; it was an artifact verification gap. The model performed the work internally, but failed to prove it to the evaluator.<br>We solved this by explicitly engineering an Output Contract (what I call <em>&quot;the receipt&quot;</em>). We forced the LLM to output its intermediate reasoning steps and shell logs as a verifiable paper trail:</p><blockquote>1. <strong>LINTER DETECTION</strong>: Display detected linter and configuration file path.<br>2. <strong>TDD VERIFICATION</strong>: Print the execution command, the initial failing spec, and the exact expected error class.<br>3. <strong>MINIMAL IMPLEMENTATION</strong>: Apply targeted code change.<br>4. <strong>PASSING RERUN</strong>: Print the final clean shell output demonstrating 0 failures.</blockquote><p>By forcing the agent to print its receipts, the evaluator could instantly verify the execution path, immediately stabilizing the score.<br><strong>The Trap: </strong><a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/testing/triage-bug">triage-bug</a><strong> (The Perils of Rubric Overfitting)</strong><br>When a skill scores poorly, the instinctive reaction is to copy the evaluation rubric&#39;s exact phrasing into your prompt instructions. With <a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/testing/triage-bug">triage-bug</a>, the evaluation expected an isolated reproduction pass targeting an out-of-stock order pathway on a POST /orders request. We patched the skill by adding hyper-specific wording targeting that exact flow.<br>The result? The aggregate score regressed.<br>By over-indexing on the evaluation rubric, we accidentally caused the model to overfit to a single test scenario. This stripped away its capability to generalize across actual codebase bugs, introducing severe token confusion. We immediately reverted the patch, learning that a low score often signals the need for a deeper systemic interface redesign rather than more instruction text.</p><p><strong>The Batching Discipline and Score Sidesteps</strong><br>As single-skill changes became too noisy, we grouped modifications into controlled batches of six skills to observe broader trends. The metrics from these runs revealed the non-linear nature of optimizing AI systems.<br>During our first major batch run (<a href="https://tessl.io/eval-runs/019e22af-bf68-7197-a02f-0d627a234104">019e22af-bf68-7197-a02f-0d627a234104</a>), the aggregate score climbed from 89.2% to 91.0%, yet individual tracking showed highly uneven performance:</p><ul><li><a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/code-quality/respond-to-review">respond-to-review</a> &amp; <a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/infrastructure/implement-background-job">implement-background-job</a> surged to a perfect <strong>100.0%</strong>.</li><li><a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/patterns/create-service-object">create-service-object</a> tanked to <strong>72.0%</strong>.</li><li><a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/planning/plan-tickets">plan-tickets</a> collapsed to <strong>65.0%</strong>.</li></ul><p>Following our bisection rule <em>“Batch for signal, but decide per skill”</em>, we kept the successful half of the prompt modifications and reverted the regressions. Surprisingly, running an evaluation on the kept half alone (<a href="https://tessl.io/eval-runs/019e22b9-bc3f-77be-9bf8-f91717b2beb9">019e22b9-bc3f-77be-9bf8-f91717b2beb9</a>) caused the aggregate score to dip back to 90.0%, even though individual skills like <a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/patterns/create-service-object">create-service-object</a> successfully recovered to 95.0%.<br>This proved that aggregate movement isn&#39;t a simple mathematical sum—downstream token prioritization fluctuates when context boundaries change.</p><h3><strong>Moving Beyond Single Samples: Release Protocol</strong></h3><p>To protect our development branch from variance, we stopped treating single Tessl evaluation runs as definitive verdicts. We implemented a rigorous multi-run protocol requiring stable averages across repeated samples before a prompt tree could be certified for production.<br>For release-candidate confidence, we bypassed single-execution testing entirely and mandated a three-run baseline check using the following CLI setup:</p><pre>tessl eval run . \<br>  --variant with-context \<br>  --agent=claude:claude-sonnet-4-6 \<br>  --runs 3 \<br>  --label release-confidence-sonnet-3xb</pre><p>This multi-run protocol completely shifted our engineering triage. Instead of chasing isolated spikes, we used the multi-run mean to isolate and fix Stable Anchors (skills that repeatedly pull down the average across all runs) while ignoring noisy, single-run fluctuations.</p><p><strong>Pushing the Peak: The Evolution to 97.45%</strong><br>With a robust multi-run testing protocol in place, we began methodically isolating stable anchors and implementing precision artifact fixes:</p><ol><li><strong>Stable Low-Tail Triage</strong>: We discovered that <a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/infrastructure/review-migration">review-migration</a> consistently failed due to missing rollout strategy logs. We updated the output style contract to mandate explicit lock-analysis and table-rewrite notes, alongside a multi-step type-change rollout pattern. This single structural change moved the skill score from 88.0% to a perfect <strong>100.0%</strong>.</li><li><strong>Contextual Alignment</strong>: For <a href="https://github.com/igmarin/rails-agent-skills/tree/8545115126933d065b3d6ef0192b9627b2eec2c6/skills/ddd/review-domain-boundaries">review-domain-boundaries</a>, we provided concrete domain separation guardrails modeled directly after modular monolith practices (e.g., explicitly stating that Billing owns invoice-generation triggers, while Fleet strictly tracks vehicle state). This lifted the boundary evaluation to <strong>95.0%</strong>.</li><li><strong>Taxonomical Cleanup</strong>: We identified that a legacy, root-level build skill was introducing significant cross-talk and prompt noise. Rather than wasting engineering time trying to optimize an obsolete prompt, we retired it completely. Cleaning our codebase taxonomy from 42 down to 41 highly distinct skills immediately lifted our multi-run aggregate baseline to <strong>96.4%</strong>.</li></ol><p><strong>The Pitfall of Progressive Disclosure</strong><br>During this push, we attempted a major architectural cleanup: moving dense, executable prompt blocks out of the primary SKILL.md files and into secondary support assets. While this made the repository look incredibly clean on paper, our dynamic runtime evaluation scores dropped immediately.</p><p>We discovered an essential constraint of LLM execution mechanics: progressive disclosure is excellent for human reference material, but highly risky for critical agent behaviors. If a model lacks immediate visibility into exact file paths, response schemas, and hard validation gates at the exact moment it executes a task, its structural consistency degrades. The core skill file must hold the primary execution parameters, reserving secondary files strictly for optional templates or mock examples.<br>Through iterative refinement, our final evidence-label pass (<a href="https://tessl.io/eval-runs/019e2aa9-ef05-768a-8773-0be3d662e99d">v6-evidence-label-sub90-followup-3x</a>) pushed our production-ready asset baseline to a record high:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*w3xrk8YOIJ-FF4DmyeyBWQ.png" /><figcaption>Evaluation run results</figcaption></figure><h4>The Trap: triage-bug (When the Scenario is the Problem)</h4><p>Not every targeted patch worked. <a href="https://github.com/igmarin/rails-agent-skills/tree/main/skills/testing/triage-bug">triage-bug</a> had a consistently low score. Codex and I tried adding more explicit wording for the exact scenario the evaluator was looking for. The result? It actually made the overall performance worse.</p><p>It taught us that a low score doesn’t always mean “<a href="https://brocku.ca/pedagogical-innovation/resources/rubrics/">add the rubric text</a>.” Sometimes it means the task, the scenario, and the skill need a deeper redesign. We had to revert the regression and accept the learning.</p><h3>The Batching Discipline and Score Sidesteps</h3><p>After single-skill patches became too noisy, we shifted to controlled batches of six skills. We’d patch Output Style contracts across several skills, then run the eval. The results were deeply instructive: a batch could improve the aggregate score while completely tanking one specific skill.</p><p>The rule became: Batch for signal, but decide per skill. We’d keep the successful half of a batch and revert the failing half. But surprisingly, running an eval on just the kept half sometimes resulted in a <em>lower</em> aggregate score than the full batch. This taught us that aggregate movement is not just the sum of the edited skills — some scenarios vary, and some persistent <em>“low-tail”</em> skills dominate the average.</p><p>The process taught us to freeze proven wins and re-rank the problem. Chasing a <strong>98%</strong> aggregate score meant that broad rewrites became dangerous. A tiny output label change could fix a skill, or destroy it.</p><h3>The Complete User Journey</h3><p>These highly optimized skills are not isolated prompt files — they map directly to an integrated, end-to-end software development lifecycle. By combining strict output contracts with structured runtime context, the transition from initial planning to fully verified code is entirely seamless:</p><figure><img alt="https://tessl.io/registry/igmarin/rails-agent-skills" src="https://cdn-images-1.medium.com/max/1024/1*VvE7ef1gwWB86jOXmjtKKA.png" /></figure><p><strong>The Empirical Mindset for Future Agents</strong><br>Transitioning from prompt engineering to agentic software development requires moving away from subjective <em>“taste”</em> and embracing continuous, data-driven measurement. A skill might read beautifully to a human engineer and still fail completely at runtime. A clean prompt refactor can inadvertently tank execution performance, while a small tweak to an output contract can shift an evaluation score more than a complete rewrite.<br>For engineers looking to build predictable, production-grade AI capabilities, the development loop must remain empirical, rigorous, and humble:</p><blockquote>Write the instruction. Run the evaluation. Analyze the failure modes. Optimize the output contract. Freeze what works. Revert what does not.</blockquote><p>This systematic methodology is how we transform unpredictable prompts into hardened, professional agentic systems that teams can confidently trust in production.</p><p><strong>A Note of Appreciation:</strong> I am deeply grateful to the team at <a href="https://tessl.io/">Tessl</a> for building a tool that has profoundly impacted my personal and professional growth. Without it, I would be in a completely different place in my journey to master AI engineering and adapt agentic workflows into my daily development work.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=138521d880da" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Beyond Vibe Coding: How rails-ai-bridge v2.2.0]]></title>
            <link>https://medium.com/@igmarin/beyond-vibe-coding-how-rails-ai-bridge-v2-2-0-6e970d2cfd55?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/6e970d2cfd55</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[mcp-server]]></category>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[cursor]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Sun, 05 Apr 2026 19:51:49 GMT</pubDate>
            <atom:updated>2026-04-05T19:56:39.429Z</atom:updated>
            <content:encoded><![CDATA[<h4>Beyond Vibe Coding: How rails-ai-bridge v2.2.0 Achieved “Semantic Parity” Across Claude 4.6, Cursor, Gemini 2.5 and Windsurf</h4><p>The primary mission of <strong>rails-ai-bridge</strong> has always been to elevate the Ruby on Rails developer experience. As I discussed in my <a href="https://medium.com/@igmarin/stop-vibe-coding-how-i-bridged-the-gap-between-rails-and-ai-063eaf0a0304">previous article</a>, this project was born from a practical necessity: to avoid ‘token-tax’ and to empower developers — from Juniors to Seniors — to leverage their favorite LLMs or IDEs with precision. It is about making development faster and ensuring that AI-driven decisions are accurate and context-aware.</p><p>This isn’t about human vs. machine; it’s about human-AI synergy. In an era where AI is becoming our primary workspace, the goal is to discover how we can work <em>better</em> together. This gem isn’t perfect — it is a living project. Every iteration is built to solve the real-world friction I face in my daily work and serves as an exercise in personal growth that I am proud to share with the community. Much like my <a href="https://github.com/igmarin/rails-agent-skills">Rails Agent Skills repository</a>, this project is a reflection of a journey that is personal, yet deeply collective.</p><p>In my previous post, I introduced <strong>rails-ai-bridge</strong> as the solution to the “context gap” — that frustrating moment when your AI assistant ignores your schema or guesses your conventions.</p><p>Today, we are launching <strong>version 2.2.0</strong>. This release isn’t just about new features; it’s about <strong>Semantic Intelligence</strong>. To prove it, I didn’t just run tests — I ran an “AI Audit” across the industry’s titans: <strong>Claude 3.5 Sonnet (v4.6), Gemini 2.5 Pro, Windsurf (Cascade), and Cursor.</strong></p><p>The results? We’ve achieved what I call <strong>“Semantic Parity.”</strong></p><h3>The Problem: Context is Not Just Text</h3><p>From “noisy” context to a 5.0/5.0 rating: A deep dive into Semantic Model Tiering, 92.92% test coverage, and the end of silent context gaps in Rails AI development.</p><p>Early versions of AI bridges treated your Rails app like a flat list of files. But a Senior Developer knows that User is a <strong>Core Entity</strong>, while Taggings is just a <strong>Pure Join Table</strong>.</p><p>If the AI doesn’t know the difference, it wastes its “attention” (and your tokens) analyzing infrastructure instead of business logic. Claude 4.6 previously flagged this as “noise.”</p><h3>The Solution: The Semantic Layer</h3><p>Version 2.2.0 introduces an automated <strong>Model Semantic Classifier</strong>. The gem now acts as a Senior Engineer, categorizing your database into:</p><ol><li><strong>Core Entities:</strong> The heart of your domain.</li><li><strong>Rich Join Entities:</strong> Intermediate tables with actual data (e.g., Rating between User and Book).</li><li><strong>Pure Join Tables:</strong> Logic-less connectors (HABTM).</li><li><strong>POJO/Services:</strong> Non-ActiveRecord classes in app/models/ that were previously &quot;silent gaps.&quot;</li></ol><h3>The Evidence: The AI Audit Scores</h3><p>We asked the leading LLMs to rate the context generated by v2.2.0. The improvement is undeniable.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/726/1*fP_mjhbxnWrU5rzLWyNV9Q.png" /><figcaption>Quality Leap (v2.1.0 vs. v2.2.0)</figcaption></figure><h3>Engineering Rigor: 92.92% Coverage</h3><p>We don’t just bridge to AI; we use the best tools to keep the bridge strong.</p><ul><li><strong>92.92% Line Coverage:</strong> Every introspection logic and serializer is battle-tested.</li><li><strong>SkunkScore 25.39:</strong> Low complexity, high maintainability.</li><li><strong>CodeRabbit Integration:</strong> Continuous, AI-powered code reviews ensuring every PR meets Senior standards.</li></ul><h3>🚀 Get Started with v2.2.0</h3><p>The gem is officially published. You no longer need to point to a branch — just add it and run.</p><pre># Add to your project<br>bundle add rails-ai-bridge<br><br># Install and Generate Context<br>rails generate rails_ai_bridge:install<br>rails ai:bridge</pre><p>Visit the gem repository to learn more about how to use it: <a href="https://github.com/igmarin/rails-ai-bridge">https://github.com/igmarin/rails-ai-bridge</a></p><p>The “Vibe Coding” era is over. It’s time to give your AI the engineering context it deserves.</p><h3>📈 Data for your Graphics (Visual Guide)</h3><p>In the next section, I asked Claude, Cursor, Gemini, and Windsurf to evaluate the gem and give me scores on things like overall quality, innovation, performance, developer experience, platform support, and architecture.</p><p>I’ve got a full report from each one (happy to share if you’re interested). It’s been really helpful to get a broader perspective and use that as input for the roadmap — just improving things step by step.</p><p>I don’t have access to Codex or Copilot right now, so if you’re able to test it with those and share your results, I’d seriously appreciate it 🙏 That kind of feedback would be super valuable.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/700/1*YXvuyDfPAsVVSkPPsHuOmw.png" /><figcaption>Claude</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/700/1*1zk5vyVk2zr3gBrkFWO27A.png" /><figcaption>Cursor</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/700/1*jL456BMVsa4sOSMsjwJCCw.png" /><figcaption>Gemini</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/700/1*rhqHheork_yECbWPO6hWwg.png" /><figcaption>Windsurf</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/640/1*Sd3ilfxdUYb2nbvTKKUoew.png" /><figcaption><strong>Semantic Distribution (Data Models)</strong></figcaption></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6e970d2cfd55" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Stop “Vibe Coding”: How I Bridged the Gap Between Rails and AI]]></title>
            <link>https://medium.com/@igmarin/stop-vibe-coding-how-i-bridged-the-gap-between-rails-and-ai-063eaf0a0304?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/063eaf0a0304</guid>
            <category><![CDATA[ruby]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Fri, 03 Apr 2026 07:22:38 GMT</pubDate>
            <atom:updated>2026-04-03T07:22:38.326Z</atom:updated>
            <content:encoded><![CDATA[<h3>Introduction: The AI Wild West</h3><p>In my previous role, before we had a formal AI policy, we were living in the “Wild West” of development. Some teammates used GitHub Copilot, others preferred Cursor, and some — like me — were hooked on CLI tools or specialized IDE integrations. We were all more productive, but we were doing it in silos.</p><p>When the company finally standardized on OpenAI (Codex) as our unique provider, a fascinating pattern emerged: everyone just plugged their API keys into their favorite editor and started “GPT-ing” their way through tasks.</p><h3>The Three Wake-Up Calls</h3><p>Three specific moments made me realize that simply having an LLM wasn’t enough:</p><ol><li><strong>The Token Burn:</strong> Our VP of Engineering noticed the bills skyrocketing. The quality of code wasn’t improving — if anything, it was getting noisier. We were told to stick to “medium” models to save money. I started searching for solutions and found rails-ai-context by Cris Nahine, which sparked the initial idea.</li><li><strong>The “10 vs. 200” Rule:</strong> A Junior Dev was tasked with extending a service. Because they didn’t have the “tribal knowledge” of our architecture, they delivered 200 lines of over-engineered code for a task that only required 10 lines and an existing Service Object. The cognitive load was too high for a newcomer, and the AI wasn’t helping them “see” the patterns we had already built.</li><li><strong>The Context Gap:</strong> During pair programming, I noticed that the same prompt gave diametrically different results depending on the editor’s “knowledge” of the project. Editors didn’t <em>know</em> the app; they were just guessing.</li></ol><p>That was the birth of <a href="https://github.com/igmarin/rails-ai-bridge"><strong>rails-ai-bridge</strong></a>. I realized we didn’t just need an AI; we needed to <strong>onboard</strong> the AI into our specific codebase.</p><h3>The Two-Layer Solution: Context is King</h3><p>The gem evolved into a “two-layer” system designed to turn a “cold start” into an informed collaboration.</p><ul><li><strong>Layer 1: Static Context (The Briefing):</strong> High-fidelity files like GEMINI.md or CLAUDE.md provide an architectural blueprint, tech stack awareness, and domain models at a glance.</li><li><strong>Layer 2: Live MCP (The Real-Time API):</strong> A Model Context Protocol (MCP) server that allows the AI to query your live schema, routes, and model details on demand.</li></ul><h3>Production-Ready: The “Brain” Lambda</h3><p>A common concern with AI tools is security. You don’t want to expose your database schema or internal routes to just anyone. With the release of <strong>v2.0.0</strong>, I introduced a way to bridge the AI context directly with your app’s existing security model.</p><p>By using what I call the <strong>“Brain” Lambda</strong>, you can define custom authorization logic inside a standard Rails initializer. This ensures that the MCP server only talks to those who are authorized.</p><pre># config/initializers/rails_ai_bridge.rb<br># Deeply integrate AI context with your existing Auth logic<br>config.mcp.authorize = -&gt;(request) {<br>  # Only developers with a valid API token can query the MCP<br>  Current.user = User.find_by(api_token: request.headers[&#39;Authorization&#39;])<br>  <br>  # Ensure the user exists and has admin privileges<br>  Current.user&amp;.admin?<br>}r</pre><h3>Why this matters:</h3><ul><li><strong>Zero-Trust Architecture:</strong> Your project’s “tribal knowledge” remains protected.</li><li><strong>Rails Native:</strong> It uses familiar patterns like Current.user and standard request headers.</li><li><strong>Extensibility:</strong> You can go beyond simple tokens — log requests, limit usage by user, or even check IP allowlists.</li></ul><h3>Multi-Assistant Performance Review</h3><p>Based on recent evaluations, here is how the top tools currently benefit from the bridge:</p><h4>1. Gemini &amp; Claude: High-Fidelity Intelligence</h4><p>For these models, the gem eliminates the “Cold Start” problem.</p><ul><li><strong>Gemini:</strong> Gains immediate “situational awareness” of the stack (Rails/Ruby versions, key gems like Sidekiq), preventing it from generating incompatible code.</li><li><strong>Claude:</strong> Uses a directive guide that enforces “good citizen” coding rules, reducing hallucinations by encouraging the use of live MCP tools for deep dives.</li></ul><h3>2. Cursor &amp; Windsurf: Precision and Complexity</h3><p>These AI-native editors thrive on the integration between static rules and live data.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gJhlkDy_pu2zqw38NVh8Bw.png" /></figure><h3>3. Copilot, Codex, and Beyond</h3><p>Even for tools without native MCP support, the gem acts as a <strong>Reference Map</strong>. By providing a unified “voice” and architectural patterns (Service Objects, Concerns, etc.), it allows these assistants to provide better reviews and more idiomatic code, functioning as a “User Manual” for the AI.</p><h3>The Road Ahead: V3 and the Open Source Vision</h3><p>I am currently working on the <strong>V3 PRD</strong>, focusing on even deeper integration and operational excellence. One of my primary goals is exploring <strong>Open Source LLMs</strong>.</p><p>The “<strong>Token Burn</strong>” I witnessed is a real barrier for many teams. I want to define specific rules and context structures that allow teams to use high-quality open-source models without sacrificing quality or breaking the bank on proprietary APIs.</p><h3>Join the Mission</h3><p>I am no longer with the company where this journey started, so I no longer have access to paid Copilot or enterprise Codex accounts. If you use these tools and want to improve your AI’s performance:</p><ol><li>Run rails-ai-bridge in your project.</li><li>Test the generated context.</li><li><strong>Share your feedback or reviews with me.</strong> The goal isn’t just to write code faster; it’s to write code that respects the soul and architecture of your project.</li></ol><p><strong>Check out the project on GitHub:</strong> <a href="https://github.com/igmarin/rails-ai-bridge">igmarin/rails-ai-bridge</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=063eaf0a0304" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your JSON Column Is Not a Settings System]]></title>
            <link>https://medium.com/@igmarin/your-json-column-is-not-a-settings-system-4b7dc46e747f?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/4b7dc46e747f</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[multitenancy]]></category>
            <category><![CDATA[feature-flags]]></category>
            <category><![CDATA[backend-engineering]]></category>
            <category><![CDATA[ruby-on-rails-development]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Sat, 07 Mar 2026 23:08:45 GMT</pubDate>
            <atom:updated>2026-03-08T18:41:51.083Z</atom:updated>
            <content:encoded><![CDATA[<p>Managing feature flags across hundreds of stores sounds like a solved problem — until you’re staring at a codebase where the frontend is making business decisions, settings live in five different places, and adding a new integration means touching everything at once.</p><p>This post walks through the architecture we designed to fix that: a <strong>polymorphic, typed settings platform</strong> with a backend projection layer that gives the frontend a clean, stable contract. If you’re building a multi-tenant e-commerce platform with growing integration complexity, this might save you some pain.</p><h3>The Problem: Settings Sprawl</h3><p>As a platform grows — more payment providers, more shipping integrations, more feature toggles per store — the places where configuration lives tend to multiply:</p><ul><li>A store_settings table for basic operational config</li><li>Payment and shipping flags scattered across join tables</li><li>Raw JSON blobs that grew organically and are now load-bearing</li><li>Frontend logic that derives feature availability by checking a combination of flags: isPremiumPlan || isPartnerStore || store.tier === &#39;enterprise&#39;</li></ul><p>Each of these is a reasonable decision at the time. But together, they create real problems:</p><p><strong>Frontend drift.</strong> When business rules live in the frontend, every client team has to replicate them. They go stale. They diverge. A backend change that should be invisible requires a frontend deploy.</p><p><strong>No validation.</strong> A string-typed key-value store will accept anything. Typos, wrong types, and unknown keys fail silently — often in production.</p><p><strong>No audit trail.</strong> Who changed this setting? When? Good luck.</p><p><strong>Manual scaling.</strong> Onboarding a new merchant or integration means touching multiple tables and knowing undocumented rules about which fields matter where.</p><h3>The Existing Pattern We Built On</h3><p>Our codebase already had a working polymorphic metadata pattern: a CustomAttribute model used to attach dynamic fields to orders.</p><p>Here’s the core idea — any entity can own a set of dynamic key-value fields:</p><pre># A polymorphic owner model<br>class CustomAttribute &lt; ApplicationRecord<br>  belongs_to :owner, polymorphic: true<br>end</pre><pre># Any model can include this concern<br>module CustomAttributable<br>  extend ActiveSupport::Concern<br>  included do<br>    has_many :custom_attributes, as: :owner<br>  end<br>end</pre><p>In practice, this is used to pass arbitrary fields through order flows — things like gift_message, promo_code, or fulfillment_partnerthat vary by integration but don&#39;t belong in the core schema.</p><p>This pattern proved the polymorphic approach works in production. But CustomAttribute was designed for <strong>dynamic per-transaction metadata</strong>, not <strong>feature governance</strong>. It stores everything as strings, has no concept of defaults or allowed values, and has no validation layer.</p><p>We needed to keep CustomAttribute for orders and build something purpose-fit for settings.</p><h3>The Architecture: Definitions + Values + Projection</h3><h3>The Data Model</h3><p>The core is two concepts that work together.</p><p><strong>setting_definitions</strong> is a catalog — the source of truth for what settings exist:</p><pre>setting_definitions<br>├── key              (e.g., &quot;shipping.provider&quot;)<br>├── value_type       (boolean | string | enum | integer)<br>├── default_value<br>├── allowed_owners   (Store, MerchantAccount, ...)<br>└── validation_meta  (allowed enum values, schema, etc.)</pre><p><strong>setting_values</strong> stores the actual per-owner values:</p><pre>setting_values<br>├── owner_type + owner_id   (polymorphic — Store, MerchantAccount, etc.)<br>├── setting_definition_id<br>├── value                   (jsonb, typed)<br>├── created_at / updated_at<br>└── updated_by</pre><p>A unique index on (owner_type, owner_id, setting_definition_id) ensures one value per owner per setting. The polymorphic owner means a single table works for Store, MerchantAccount, or any future entity — without schema changes.</p><p>Defaults live in code, not in the database. The DB only stores rows when a value differs from the default. This keeps the table lean even at thousands of stores.</p><h3>Definitions in Code</h3><p>Each resource type registers its own definition class. Here’s what that looks like for a Store:</p><pre># app/lib/settings/definitions/store.rb<br>module Settings<br>  module Definitions<br>    class Store<br>      def self.all<br>        {<br>          # Type is inferred from the default value — no explicit declaration needed<br>          notifications_enabled:  { default: true },<br>          max_product_variants:   { default: 50 },<br>          tax_rate:               { default: 0.0 },<br>          shipping_provider:      { default: &#39;standard&#39;, allowed: %w[standard express overnight] },<br>          checkout_flow:          { default: &#39;single_page&#39;, allowed: %w[single_page multi_step] },<br>          payment_method_required: {<br>            default: false,<br>            # source: reads from a relation when no preference is stored<br>            source: -&gt;(s) { s.merchant_account&amp;.requires_upfront_payment? }<br>          }<br>        }<br>      end<br>    end<br>  end<br>end</pre><pre>Settings::Definitions.register(Store, Settings::Definitions::Store)</pre><p>Type inference rules are simple: false/true → boolean, 0 → integer, 1.0 → float, &#39;standard&#39; → string. No extra config needed.</p><h3>The API</h3><pre>Settings.resolve(settingable:, key:, override: nil)   # Single value<br>Settings.resolve_all(settingable:, keys: nil)          # All values as hash<br>Settings.apply!(settingable:, settings:)               # Persist overrides<br>Settings.keys_for(settingable)                         # Keys defined for this resource</pre><p>The resolve order is: override (request-time) → stored preference → source (relation) → default.</p><h3>The Projection Layer</h3><p>The biggest shift is how feature state reaches the frontend. Instead of raw flags, the backend projects a structured, computed payload:</p><pre>{<br>  &quot;catalog&quot;: {<br>    &quot;enabled&quot;: true,<br>    &quot;can_add_products&quot;: true,<br>    &quot;can_bulk_import&quot;: false<br>  },<br>  &quot;payments&quot;: {<br>    &quot;enabled&quot;: true,<br>    &quot;provider&quot;: &quot;stripe&quot;,<br>    &quot;payment_method_required&quot;: true<br>  },<br>  &quot;shipping&quot;: {<br>    &quot;enabled&quot;: true,<br>    &quot;provider&quot;: &quot;express&quot;,<br>    &quot;can_set_custom_rates&quot;: false<br>  },<br>  &quot;storefront&quot;: {<br>    &quot;checkout_flow&quot;: &quot;single_page&quot;,<br>    &quot;notifications_enabled&quot;: true<br>  }<br>}</pre><p>This payload is computed from: integration lifecycle state + plan/partner-derived rules + explicit persisted overrides. The frontend asks “what can this store do?” and gets a complete, authoritative answer — no derivation needed on the client.</p><h3>Before vs. After</h3><p><strong>Before — frontend deriving feature state:</strong></p><pre>// Frontend has to know about plan tiers, partner types, and edge cases<br>const canBulkImport =<br>  store.plan === &#39;enterprise&#39; &amp;&amp;<br>  !isReadOnlyPartner &amp;&amp;<br>  store.catalog_integration_active;</pre><p><strong>After — frontend consuming a projection:</strong></p><pre>// Frontend just reads what the backend already computed<br>const canBulkImport = features.catalog.can_bulk_import;</pre><p><strong>Before — writing a setting:</strong></p><pre># No validation, no type enforcement, anything goes<br>store.settings[&quot;shipping_provider&quot;] = params[:provider]<br>store.save</pre><p><strong>After — writing a setting:</strong></p><pre># Validated against the definition before touching the DB<br>Settings.apply!(<br>  settingable: store,<br>  settings: { shipping_provider: params[:provider] }<br>)<br># =&gt; raises ArgumentError if key is unknown or value not in allowed list</pre><h3>Rails Console Walkthrough</h3><p>This is where the architecture earns its keep. Here’s a full tour of how to interact with it from the console.</p><h3>Basic Read &amp; Write</h3><pre>store = Store.find(42)</pre><pre># Read a single setting — returns proper Ruby type, not a string<br>Settings.resolve(settingable: store, key: :notifications_enabled)<br># =&gt; true  (Boolean, not &quot;true&quot;)</pre><pre>Settings.resolve(settingable: store, key: :max_product_variants)<br># =&gt; 50  (Integer)</pre><pre>Settings.resolve(settingable: store, key: :shipping_provider)<br># =&gt; &quot;standard&quot;  (String, downcased and stripped)</pre><pre># Read all settings for this store at once<br>Settings.resolve_all(settingable: store)<br># =&gt; {<br>#      notifications_enabled: true,<br>#      max_product_variants: 50,<br>#      tax_rate: 0.0,<br>#      shipping_provider: &quot;standard&quot;,<br>#      checkout_flow: &quot;single_page&quot;,<br>#      payment_method_required: false<br>#    }</pre><h3>Writing Overrides</h3><pre># Persist a new value — only writes a DB row if it differs from the default<br>Settings.apply!(settingable: store, settings: { shipping_provider: &#39;express&#39; })</pre><pre># Confirm it was saved<br>Settings.resolve(settingable: store, key: :shipping_provider)<br># =&gt; &quot;express&quot;</pre><pre># Input normalization happens automatically — &quot;EXPRESS&quot; and &quot; express &quot; both work<br>Settings.apply!(settingable: store, settings: { shipping_provider: &#39;  EXPRESS  &#39; })<br>Settings.resolve(settingable: store, key: :shipping_provider)<br># =&gt; &quot;express&quot;</pre><pre># Boolean casting is flexible — &quot;1&quot;, &quot;on&quot;, &quot;yes&quot;, &quot;true&quot; all resolve to true<br>Settings.apply!(settingable: store, settings: { notifications_enabled: &quot;1&quot; })<br>Settings.resolve(settingable: store, key: :notifications_enabled)<br># =&gt; true</pre><pre># Apply multiple settings in one call<br>Settings.apply!(<br>  settingable: store,<br>  settings: {<br>    checkout_flow: &#39;multi_step&#39;,<br>    max_product_variants: 100,<br>    tax_rate: 0.08<br>  }<br>)</pre><h3>Resetting to Default</h3><pre># Pass nil to delete the stored override and fall back to the default<br>Settings.apply!(settingable: store, settings: { shipping_provider: nil })</pre><pre>Settings.resolve(settingable: store, key: :shipping_provider)<br># =&gt; &quot;standard&quot;  (back to the default)</pre><pre># Same happens if you write the default value explicitly — no row is stored<br>Settings.apply!(settingable: store, settings: { max_product_variants: 50 })</pre><pre>Store.find(42).setting_values.where(key: :max_product_variants).count<br># =&gt; 0  (nothing stored, default is sufficient)</pre><h3>Request-Time Overrides (Not Persisted)</h3><p>Useful when you need to apply a value for the duration of one request — like a query param or a temporary A/B test variant — without touching the database:</p><pre># Pass override: to get a value for this call only<br>Settings.resolve(<br>  settingable: store,<br>  key: :checkout_flow,<br>  override: params[:checkout_flow]<br>)<br># =&gt; &quot;multi_step&quot;  (used for this request, DB unchanged)</pre><pre># Safe to pass ActionController::Parameters values directly — they are cast and normalized<br>Settings.resolve(<br>  settingable: store,<br>  key: :notifications_enabled,<br>  override: params[:notifications_enabled]   # &quot;true&quot;, &quot;1&quot;, &quot;on&quot; all work<br>)<br># =&gt; true</pre><h3>The source: Option — Reading From a Relation</h3><p>When a setting should reflect the state of a related model unless explicitly overridden:</p><pre>rmerchant = MerchantAccount.find(7)<br>merchant.requires_upfront_payment?<br># =&gt; true</pre><pre>store = Store.find(42)<br>store.merchant_account<br># =&gt; merchant</pre><pre># No stored preference yet — resolves via source lambda<br>Settings.resolve(settingable: store, key: :payment_method_required)<br># =&gt; true  (read from merchant_account.requires_upfront_payment?)</pre><pre># Now explicitly override it for this store<br>Settings.apply!(settingable: store, settings: { payment_method_required: false })</pre><pre>Settings.resolve(settingable: store, key: :payment_method_required)<br># =&gt; false  (stored preference wins over source)</pre><pre># Reset — falls back to source again<br>Settings.apply!(settingable: store, settings: { payment_method_required: nil })<br>Settings.resolve(settingable: store, key: :payment_method_required)<br># =&gt; true  (source takes over again)</pre><h3>Validation and Error Cases</h3><pre># Unknown key — raises immediately, never silently ignored<br>Settings.apply!(settingable: store, settings: { unknown_setting: &#39;x&#39; })<br># =&gt; ArgumentError: Unknown key: unknown_setting for Store</pre><pre># Value not in allowed list<br>Settings.apply!(settingable: store, settings: { shipping_provider: &#39;drone&#39; })<br># =&gt; ArgumentError: Invalid value &quot;drone&quot; for shipping_provider.<br>#    Allowed: [&quot;standard&quot;, &quot;express&quot;, &quot;overnight&quot;]</pre><pre># Wrong type<br>Settings.apply!(settingable: store, settings: { max_product_variants: &#39;many&#39; })<br># =&gt; ArgumentError: Invalid type for max_product_variants.<br>#    Expected Integer, got String.</pre><pre># Check which keys are defined for a resource<br>Settings.keys_for(store)<br># =&gt; [:notifications_enabled, :max_product_variants, :tax_rate,<br>#     :shipping_provider, :checkout_flow, :payment_method_required]</pre><h3>Working With Multiple Resource Types</h3><p>Because the owner is polymorphic, the same system works for any model:</p><pre>merchant = MerchantAccount.find(7)</pre><pre># MerchantAccount has its own definition with different keys<br>Settings.keys_for(merchant)<br># =&gt; [:payout_schedule, :currency, :requires_upfront_payment, :invoice_frequency]</pre><pre>Settings.resolve(settingable: merchant, key: :payout_schedule)<br># =&gt; &quot;weekly&quot;</pre><pre>Settings.apply!(settingable: merchant, settings: { payout_schedule: &#39;daily&#39;, currency: &#39;eur&#39; })</pre><pre>Settings.resolve_all(settingable: merchant)<br># =&gt; { payout_schedule: &quot;daily&quot;, currency: &quot;eur&quot;, requires_upfront_payment: false, invoice_frequency: &quot;monthly&quot; }</pre><pre># Store and MerchantAccount both use the same setting_values table<br># but their keys are completely separate — no collision possible</pre><h3>Inspecting What’s Actually Stored</h3><pre>store = Store.find(42)</pre><pre># See only the rows that differ from defaults (the actual DB rows)<br>store.setting_values<br># =&gt; [#&lt;SettingValue key: &quot;shipping_provider&quot;, value: &quot;express&quot;, updated_by: &quot;admin@example.com&quot;&gt;]</pre><pre># A store with all defaults has no rows at all<br>Store.find(99).setting_values.count<br># =&gt; 0</pre><pre># But resolve_all still returns full hash using defaults<br>Settings.resolve_all(settingable: Store.find(99))<br># =&gt; { notifications_enabled: true, max_product_variants: 50, ... }</pre><h3>Adding a New Setting</h3><p>Because the type system is definition-driven, adding a new key is a one-line change:</p><pre>def self.all<br>  {<br>    notifications_enabled:   { default: true },<br>    max_product_variants:    { default: 50 },<br>    tax_rate:                { default: 0.0 },<br>    shipping_provider:       { default: &#39;standard&#39;, allowed: %w[standard express overnight] },<br>    checkout_flow:           { default: &#39;single_page&#39;, allowed: %w[single_page multi_step] },<br>    payment_method_required: { default: false, source: -&gt;(s) { s.merchant_account&amp;.requires_upfront_payment? } },</pre><pre>    # New — just add it here. Type inferred from default. No migration needed.<br>    reviews_enabled:         { default: false },<br>    max_images_per_product:  { default: 10 }<br>  }<br>end</pre><p>No migration. No schema change. The new key is immediately available via resolve, and apply! will accept and validate it from the moment the file is deployed.</p><h3>Migration Strategy: Don’t Flip the Switch</h3><p>A change this broad needs a careful rollout. We designed five phases:</p><p><strong>Phase 1 — Foundation.</strong> Build the tables and core services (resolver, validator, updater). No production traffic yet.</p><p><strong>Phase 2 — High-value keys first.</strong> Migrate the settings you care most about — the ones most likely to cause bugs if wrong. This is where gaps in your definition catalog surface.</p><p><strong>Phase 3 — Backfill with dual-read.</strong> Populate the new tables from legacy sources. Run both old and new reads in parallel and compare results automatically. Parity checks catch drift before it becomes an incident.</p><p><strong>Phase 4 — Endpoint cleanup.</strong> Remove scattered settings logic from controllers. Everything routes through the projector/updater services.</p><p><strong>Phase 5 — Cohort rollout.</strong> Feature-flag the new projection endpoint. Start with a small cohort of stores, monitor error rates and validation failures, expand gradually.</p><p>The dual-read phase is the most important safety net — it lets you prove correctness before committing. For high-risk endpoints, optional dual-write makes rollback trivial.</p><h3>Key Takeaways</h3><p><strong>Defaults in code, overrides in the database.</strong> You only store what differs. This keeps the table lean and makes it easy to reason about what’s been explicitly configured vs. what’s inherited.</p><p><strong>Type inference keeps definitions concise.</strong> The default value <em>is</em> the type declaration. No extra metadata, no separate type column.</p><p><strong>Unknown keys raise immediately.</strong> Never silently ignored. This is the single biggest quality-of-life improvement over raw JSON or string KV stores.</p><p><strong>The source option bridges the gap.</strong> When a setting should reflect another model’s state by default, source: handles it cleanly — without duplicating data or coupling models.</p><p><strong>Own the projection, not the flags.</strong> Give the frontend a computed answer, not the raw inputs. You’ll ship fewer frontend changes when business rules change.</p><p><strong>Build on what works.</strong> The polymorphic owner pattern was already proven in production. Extend it rather than invent something new.</p><p><em>Have you dealt with feature flag or settings sprawl at scale? I’d love to hear what approaches worked — or didn’t — for your team.</em></p><p><strong><em>Note:</em></strong><em> This article was written with the support of </em><a href="https://mumoc.medium.com/"><em>Mumo</em></a><em> (aka Carlos Muñiz). Unfortunately I couldn’t list him as an official co-author, but his mentorship and ideas were the spark that inspired this piece.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4b7dc46e747f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Engineer Who Understands the Product Will Always Win]]></title>
            <link>https://medium.com/@igmarin/the-engineer-who-understands-the-product-will-always-win-1b073585915c?source=rss-bfcd072d0964------2</link>
            <guid isPermaLink="false">https://medium.com/p/1b073585915c</guid>
            <category><![CDATA[engineering-mangement]]></category>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[product-development-cycle]]></category>
            <dc:creator><![CDATA[Ismael G Marin C]]></dc:creator>
            <pubDate>Sat, 07 Mar 2026 22:09:24 GMT</pubDate>
            <atom:updated>2026-03-07T22:09:24.896Z</atom:updated>
            <content:encoded><![CDATA[<h4>Why the future belongs to Product Engineers — and why I believe this from personal experience</h4><p>I never planned to become a software engineer.</p><p>I started my career studying Economics. About halfway through the degree, life circumstances pushed me to make a significant change, and I transitioned into engineering. At first glance, those two paths seem completely unrelated. But over time, that combination became one of my biggest strengths — and the foundation of everything I’m about to share with you.</p><h4>The Accidental Lesson That Changed Everything</h4><p>When I started working as a freelance software engineer, it was just a friend and me. We weren’t particularly special technically. What set us apart was something subtler: we could understand the <strong>business needs</strong> behind the technical requirements. My economics background gave me a lens that most engineers around me didn’t have — I naturally thought about problems in terms of value, trade-offs, and outcomes, not just code.</p><p>But the moment that truly crystallized my thinking happened at a Startup Weekend event. I joined mostly for fun, as an experiment. What I didn’t expect was that it would change the way I think about engineering forever.</p><p>The constraint was brutal: build an MVP in under 48 hours. By the end of the event, we had something that was, honestly, <strong>kind of useful</strong>. Not impressive. Not polished. But functional enough.</p><p>Then something unexpected happened.</p><p>Every team member shared the project on social media and asked friends to try it. Within the first 12 hours, we had real users. Over the following hours, a feedback loop formed naturally: users responded, we made changes, we deployed updates, we asked for more feedback. By the end, we had over 300 users — and many of them weren’t even our friends anymore. The product had started spreading organically.</p><p>Looking back, I realized we had accidentally done something I didn’t even know had a name at the time: <strong>product validation</strong>.</p><p>That experience pushed me toward books like <strong>Rework</strong> and <strong>The Hard Thing About Hard Things</strong>, and through those ideas I arrived at a belief I’ve carried ever since:</p><blockquote>Technology is a means, not the end. The more aligned engineering is with product and business goals, the more impactful the results.</blockquote><p><strong>A Career Built Around One Idea</strong></p><p>Over the years I’ve worked across software development agencies in several roles — Engineer, Senior Engineer, Tech Lead, Product Manager, and Engineering Manager. The titles changed. The mindset didn’t.</p><p>Regardless of the role, I always tried to operate by three simple principles:</p><blockquote>1. First, understand the product.<br>2. Second, ensure what we build actually delivers value.<br>3. Third, align on constraints: time, scope, and outcomes.</blockquote><p>Sometimes the right approach is building a quick MVP. Sometimes it means phasing delivery. Sometimes it means <strong>skipping features entirely</strong> to focus on what customers truly need first.</p><p>This sounds obvious. In practice, it’s surprisingly rare.</p><h3>The Gap Nobody Talks About</h3><p>After years working across different organizations and teams, I kept noticing a pattern: a significant gap between product and engineering. Not a technical gap. A <em>collaboration</em> gap. A <em>language</em> gap. A gap in how each side defines success.</p><p>Engineering teams optimized for shipping code. Product teams optimized for shipping features. And somewhere in between, the actual question <strong>are we building the right things, and are they delivering real value? </strong>got lost.</p><p>I’ve seen two symptoms of this gap show up repeatedly, and I think they’re worth naming directly.</p><p><strong>Symptom 1: Feature Factory Mode</strong></p><p>When engineering and product operate in silos, organizations tend to fall into what I call “feature factory mode.” Decisions get driven almost entirely by two external forces:</p><blockquote>- What a competitor just shipped<br>- What a key client specifically requested</blockquote><p>Both of these inputs matter. But when they become the <strong>primary</strong> drivers of your roadmap, the consequences compound over time: fragmented products, inconsistent user experiences, growing technical debt, and a team that’s always reacting and never leading.</p><p>The deeper problem is strategic: you cede control of your product narrative to others. You stop being the one who defines where the industry is heading and become the one who follows.</p><p><strong>Symptom 2: The Estimate-Then-Disappoint Cycle</strong></p><p>When engineers aren’t connected to product context, roadmap planning becomes a guessing game. Product teams make commitments based on incomplete information. Engineering teams receive requirements and discover constraints too late to change course. The result is a familiar cycle: over-promise, scramble, under-deliver, repeat.</p><p>This isn’t a people problem. It’s a structural one. And it’s fixable.</p><p><strong>What a Product Engineer Actually Is</strong></p><p>I want to be precise here, because “Product Engineer” risks becoming another buzzword.</p><p>A Product Engineer is not simply an engineer who attends more product meetings. It’s not a new job title or a hybrid role. It’s a <strong>mindset</strong> — one defined by dual fluency:</p><blockquote>- Deep technical knowledge of the software: its architecture, its constraints, its debt, its potential.<br>- An equally deep understanding of the product: its value, its users, its competitive position, its strategic direction.</blockquote><p>The difference in practice looks like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-Q5Dd6aLMrFXmqCyAlk2vg.png" /></figure><p>One important note: <em>this is not a criticism of engineers who focus on technical excellence. </em>Technical depth is non-negotiable. Product Engineers are engineers first — the product dimension adds breadth, it doesn’t replace depth. The best engineers I’ve worked with were technically rigorous <strong>and</strong> deeply curious about the product. One doesn’t cancel the other.</p><h4>The Superpower Nobody Mentions</h4><p>Here’s what I think is the most underappreciated benefit of the Product Engineer mindset, and the one I’ve seen make the biggest practical difference:</p><blockquote>A Product Engineer simultaneously understands where the product needs to go and where the software currently stands. That combination is rare — and it’s the foundation of realistic goal-setting.</blockquote><p>When someone can hold both of those truths at the same time, something shifts in how roadmaps get built. Milestones become grounded in reality. Trade-off conversations happen earlier and with better information. The team stops making commitments that quietly everyone knows are aspirational and starts making commitments that are genuinely achievable.</p><p>This matters more than most leaders realize. Sustainable growth — the compounding kind — is built on a foundation of delivered promises and accumulated trust. And you can’t build that without the kind of clarity a Product Engineer brings to the table.</p><h4>From Reactive to Proactive: The Culture Shift That Actually Matters</h4><p>Fixing the gap between product and engineering isn’t just about improving collaboration. It’s about changing the <strong>posture</strong> of the entire organization — from reactive to proactive.</p><p>Reactive organizations wait for signals: a competitor moves, a client requests something, the market shifts. Then they scramble to respond.</p><p>Proactive organizations generate their own signals. They design their systems to <strong>learn</strong>. They build feedback loops that surface insights before clients articulate them. They have opinions about where the industry is going and act on those opinions with conviction.</p><p>The bridge between reactive and proactive is data — but not data in the abstract sense. I mean two specific kinds:</p><p><strong>Data for your customers: </strong>Usage insights that help them understand their own behavior. Benchmarks that position your platform as a source of truth, not just a transaction layer. Proactive recommendations that add value before a client even knows they have a question.</p><p><strong>Data for internal decisions: </strong>Feature adoption metrics that tell you what’s actually being used. Friction maps that reveal where users struggle. Leading indicators that help you anticipate problems and opportunities before they become obvious.</p><p>Product Engineers are uniquely positioned to build this capability, because they understand both <strong>what data the system can generate</strong> and <strong>what decisions that data could inform</strong>. That’s a powerful combination.</p><h4>Why This Matters Even More Today</h4><p>We are in the middle of a fundamental shift in what software engineering means.</p><p>With the rapid rise of AI, the cost of writing code is dropping dramatically. Tools that used to take weeks to build can now be prototyped in hours. In this environment, the scarce resource is no longer the ability to write code — it’s the ability to decide <strong>what to build</strong> and <strong>why it matters</strong>.</p><p>Engineers who understand product, business impact, and user value will be far more effective than those who focus solely on technical implementation. This isn’t a threat to engineers. It’s an invitation to expand the definition of what great engineering looks like.</p><p>The most valuable engineers in the next decade won’t just be the ones who write the cleanest code. They’ll be the ones who understand the product deeply enough to know which code is worth writing at all.</p><h4>A Final Thought</h4><p>My path to this belief was unconventional. Economics to engineering. Freelance work to startup experiments. Accidental product validation with 300 users on a weekend. A career spent moving across roles and always asking the same question: <strong>are we building the right things?</strong></p><p>I don’t think the path matters as much as the question. And I think more engineers asking that question — seriously, consistently, with curiosity — would change a lot of organizations for the better.</p><p>If any of this resonates with your experience, I’d genuinely love to hear about it. How have you navigated the gap between engineering and product in your own work? What’s worked, and what hasn’t?</p><p><em>Thanks for reading. If you found this useful, consider sharing it with someone on your team — whether they sit on the product side or the engineering side.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1b073585915c" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>