Jorge Alvarez - Blog

AI made code and design easy. Conversion is still the hard part.

2026-04-14T00:00:00Z

AI has made two things trivial: writing the code behind a website, and designing how it looks. Both used to be jobs. Now they're prompts.

That sounds like the end of the web as a craft. It isn't. It just means the craft moved.

The part that still matters — the part AI can't do for you — is building a site that converts.

Code and design are both commodities now

A year ago, "I need a website" meant hiring a developer, a designer, or both. Today, Squarespace, v0, Lovable, or Claude Code will hand you a clean, professional site from a prompt in an afternoon. The HTML is fine. The layout is fine. The typography is fine.

It's also completely interchangeable. Same hero, same three-column features block, same stock photography, same CTA. When everyone's site looks the same and ships in the same week, neither code nor design is a differentiator anymore.

If it can be generated, it can't be your edge.

And the traffic math has shifted underneath all of it. Nearly 60% of Google searches now end with zero clicks, and AI overviews drop organic click-through by as much as 61%. Fewer people are visiting, and the ones who do arrive with sharper intent. That makes every visit more expensive and more valuable — which means the site has to do real work when someone shows up.

Conversion is the part AI can't automate

Conversion isn't a visual problem. It's a thinking problem.

It's knowing who your customer actually is — not the persona, the real one, the one who opens your site at 11pm with a specific worry. It's knowing which objection kills the deal and answering it before they ask. It's knowing why people who land on your pricing page bounce, and whether the fix is copy, proof, price, or the offer itself.

AI can't do any of that for you. It doesn't know your business model. It doesn't know your customer's budget cycle. It can't look at a site that gets traffic but doesn't sign anyone up and tell you why. It'll happily generate another hero section, but the hero section was never the problem.

The code is the easy part now. The design is the easy part now. The thinking is the work.

Change the question you ask about your site

Stop asking "does it look good?" Start asking "is this bringing me customers next month?"

Here's a useful test: if an AI could answer every question your site tries to answer, would anyone still need to visit? If the answer is no, the site is doing the wrong job — and a prettier hero section won't fix it. A cleaner codebase won't fix it either.

Measure the site against the outcome you actually care about: leads, signups, contacts, revenue. That's the part no AI can replace, and that's the part worth paying for.

Summary

AI took code and design off the critical path. Anyone can ship a good-looking site in an afternoon. What AI can't do is figure out who your customer is, what stops them from buying, and how to fix it. That's conversion — and conversion is where the work lives now.

We need more open source Ruby on Rails projects

2026-04-12T00:00:00Z

I asked Claude a simple question: "If you were working on a web project, which language and framework would you choose and why? Don't think about me as a developer -- think about yourself as an LLM."

It did not pick Rails.

The LLM's honest answer

Claude picked Python and TypeScript. Not because they are better languages -- but because its code generation quality is directly proportional to how many high-quality examples exist in its training data.

Python and TypeScript dominate open source repositories, Stack Overflow, tutorials, and documentation. When an LLM writes Python or TypeScript, it draws from an enormously deep well of patterns. It makes fewer mistakes, knows more edge cases, and generates idiomatic code more reliably.

About Rails, Claude said something that should concern every Ruby developer: "I can write solid Rails code, but I'm more likely to hallucinate a method name, use a deprecated API, or miss a Rails 7+ convention. The gap isn't huge, but it's real."

I can confirm this from my own experience. I use Claude Code every day to build Rails applications -- this blog, my daily work, side projects. The AI is good at Rails. But it is noticeably better at TypeScript. It hallucinates less, catches more edge cases, and writes more idiomatic code in languages where the training data is deeper.

What makes LLMs most productive is not the language itself -- it is how well-typed and explicit the code is. TypeScript beats JavaScript for LLMs because type annotations act as self-documenting constraints. Convention-heavy frameworks like Rails, with all their implicit magic, are paradoxically harder for AI because there is more context the model needs to get right from memory rather than from explicit structure in the code.

I see this every day

Ruby and Rails were designed with a clear philosophy: optimize for developer happiness. Convention over configuration. Don't Repeat Yourself. Make the developer's life easier.

That philosophy was perfect for a world where humans wrote every line of code. But that world is changing fast.

I build with Claude Code daily. I watch it write controllers, models, tests, service objects. A growing percentage of production code -- in my projects and everywhere else -- is being written by AI agents. Claude Code, GitHub Copilot, Cursor, Codex, and dozens of other tools are becoming primary authors of code while developers shift toward reviewing, directing, and architecting.

In this new reality, developer happiness is necessary but no longer sufficient. We also need to think about AI fluency -- how well can an LLM understand, generate, and reason about code in a given ecosystem?

Right now, Ruby on Rails is falling behind on that metric. Not because of any technical shortcoming, but because of a training data gap.

The training data problem

LLMs learn from what they have seen. The more high-quality, diverse, well-documented open source projects exist in a given language, the better the LLM performs with that language. It is that simple.

Look at the JavaScript and Python ecosystems. Thousands upon thousands of open source projects, tutorials, blog posts, and examples. Every possible pattern, every edge case, every architectural decision -- documented and available for training.

Now look at Ruby on Rails. We have some excellent open source projects -- Discourse, Mastodon, GitLab, Solidus. More recently, 37signals made a significant contribution by open sourcing their ONCE products: Campfire (group chat), Writebook (online book publishing), and Fizzy (kanban tracking). These are production-grade Rails applications built by the creators of the framework itself -- exactly the kind of high-quality, real-world codebases that LLMs need to learn from.

But even with these additions, the volume does not compare to what exists in JavaScript or Python. Too many Rails applications remain proprietary, behind closed doors, invisible to training datasets.

This creates a vicious cycle: LLMs perform worse with Rails, so developers building with AI choose other stacks, so fewer new Rails projects get created, so even less training data exists, so LLMs fall further behind.

Rails magic becomes an AI obstacle

The very things that make Rails beautiful for human developers make it harder for AI agents.

Convention over configuration means a lot of implicit knowledge is required. A human Rails developer knows that a model called User maps to a users table, that has_many :posts creates a whole set of methods, that before_action callbacks fire in a specific order. This implicit knowledge is what makes Rails so productive for experienced developers.

But for an LLM, every implicit convention is a potential hallucination point. There is no type signature to anchor to, no explicit declaration to reference. The model has to recall the convention from its training data -- and if that training data is thin, it gets things wrong.

I hit this regularly. Claude Code will generate a method call that looks right but does not exist. It will use a Rails 6 pattern in a Rails 8 app. It will miss a convention that any experienced Rails developer would know instinctively. The model is not stupid -- it just has less to draw from.

TypeScript, by contrast, spells everything out. The types are right there in the code. An LLM does not need to remember conventions -- it can read the constraints directly.

This does not mean Rails needs to become TypeScript. But it does mean the Rails community needs to compensate for this structural disadvantage by flooding the training pipeline with high-quality examples.

What I am doing about it -- and what you can do too

I am not going to write a list of things "we as a community should do" and leave it at that. Here is what I am actually doing, and what I think you should consider.

I open source my work. This blog is a Rails 8.1 application. I have many Ruby on Rails projects in my public github repository. Every controller, every model, every test -- it is all training data. If you have a Rails application, even a small one, even an imperfect one, consider open sourcing it. Every public repository helps.

I write about Rails and AI. You are reading this. Blog posts, tutorials, guides -- they all end up in training datasets. I write about how I use Claude Code with Rails, how I integrate LLMs into my SaaS products, what patterns work in production. Every piece of public Rails content makes AI a little bit better at our stack. Write about how you solved that tricky Active Record query. Document your Hotwire patterns. Explain your Turbo Stream architecture.

I document conventions explicitly. The Rails guides are good, but we need more. When I write a tutorial, I spell out the things that experienced Rails developers take for granted. Instead of relying on "every Rails developer knows this," I write it down. LLMs benefit from explicit documentation of patterns and conventions that humans learn through years of experience. It might sound counterintuitive, but we should write content thinking that LLMs will read it and learn from it so they can teach the developers that use those LLMs.

Build reference applications. The Rails community would benefit enormously from a set of well-maintained, well-documented reference applications covering common patterns -- multi-tenancy, API design, real-time features with Hotwire, background job architectures, authentication flows. Not toy examples -- production-grade references. 37signals started this with ONCE. We need more.

Contribute to Rails itself. The framework's own codebase, tests, and documentation are prime training material. Better inline documentation, more descriptive commit messages, clearer test names -- all of this helps LLMs understand Rails conventions.

This matters more than you think

If LLMs consistently perform better with Python and TypeScript than with Ruby, the next generation of developers -- who increasingly rely on AI assistance -- will naturally gravitate away from Rails. Not because Rails is worse, but because their AI tools work better with other stacks.

I have been building SaaS products with Rails for 20 years. I have watched adoption cycles come and go. When Stack Overflow became the de facto knowledge base, languages with more Stack Overflow coverage gained an adoption advantage. Training data is the new Stack Overflow.

Ruby on Rails gave us an era of unmatched developer productivity. It showed the world that web development could be joyful. That philosophy still matters -- arguably more than ever in a world drowning in over-engineered complexity.

I want to make sure that when an AI agent sits down to write code, it can write Rails as fluently as it writes Next.js. And that starts with us giving those AI agents something to learn from.

Open source your projects. Write about your work. Document your patterns. The future of Rails depends on it.

Building Tools for AI Agents: What I've Learned Working with Claude Code

2026-03-26T00:00:00Z

Most developers using Claude Code treat it as a very smart autocomplete. They type a prompt, get some code, and move on. But the real power unlock happens when you start building tools for the agent — extending what it can do rather than just asking it to write code for you.

I've been spending a lot of time lately thinking about this, especially after reading Anthropic's engineering blog on writing effective tools for agents. Building tools for AI agents requires fundamentally rethinking how we design software interfaces. You're not writing an API for a human developer anymore. You're writing one for a non-deterministic system that reads documentation, makes decisions, and occasionally gets confused.

Agents don't use tools the way you do

When I build a REST API or a Ruby gem, I think about the developer who will read the docs, understand the data model, and write integration code. That developer has state in their head — they remember what they did three API calls ago.

An AI agent doesn't work that way. It operates within a context window, and every token it reads is one less token it has available for reasoning. Anthropic's team illustrates this well: imagine asking an agent to look up a contact in an address book. A traditional program would iterate through entries efficiently. But an agent has to read each entry token by token, burning through its context window on irrelevant data.

If your tool returns a 500-line JSON response when the agent only needs three fields, you're wasting the agent's most precious resource: attention.

The MCP ecosystem changed everything

The Model Context Protocol (MCP), which Anthropic open-sourced in late 2024, has become the standard for connecting AI agents to external tools. Since then, OpenAI adopted it across ChatGPT, Google confirmed support for Gemini, and the protocol was donated to the Linux Foundation's Agentic AI Foundation in December 2025. It's no longer an Anthropic thing — it's an industry thing.

For Claude Code specifically, MCP servers are how you give the agent access to your databases, APIs, internal tools, and custom workflows. There are two main transport types: HTTP servers for remote/cloud services and stdio servers for local processes that need direct system access.

There are MCP servers for GitHub, PostgreSQL, file systems, and hundreds more. And here's where it gets interesting for us as developers: you can build your own.

In fact, this very blog runs on a custom MCP server. It exposes a handful of tools — create_article, publish_article, list_categories, search_articles — that let Claude Code manage the entire content workflow. This post you're reading right now? I wrote the draft, asked Claude to add documentation links and publish it, and it did — creating the article, assigning the category, and setting the publication date, all through MCP tool calls. No admin panel, no browser, no copy-pasting into a CMS. Just a conversation in the terminal.

That's a concrete example of what I mean by building tools for the agent rather than asking it to write code for you. The MCP server for this blog is a small Rails API — about 7 endpoints — but it turns Claude Code into a full publishing assistant.

Fewer tools, smarter tools

One of the most counterintuitive lessons from working with agent tooling is that more tools is not better. Anthropic's engineering team recommends implementing fewer, more thoughtful tools that target high-impact workflows rather than wrapping every API endpoint.

Think about it from the agent's perspective. Every tool you expose adds to the decision space. If you give an agent 50 narrow tools, it has to figure out which combination to use and in what order. If you give it 10 well-designed tools that handle common workflows end-to-end, it can get things done in fewer steps with less room for error.

This is something I've experienced firsthand building tools. My first instinct was to create granular tools — one to list users, another to fetch a specific user, another to update a field. But consolidating those into higher-level operations like find_and_update_user or generate_user_report made the agent dramatically more effective.

It's the same principle behind fat models in Rails: push the complexity down into the tool so the consumer (in this case, the agent) can stay focused on the task.

How to write tool descriptions that actually work

This might be the most underrated aspect of building agent tools. The description you give a tool is not just documentation — it's the primary interface the agent uses to decide when and how to call it.

Anthropic's recommendation is to describe tools as you would explain them to a new team member. Make implicit assumptions explicit. Use unambiguous parameter names (user_id instead of just user). Include what the tool does, when to use it, and what it returns.

I've found that even small changes to tool descriptions can have outsized effects on agent performance. Adding a single sentence like "Use this tool when you need to check if a deploy is safe to proceed" to a deployment tool's description cut misuse of that tool by the agent significantly.

Here's a pattern I follow for my tool descriptions:

What it does — A single sentence explaining the tool's purpose.
When to use it — Specific scenarios where this tool is the right choice.
What it returns — The shape and meaning of the response.
What it does NOT do — Boundaries to prevent misuse.

CLAUDE.md is your project's instruction manual for the agent

If you're using Claude Code and haven't set up a CLAUDE.md file in your project root, you're leaving a lot of value on the table. This file is essentially a briefing document that Claude reads every time it starts working on your codebase. It prevents the agent from having to rediscover your build commands, test runners, architecture patterns, and conventions every session.

In this blog's Rails project at alvareznavarro.es, the CLAUDE.md file includes the development commands (bin/dev, bin/rails test, bin/rubocop), the site structure, authentication approach, model relationships, and infrastructure details. It's not long — maybe 80 lines — but it saves an enormous amount of time and makes the agent's output far more consistent.

Think of it as an onboarding document for an extremely fast but forgetful developer who joins your team fresh every single day.

Custom slash commands and skills

Beyond MCP servers, Claude Code supports custom slash commands and skills through .claude/commands/ and .claude/skills/ directories. These are essentially prompt templates written in Markdown that you can invoke during a session.

The beauty of this approach is its simplicity. You write a Markdown file with natural language instructions, drop it in the right folder, and suddenly your agent has a new capability. Need a command that generates a migration following your team's conventions? Write a .claude/commands/generate-migration.md file that describes exactly how you want it done.

Skills add an extra layer with YAML frontmatter that controls when Claude automatically invokes them. This means you can create tools that trigger based on context — the agent recognizes when a skill is relevant and uses it without you having to explicitly call it.

Design for token efficiency

Every response your tool generates costs tokens, and tokens cost both money and, more importantly, context space. Some practical guidelines:

Return only what's needed. If your tool fetches user data but the agent only needs the name and email for the current task, consider offering a response_format parameter that lets the agent choose between a concise and a detailed response.

Use meaningful identifiers. Return jorge-alvarez instead of a1b2c3d4-e5f6-7890-abcd-ef1234567890. When the agent needs to reference this entity later, a human-readable slug is far less likely to cause errors than a UUID the agent has to copy perfectly.

Implement sensible defaults for pagination. Don't return 10,000 records when the agent probably needs the first 20. Anthropic suggests capping responses at around 25,000 tokens for Claude Code.

Make errors actionable. Instead of returning Error 422, return "The user email is already taken. Try searching for the existing user with find_user(email='...')". Give the agent a path forward.

The eval loop: how to actually improve your tools

One thing that struck me from Anthropic's approach is how seriously they take evaluation. They don't just build a tool and ship it. They generate realistic test scenarios, run them programmatically, track metrics beyond simple accuracy (runtime, token consumption, error rates), and iterate.

You can adopt a lighter version of this. After building a tool, try using it with Claude Code on real tasks from your daily work. Pay attention to when the agent picks the wrong tool, when it calls a tool with incorrect parameters, and when it asks for clarification it shouldn't need. Each of these is a signal that your tool's interface needs refinement.

A structured approach to measuring tool quality — even if it's just a spreadsheet tracking success rates across a dozen test prompts — will teach you more about agent-tool interaction than any blog post (including this one).

The bigger picture

One analysis of open-source pull requests found that structured AI development with MCP servers and project-scoped configuration produced significantly fewer defects and security vulnerabilities compared to ad-hoc approaches. The exact numbers will vary across teams, but the direction is clear: giving agents well-designed tools leads to better outcomes than just letting them freestyle.

We're moving from a world where AI assists with code completion to one where AI agents orchestrate entire development workflows. The developers who learn to build good tools for these agents will have a significant advantage — not because the tools are hard to build, but because the design thinking required is genuinely different from what most of us are used to.

The good news is that if you already care about clean API design, good documentation, and thoughtful abstractions, you're most of the way there. The shift is in empathy: instead of designing for a human developer reading your docs, you're designing for an agent that reads your descriptions, makes decisions based on them, and occasionally needs to be steered back on track.

Start small. Pick one repetitive workflow in your development process, build an MCP server or a custom slash command for it, and see how Claude Code handles it. Iterate from there. That's how I started — a simple MCP server so I could publish blog posts from the terminal — and it's changed how I think about developer tooling entirely.

How I built a complete analytics dashboard for my Rails blog with Claude Code

2026-03-23T00:00:00Z

Most developers reach for Google Analytics without thinking. It's free, it's everywhere, and you already have an account. But you're running Rails -- you have a database, a server, and a framework that's very good at building things. Why hand your visitors' data to Google when you can own every line of the analytics code yourself?

I built a full analytics dashboard for this blog: unique visitors, page views, bounce rate, visit duration, traffic trends with SVG charts, geolocation by country, referral breakdowns, period-over-period comparison. It's public -- go look at it at /analytics. Every metric, every chart, every table. No third-party scripts, no cookie banners, no data leaving my server.

Here's exactly how I built it with Claude Code as my AI pair programmer.

Why build your own analytics

Four reasons, in order of importance:

Privacy. No third-party JavaScript tracking your visitors across the web. No cookie consent banners. No GDPR headaches beyond what you'd already have. Your visitors' data stays in your database, on your server.

Ownership. When Google decides to change their dashboard, deprecate a metric, or sunset Universal Analytics (again), you're not affected. Your data, your queries, your rules.

Customization. Google Analytics shows you what Google thinks matters. I wanted to see exactly the metrics relevant to a solo blog -- top pages, referral domains classified by type (social, search, other), period comparison badges, and a clean SVG trend chart. No funnel analysis, no e-commerce tracking, no noise.

Simplicity. One gem for tracking. One controller for queries. One view for display. That's the entire analytics stack. Compare that to learning GA4's event model, tag manager, data streams, and property configuration.

The alternatives like Plausible, are good products. But they cost money, run on someone else's infrastructure, and still mean you don't own the code. For a personal blog, building it yourself takes less time than evaluating SaaS options.

The tools

Three pieces make this work:

Ahoy Matey handles page view tracking. It's a Rails gem that records visits and events server-side -- no JavaScript tracker needed, no cookies. It creates two tables (ahoy_visits and ahoy_events) and gives you ActiveRecord models to query them. Configure it to run without cookies and you get privacy-friendly tracking with zero client-side code.

Geocoder + MaxMindDB handle IP geolocation. Geocoder is the standard Ruby geocoding gem. Pair it with a local MaxMind GeoLite2-City database file and every IP lookup happens on your server -- no external API calls, no rate limits, no latency. Ahoy integrates with Geocoder automatically if you tell it to.

Claude Code + Ariadna is how I actually built it. Claude Code is Anthropic's CLI tool for AI pair programming -- you describe what you want, it reads your codebase, and writes the code. Ariadna is a Claude Code plugin that adds structured planning on top. Instead of going straight from idea to code, Ariadna introduces a workflow: write a design spec that describes what to build and why, generate an implementation plan with specific tasks, file paths, and commit messages, then execute task by task with clean atomic commits. Think of it as adding a planning layer between "I want analytics" and "here's the code."

The Ariadna workflow for the analytics dashboard looked like this:

Design spec -- I described the dashboard I wanted: KPI cards, SVG charts, period comparison, geolocation. I specified Ahoy for tracking, no JavaScript charting libraries, public access without authentication.
Implementation plan -- Ariadna broke the spec into ordered tasks: install and configure Ahoy, create the Trackable concern, build the analytics controller with metric calculations, build the view with SVG charts, add geolocation, write tests.
Execution -- Claude Code followed the plan task by task. I reviewed each commit before moving to the next. If something needed adjustment, I said so and Claude Code corrected it.

The design spec was around 200 lines. The implementation plan was over 800. The resulting code was clean, tested, and shipped in one session.

Tracking page views automatically

The first thing you need is a way to record every page view without touching every controller action. A Rails concern handles this perfectly.

# app/controllers/concerns/trackable.rb
module Trackable
  extend ActiveSupport::Concern

  included do
    after_action :track_page_view
  end

  private

  def track_page_view
    return unless trackable_request?
    ahoy.track "Page View", url: request.path
  end

  def trackable_request?
    request.get? &&
      request.format.html? &&
      response.successful? &&
      !request.path.start_with?("/admin", "/login", "/session", "/up", "/mcp")
  end
end

Include this in ApplicationController and every public page request is tracked automatically. The trackable_request? method filters out the noise -- admin pages, login attempts, health checks, API endpoints. Only successful GET requests for HTML pages get recorded.

The Ahoy configuration is equally minimal:

# config/initializers/ahoy.rb
class Ahoy::Store < Ahoy::DatabaseStore
end

Ahoy.api = false
Ahoy.cookies = :none
Ahoy.server_side_visits = :when_needed
Ahoy.visit_duration = 30.minutes

Three lines that matter: api: false disables the JavaScript API (we don't need it), cookies: :none means no cookies are set on the visitor's browser, and server_side_visits: :when_needed creates visit records on the server side. Zero JavaScript. Zero cookies. Every page view is tracked by a single after_action callback.

The analytics controller -- computing real metrics

The analytics controller the raw Ahoy data and computes the metrics you'd expect from any analytics dashboard.

The controller starts by determining the time period and querying both the current and previous periods:

def index
  @period = params[:period] || "30d"
  @since = period_start(@period)
  @previous_since = previous_period_start(@period)

  visits = Ahoy::Visit.where("started_at >= ?", @since)
  previous_visits = Ahoy::Visit.where(
    "started_at >= ? AND started_at < ?", @previous_since, @since
  )
  events = Ahoy::Event.where("time >= ?", @since)
    .where(name: "Page View")
  # ...
end

Four periods are available: today, seven days, 30 days, and 12 months. Each one also queries the equivalent previous period for comparison. The seven-day view compares against the previous seven days, the 30-day view against the previous 30 days.

Unique visitors is straightforward -- Ahoy assigns each visitor a visitor_token based on their IP and user agent:

@unique_visitors = visits.distinct.count(:visitor_token)

Bounce rate requires grouping events by visit and counting how many visits had only one page view:

def compute_bounce_rate(events_scope)
  page_view_counts = events_scope.group(:visit_id).count
  visits_with_views = page_view_counts.size
  return 0 if visits_with_views == 0

  bounced = page_view_counts.count { |_, count| count == 1 }
  (bounced.to_f / visits_with_views * 100).round(0)
end

A bounce is a visit where the visitor saw exactly one page and left. Simple concept, but getting the query right matters. We group all page view events by visit_id, count them, and determine what percentage of visits had exactly one event.

Visit duration is trickier. You can only calculate duration for visits where the visitor viewed at least two pages -- single-page visits have no second timestamp to measure against. This uses SQLite's strftime to compute the difference in seconds between the first and last event:

def compute_avg_duration(events_scope)
  durations = events_scope
    .group(:visit_id)
    .having("COUNT(*) >= 2")
    .pluck(Arel.sql(
      "CAST(strftime('%s', MAX(time)) - strftime('%s', MIN(time)) AS INTEGER)"
    ))

  return 0 if durations.empty?
  (durations.sum / durations.size.to_f).round(0)
end

The HAVING("COUNT(*) >= 2") clause is critical. Without it, you'd include single-page visits as zero-duration entries and artificially deflate the average.

Period comparison computes the percentage change and flags whether the change is positive or negative -- with special handling for bounce rate, where a decrease is actually good:

def percentage_change(current, previous, inverted: false)
  return nil if previous == 0 && current == 0
  return :new if previous == 0

  change = ((current - previous) / previous.to_f * 100).round(0)
  { value: change, positive: inverted ? change <= 0 : change >= 0 }
end

The inverted: true flag for bounce rate means that when the bounce rate drops, the badge shows green, not red. Small detail, but it avoids confusing yourself every time you check the dashboard.

The helper methods that display these metrics in the view are equally direct:

# app/helpers/analytics_helper.rb
module AnalyticsHelper
  def format_duration(seconds)
    seconds = seconds.to_i
    return "0s" if seconds <= 0

    hours = seconds / 3600
    minutes = (seconds % 3600) / 60
    secs = seconds % 60

    parts = []
    parts << "#{hours}h" if hours > 0
    parts << "#{minutes}m" if minutes > 0
    parts << "#{secs}s" if secs > 0 || parts.empty?
    parts.join(" ")
  end

  def change_badge(change)
    return "" if change.nil?

    if change == :new
      tag.span("New", class: "analytics-kpi-change analytics-kpi-change--new")
    else
      css = change[:positive] ? "analytics-kpi-change--up" : "analytics-kpi-change--down"
      arrow = change[:positive] ? "↗" : "↘"
      tag.span("#{arrow} #{change[:value].abs}%",
        class: "analytics-kpi-change #{css}")
    end
  end
end

format_duration converts seconds into a human-readable string -- "2m 30s" instead of "150." change_badge renders the comparison indicator with an arrow and color.

Visualizations with pure SVG

I made a deliberate choice here: no Chart.js, no D3, no JavaScript charting library. The traffic trend chart is rendered entirely in ERB and SVG. One less dependency, works without JavaScript, and the code is surprisingly simple.

The view calculates SVG coordinates from the data and draws a polyline with a gradient fill:

<%
  points = @trend_data.to_a
  max_val = points.map(&:last).max.to_f
  max_val = 1.0 if max_val == 0
  chart_w = 800
  chart_h = 200
  usable_w = chart_w
  usable_h = chart_h - 40  # padding

  coords = points.each_with_index.map do |(_, val), i|
    x = i * (usable_w.to_f / (points.size - 1))
    y = 20 + usable_h - (val / max_val * usable_h)
    [x.round(1), y.round(1)]
  end

  polyline = coords.map { |x, y| "#{x},#{y}" }.join(" ")
  area = "#{coords.first[0]},#{chart_h} #{polyline} #{coords.last[0]},#{chart_h}"
%>

<svg viewBox="0 0 800 200" preserveAspectRatio="none">
  <polygon points="<%= area %>" fill="url(#areaGradient)" />
  <polyline points="<%= polyline %>" fill="none"
    stroke="var(--accent)" stroke-width="2.5"
    stroke-linejoin="round" stroke-linecap="round" />
  <% coords.each do |x, y| %>
    <circle cx="<%= x %>" cy="<%= y %>" r="3"
      fill="var(--accent)" stroke="var(--surface)" stroke-width="1.5" />
  <% end %>
  <defs>
    <linearGradient id="areaGradient" x1="0" y1="0" x2="0" y2="1">
      <stop offset="0%" stop-color="var(--accent)" stop-opacity="0.2" />
      <stop offset="100%" stop-color="var(--accent)" stop-opacity="0.02" />
    </linearGradient>
  </defs>
</svg>

The math is basic: map each data point to an x,y coordinate within the SVG viewBox, join them into a polyline string, and create a polygon for the gradient fill area. Grid lines are dashed <line> elements. Data point dots are <circle> elements. The whole chart responds to CSS custom properties (var(--accent), var(--surface)), so it works with light and dark themes automatically.

For tabular data -- top pages, referrers, countries -- I use inline bar visualizations. Each row has a background bar whose width is proportional to the maximum value:

<% @top_pages.each do |page, count| %>
  <tr>
    <td>
      <div class="analytics-table-bar-cell">
        <div class="analytics-table-bar"
          style="width: <%= (count / max_page * 100).round(1) %>%">
        </div>
        <span><%= truncate(page, length: 60) %></span>
      </div>
    </td>
    <td class="analytics-table-num"><%= number_with_delimiter(count) %></td>
  </tr>
<% end %>

The bar is just a div with a percentage width and a translucent background color. The text sits on top. It gives you the visual impact of a bar chart inside a table, with no JavaScript.

Adding geolocation

Knowing which countries your visitors come from is valuable, and it doesn't require an external API. MaxMind publishes a free GeoLite2 database that maps IP addresses to countries and cities. Download the .mmdb file, drop it in your project, and configure Geocoder to use it:

# config/initializers/ahoy.rb (geolocation section)
mmdb_path = Rails.root.join("db/maxmind/GeoLite2-City.mmdb")
if mmdb_path.exist?
  Geocoder.configure(
    ip_lookup: :geoip2,
    geoip2: { file: mmdb_path }
  )
  Ahoy.geocode = true
else
  Ahoy.geocode = false
end

The conditional check means the app works without the MaxMind file -- it just skips geolocation. This matters for development environments and CI where you might not have the database file.

When Ahoy records a visit, Geocoder looks up the IP address against the local MaxMind database and populates the country field. The controller query is one line:

@top_countries = visits.where.not(country: [nil, ""])
  .group(:country).order(Arel.sql("count(*) DESC")).limit(20).count

Testing

The analytics dashboard has 11 integration tests covering the full range of functionality. The test file uses two helper methods that create Ahoy records directly:

def create_visit(visitor_token: SecureRandom.hex,
                 started_at: Time.current, **attrs)
  Ahoy::Visit.create!(
    visit_token: SecureRandom.hex,
    visitor_token: visitor_token,
    started_at: started_at,
    **attrs
  )
end

def create_event(visit:, time: Time.current, url: "/blog")
  Ahoy::Event.create!(
    visit: visit,
    name: "Page View",
    properties: { "url" => url },
    time: time
  )
end

These helpers let you set up precise test scenarios. For example, testing bounce rate:

test "calculates bounce rate from single-page visits" do
  v1 = create_visit(started_at: 1.day.ago)
  create_event(visit: v1, time: 1.day.ago) 

  v2 = create_visit(started_at: 1.day.ago)
  create_event(visit: v2, time: 1.day.ago)
  create_event(visit: v2, time: 1.day.ago + 5.minutes, url: "/about") 

  get analytics_url

  assert_response :success
  assert_select ".analytics-kpi-card .analytics-kpi-value", text: "50%"
end

One visit with one page view, one visit with two page views. Expected bounce rate: 50%. The test asserts the rendered HTML contains exactly that value. Other tests cover unique visitor deduplication, visit duration calculation, zero-data handling, period selection, country display, and comparison badges.

The Claude Code workflow that made this fast

This is where I want to be specific about what "AI pair programming" actually means in practice, because most descriptions stay vague.

Claude Code is a CLI tool. You run it in your terminal, it has access to your project files, and you have a conversation about what to build. It reads your code, suggests changes, writes files, runs tests. Think of it as a very capable colleague who can type fast but needs you to steer.

Ariadna is a plugin for Claude Code that adds structure. Without Ariadna, a typical Claude Code session goes: "Build me analytics." Claude Code starts writing code, you review as it goes, you course-correct when needed. This works fine for small tasks. For anything bigger, you end up with a wandering conversation and code that reflects that wandering.

With Ariadna, the workflow has explicit phases:

Design spec. You describe what you want to build, why you're building it, and the key architectural decisions. For the analytics dashboard, the spec covered: which gem to use for tracking (Ahoy), how to handle geolocation (local MaxMind file), what metrics to compute (unique visitors, bounce rate, duration, period comparison), how to render charts (pure SVG, no JavaScript libraries), and access control (public, no authentication). The spec is a document, not a conversation -- it's written to a file that becomes the source of truth for the build.

Implementation plan. Ariadna generates an ordered list of tasks from the spec. Each task specifies exactly which files to create or modify, what the code should accomplish, and a pre-written commit message. The plan for the analytics dashboard had tasks like: "Install and configure Ahoy gem with cookie-less tracking," "Create Trackable concern with smart request filtering," "Build AnalyticsController with KPI computation methods," "Add SVG chart generation to analytics view," "Configure MaxMind geolocation," and "Write integration tests." Each task included the specific file paths, the approach, and success criteria.

Execution. Claude Code follows the plan task by task. It writes the code, runs the tests, and creates a commit. You review each commit before the next task starts. If something needs adjustment -- "that bounce rate calculation is wrong" or "I want the chart to use CSS custom properties" -- you say so, Claude Code fixes it, and the commit is amended before moving on.

Making it public

Most analytics dashboards sit behind a login. I made mine public because transparent analytics builds trust. When someone reads a blog post and wonders "does anyone actually read this?" they can check for themselves.

There's no sensitive data on the page -- just aggregate metrics. Individual visitor IPs and tokens never appear in the view. The worst someone can learn from my public analytics is which pages are popular and what countries my readers are from.

What I learned

Building your own analytics dashboard takes less time than you'd expect. The Ahoy gem handles the hard parts -- visit tracking, visitor identification, event storage. What's left is a controller that runs queries and a view that renders the results.

The total footprint: an entire analytics system in under 600 lines of code (including views). Every line is readable, every query is understandable, and every metric is computed exactly the way I want it.

Using Claude Code with the Ariadna planning workflow meant the code came out clean on the first pass. The spec forced me to make architectural decisions up front -- cookie-less tracking, pure SVG charts, inverted bounce rate comparison -- instead of discovering them mid-build. The plan gave Claude Code a clear path to follow, which meant fewer course corrections and more time reviewing code instead of writing prompts.

The stack is simple: Rails + Ahoy + Geocoder + MaxMind + CSS custom properties + ERB. No JavaScript analytics library, no charting framework, no external tracking service. Everything runs on the same server that runs the blog.

Check out my analytics at alvareznavarro.es/analytics. Then build your own. If you're running Rails, you already have everything you need.

The Five Ways to Customize Claude Code

2026-03-18T00:00:00Z

Claude Code ships with five customization mechanisms — CLAUDE.md, Skills, Sub-agents, Hooks, and MCP servers — and each one solves a different problem. Choosing the wrong one means either cluttering every conversation with irrelevant context or missing critical instructions when they matter most.

After watching Anthropic's breakdown of these tools, I wanted to distill the key ideas and share how I think about each one in practice.

CLAUDE.md — Always-On Project Standards

CLAUDE.md loads into every single conversation. It's the equivalent of a project's .editorconfig or .rubocop.yml — rules that apply unconditionally.

Use it for:

Framework preferences — "Use TypeScript strict mode" or "Follow Rails conventions"
Hard constraints — "Never modify the database schema directly" or "Always run tests before committing"
Coding style — Naming conventions, file organization patterns, preferred libraries

The key principle: if the instruction is relevant regardless of what task you're working on, it belongs in CLAUDE.md.

What doesn't belong here: detailed checklists, task-specific procedures, or domain knowledge that only applies sometimes. That's what Skills are for.

Skills — On-Demand Expertise

Skills are the opposite of CLAUDE.md in one important way: they load on demand, only when Claude matches your request to a relevant skill.

Think of it this way: your PR review checklist doesn't need to be in context when you're writing new code. It activates when you ask for a review. A deployment procedure loads when you mention deploying.

Use Skills for:

Task-specific expertise — Review checklists, deployment guides, content templates
Knowledge that's only relevant sometimes — Regulatory references, API documentation, style guides for specific content types
Detailed procedures that would add noise if they were always present

The distinction is simple: CLAUDE.md is "always apply this", Skills are "apply this when the topic comes up."

Sub-Agents — Isolated Execution Contexts

Skills add knowledge to your current conversation — they enhance Claude's reasoning within the same context. Sub-agents are fundamentally different: they run in a separate context entirely.

A sub-agent receives a task, works on it independently with its own tool access, and returns results back to your main conversation. The main conversation and the sub-agent are isolated from each other.

Use Sub-agents when:

You want to delegate a task to a separate execution context
The delegated work needs different tool access than your main conversation
You want isolation between the delegated work and what you're doing — so one doesn't pollute the other

The mental model: Skills are like calling a colleague over to look at your screen. Sub-agents are like sending a task to a colleague who works on it at their own desk and brings you back the results.

Hooks — Event-Driven Automation

Hooks fire on events, not on requests. This is the critical distinction from Skills.

A Hook might run a linter every time Claude saves a file, validate input before certain tool calls, or trigger automated side effects after Claude performs an action. They're reactive — they respond to what Claude does, not what you ask.

Use Hooks for:

Operations that should run on every file save — linting, formatting, validation
Validation before specific tool calls — sanity checks, safety guards
Automated side effects — logging, notifications, synchronization

Meanwhile, Skills are request-driven: they activate based on what you're asking Claude to do. Hooks are event-driven: they activate based on what Claude is doing.

MCP Servers — External Tool Integration

MCP (Model Context Protocol) servers provide external tools and data sources that Claude can use. While the other four mechanisms customize Claude's behavior and knowledge, MCP servers extend what Claude can actually do.

They connect Claude to external systems — databases, APIs, file systems, third-party services — giving it capabilities beyond its built-in tools.

Putting It All Together

A well-configured setup typically combines multiple mechanisms, each handling its own specialty:

Mechanism	When It Applies	What It Does
`CLAUDE.md`	Every conversation	Project-wide standards and constraints
Skills	When topic matches	Task-specific expertise and procedures
Sub-agents	When delegating	Isolated task execution with separate context
Hooks	On specific events	Automated operations triggered by actions
MCP Servers	When external tools needed	Connections to external systems and data

The key insight is: don't force everything into one mechanism. If you're putting detailed review checklists in CLAUDE.md, you're adding noise to every conversation. If you're trying to use Skills for automated validation on file saves, you're using the wrong tool.

Each mechanism has a clear purpose. Match the mechanism to the need, and combine them for comprehensive customization.

My Setup as an Example

For context, on the Rails projects I work on, my approach looks roughly like this:

CLAUDE.md: Rails conventions, test commands, deployment constraints, coding style preferences
Skills: Content creation templates, PR review checklists, compliance reference material
Hooks: Running RuboCop on saved files, validating migrations
MCP Servers: Connecting to project management tools, calendar, email

The result is a Claude that knows my project's rules at all times, brings in specialized knowledge when relevant, automates repetitive checks, and can interact with external services — all without any single conversation being overloaded with irrelevant context.

SaaS is not dying, SaaS is evolving

2026-03-17T00:00:00Z

There's a narrative gaining traction in tech circles: AI will kill SaaS. The argument goes something like this — if anyone can prompt an AI to build a custom app in a weekend, why would they pay monthly for someone else's software?

It sounds compelling. It's also wrong.

SaaS isn't dying. It's being forced to evolve.

Everyone can cook, not everyone runs a restaurant

The "AI replaces SaaS" argument is essentially saying that because you have a kitchen, you'll never go to a restaurant again. Sure, you can cook. You might even enjoy it. But there's a reason restaurants exist: consistency, expertise, the fact that someone else handles sourcing ingredients, managing health inspections, and cleaning up afterwards.

The same applies to software. Yes, AI can help you vibe-code an expense tracker over a weekend. It might even work well — for you, on your laptop, with your data. But the moment you need multi-user access, audit trails, regulatory compliance, data backups, or integration with your bank... you're no longer cooking dinner. You're running a restaurant.

The invisible cost of software isn't building version one. It's maintaining version 347 while keeping everything else running.

Where AI actually changes the game for SaaS

Instead of replacing SaaS, AI should be transforming what SaaS products can do. Here are the areas where I see the most immediate impact.

Populating forms should feel effortless

Nobody likes filling out forms. Not employees, not HR managers, not accountants. AI should be the layer that eliminates the friction: scan a document, extract the data, pre-fill the fields, ask for confirmation. The user's job shifts from data entry to data validation.

This doesn't replace the SaaS product underneath. It makes it dramatically better. The form, the validation rules, the storage, the permissions — all of that still needs to exist. AI just removes the most tedious part of interacting with it.

Business intelligence should be proactive, not passive

Traditional BI in SaaS works like this: you build a dashboard, you check the dashboard, you notice something, you act on it. The problem is that most people don't check their dashboards often enough, and when they do, they're looking at last month's data.

AI flips this model. Instead of waiting for you to ask the right question, the system should surface anomalies, generate custom reports on demand, and alert you about trends before they become problems. "Your absenteeism rate spiked 40% this quarter compared to your industry average" is infinitely more useful than a chart you might glance at once a month.

This is where SaaS has a massive advantage over any DIY tool: aggregated intelligence across thousands of companies. Your weekend project only knows about your data. A mature SaaS product can benchmark you against anonymized data from your entire industry.

The local AI experiment

Here's something I've been exploring lately: running AI models locally. Not as a replacement for frontier models, but as a practical layer for specific, repetitive tasks.

Frontier models like Claude or GPT-5 are extraordinary, but they're expensive for high-volume, low-complexity operations. If your SaaS needs to classify 10,000 support tickets a day or extract data from thousands of invoices, sending each one to a frontier API burns through your budget fast.

Training — or more precisely, fine-tuning — a smaller model for a specific task is, for now, the most practical solution. You trade general intelligence for speed and cost efficiency on a narrow problem. A 7B parameter model fine-tuned on your domain-specific data can outperform a general-purpose frontier model on that one task, at a fraction of the cost.

This creates a new architecture pattern for SaaS: use local or fine-tuned models for the heavy lifting (classification, extraction, routine analysis), and reserve frontier models for the complex, nuanced tasks that justify the cost (generating insights, handling edge cases, natural language interaction).

The SaaS products that figure out this balance will have a significant cost advantage — and that advantage gets passed to customers.

SaaS pricing will evolve too

The traditional per-seat model made sense when software was a tool that humans operated. More humans, more seats, more revenue. But AI changes that equation. If an AI agent handles 60% of the work that three employees used to do, paying for three seats feels wrong.

SaaS pricing is already shifting. Expect to see more of:

Band-based flat tiers — pay based on company size or usage volume, not headcount
Outcome-based pricing — pay for results delivered (invoices processed, reports generated, candidates screened) rather than access granted
Hybrid models — a base platform fee plus AI-powered features priced by consumption

This isn't the death of SaaS revenue. It's a realignment. The products that deliver measurable value will charge for that value. The ones that were just charging for access to a UI will struggle — and honestly, they should.

The real question isn't "SaaS or AI"

The narrative of AI killing SaaS creates a false dichotomy. The real evolution is AI inside SaaS — making products smarter, interactions smoother, and pricing more aligned with value.

The vibe-coded weekend apps will keep appearing. Some will even be useful. But the vast majority of businesses will continue choosing maintained, integrated, compliant software built by teams who do nothing but solve that specific problem, every single day.

SaaS isn't dying. The lazy version of SaaS is dying.

Introducing Mario v2 — persistent brand context for Claude Code content creation

2026-03-05T00:00:00Z

If you've ever used Claude Code for marketing content, you've probably hit
the same wall I did: every new session starts from zero. No memory of your
brand voice, no idea who your audience is, no clue about your competitors.
You end up copy-pasting the same context over and over, and the output
still feels… generic.

That's the problem Mario was built to solve, and v2 takes it a lot further.

What Mario does

Mario is a Ruby gem that turns Claude Code into a brand-aware content
engine. You run it once to build your brand foundations — identity, voice,
audience personas, competitive landscape, messaging framework — and those
foundations persist across every session after that.

The workflow is straightforward: you run /mario:new-project to set up your
brand, then /mario:create whenever you need content. Mario loads your brand
context automatically, runs topic research in the background, and routes
the work to specialised marketing agents depending on what you're creating
— whether that's web copy, email campaigns, social posts, or SEO content.

No more re-explaining who you are every time you open a new session.

The brand foundations

When you initialise a project, Mario generates 8 documents through a
structured interview process: Brand identity, Voice & tone, Audience
personas, Competitive landscape, Messaging framework, Product/service
details, Channels & distribution, and a synthesised Brand bible for quick
reference.

These aren't throwaway files. They're the persistent context that every
piece of content draws from, which is what keeps your output consistent
whether you're writing a blog post on Monday or an ad campaign on Friday.

Specialised agents

One thing I'm particularly happy with in v2 is the agent architecture.
Instead of dumping everything into a single prompt, Mario uses
orchestrators that spawn domain-specific executors — strategy, web copy,
email, social, SEO, paid ads — each loaded with its own marketing
frameworks and best practices.

There are also research agents that run in parallel to analyze competing
content before you even start writing, and audit agents that can score a
website across six dimensions. The orchestrators themselves stay
lightweight, using roughly 10-15% of context, so the specialised agents
have room to actually do their work.

Audits and competitor analysis

Two features that have been really useful in practice: /mario:audit runs a
comprehensive scoring analysis of any website with five parallel agents
evaluating content, conversion, SEO, positioning, and brand consistency. If
you just need a quick read, /mario:quick-audit gives you a 60-second
snapshot.

And /mario:competitors lets you run a side-by-side comparison of competitor
sites against your own positioning. It's a solid starting point for
figuring out where you stand and where the gaps are.

Getting started

Installation is simple:

bash

gem install marketing_mario
mario install --global

You'll need Ruby 3.1+ and Claude Code access. From there, run
/mario:new-project to build your foundations and you're ready to go. The
whole thing is MIT licensed and the source is on GitHub
https://github.com/jorgegorka/mario.

What's next

I'm already working on improvements based on how people are using it in the
real world. If you give it a try, I'd genuinely appreciate feedback — open
an issue, send a PR, or just let me know what works and what doesn't.

There's never been a better time to become a web developer

2026-03-03T00:00:00Z

I've been building for the web for over two decades. I've survived the jQuery era, the rise and fall of framework fatigue, and more "Ruby on Rails is dead" takes than I can count. And I'm telling you right now: if you're thinking about getting into web development, or you're already in it and wondering where things are headed, this is the moment.

Not because the tools are shinier. Not because salaries are up. Because the job itself has fundamentally changed — and it changed in our favor.

It was never about the code.

Here's something that took me years to internalize: web development was never about writing code. It was always about solving problems for people. The code was just the medium.

Think about it. Nobody hires you because you write elegant Ruby or perfectly typed TypeScript. They hire you because their users need something — a workflow that doesn't suck, a way to get paid faster, a dashboard that actually tells them what's going on. Your job is to figure out what that something is and make it real.

The problem is that for a long time, the "making it real" part consumed so much energy that we barely had time for the "figuring out" part. You'd spend three days fighting CSS grid or debugging a race condition, and by the time you shipped, nobody remembered what problem you were solving in the first place.

That ratio has flipped.

AI handles the typing. You handle the thinking.

AI code assistants are writing most of the boilerplate now. And honestly? They're pretty good at it. Not perfect — you still need to review, refactor, and make architectural decisions — but the days of spending an afternoon scaffolding a CRUD interface are over.

What this means in practice is that you finally have time to do the parts of the job that actually matter. Validating requirements with stakeholders before you write a single line. Questioning whether the proposed solution is even the right one. Thinking about edge cases, accessibility, performance, security — all the stuff that separates a feature from a good feature.

AI didn't replace developers. It removed the busywork that was preventing developers from doing their actual job.

Iteration speed is a superpower.

Here's where it gets really interesting. When generating code takes minutes instead of days, you can produce multiple solutions to the same problem. Not hypothetically — literally. You can build two different approaches, put them in front of real users, and let data decide which one wins.

A/B testing used to be something only companies with dedicated growth teams could pull off. Now? A single developer can spin up variants, instrument them, and iterate based on results. You're not guessing anymore. You're experimenting.

That changes the entire dynamic of how we build products. Less "I think this is the right approach" and more "let's find out.".

The end of backend developer vs. frontend developer

I'm going to say something that might be uncomfortable: the distinction between "backend developer" and "frontend developer" is dying. And if you're clinging to one of those labels, it's time to let go.

AI has lowered the barrier to working across the entire stack. The frontend specialist who "doesn't do databases" and the backend engineer who "doesn't touch CSS" — those roles made sense when each layer required deep, specialized knowledge just to be productive. But the tools have changed. You can scaffold a Rails application in seconds, write a new feature, test it, and deploy it — all in the same afternoon.

The market is moving toward full-stack web developers. People who understand the whole picture, who can own a feature end to end, who don't need to wait for three different teams to align before something ships.

Either you're a web developer, or you're competing against someone who is. Adapt accordingly.

You're a builder now

This is the mindset shift that matters most. You're not a "developer" in the old sense of the word — someone measured by lines of code, pull requests, or how many Jira tickets they close. You're a builder.

And builders are measured by what they ship.

How many features did you deliver this quarter? How many improvements made it to production? Did user retention go up? Did support tickets go down? Those are the questions that matter now. Not "how clean is your git history" or "how many code reviews did you do."

I'm not saying code quality doesn't matter — it does, as a means to an end. But the end is always the same: working software in production, making money for your company, solving problems for your users.

The best code in the world is worthless if it's sitting in a branch that never got merged.

The best code is the code in production

Let me be blunt about this one. The best code is the code that's in production making money for your company. Full stop.

Not the code that's "architecturally pure." Not the code that follows every pattern in the book. Not the code that got praised in a conference talk. The code that shipped, that works, that users interact with every day, that generates revenue.

This isn't an excuse to ship garbage. It's a reminder that perfection is the enemy of delivery. A well-tested, slightly imperfect feature that's live and generating value beats a beautifully engineered feature that's been "almost ready" for three sprints.

Three OKRs for the AI development era

If you take nothing else from this post, take this. In this new era, every feature you build should be measured against three criteria. Think of them as your personal OKRs:

Useful. Does it solve a real problem? Did someone actually ask for this, or are you building it because it's technically interesting? If users don't need it, it doesn't matter how well it's built.

Performant. Does it work fast enough that users don't notice it? Performance isn't a nice-to-have. A slow feature is a broken feature.

Secure. Is it safe? Did you think about authorisation, input validation, data exposure? Security isn't something you bolt on after launch. It's baked into every decision from day one.

Useful. Performant. Secure. If your feature checks all three boxes, you did your job. If it doesn't, nothing else matters.

The opportunity is right now

We're in one of those rare inflection points where the tools, the market, and the culture are all aligned in favor of people who build things for the web.

AI is handling the grunt work. The industry is consolidating around full-stack, outcome-oriented roles. Companies are starting to reward shipping over process. And the web itself — still the most open, most accessible, most democratic platform ever built — isn't going anywhere.

If you're already a web developer, level up. Learn to think across the stack. Embrace AI as a tool, not a threat. Focus on outcomes, not output.

If you're thinking about becoming one, stop thinking and start building. The barrier to entry has never been lower, and the ceiling has never been higher.

There's never been a better time.

Ruby on Rails efficient development with Claude Code

2026-03-01T00:00:00Z

My son Mario Alvarez Navarro and I released Ariadna, a Ruby gem that turns Claude Code into a disciplined engineering team for Rails projects.

Claude Code is exceptional for quick changes and one-off tasks, but when work gets complex (new modules, intricate integrations, features spanning multiple application layers) direct execution falls short.

Ariadna adds what's missing: structure.

The workflow is built around a three-step cycle: plan, execute, verify. Each phase produces detailed plans with Rails conventions baked in. Execution spawns specialised agents in parallel (backend, frontend, testing), each with its own context window. And verification doesn't check whether tasks were completed — it checks whether the phase goal was actually achieved.

What changes compared to using Claude Code directly:

Persistent memory across sessions. A STATE.md file tracks decisions, progress, and blockers.
Specialised agents that automatically load Rails guides based on the plan's domain.
Wave-based parallel execution, where plans without dependencies run simultaneously.
Conversational verification that evaluates results against objectives, not against a task checklist.

This is not vibe coding. You get the best results when you review both the generated plans and the outcome of each phase. It's a tool for complex work that requires human judgment at every step.

It works for greenfield projects and existing applications alike. The map-codebase command analyses the codebase before starting, and you can work with full milestones or quick tasks that maintain the same guarantees.

Open source, MIT license.

Ariadna

The bitter lesson

2026-01-20T00:00:00Z

Last week I read "The Bitter Lesson" an essay that AI researcher Rich Sutton wrote in 2019.

http://www.incompleteideas.net/IncIdeas/BitterLesson.html

His argument is simple and uncomfortable: across 70 years of AI research, the approaches that won were never the clever, hand-crafted ones built on human expertise. They were the brute-force methods that just threw more computation at the problem. Chess, Go, speech recognition, computer vision — every time, the "elegant" human-knowledge approach lost to the one that simply searched and learned at scale.

I think web development is next.

We've spent decades refining our craft. Design patterns, architectural principles, clean code philosophies, framework wars. We take pride in writing elegant solutions. And we should — it's been the right approach when humans are the ones writing and maintaining every line.

But an AI writing code doesn't need to be a craftsman. It doesn't need to intuit the "right" pattern on the first try. It can generate dozens of possible implementations, test them, evaluate trade-offs, and pick the most adequate one. Not because it understood the problem deeply, but because computation is cheap and getting cheaper.

It's brute force. And if Sutton's lesson holds, brute force wins.

This doesn't mean developer expertise becomes worthless overnight. But it does mean the value shifts — from writing the code to defining what "adequate" means. From craftsmanship to judgment.

The bitter lesson for us might be accepting that the next leap in software quality won't come from a better framework or a cleaner architecture. It'll come from a machine that just tries everything and picks what works.

Ruby on Rails MCP server that provides a knowledge base for AI agents

2025-12-27T00:00:00Z

Along with my son Mario Alvarez Navarro we have developed an open source application called Minerva.

It's a Ruby on Rails MCP (Model Context Protocol) server that provides a knowledge base for AI agents. Elevate your AI applications with enhanced reasoning and dynamic tool usage through RAG-powered document retrieval.

What is Minerva?

Minerva is a self-hosted knowledge base that connects directly to AI agents like Claude, Cursor, or any MCP-compatible tool. You feed it your documents and it makes them available to AI through semantic search, so your AI assistant can reason with your own data.

Instead of copy-pasting context into every conversation, Minerva lets your AI agent pull exactly the information it needs, when it needs it.

Features

Document Management - Create and organise markdown documents via an intuitive web UI.
PDF Processing - Upload PDFs with automatic text extraction. Drop a PDF and Minerva handles the rest.
Website Scraping - Import content from web pages and crawl entire sites to build your knowledge base.
RAG Search - Vector similarity search powered by pgvector embeddings. Minerva finds the most relevant documents for any query.
MCP Interface - Connect directly to Claude, Cursor, or any MCP-compatible AI agent. One endpoint, zero friction.

Architecture

We built Minerva with a focus on simplicity and minimal dependencies:

PostgreSQL with pgvector for vector storage (768-dimensional embeddings with HNSW indexing)
Ollama for local embedding generation using the nomic-embed-text model — no external API calls needed
Solid Queue / Solid Cache / Solid Cable for background jobs and caching — no Redis required
Propshaft + importmap-rails for assets — no Node.js required
Kamal for deployment

The entire stack runs on Rails 8 with PostgreSQL. That's it. No Redis, no Node.js, no complex infrastructure.

How it works

Minerva exposes a single /mcp endpoint that AI agents connect to. When an agent needs information, it calls the DocumentSearch tool through MCP, and Minerva returns the most relevant documents from your knowledge base using vector similarity search.

Setting it up with Claude Code is as simple as pointing to your Minerva instance:

{
  "mcpServers": {
    "minerva": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Open Source

Minerva is fully open source under the MIT license. You can find the code, installation instructions, and documentation on GitHub:

github.com/jorgegorka/minerva

Contributions are welcome!

IDEs are dead

2025-11-25T00:00:00Z

I hear a lot lately that 2026 is the year where the IDE dies. LLMs will be so good that they will generate all the code by themselves and developers will become a mix of product managers, architects and code reviewers.

Creating code has never been a goal by itself. The features that the code creates, solving problems for those using our software, that's the goal of every (valuable) line of code.

Opus 4.5 is an impressive LLM the quality of its code and its planning capabilities are astonishing. Cursor's composer and GPT codex are also very good. Based on the evolution of the last 6 months we'll have very capable LLMs in no time.

But that approach still leaves us with a big unsolved problem. It's us that still need to provide all business decisions for the LLM.

The real revolution, the big shift in how we develop software will come the day we can talk to LLMs about our business.

It is only when the LLMs understand our business that they can start asking the right questions when we ask for a new feature or a bug fix.

I can see this as a big change of paradigm same as with the autonomous car. The real change in autonomous cars is not that they can drive unattended. The change is that because they can drive unattended, I don't need to buy a car anymore, I will use an app to request one when I need it and it will take me to my destination and then leave to serve another person. That completely reshapes the automotive industry.

It's the same with LLMs. Context engineering, the current tools… they are focused on the code and we should focus on the problems that we are trying to solve with that code.

That's when the big shift will come.

Testing in the Age of AI

2025-11-11T00:00:00Z

One of the first things I integrated into my development workflow with AI was writing tests.

AIs are remarkably good at this. Give them context about your codebase, and they'll generate comprehensive test suites faster than you can write a single spec file.

The "overtesting" problem

There's a recurrent pattern: "AI tends to overtest." Too many assertions, edge cases you'd never bother with manually...

Before AI, this was a legitimate concern. Every test you write is a test you have to maintain. But if the AI writes the tests and maintains them, and your role becomes supervisory—reviewing, approving, and steering—then a bit of "overtesting" is not a big deal. The economics of quality have changed.

If you use Claude Code, create a "Testing Skill"

This is the secret to scaling consistency. Here's my approach to building one:

Audit your patterns: Let Claude examine your existing tests first so it can replicate your specific style.

Define fixture strategy: Be explicit about when to use fixtures vs. creating fresh records.

Set stub boundaries: Define what's okay to stub (External APIs? DB calls?).

Time-travel rules: Establish conventions for date/time handling to avoid flaky tests.

Add guardrails: Focus on behavior, not implementation details. No testing private methods!

E2E testing just became accessible

With Claude Code's browser integration, complex E2E tests are now just a natural language prompt away:

"Login as employee@test.com, create 3 items from different categories, assign them to different offices, and generate an items export report to CSV."

That's the whole spec. What used to be painful to maintain is now a simple conversation.

Conclusion

Improving test coverage and simplifying maintenance is the "low-hanging fruit" of AI integration. It's low risk, high visibility, and provides immediate value to any team.

Just make sure everyone shares the same Testing Skill and context. Consistency is what makes this scale.

Claude Code configuration

2025-11-05T00:00:00Z

After months of using Claude Code, I've found a configuration that's improved my development workflow.

The key? Separating roles from business logic.

My approach: Skills = Roles, Commands = Business Logic

I created dedicated skills for each role: Developer, Reviewer, Refactor, Designer, Product Manager.

Each skill contains role-specific context: best practices, patterns, architecture guidelines, dos and don'ts. Claude actually helped me create these—I just supervised and refined the content.

All domain-specific logic lives in commands. For example, my "Employees" command includes the relevant models, relationships, permissions, and roles.

What makes it work

Explicit skill loading - I always load the appropriate skill before starting an assignment.

Plan mode for complex tasks - Claude creates a detailed task list before diving in.

Context management - I clear context around 75% capacity and re-feed the skill, command, and task list (both completed and pending).

The results?

Using Claude Code (Opus 4.5) with this setup has been transformative. The code quality is consistently high, and the structured approach creates predictable results.

What's your experience with Claude Code?

Why regular feedback is so important for remote teams

2018-05-09T00:00:00Z

I've written a post for Happy Mood Score. It's called: Why regular feedback is so important for remote users.

You can find advice on topics like:

Non-verbal communication
Encourage collaboration
Focus on achievements not hours
Avoid the "Green dot syndrome"
Ask how your employees feel as much as what they are doing.

You can read the article here:Why regular feedback is so important for remote users.

How the size of a company affects developers

2018-04-05T00:00:00Z

I've been working in companies of different sizes both as a freelancer, employee and founder and although logic dictates that the size of the company will affect the way you work, I've seen developers that always try to work in the same way.You should adapt to the constrains and advantages that the company's size imposes on you.

Let's see some differences and how they impact the way you work.

The cost of delay

A small company is usually constrained by limited financial resources. That is not good nor bad. It's a fact and you should take it into account.

If a project is delayed the costs of that delay may jeopardise not only the project but the hole company. Small companies do not usually have the financial resources big companies have and therefore any delay is specially harmful for them. Yes, I know, that puts some pressure on you but that is fine as long as you are aware of that. In small companies or startups good enough is better than perfect. Do not strive for perfection, just get things done!.

Small companies should only hire "full-stack" developers. People that can help them ship code. One sprint you focus on backend development and the next sprint you focus on frontend development. Your flexibility, your ability to wear different hats is really beneficial for the company and will help it to achieve their goals.

The cost of change

W hen you work for a big company with tens or hundreds of developers you should take into account the cost of change. The way you name variables, best practices, how you review code and how you merge it. All must be know beforehand by everyone involved and that has a cost.

Changing your ticket application can be very costly both in time and money if you have 200 developers. Creating accounts, migrating information, teaching the tool... That cost is negligible in a small company,

Even small details like how you name variables or how to test your code have a big impact on big companies where all developers should follow the same best practices.

Good thing is that time is not a constraint, sure there are deadlines, but their impact is not as acute as in small companies, A two weeks delay in a 3 months project is not a big deal in a big company and may have a dangerous impact in a small company.

In may cases a small delay is desirable if that helps the project to follow all best practices that the company imposes to itself. Your role as a developer must be to generate very high quality code. Measure twice, cut once. Once some code is merged into the codebase it's exposed to all your colleagues and it won't be easy to modify later on. Your classes and methods will be used by your colleagues and any change to them will probably have deeper implications and side effects.

In big companies roles should be very clear from the very beginning and a separation between backend and frontend roles is really beneficial. It helps you as a developer to focus on a specific part of the application and makes it easier for you to apply and follow the rules and best practices.

The cost of onboarding

This cost is frequently overlooked and underestimated. Having a new person up-to-speed and productive is not easy. In small companies the biggest hurdle is not technical but making the new developer understand the business logic of the company. In a big company you don't have that problem because people work in teams where the business logic is constrained but on the other side there are many rules and best practices that you need to learn so it will also take some time for the new developer to become productive.

I've frequently found that the onboarding process of the companies I've worked for (no matter the size) is focused on technical aspects with a quick view of the company business model. I think small companies should pay more attention and explain their business model to new employees because it has a big impact on their productivity.

On the other side the cost of losing talent is bigger in a small company not only because the technical skills but also because losing someone that really knows our company, how it works, its goals and objectives makes it very difficult to replace even knowing that the onboarding process is quicker in a small company. Big companies can afford lose talent without risking as much as small companies but it's something they should avoid as well because knowing the "company culture" is an important asset.

Agile vs.efficient

We all know a lot of big companies calling themselves "agile" but I've never really seen one that truly is.

Big companies can be efficient but can never be agile. Only small companies can be agile. That is a big advantage for them if they know how to use it.

A startup can (and should) pivot and change its strategy. They can do that in less than one week. That is impossible to do for a big company where you need to coordinate a lot of people. That is the truly definition of agile: The ability of changing your mind and having a team and a process that helps you do that.

You can pivot and change strategy in a big company but you need a lot of planning and that takes time. The more people you have the more time you need to pivot. And you can do all of that change in a very efficient and optimised way but never agile.

Summary

As developers we need to be aware of the constrains and advantages of the different sizes of companies.

I've worked with some developers that try to work the same way whether they are working for a big or a small company. I think that is a big mistake that can lead to frustration both for the developer and the company. You need to be flexible and agile and adapt the way you work and the way you code to the needs of the company you are working for.

Do you know how your customers use your product?

2017-03-16T00:00:00Z

When you create your own startup and have a technological background, as I do, is very easy to think that what your customers need is a product full of features. But what your customers need is a product that makes their lives easier, period.

Having a product with the right features is more important than having a product with a lot of features.

That is why I spend a few hours every week looking at the usage patterns of Happy Mood Score.

To know how people are using HMS I use Google Analytics and Events.

The firs step is to define what I want to know. The most important thing I want to track in Happy Mood Score is:

Feedback

Peer to peer rewards

Ideas

Then there are other metrics that I want to know also like: adding new employees, 1on1 notes or teams.

All those metrics will tell me important information about the use of HMS. To capture that information I use a Google Analytics feature called: Events. In Google Analytics adding an event is very easy. You need to add the following line of code:

ga('send', 'event', 'Category', 'Action', 'Label', Value);

For instance: Let's say that I want to track when someone creates a new High 5 (High 5s are peer to peer rewards in Happy Mood Score). I would add the following event after the High 5 has been created successfully.

ga('send', 'event', 'High5', 'New', 'UserDashboard', 0);

Category: I am tracking which tool is being used, in this case the High 5.

Action: I am saving the specific action the user is doing like: New, Edit, Delete.

Label: Where is the user doing that. Users can give a High 5 to other users in different parts of the application. Now I know which place is being used the most.

Value: This is a numeric field so I use it to know if the High 5 has a message included. If that is the case then it will be 1 or 0 if no message is present.

As you can see there is a lot of interesting information that I know using events.

Combine this information with some custom metrics like, for instance, if the company is in the trial period or not, and you will have a lot of useful information to make informed decisions.

Now I can create custom reports that will tell me:

How many new employees are adding companies in the trial period?

How many High 5s are created each week/month?

Which areas of the application are being used the most/least?

Which day do people create more feedback, High 5s, ideas?

There is also a report called "Events Flow" where I can learn things like:

After reporting their status 50% of the people send a feedback message and then 16% of that people send an average of 2 High 5s to co-workers.

How cool is that? A lot of information available with a small effort.

I know there are other tools available, like Mixpanel, but I found them very expensive specially for a bootstrapped startup like us.

Are you tracking the usage of your product? I would love to know how you do it and any tips, improvements or suggestions.

Why every startup should start bootstrapped

2017-02-23T00:00:00Z

When I started Happy Mood Score 2 years ago I made the decision that it should be a bootstrapped startup.

I had a vision in my mind: Create a team management tool that team managers and HR departments would love. And I knew that in order to achieve that vision I should bootstrap.

There are two kind of investments: Seed investment and Series A, B, C,... investment.

Seed investment is used to create the startup: Hire employees, develop a product, define buyers and create a marketing strategy.

Series A, B, C... investment is needed when a startup has a solid idea, has found a business model and wants to grow, expand, acquire competitors, etc.

If you get money from investors early (seed stage) you also give them the ability to influence the company's decisions.

If you get money from investors early (seed stage) you also give them the ability to influence the company's decisions. Your vision and your goals are not what matter anymore. Now it's a shared vision and shared goals.

When the time is right (series A, B...) sharing that vision and goals with investors can boost your company. It can make a big difference. But when a company is starting it is almost never the right time.

You need to be free to make the right decisions. You need to be free to make the wrong decisions. To pivot, to change, to experiment, to evolve, to learn.

In this two years my vision and reality have clashed many times. I've learned from my mistakes. Happy Mood Score is not the product I'd developed two years ago. It has evolved, it has improved. I have also evolved and improved. We are both better than two years ago.

I'd never have had the opportunity to do so with investors joining the company from the very beginning.

There are so many hats I have to wear now. Developer, marketing, customer support, accountant. But I kinda like it. I know it doesn't scale and that it will have to change someday but I'm enjoying every minute of it while it last.

We are two people working full time on Happy Mood Score now. I do all the customer support myself. It's one of the things that I like the most. Talking to customers, people using HMS, knowing what they like, what they don't...

I'm really proud with my current marketing strategy. Online advertising is very expensive : LinkedIn, AdWords, Facebook Ads, Twitter Ads. They cost a fortune (I'll write about this in another post). So I had to be creative and use other approaches that do not involve spending $1.000/month in each of those channels.

With 20 employees you need to be the CEO 100% of your time

If you start with seed capital and you have 20 employees from the very beginning you may grow faster and you may launch a big product from the start. But with 20 employees you need to be the CEO 100% of your time. Unfortunately it involves losing contact with your customers and your product the moment your company and your vision need it the most.

It could be worse. You may hate being the CEO. All of a sudden you spend all your time managing employees, forecasts and investors. If you are a doer it can be very frustrating.

In a bootstrapped company you actually do things. You get your hands dirty from the start. When the company grows and you find yourself doing more management work than actual work then you can decide to step forward and take the role or hire a CEO. That could be a good moment for finding investors. A good investor will not only give you money but also advice on how to move into the future.

A bootstrapped startup can be harder to evolve than a seeded startup but the journey is very rewarding, you will learn a lot of things and you are going to love every single minute of it.

Would you spend $1.5 million in a domain name?

2017-02-12T00:00:00Z

I've been following sumome.com for the last year or so. I even use it on Happy Mood Score to get subscribers to our monthly newsletter about employee management, feedback, engagement, remote employees and digital nomads.

I must confess I was very surprised when they announced that they spent $1.5 million to buy sumo.com. That is a lot of money for a generic domain.

Noah Kagan, the founder of SumoMe has a podcast explaining the lessons learned spending that ludicrous amount of money on a domain. Also there is an infographic about how expensive the domain was. Hint: You can buy 28,301 sumo belts with that money.

These are the reasons why I would never spend so much money on a domain like sumo.com:

It's a word that is unrelated to your business relevant keywords.
The sport (Sumo) is really well known all over the planet. Sumo has a strong association for most of us and that association is big guys slapping and pushing each other's out of a ring. Do not forget about throwing salt. :-)
I reckon that for much less than the cost of sumo.com they could have renamed the company, buy a cheap .com and spend a few hundred of thousands advertising the rebranding.

I wonder how many visitors they will get that are looking for some information about Sumo (the sport) and end up visiting that domain.

Noah Kagan is a very smart guy. He did an amazing job at Mint so what I won't do is to criticise or underestimate him. I'm not saying that he's wrong only that I would have put my branding money in another place.

Now let's wait and see what the ROI of this huge buy is. I'm sure he'll write a post about it in due time.

peer-to-peer rewards as a way of recognition at work

2016-06-21T00:00:00Z

Peer-to-peer rewards are the best form of recognition at work. Well, maybe not the best but one of the best. It is in the top 3, that’s for sure.

In most companies recognition usually comes “from above” and that is good, we all love that our boss/manager recognise our hard work and commitment. That is part of your job as a boss because to be a good leader you must acknowledge the work of your team members. It is mandatory and if you don’t do that then you are not a good boss, period.

But when you receive recognition from one of your co-workers then things change, you feel proud and happy. Your self-esteem increases as do your sense of belonging to the team. And that is because your co-workers don’t need to reward you for your hard work. They have no obligation, it is entirely optional and that is the main reason that it feels really great when they do.

If you are a digital nomad or you work on a distributed team there is the risk of feeling disconnected. You work as an individual and your sense of belonging to a team can be very low. In these environments having a peer-to-peer reward system is very important.

The simple act of sending a virtual High 5 to one of your colleagues can have a big impact on both of you. It will increase your involvement with the team and will increase the self-esteem of the receiver. It is the best way to recognise the work of those team members who are always ready to help, good team players, good co-workers…

Happy Mood Score has peer-to-peer rewards available for everybody, we call them High 5.

Don’t reward the rewards

A question that frequently arise when using Happy Mood Score Hi 5 is: when I receive a High 5 from one of my co-workers, why I can’t see who gave it to me?.

The reason is very simple. From my experience implementing reward systems on companies, people who receive a High 5 tend to give another High 5 to the person that sent it as a way of saying thank you.

That is not a good use of a peer-to-peer system and must be avoided. If you don’t know who send a High 5 to you, you can’t, obviously, give another in return. This measure will increase the efficiency of the system in the long term.

If you are a team manager, work for the human resources department or you are thinking about implementing a peer-to-peer reward system at your company there is no better tool than Happy Mood Score.