Simon Willison described the core risk well in The Lethal Trifecta. When three things combine in a system: access to private data, exposure to untrusted content, and the ability to communicate externally, the situation becomes dangerous.

The reason is structural: LLMs follow instructions in content. That is what makes them useful. It is also what makes them exploitable. An attacker embeds instructions in a document, an email, a webpage, and the model may execute them.

Prompt injection is the number one vulnerability in LLM applications according to OWASP's Top 10 for LLMs. And unlike SQL injection, where patterns are well-defined and tools are mature, LLM security does not yet have a comparable development workflow.

I tried to compile some best practices into two Claude Code skills, or better said, agentic skills because they should work with multiple agent harnesses.

I want to be clear upfront: this will not protect you as well as a static analysis tool would. LLM-based security review is not the same as deterministic rule checking. What these skills do is give you a structured checklist, grounded in authoritative sources, that you can run as part of your normal workflow. Still even if you use these skills you can still be open to prompt injection or other possible attack vectors. But I think these are a good start or at least a better start.

I am of course open to PRs and changes at https://github.com/lucianghinda/llm-prompts-skill if you discover better heuristics that we can apply to improve the security of LLMs prompts.

The Problem

Think about what "checking for prompt injection" actually means in practice. It is not one thing. The OWASP LLM01:2025 checklist has 23 items just for direct injection. MITRE ATLAS adds 12 mitigation controls. NVIDIA NeMo Guardrails covers another 16 implementation patterns for RAG pipelines and jailbreak detection.

That is 51 distinct checks, and the list grows every time a new attack vector is discovered.

We have linters for code style, static analysis for bugs, dependency scanners for known CVEs. We have nothing comparable for LLM security that runs as part of a normal development workflow. Knowing about prompt injection in the abstract and having a structured way to check for it are two different things.

So I tried to build something useful here.

What I Built

Two companion skills, designed to be used with the Claude Code CLI or Codex or OpenCode or any kind of agentic harness that uses skills.

llm-prompts:reviewer — point it at any codebase and it runs 51 checks across OWASP, MITRE ATLAS, and NeMo Guardrails. Every finding is rated CRITICAL / HIGH / MEDIUM / LOW with a precise location in your code and concrete remediation guidance. Of course when I say "running the 51 checks" I mean the LLM will try to read the code, understand it and check it against those checks. This is not a static analysis tool.

llm-prompts:builder — answer 6 questions about your integration (role, task, data sources, output usage, language, architecture) and it generates a secure system prompt plus scaffolding code. Every generated line is annotated with the check ID it satisfies: # WHY: [O-7].

Here is what a reviewer report looks like:

PROMPT INJECTION SECURITY REVIEW
=================================
Scope:    codebase
CRITICAL: 3 fail / 2 pass
HIGH:     5 fail / 4 pass

TOP RISKS
---------
1. [O-7] No structured prompt separation
   Risk: User input is concatenated directly into the prompt
         — attacker can override system instructions
   Location: app.py:42
   Remediation: Wrap user input in a USER_DATA_TO_PROCESS block
                with --- delimiters...

The 51 Checks, Briefly

The framework is grounded in three authoritative sources.

OWASP LLM01:2025 (O-1 through O-23) covers the fundamentals: input validation, injection pattern detection, typoglycemia defenses (deliberately misspelled words used to bypass keyword filters), the StruQ structured prompt separation pattern, output validation, system prompt leakage, HTML/Markdown injection in outputs, access control, rate limiting, logging, and alerting.

MITRE ATLAS (M-1 through M-12) maps to their adversarial AI threat framework: GenAI Guardrails (AML.M0020), GenAI Guidelines (AML.M0021), Human-in-the-Loop gates (AML.M0029), Tool Invocation restrictions (AML.M0030), Memory Hardening (AML.M0031).

NeMo Guardrails patterns (N-1 through N-16) go deeper into RAG-specific risks: pre-indexing document validation, retrieval filtering, source attribution, heuristic and classifier-based jailbreak detection, PII detection, and three-layer defense configuration.

Each finding in the report maps to one of these check IDs so when you fix something, you know exactly which risk you addressed.

Of course I feel the need to say again that this is not a static analysis tool but an LLM so it might skip some of these checks or decide that they pass even if they should not. I see this as a starting point and you should make sure to manually review the prompts.

The Builder: Focused on security

I think the reviewer is the more immediately useful skill, but the builder is more interesting to me as a design idea.

The insight is this: it is easier to build something secure from the start than to retrofit security onto existing code. The builder operationalizes that by generating code where every defense is intentional and documented.

You answer the six questions, and it generates in Ruby and if you need to in Python:

• A system prompt with all five OWASP structural elements present

• guardrails.rb with InputGuardrail (length limits, encoding detection, injection pattern matching, typoglycemia defense) and OutputGuardrail (leakage detection, PII scanning, HTML injection detection)

• integration.rb with rate limiting, structured logging, and the main request handler

• tools.rb if you chose tool calling — parameterized queries, allowlisted tables, human-approval gates for destructive actions

• rag.rb if you chose RAG — pre-indexing validation, retrieval filtering, source provenance tracking

For JavaScript/TypeScript, the builder generates the prompt construction function.

Every generated line of code includes a comment like # WHY: [O-7]. That annotation does two things. First, it makes the purpose of the code explicit a future developer can see that a particular block exists to prevent structured prompt injection, not as an arbitrary formatting choice. Second, it makes the code reviewable against the framework. You can grep for WHY: [O-7] and immediately see all the places where that specific check is addressed.

This is what I mean by security that documents itself. The check IDs become a shared vocabulary between the code, the review report, and the security team without any additional documentation effort.

A Reference Implementation

The repo includes two fixture apps in tests/fixtures/:

• defended-app/ — a complete Flask + OpenAI chatbot that demonstrates every defense. This is the canonical reference the builder generates from.

• vulnerable-app/ — the same app, stripped of all guardrails. Raw string concatenation, no validation, no structured separation.

I found having both versions genuinely useful while building this. The vulnerable version is not just for illustration — it is the test target. Seeing what an insecure app looks like at the code level makes it much easier to recognize the same pattern in your own codebase.

Testing

I wanted to be able to trust that the skills catch what they claim to catch.

The test suite runs both skills against the fixture apps using the real Claude CLI and validates that the output contains the expected PASS/FAIL verdicts:

# Reviewer against both fixtures
./tests/run-tests.sh --claude-only vulnerable-app
./tests/run-tests.sh --claude-only defended-app

# Builder scenarios
./tests/test-builder-claude.sh basic-chatbot
./tests/test-builder-claude.sh rag-assistant
./tests/test-builder-claude.sh tool-calling-agent

Each test invokes real LLM calls, so they take 60-180 seconds. A test fails only when a CRITICAL or HIGH verdict is missing — MEDIUM and LOW mismatches are reported as warnings.

The supported languages for code templates are Python, JavaScript/TypeScript, Ruby, and Go.

What This Is and Is Not

I want to be honest about the limits here.

LLM-based security review is not deterministic. A static analysis tool will catch every instance of a pattern, every time, with no variation. These skills run a checklist using an LLM, so results can vary. Willison's point in the lethal trifecta piece is worth repeating: in security contexts, 95% protection is not protection. A missed check is a real gap.

So I am not arguing this replaces a security audit. A dedicated penetration tester will find things this framework misses. I am not even arguing these skills are equivalent to a good static analyzer.

What I think they do: they raise the floor, especially for solo developers and small teams building LLM features without dedicated security expertise. The 51 checks give you a structured starting point you can run during development, not just at the end. The check IDs give you a shared vocabulary. And the annotations give you documentation you did not have to write separately.

It is more comfortable to identify gaps in a review report than to explain them after a production incident.

The project is open source. If you find that the builder generates code that does not hold up against your real requirements, or if you think I got a check wrong, I would genuinely like to know. Please open an issue.

Resources

• The Lethal Trifecta for AI Agents by Simon Willison

• OWASP Top 10 for Large Language Models 2025

• OWASP Prompt Injection Prevention Cheat Sheet

• MITRE ATLAS — Adversarial Threat Landscape for AI Systems

• NVIDIA NeMo Guardrails

• StruQ: Defending Against Prompt Injection with Structured Queries

• llm-prompt-injection-reviewer on GitHub

Why I built this

Seeing the skills for upgrading a Rails app released in the last months with the one from OmbuLabs/FastRuby.io being released last week:

• OmbuLabs/FastRuby.io: detection patterns, gem compatibility data, upgrade methodology

• maquina-app/rails-upgrade-skill by Mario Alberto Chávez Cárdenas: breaking changes reference tables, deprecation timeline

I got thinking that maybe it is time for superpowers-rusuperpowers-rubyby to have such a skill.

The workflow

The skill runs a six-step process, but three of those steps are hard gates: the agent cannot proceed past them unless a condition is met.

The first gate is a green test suite. The agent runs the tests before touching anything. If tests are failing before the upgrade starts, failures after the upgrade are ambiguous. You cannot tell what you broke from what was already broken. I have made that mistake before.

The second gate checks config.load_defaults. If there is a new_framework_defaults_*.rb file from a previous upgrade with unresolved settings, that needs to be resolved before starting another upgrade. Stacking unresolved defaults makes the transition plan unreliable.

The third gate is explicit approval. Before the agent touches any files, it compiles an upgrade report: configuration changes, code issues by severity, gem updates, and a load_defaults transition plan. I have to approve that report before anything is modified. Some upgrades are a few dependency bumps. Others involve weeks of work. I want to know which one I am starting before it has already begun.

Between the gates, the skill fetches a live configuration diff from GitHub:

https://api.github.com/repos/railsdiff/rails-new-output/compare/v{FROM}...v{TO}

This is the data behind railsdiff.org. Every config file added, modified, or removed between two Rails versions, fetched on each run. I did not want to maintain a static list that would go stale the moment a new version shipped.

For code-level detection, the agent searches the codebase directly with Grep. It looks for things like Rails.application.secrets, params == comparisons, config.cache_classes, ActiveRecord::Base.connection without a block. No script generation, no round-trip. Findings come back with file:line references.

Reference files

I included seven reference files in the references/ directory:

• breaking-changes.md: HIGH/MEDIUM/LOW tables for all seven version pairs from 5.2 through 8.1

• detection-patterns.md: Grep and Glob patterns organized by version pair

• gem-compatibility.md: ~50 popular gems with the minimum required version for each Rails release

• load-defaults-guide.md: every config.load_defaults setting from 5.2 through 8.1 with risk tiers

• deprecation-timeline.md: when features were deprecated, when they were removed, what replaced them

• dual-boot-guide.md: complete next_rails setup including the NextRails.next? pattern and CI config

• troubleshooting.md: common upgrade errors and their fixes

I originally considered splitting the load_defaults guide and dual-boot setup into separate companion skills. I decided against it. Having everything in one place means there is nothing extra to install, and the reference material stays in sync with the skill itself.

The fetch-changelogs script

There is also a small utility at scripts/fetch-changelogs.sh. It fetches CHANGELOG entries for a specific Rails version from GitHub and writes them to files, one per component and a consolidated version.

./scripts/fetch-changelogs.sh 8.1.0
./scripts/fetch-changelogs.sh 8.1.0 ./changelogs
./scripts/fetch-changelogs.sh --list-versions

Rails keeps separate CHANGELOGs per component: Action Cable, Active Record, Action Pack, and nine others. The script fetches all twelve and extracts just the section relevant to the requested version. I find it useful to read the raw changelog before running the upgrade workflow.

Attribution

I want to be clear about where this came from. Two existing skills did the hard work of organizing the reference material I use here:

• OmbuLabs/FastRuby.io: detection patterns, gem compatibility data, upgrade methodology

• maquina-app/rails-upgrade-skill by Mario Alberto Chávez Cárdenas: breaking changes reference tables, deprecation timeline

Both are MIT-licensed and both are excellent. If you are looking for a Rails upgrade skill, I genuinely recommend looking at them first and using them directly. At the moment they are more battle tested than this skill and also those are skills from people with a long track record. Ombulabs/FastRuby are having the biggest experience with Rails upgrades so I think their skill is the best one so far.

Here is what I added/changed in this skill:

1. Self-contained, no external dependencies. OmbuLabs requires three companion skills installed. My version works anywhere Claude Code works.

2. Live config diffs from railsdiff.org. Neither source skill fetches configuration changes from the actual railsdiff.org data. The GitHub API call on every run means the diff is always current.

3. No script generation, no MCP dependencies. Nothing extra to install or configure.

4. Three hard gates. Green test suite, clean config.load_defaults, and explicit approval before any execution. Not soft suggestions but actual stops.

5. A pragmatic version range. Mario covers 7.0+, OmbuLabs goes back to 2.3. I chose 5.2 through 8.1 because that is the practical range for most apps still being upgraded today.

6. A linear six-step workflow. OmbuLabs has eight steps with numbering gaps. I wanted a clear sequence with no ambiguity about what comes next.

7. An integrated upgrade report. railsdiff config data, codebase detection findings, and an effort estimate in a single template, before any approval is requested.

8. Cross-references to the official Rails upgrade guide. Neither source skill does this explicitly.

If my version does not fit your workflow, their skills are the right starting point for building your own or use them as they are.

I think this is one of the more interesting things about working with LLMs on developer tooling. You can take reference material that other people have carefully organized, mix it with your own workflow preferences, and get something that fits exactly how you work. The raw material was already there. I just combined it differently.

My additions are small compared to what both teams built. I am grateful to them for releasing it all under MIT.

No migration needed

Purely additive release. If you are on 6.0.x, reinstall the plugin or update it to pick up the new skill. Or wait until you actually need to upgrade Rails.

If you try it and find something that does not work well, I would love to hear about it.

Resources

• superpowers-ruby v6.1.0

• OmbuLabs/FastRuby.io rails-upgrade-skill

• maquina-app/rails-upgrade-skill by Mario Alberto Chávez Cárdenas

• railsdiff.org: the config diff tool the skill uses

So I analyzed 48+ planning skills across five repositories and combined the strongest elements into one flow. That is superplanning.

The problem with using multiple planning skills

When I started using Claude Code for serious product work, I had at least five planning-related skills available: ce:brainstorm for requirements, ce:plan-beta for implementation units, office-hours for pressure-testing ideas, plan-ceo-review for scope discipline, plan-eng-review for architecture review. These were the main ones.

Each one did something the others didn't. But using them together meant manually carrying findings from one session into the next, re-establishing context every time, and deciding myself which skill to reach for first.

What superplanning does

Superplanning is a single Claude Code skill that handles three scenarios: brainstorming an idea, planning a new product, planning a new feature for an existing codebase all using a shared 7-phase flow.

Phase 0: INTAKE & ROUTE     — detect mode, check for prior work, classify scope
Phase 1: GROUND             — research context
Phase 2: CHALLENGE & EXPLORE — pressure test the premise before any solution work
Phase 3: DEFINE             — produce requirements doc or product docs
Phase 4: STRUCTURE          — break work into implementation units
Phase 5: VALIDATE           — multi-persona review (CEO → Design → Eng)
Phase 6: DEEPEN             — targeted research on weakest sections (conditional)
Phase 7: HAND OFF           — summary, artifacts, recommended next step

You don't choose which skill to use. Phase 0 detects what you're doing and routes accordingly.

Three things I found worth preserving

There were 15 techniques worth integrating from the source skills. I want to explain three of them, because they are the ones I did not find elsewhere.

Stage-routed forcing questions. The six forcing questions from office-hours — Demand Reality, Status Quo, Desperate Specificity, Narrowest Wedge, Observation & Surprise, Future-Fit are not all asked in every session. They route by product stage. Pre-product gets Q1–Q3. Teams with paying customers get Q4–Q6. Asking a team with 500 paying customers to prove demand is insulting and irrelevant. The routing makes the questions land where they actually hurt.

Anti-sycophancy as structural constraints, not style guidance. "Be critical" is tone advice and models ignore it. The stronger approach is naming the specific phrases that signal sycophancy and banning them:

• "That's interesting" → take a position instead

• "There are many ways to think about this" → pick one, state what evidence would change your mind

• "That could work" → say whether it WILL work and what evidence is missing

The rule is: take a position AND state what evidence would change it. If the behavior you would use to hedge is named and banned, the model cannot accidentally use it.

Confidence gap scoring. After a plan is drafted, each section is scored trigger count (checklist problems found) + risk bonus + critical-section bonus. Only the top 2–5 sections are deepened with targeted research. Generic "improve the plan" instructions produce uniformly padded plans. Scoring concentrates improvement where the plan is actually weakest.

At the end you will have a series of documents under docs that you can use in any future planning session.

What each source contributed

I want to be clear about attribution because the useful techniques here came from other people's work. This is based on their experience and how they shared that experience through agent skills.

The flow spine and requirements document template with stable IDs (R1, R2...) came from ce:brainstorm in compound-engineering. The implementation unit structure (each unit specifying exact file paths, requirements trace, test scenarios, verification) came from ce:plan-beta, also compound-engineering. The forcing questions and anti-sycophancy rules came from office-hours in gstack. The scope modes came from plan-ceo-review in gstack. The shadow path tracing technique came from feasibility-reviewer in compound-engineering, elevated to a Prime Directive in the CEO review phase. The confidence gap scoring came from deepen-plan-beta in compound-engineering. The multi-persona document review came from document-review, also compound-engineering.

The full attribution table with what was used and how it was adapted is in SOURCES.md.

Installation

Copy skills/superplanning/ into your global Claude skills directory:

cp -r skills/superplanning ~/.claude/skills/superplanning

Or point --plugin-dir at the repo root for a single session:

claude --plugin-dir /path/to/superplanning

Or copy skills/superplanning/ into your project's .claude/skills/ directory for project-local access:

your-project/
└── .claude/
    └── skills/
        └── superplanning/

The skill works in other agentic tools too (Codex, Gemini), not just Claude Code.

The skill triggers automatically from phrases like "brainstorm this idea", "plan this from scratch", "is this worth building". You can also invoke it explicitly: superplanning, here's my idea: [describe it].

I think this is genuinely useful not because the 7-phase flow is clever, but because having the challenge phase happen before the define phase, automatically, without you having to remember to run a separate skill, changes what you end up with.

If you try it and find something that doesn't work as described, I would be glad to hear about it.

Resources

• superplanning on GitHub

• compound-engineering-plugin — source for ce:brainstorm, ce:plan-beta, ce:ideate, deepen-plan-beta, document-review, feasibility-reviewer

• gstack skills — source for office-hours, autoplan, plan-ceo-review, plan-eng-review, plan-design-review

• superpowers — source for brainstorming, writing-plans, subagent-driven-development

• agent-os — source for plan-product, shape-spec

• rails-claude-code — source for mvp-creator

The compound skill

I found that the compound skill from the folks at Every solves the problem of redisovering the same solution in various forms. The idea is simple: right after you and your agent fix something - while the context is still fresh - you capture what you actually did into a structured learning doc in docs/solutions/.

Next time you hit the same class of problem, the agent learns and uses it.

I think this is one of the most useful skills to add to a Ruby/Rails project. When you are working on a Rails app, you accumulate a lot of tribal knowledge - about how your specific setup works, what N+1 patterns are common in your models, how your Stimulus controllers are wired. The compound skill makes that knowledge persistent and searchable.

I adapted the skill for superpowers-ruby from the original compound-engineering-plugin. The changes were mostly about conventions, reducing the frontmatter to name and description only, rewriting the description to be trigger-first, and compressing the content from 1901 to 690 words. The core idea is entirely from the Every team and I want to give them full credit for it.

The companion: compound-refresh

The second skill is superpowers:compound-refresh. This one runs after refactors, Rails upgrades, or migrations - when the learnings you captured might have drifted from how the code actually works now. Based on the same skill from compound-engineering-plugin.

It has two modes. In interactive mode, it asks you one question at a time and leads with a recommendation. In autonomous mode (mode:autonomous), it processes everything without asking, marks ambiguous cases as stale, and generates a full report at the end.

There are four outcomes for each learning doc: Keep, Update, Replace, or Archive. The hardest distinction to get right is Update vs Replace - if you find yourself rewriting the solution section, that is Replace, not Update.

I also added a Common Mistakes section to this skill because I found during testing that agents would Archive learnings when the referenced files were gone - even when the problem domain was still active. The file being gone does not mean the problem went away.

Ruby skill improvements

I also revisited the ruby skill itself.

The original description started with "Ruby language conventions, idioms, and modern features (3.x+) for writing idiomatic Ruby code. Covers error handling patterns..." - and I found this was causing a problem.

When agents see a description that summarizes the content, they use it as confirmation they already know the topic. They answer from training memory instead of loading the skill body. For general Ruby questions this is fine, but the skill contains opinionated conventions that agents do not know by default - like the Weirich raise/fail distinction.

Here is what I mean. Ask an agent "should I use raise or fail?" without loading the skill and you get:

▎ "They are aliases in Ruby. Use whichever you prefer."

That is technically true. But the Weirich convention says: use fail when raising a new exception, reserve raise only for re-raising a caught one. It is a semantic signal to readers about intent. Agents only know this if they read the skill.

I rewrote the description to start with "Use when..." and added raise vs fail as a keyword so the skill surfaces for the exact questions it uniquely answers. I also added an Overview section and a Common Mistakes table

• including rescue Exception which catches SignalException and NoMemoryError and should almost never be used.

Ruby commit message skill

The release also includes a smaller addition: a skill for writing Ruby-style git commit messages (PR #1). It covers tense, length limits, subject/body separation, and conventions for referencing Ruby classes, methods, and modules in commit subjects.

You can find all of this in superpowers-ruby v5.0.6. If you try the compound skills on a Ruby or Rails project and find something that does not work well, I would be glad to hear about it.

Resources

• superpowers-ruby v5.0.6

• EveryInc/compound-engineering-plugin — the original compound skill this was adapted from

• Jesse Vincent's superpowers — the base this project is built on

Let's start.

The 3 Cops

The cops are:

1. Style/SelectByKind (PR #14808)

2. Style/SelectByRange (PR #14810)

3. Style/PartitionInsteadOfDoubleSelect (PR #14923)

Each is marked as correctable so if you run this you can automatically apply the changes.

1) Style/SelectByKind

This one rewrites class/module filtering from select/reject to grep/grep_v.

# before
array.select { |x| x.is_a?(Foo) }
array.reject { |x| x.is_a?(Foo) }

# after
array.grep(Foo)
array.grep_v(Foo)

From the PR discussion, two details mattered to me:

• The name changed from SelectByClass to SelectByKind, because modules are valid too, not only classes.

• There is historical context: Enumerable#grep has existed in Ruby for decades, and class matching via === is old Ruby behavior, not a new trick.

I am not saying select { is_a? } is bad code. I am arguing grep(Foo) signals intent faster once the team gets used to it.

Why does grep(Foo) work at all?

Enumerable#grep filters by evaluating pattern === element for each element, where the pattern is always on the left. The left-hand operand decides what === means: Class defines it to call is_a?, Range defines it to call cover?, and Regexp defines it to call match?.

This is why grep(Foo), grep(1..10), and grep(/pattern/) all work the same way. The unifying idea is that grep is a pattern filter, and === is the protocol each pattern type implements.

One thing to watch: if you are using find { |x| x.is_a?(Foo) }, do not rewrite it to grep(Foo).first. The find version stops at the first match. The grep version builds the entire result array first, then takes the first element. The cop intentionally excludes find/detect for exactly this reason.

2) Style/SelectByRange

This one rewrites range checks to grep(range) / grep_v(range).

# before
array.select { |x| (1..10).cover?(x) }
array.reject { |x| (1..10).cover?(x) }

# after
array.grep(1..10)
array.grep_v(1..10)

This PR was explicitly inspired by SelectByKind, and follows the same philosophy: if you are pattern-filtering, use Ruby's pattern-filtering API directly.

For me, this is a consistency win more than anything else. If your codebase already uses grep for regexp or class matching, range matching with grep fits naturally. So if you enable the first cop I shared you should also enable this one.

3) Style/PartitionInsteadOfDoubleSelect

This one is a bit more practical.

# before
positives = array.select { |x| x > 0 }
negatives = array.reject { |x| x > 0 }

# after
positives, negatives = array.partition { |x| x > 0 }

The PR went beyond the obvious case. During review, it added support for:

• &:symbol forms

• mixed forms (select(&:positive?) + reject { |x| x.positive? })

• structural negation pairs (select { expr } with select { !expr }, and same for reject)

To keep in mind: === Is Not Symmetric

There is one thing I want to make explicit because it is easy to get wrong and the mistake is silent in case you are new to Ruby.

=== is a regular Ruby method called on the left-hand object. So A === B calls A.===(B)

Integer === 42        # calls 42.is_a?(Integer)  → true
(1..10) === 5         # calls (1..10).cover?(5)   → true
/foo/   === "foobar"  # calls /foo/.match?("foobar") → true

If you reverse the order, you are calling === on a plain object: an integer instance, a string instance, a custom class instance. None of those override ===. They fall through to Object#===, which is just self == other.

42 === Integer        # 42 == Integer  → false (always)
5  === (1..10)        # 5 == (1..10)   → false (always)
"foobar" === /foo/    # "foobar" == /foo/ → false (always)

The part to pay attention is that Ruby will return false and not raise an error because those objects are implementing the === comparison. It is not just what you might expect it to be. You just get the wrong answer.

Here is the trap in a realistic scenario:

data = [1, "hello", 2, "world", 3]

# correct
data.grep(Integer)                    # => [1, 2, 3]
data.select { |x| Integer === x }     # => [1, 2, 3]

# reversed: looks similar, silently broken
data.select { |x| x === Integer }     # => []

The reversed version returns an empty array every time, with no warning, as it is expected cause the object x is defining ===.

You can find out that in these two cases there are two different methods executed:

1.method(:===) # => #<Method: Integer#===(_)>
Integer.method(:===) # => #<Method: #<Class:Integer>(Module)#===(_)>

The method Integer#=== is defined as an alias for == and says this:

Returns whether self is numerically equal to other:

But the method from Module#=== is defined as:

Returns whether other is an instance of self, or is an instance of a subclass of self

There is one edge case where reversal accidentally works by default: when both sides are strings.

"hello" === "hello"   # => true   (String#== compares values)
"hello" === "world"   # => false

This works because String#== compares string content. The moment you switch to a Regexp or a class, the reversal breaks.

/hello/ === "hello world"    # => true   (Regexp#match?)
"hello world" === /hello/    # => false  (String#== sees a non-String, returns false)

grep protects you from this by always calling pattern === element with the pattern on the left. That is part of why reaching for grep is the right call, not just a style preference.

Benchmarks I Ran

I wrote three Ruby scripts to sanity-check behavior and measure runtime:

• benchmark_select_by_kind.rb

• benchmark_select_by_range.rb

• benchmark_partition_instead_of_double_select.rb

Each script first asserts semantic equivalence, then runs repeated benchmarks with benchmark-ips.

ruby benchmark_select_by_kind.rb
ruby benchmark_select_by_range.rb
ruby benchmark_partition_instead_of_double_select.rb

Results on my machine

• SelectByKind: grep(UserRecord) reached 4.2 i/s vs 2.6 i/s for select { is_a? } (about 1.62x throughput).

• SelectByRange: grep(range) and grep_v(range) reached 1.1 i/s vs 0.9 i/s for cover?-based filters (about 1.17x throughput).

• PartitionInsteadOfDoubleSelect: partition reached 1.0 i/s vs 0.6 i/s for select + reject (1.68x throughput), because it walks once.

Should You Enable Them?

My recommendation:

1. Enable Style/SelectByKind - because it encodes idiomatic Ruby and keeps intent explicit.

2. Enable Style/SelectByRange - because it keeps filtering style consistent across regex, class, and range patterns.

3. Enable Style/PartitionInsteadOfDoubleSelect - because this one is both cleaner and genuinely more efficient.

Since these cops were added in v1.85.0, they may still be in pending status and not enabled by default. Here is the .rubocop.yml snippet to enable them explicitly:

Style/SelectByKind:
  Enabled: true

Style/SelectByRange:
  Enabled: true

Style/PartitionInsteadOfDoubleSelect:
  Enabled: true

If your team is not used to grep / grep_v, there will be a short learning curve. I still think it is worth it.

I might have missed edge cases in unusual enumerables. The performance gains are small in isolation so I think performance should not be the main metric why you should consider these cops. If you saw different benchmark behavior in your app, I would genuinely like to hear it.

Resources

• PR #14808 - Add new Style/SelectByKind cop

• PR #14810 - Add new Style/SelectByRange cop

• PR #14923 - Add new Style/PartitionInsteadOfDoubleSelect cop

• RuboCop 1.85.0 release notes

• benchmark-ips

• Ruby docs - Enumerable#grep

• Ruby docs - Enumerable#grep_v

• Ruby docs - Enumerable#partition

• Ruby issue #14197 (select with pattern argument proposal)

• Ruby issue #11049 (grep_v addition)

This means you can give Claude Code or OpenCode direct access to RuboCop as a structured tool, not just as a background linter.

What Is RuboCop MCP

MCP stands for Model Context Protocol. It is an open standard for connecting AI applications to external systems. When RuboCop runs as an MCP server, the LLM can call it directly as a tool instead of running it as a command-line process and parsing its output.

RuboCop 1.85.0 (released 2026-02-26) added experimental MCP support via PR #14911. The motivation from the contributor who built it:

"everyone is using tools like Claude Code, Codex and Cursor"

The MCP server exposes two tools:

• rubocop_inspection - inspect Ruby code for offenses. Accepts a path to check files on disk or source_code for inline code. Returns detected offenses as JSON.

• rubocop_autocorrection - autocorrect offenses. Same inputs as inspection, plus a safety boolean (defaults to true). When true, only safe corrections are applied.

The server runs as a long-lived process over stdio, which is the same principle as RuboCop's Server Mode and LSP mode. The practical benefit for an LLM: instead of parsing human-readable CLI output, it gets structured JSON with location information it can act on reliably.

You need at least RuboCop 1.85.0 to use this. Check your version with bundle exec rubocop --version.

How to Add Rubocop MCP for Claude Code

Here is how to install Rubocop MCP for Claude Code:

1. Go to the project where you want to have the MCP enabled

2. Execute the following from command line:

claude mcp add rubocop -- bundle exec rubocop --mcp

You can then check the configuration at ~/.claude.json (this is not ~/.claude/settings.json) where you will see a line like this:

{
  "<absolute path to your project>": {
    "mcpServers": {
      "rubocop": {
        "type": "stdio",
        "command": "bundle",
        "args": [
          "exec",
          "rubocop",
          "--mcp"
        ],
        "env": {}
      }
    }
  }
}

Check that Rubocop MCP works by asking something like this to Claude:

Tell me Rubocop offenses for test/models/user_test.rb

You should see something like:

How to Add Rubocop MCP for OpenCode

Here is how to configure Rubocop MCP for OpenCode:

1. Go to the project where you want to have the MCP enabled

2. Create a file if you don't already have one called opencode.json

3. Add the following to that file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rubocop": {
      "type": "local",
      "command": ["bundle", "exec", "rubocop", "--mcp"],
      "enabled": true
    }
  }
}

Check that Rubocop MCP works by asking something like this to OpenCode:

Tell me Rubocop offenses for test/models/user_test.rb

You should see something like:

It might be that I got some details wrong or that there are edge cases I did not hit. If you have feedback or corrections, I would be glad to hear them.

Resources

• RuboCop MCP documentation

• PR #14911 - Support built-in MCP server

• RuboCop 1.85.0 changelog

• Model Context Protocol

• MCP clients list

• Claude Code MCP documentation

• OpenCode documentation

Here the things are simple: OpenCode automatically detects what LSP you need and will install it for you.

In case of Ruby OpenCode labels the LSP as ruby-lsp in the UI, but that label turns out to be a bit misleading.

What Runs Under the Hood

When you open a .rb file in OpenCode, it automatically detects the extension, finds the nearest Gemfile as the project root, and sets up a language server for you.

The gem it installs and runs is rubocop in --lsp mode, not the ruby-lsp gem from Shopify. These are two different projects. The UI still shows ruby-lsp as the label, but that is kept for backward compatibility. What is actually running underneath is rubocop --lsp.

If rubocop is not found in your PATH, OpenCode installs it automatically into its own managed directory. It does not touch your project's Gemfile or your system gems. You can opt out entirely by setting OPENCODE_DISABLE_LSP_DOWNLOAD=true.

Why Rubocop Replaced ruby-lsp

This was not always the case. OpenCode originally used the ruby-lsp gem. There is a pull request (#4543) that explains exactly why it was replaced.

There were two problems with ruby-lsp. The first was a flag mismatch: ruby-lsp was being invoked with --stdio, a flag it does not actually recognize.

The second problem was more fundamental: startup time. OpenCode has a 3-second timeout for LSP servers to initialize. The ruby-lsp gem was taking around 2.65 seconds to start. That is technically within the limit, but in practice it was frequently timing out before delivering any diagnostics.

RuboCop's LSP mode initializes in about 0.58 seconds. That is 78% faster, and reliably within the timeout. According with the PR.

A Sensible Match for an AI Coding Tool

The contributor who made the switch added a point I find worth thinking about.

"rubocop doesn't include unnecessary IDE features: No autocomplete (LLM handles this), No go-to-definition (LLM provides context)"

In a traditional editor/IDE, autocomplete and go-to-definition are essential. In an AI coding tool, the LLM already handles both. What you actually want from a language server in this context probably is linting, warnings, and syntax error detection.

The Label Mismatch

One thing worth knowing if you look at the OpenCode UI: the ruby-lsp label you see on the right side refers to the internal server ID, not the gem name. The ID was kept as "ruby-lsp" after the switch to avoid breaking existing configurations. So if you see that label and assume the Shopify ruby-lsp gem is running, it is not. It is rubocop.

It might be that I missed something or that there are edge cases I did not hit. If you have feedback or corrections, I would be glad to hear them.

Resources

• OpenCode documentation - LSP

• OpenCode GitHub repository

• PR #4543 - fix: replace ruby-lsp with rubocop for better LSP performance

• RuboCop LSP support

• ruby-lsp by Shopify

This way you can use Ruby LSP as a real tool inside Claude Code, and the setup takes just a few steps.

What is Ruby LSP and Why Does It Matter in Claude Code

Ruby LSP is a language server for Ruby built by Shopify. It provides go-to-definition, document symbols, hover information, and diagnostics. In your editor - VS Code, Neovim, Zed - you probably already use it and do not even notice because it just works.

In Claude Code, having LSP support means Claude can ask for things like:

• List classes/methods/constants in a file

• Jump to where a symbol is defined

• Find all usages of a symbol

• Get type info/docs for a symbol

• Search symbols across the whole project

• Find implementations of an interface

• Trace call hierarchy

Think about the difference: reading a Ruby file and guessing the structure vs. asking "what are all the methods in this class?" and getting back exact symbol names, kinds, and line numbers. The second is more reliable, especially in larger codebases.

Step 1: Install the ruby-lsp Gem

Make sure the ruby-lsp gem is installed in your Ruby environment for your specific Ruby version:

gem install ruby-lsp

Verify it is available:

which ruby-lsp
# => /Users/yourname/.gem/ruby/3.3.0/bin/ruby-lsp

If you use a version manager like rbenv or asdf, install it for the Ruby version you use in your projects.

Step 2: Install the Plugin

The Ruby LSP team published their plugin in the official Claude plugin directory. This means you no longer need to add a third-party marketplace first - one command is enough.

Run this in your terminal or directly inside Claude Code with the /plugin prefix:

# In terminal
claude plugin install ruby-lsp@claude-plugins-official

Or inside Claude Code:

# inside Claude Code session
/plugin install ruby-lsp@claude-plugins-official

The @claude-plugins-official suffix tells Claude Code to look up the plugin in the official directory. No need to add an extra marketplace.

Step 3: Enable the LSP Tool via Environment Variable

Claude Code requires an explicit opt-in to expose LSP tools. Add this to ~/.claude/settings.json under the env key:

{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  }
}

The Complete settings.json

Here is what the relevant parts of ~/.claude/settings.json look like after all steps:

{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  },
  "enabledPlugins": {
    "ruby-lsp@claude-plugins-official": true
  }
}

Step 4: Restart and Verify

To load the LSP plugin you need to restart Claude Code completely, not just run /reload-plugins.

Then navigate to a Ruby project and test it. Ask Claude:

list symbols in app/models/user.rb using LSP

Here is what you should see (of course the symbols might vary, here I have a simple User object):

⏺ LSP(operation: "documentSymbol", file: "app/models/user.rb")
  ⎿  Found 2 symbols
     Document symbols:
     User (Class) - Line 1
       has_many :sessions (Method) - Line 3

| Symbol | Kind | Line |
|---|---|---|
| User | Class | 1 |
| has_many :sessions | Method | 3 |

Summary

Here are the steps, in order:

1. Install the gem: gem install ruby-lsp

2. Install the plugin: claude plugin install ruby-lsp@claude-plugins-official

3. Add ENABLE_LSP_TOOL: "1" to ~/.claude/settings.json under env

4. Restart Claude Code

Resources

• Ruby LSP - the official Ruby language server by Shopify and Ruby LSP GitHub repository

• Claude Code documentation

• Claude Code plugins

• Claude code official plugins Github repository

I know there are already packages in JavaScript or other languages, but I wanted to have a couple of tools written in Ruby to be included in other (more complex) DX tools.

Why Ruby for Agent Tooling?

Ruby is both a scripting language and a web development language. This dual nature makes it a good fit suited for building developer experience tools. While most AI agent tooling exists in the JavaScript ecosystem, there is value in having native Ruby implementations that integrate naturally with Ruby workflows and Rails applications.

The future of building terminal user interfaces (TUI) with Ruby is getting easier. With libraries like Charm and Ratatui offering Ruby wrappers, the possibilities for creating sophisticated command-line tools are expanding.

Three Foundation Gems

I built three gems that work together to provide basic infrastructure for AI agent tooling:

1. agent_skills_configurations

A unified interface for discovering and accessing skill configuration paths for various AI coding agents.

It will give you the configuration location/folder per each installed (or not) AI coding agent. This solves the problem of knowing where different agents store their skills and configurations across different systems.

Key features:

• Detect installed AI coding agents

• Get configuration paths for each agent

• Unified interface regardless of agent type

GitHub: https://github.com/lucianghinda/agent_skills_configurations

require "agent_skills_configurations"

# Find a specific agent
agent = AgentSkillsConfigurations.find("cursor")
agent.name              # => "cursor"
agent.display_name      # => "Cursor"
agent.skills_dir        # => ".cursor/skills"
agent.global_skills_dir # => "/Users/username/.cursor/skills"

# List all detected agents
AgentSkillsConfigurations.detected.map(&:name)
# => ["cursor", "claude-code", "windsurf", ...]

# List all configured agents (49+ supported)
AgentSkillsConfigurations.all.map(&:name)
# => ["amp", "claude-code", "cursor", "codex", "windsurf", ...]

2. agent_skill_parser

A Ruby gem for parsing skill files that use YAML frontmatter and markdown body content.

It will parse an AgentSkill file according with specifications from agentskills dot io and return an object with those properties. This makes it easy to programmatically work with agent skills, validate them, and extract metadata.

Key features:

• Parse YAML frontmatter from skill files

• Extract markdown body content

• Return structured objects for easy manipulation

• Follow agentskills.io specifications

GitHub: https://github.com/lucianghinda/agent_skill_parser

Taking an example of a markdown for an Agent Skill like this one:

---
name: pdf-processing
description: Extract text from PDF documents using various parsing strategies
license: Apache-2.0
compatibility: OpenAI Anthropic
metadata:
  author: Acme Inc
  version: 1.0.0
  category: document-processing
allowed-tools: Bash(git:*) Read
---

## Instructions

This skill helps extract text from PDFs.

### Step 1: Download the PDF
Use the Bash tool to download PDF files from URLs.

skill = AgentSkillParser.parse("path/to/skill.md")

skill.name          # => "pdf-processing"
skill.description   # => "Extract text from PDF documents..."
skill.body          # => "## Instructions\n\nThis skill helps..."

fm = skill.frontmatter

fm.name             # => "pdf-processing"
fm.description      # => "Extract text from PDF documents..."
fm.license          # => "Apache-2.0"
fm.compatibility    # => "OpenAI Anthropic"
fm.metadata         # => {"author" => "Acme Inc", "version" => "1.0.0", "category" => "document-processing"}
fm.allowed_tools    # => [#<AllowedTool name="Bash" pattern="git:*">, ...]

tool = skill.frontmatter.allowed_tools.first

tool.name    # => "Bash"
tool.pattern # => "git:*"

3. agents_skill_vault

A gem that can manage a vault (a local folder) with various skills from Github URLs.

Basically you can give it a list of Agent Skills (or repositories) and it will download and sync them on a local folder. This becomes the foundation for managing collections of skills, keeping them updated, and distributing them across teams.

Key features:

• Download skills from GitHub repositories

• Manage local skill collections

• Sync skills to keep them updated

• Support for multiple skill sources

GitHub: https://github.com/lucianghinda/agents_skill_vault

require "agents_skill_vault"

# Create a vault in a directory
vault = AgentsSkillVault::Vault.new(storage_path: "~/.my_vault")

# Let's assume we have this Github Repo

# that has this organisation
# .
# ├── LICENSE
#└── skills
#    ├── commit-message
#    │   └── SKILL.md
#    ├── improving-testing
#    │   └── SKILL.md
#    └── pr-description
#        └── SKILL.md

# Add a full repository
vault.add("https://github.com/lucianghinda/agentic-skills")

# But you can also add a specific skill
# Add a specific folder and even add a custom label
vault.add(
  "https://github.com/nateberkopec/dotfiles/tree/main/files/home/.claude/skills/readme-writer",
  label: "readme-writer"
)

# List all resources
vault.list.each do |resource|
  puts "#{resource.label} -> #{resource.local_path}"
end

# This will output

# lucianghinda/agentic-skills/commit-message -> /Users/lucian/.my_vault/lucianghinda/agentic-skills
# lucianghinda/agentic-skills/improving-testing -> /Users/lucian/.my_vault/lucianghinda/agentic-skills
# lucianghinda/agentic-skills/pr-description -> /Users/lucian/.my_vault/lucianghinda/agentic-skills
# readme-writer -> /Users/Lucian/.my_vault/nateberkopec/dotfiles/files/home/.claude/skills/readme-writer

# Sync a specific resource
result = vault.sync("rails/rails")
puts "Synced!" if result.success?

# Sync all resources
vault.sync_all

Building with AI Assistance

The code created for them was generated using a combination of Claude Code + GLM via Claude Code, OpenCode and Moltbot.

I reviewed all the code and manually refined it until I got a version that is good enough for release. This approach allowed me to quickly scaffold the basic structure and functionality, while maintaining control over the final implementation quality.

AI-assisted development worked well for:

• Initial project structure and boilerplate

• Basic implementation patterns

• Test scaffolding

• Documentation templates

Human review was essential for:

• API design decisions

• Edge case handling

• Code organization and clarity

• Ensuring consistency across all three gems

What You Can Build

I have in mind a couple of tools:

Team skill management: Create CLI tools that distribute and sync approved agent skills across your team. No more manual copying of configuration files or sharing snippets in Slack.

Skill validation: Build tools that parse and validate agent skills before they are used. Check for required fields, verify tool permissions, and ensure skills follow your team's standards.

Skill discovery: Create dashboards or search tools that help developers find and understand available agent skills. Parse skills from multiple sources, display their capabilities, and show which agents support them.

Automation workflows: Build scripts that keep agent skills synchronized across different agents (Cursor, Windsurf, etc.). Update a skill once, distribute it everywhere.

Internal registries: Combine all three gems to build skill marketplaces or internal registries where developers can browse, test, and install skills with confidence.

Looking Forward

I want to see more gems or libraries built with Ruby to provide a great foundation of DX. The Ruby ecosystem has an excellent developer experience. Here are some examples that maybe now they are taken for granted: IRB + Rails console, rake …

These three gems are a starting point. A lot of improvements can be made, but I think they can provide a solid foundation to build more gems on top of them.

All three are open source and available on GitHub under Apache 2.0 License. In case you wonder why Apache 2.0 Licence that is mainly as it explicitely defines the license for contributions.

If you spend significant time reviewing code changes in the terminal, delta can transform your workflow from reading simple diff output to working with syntax-highlighted, readable diffs.

Installing and Configuring Delta

First, install delta from https://github.com/dandavison/delta

Then configure your .gitconfig:

[core]
    pager = delta

[interactive]
    diffFilter = delta --color-only

[delta]
    navigate = true
    dark = true

[merge]
    conflictstyle = zdiff3

Visual Comparison

The difference is immediately visible when you run git diff. Without delta, you get standard monochrome output that can be hard to parse, especially for longer diffs. With delta, you get:

• Syntax highlighting based on file type

• Side-by-side or unified view options

• Line numbers

• Better visual separation between changes

Configuring Lazygit with Delta

I use lazygit for managing my git workflow. Configuring it to work with delta is simple, just add this line to your lazygit configuration:

git:
  paging:
    pager: delta --dark --paging=never --line-numbers

The Result

Without delta, lazygit displays diffs in plain diff format with just a bit of highlighting. With delta configured, you get the same rich syntax highlighting and visual improvements directly in your lazygit interface.

Here is how lazygit looked without delta configured:

And here is how it looks like with delta configured:

This makes reviewing changes faster and reduces eye strain when working through multiple diffs in a session. When you are working with LLMs and constantly reviewing generated code or refactorings, these small improvements in readability add up quickly.

👉 If you like this article and want it in your inbox each week, subscribe to my newsletter. You’ll find ideas on Ruby, software development, software testing, building products and workshops, plus notes on creativity, tech trends, and whatever else sparks my curiosity.

👐 Want to improve your developer testing skills? Visit goodenoughtesting.com/articles to discover resources on testing for developers.

👉 Join my Short Ruby Newsletter for weekly Ruby updates and visit rubyandrails.info, a directory of Ruby learning content.

🤝 Connect with me on Linkedin, Bluesky, Ruby.social, , and Twitter, where I mostly post about Ruby and Ruby on Rails.

🎥 Follow my YouTube channel for short videos about Ruby and Rails.

When I work on a project that uses RSpec, I prefer not to use let!. Instead, I call the let variable inside the before block.

RSpec.describe Thing do   
 let(:precondition) { create(:item) }

 before  
   precondition  
 end

 it 'returns that specific value' do  
   # do
   # expect  
 end  
end

Taking it a step further, if you do not need to reference precondition in your tests, you can do this instead:

RSpec.describe Thing do   
 before  
   create(:item)  
 end

 it 'returns that specific value' do  
   # do
   # expect  
 end  
end

First what does let! do? It just a call to the normal let and then setting a before block for the same name.

# source: https://github.com/rspec/rspec/blob/main/rspec-core/lib/rspec/core/memoized_helpers.rb#L329
def let!(name, &block)
  let(name, &block)
  before { __send__(name) }
end

Reason 1: let! is actually a precondition for a test and it hides it

In testing let! acts as a test precondition: the required state of the system before running a specific test. This should be visible while reading the test and using ! for this makes it hard to spot and hard to load it in the mental context.

It is harder to notice a let! among several let statements when you are trying to debug than seeing a before block which clearly communicate intention to run some preconditions.

RSpec.describe Thing do   
 let(:account) { build(:account) }  
 let!(:organisation) { build(:organisation, account: account) }

 it 'returns that specific value that we want' do  
   # test  
 end  
end

compared with:

RSpec.describe Thing do
 let(:account) { build(:account) }  
 let(:organisation) { build(:organisation, account: account) }

 before
   organisation  
 end

 it 'returns that specific value that we want' do  
    # test 
 end  
end

Which version makes it clearer that the organisation is created before each test?

Reason 2: It hides the order of execution of preconditions

Here is a comparison:

RSpec.describe Thing do   
 let!(:account_a) { build(:user, email: email) }  
 let!(:account_b) { build(:user, user: email2) }  
 let(:organisation) { build(:organisation, account: account) }  
 let(:team) { build(:team, account: organisation) }  

 it 'returns that specific value that we want' do  
    # test 
 end  
end

compared to

RSpec.describe Thing do   
 let(:account_a) { build(:user, email: email) }  
 let(:account_b) { build(:user, user: email2) }  
 let(:organisation) { build(:organisation, account: account) }  
 let(:team) { build(:team, account: organisation) }  

 before  
   account_a  
   account_b  
 end

 it 'returns that specific value that we want' do  
    # test 
 end  
end

But imagine that after a series of changes there is a risk that someone might put a let! among other calls.

RSpec.describe Thing do   
 let!(:account_a) { build(:user, email: email) }  
 let(:organisation) { build(:organisation, account: account) }  
 let!(:account_b) { build(:user, user: email2) }
 let(:team) { build(:team, account: organisation) }  

 it 'returns that specific value that we want' do  
    # test 
 end  
end

A Minitest equivalent

Here are three ways to write something similar in Minitest:

class ThingTest < Minitest::Test  
   def setup  
       @account_a = build(:user, email: email)  
       @account_b = build(:account, user: user)  
       @organisation =  build(:organisation, account: account)  
   end

   def test_computed_slug_returns_with_dashes  
       @account_a.name = "My Name"        

       assert_equal "my-name", @account_a.computed_slug  
   end  
end

Here is another approach:

class ThingTest < Minitest::Test  
   attr_accessor :account_a, :account_b, :organisation  

   def setup  
       @account_a = build(:user, email: email)  
       @account_b = build(:account, user: user)  
       @organisation =  build(:organisation, account: account)  
   end

   def test_computed_slug_returns_with_dashes  
       account_a.name = "My Name"

       assert_equal "my-name", account_a.computed_slug  
   end  
end

👉 If you like this article and want it in your inbox each week, subscribe to my newsletter. You’ll find ideas on Ruby, software development, software testing, building products and workshops, plus notes on creativity, tech trends, and whatever else sparks my curiosity.

👐 Want to improve your developer testing skills? Visit goodenoughtesting.com/articles to discover resources on testing for developers.

👉 Join my Short Ruby Newsletter for weekly Ruby updates and visit rubyandrails.info, a directory of Ruby learning content.

🤝 Connect with me on Linkedin, Bluesky, Ruby.social, , and Twitter, where I mostly post about Ruby and Ruby on Rails.

🎥 Follow my YouTube channel for short videos about Ruby and Rails.

system = {
  users: [
    { username: 'alice', role: 'admin', email: 'alice@example.com' },
    { username: 'bob', role: 'user', email: 'bob@example.com' },
    { username: 'charlie', role: 'moderator', email: 'charlie@example.com' }
  ]
}

moderator = system[:users].find { |u| u[:role] == 'moderator' }
email = moderator[:email] 

puts email # charlie@example.com

Now here is doing the same thing in Ruby using pattern matching:

system = {
  users: [
    { username: 'alice', role: 'admin', email: 'alice@example.com' },
    { username: 'bob', role: 'user', email: 'bob@example.com' },
    { username: 'charlie', role: 'moderator', email: 'charlie@example.com' }
  ]
}

system => {users: [*, { role: 'moderator', email: }, *]}
puts email # charlie@example.com

Let’s put the two lines one above the other:

# Using Enumerator#find
moderator = system[:users].find { |u| u[:role] == 'moderator' }
email = moderator[:email] 

# Using Pattern Matching
system => {users: [*, { role: 'moderator', email: }, *]}

There is another difference between them: in case of Pattern Matching it will throw a NoMatchingPatternError when not found, while the two lines that use Enumerator#find will throw a NoMethodError:

moderator = system[:users].find { |u| u[:role] == 'THIS_ROLE_DOES_NOT_EXISTS' }
email = moderator[:email] 
# undefined method '[]' for nil (NoMethodError)

system => {users: [*, { role: 'THIS_ROLE_DOES_NOT_EXISTS', email: }, *]}
# {users: [{username: "alice", role: "admin", email: "alice@example.com"}, 
# {username: "bob", role: "user", email: "bob@example.com"}, 
# {username: "charlie", role: "moderator", email: "charlie@example.com"}]}: 
# [{username: "alice", role: "admin", email: "alice@example.com"}, 
# {username: "bob", role: "user", email: "bob@example.com"}, 
# {username: "charlie", role: "moderator", email: "charlie@example.com"}] 
# does not match to find pattern (NoMatchingPatternError)does not match 
# to find pattern (NoMatchingPatternError)

How does pattern matching work in this example

If email does not exist either as a variable or method, matching it will create a local variable with the value from the matched row's key.

system = {
  users: [
    { username: 'charlie', role: 'moderator', email: 'charlie@example.com' }
  ]
}
system => {users: [*, { role: 'moderator', email: }, *]}
puts binding.local_variables
# => [:system, :email]

If a variable of method labeled email does exists, it will just try to match it against its value:

system = {
  users: [
    { username: 'charlie', role: 'moderator', email: 'charlie@example.com' }
  ]
}

email = 'charlie@example.com'
system => {users: [*, { role: 'moderator', email: }, *]}
puts email # charlie@example.com

If the variable already has a value, it will be overriden if the matching is succesful:

system = {
  users: [
    { username: 'charlie', role: 'moderator', email: 'charlie@example.com' }
  ]
}
email = 'bob@example.com'
system => {users: [*, { role: 'moderator', email: }, *]}
puts email # charlie@example.com

You can force if you want to search for the content of that variable with the ^ operator:

system = {
  users: [
    { username: 'charlie', role: 'moderator', email: 'charlie@example.com' }
  ]
}
email = 'bob@example.com'
system => {users: [*, { role: 'moderator', email: ^email}, *]}
# {users: [{username: "charlie", role: "moderator", email: "charlie@example.com"}]}: [{username: "charlie", role: "moderator", email: "charlie@example.com"}] does not match to find pattern (NoMatchingPatternError)

👉 If you like this article and want it in your inbox each week, subscribe to my newsletter. You’ll find ideas on Ruby, software development, software testing, building products and workshops, plus notes on creativity, tech trends, and whatever else sparks my curiosity.

👐 Want to improve your developer testing skills? Visit goodenoughtesting.com/articles to discover resources on testing for developers.

👉 Join my Short Ruby Newsletter for weekly Ruby updates and visit rubyandrails.info, a directory of Ruby learning content.

🤝 Connect with me on Linkedin, Bluesky, Ruby.social, , and Twitter, where I mostly post about Ruby and Ruby on Rails.

🎥 Follow my YouTube channel for short videos about Ruby and Rails.

If you have something like this in your en.yml file:

en:
  terms:
    yes: Yes
    no: No
    switch_on: On
    switch_off: Off
    accept: true
    reject: false

And then you will try to load them via Rails console like this:

I18n.locale = :en # make sure you have set a default locale
I18n.backend.send(:translations)[:en][:terms]
# => {true => true, false => false, switch_on: true, switch_off: false, accept: true, reject: false}

Notice there that there is no key yes, no and more so all values Yes, No, On Off, true, false were converted to TrueClass or FalseClass in Ruby.

That for me was quite interesting so I dig deeper to understand why this is happening.

Ruby on Rails loads locales using the gem i18n for locales. And that gem is using psych or yaml (which is aliased from psych - see https://github.com/ruby/yaml)

Processing YES, yes, NO, no, on, ON, off, OFF …

Looking at psych here are some tests that we can run:

assert_equal true, Psych.safe_load("--- YES")
assert_equal true, Psych.safe_load("--- Yes")
assert_equal true, Psych.safe_load("--- yes")

assert_equal true, Psych.safe_load("--- TRUE")
assert_equal true, Psych.safe_load("--- True")
assert_equal true, Psych.safe_load("--- true")

assert_equal true, Psych.safe_load("--- ON")
assert_equal true, Psych.safe_load("--- on")
assert_equal true, Psych.safe_load("--- On")

Notice that it will transform all of those values in TrueClass / true .

If we then run these tests it will return FalseClass / false :

assert_equal false, Psych.safe_load("--- NO")
assert_equal false, Psych.safe_load("--- No")
assert_equal false, Psych.safe_load("--- no")

assert_equal false, Psych.safe_load("--- FALSE")
assert_equal false, Psych.safe_load("--- False")
assert_equal false, Psych.safe_load("--- false")

assert_equal false, Psych.safe_load("--- OFF")
assert_equal false, Psych.safe_load("--- Off")
assert_equal false, Psych.safe_load("--- off")

Could not find the exact documentation about this but it seems like psych implements YAML version 1.1 that defines the following:

Notice there that it also defines Y, y, N, n as booleans.

assert_equal "Y", Psych.safe_load("--- Y")
assert_equal "y", Psych.safe_load("--- y")

assert_equal "N", Psych.safe_load("--- N")
assert_equal "n", Psych.safe_load("--- n")

But in our case when psych does not do that.

Why Psych does not convert Y, y, N, n to booleans?

The difference is documented for example in psych gem test suite for example:

    # source: https://github.com/ruby/psych/blob/master/test/psych/test_boolean.rb
    # YAML spec says "y" and "Y" may be used as true, but Syck treats them
    # as literal strings
    def test_y
      assert_equal "y", Psych.load("--- y")
      assert_equal "Y", Psych.load("--- Y")
    end

    # YAML spec says "n" and "N" may be used as false, but Syck treats them
    # as literal strings
    def test_n
      assert_equal "n", Psych.load("--- n")
      assert_equal "N", Psych.load("--- N")
    end

syck was an old parser for YAML written in C that seems to have been implemented since Ruby 1.9 (maybe even earlier) and syck implemented YAML version 1.0. See https://ruby-doc.org/stdlib-1.9.3/libdoc/syck/rdoc/Syck.html

I could not find the exact specification in YAML version 1.0 that defines the booleans so it could be there was a discussion about this and syck, as the YAML parser implemented in C and used by Ruby, decided to adopt it.

Here is the test_boolean.rb from syck and notice there YAML spec says "y" and "Y" may be used as true, but Syck treats them # as literal strings

###
    # YAML spec says "y" and "Y" may be used as true, but Syck treats them
    # as literal strings
    def test_y
      assert_equal "y", Psych.load("--- y")
      assert_equal "Y", Psych.load("--- Y")
    end

    ###
    # YAML spec says "n" and "N" may be used as false, but Syck treats them
    # as literal strings
    def test_n
      assert_equal "n", Psych.load("--- n")
      assert_equal "N", Psych.load("--- N")
    end

How to protect from this using RubySchema.org

RubySchema:

Ruby schema is a collection of JSON schemas for common Ruby gems. With these schemas, we can now enjoy auto-complete, validation and inline documentation right in our YAML files.

If your code editor supports YAML Language Server (and most of them do) make sure you have it installed and then if you add the following lines at the beginning of your YAML locales file:

# yaml-language-server: $schema=https://www.rubyschema.org/i18n/locale.json
%YAML 1.1
---

Then in case you will write inside the file something like this:

# yaml-language-server: $schema=https://www.rubyschema.org/i18n/locale.json
%YAML 1.1
---
en:
  yes: "Yes"
  on: "On"

Then your editor will show you a message like this:

👉 If you like this article and want it in your inbox each week, subscribe to my newsletter. You’ll find ideas on Ruby, software development, software testing, building products and workshops, plus notes on creativity, tech trends, and whatever else sparks my curiosity.

👐 Want to improve your developer testing skills? Visit goodenoughtesting.com/articles to discover resources on testing for developers.

👉 Join my Short Ruby Newsletter for weekly Ruby updates and visit rubyandrails.info, a directory of Ruby learning content.

🤝 Connect with me on Linkedin, Bluesky, Ruby.social, , and Twitter, where I mostly post about Ruby and Ruby on Rails.

🎥 Follow my YouTube channel for short videos about Ruby and Rails.

1. Use time.iso8601

2. Use time.to_fs(:iso8601)

Comparing two DateTime values

For example, to compare two DateTime values maybe you can try to write it like this:

def test_question_answered_at_the_same_as_survey
   assert_equal question.answered_at, survey.answered_at
end

describe 'question#answered_at'
   it 'is the same as survey' do 
       expect(question.answered_at).to eq(survey.answered_at)
   end
end

This approach can cause issues if there are microsecond delays when saving values to the database.

There are several ways to address this issue.

Using .change

One option is to use .change to set microseconds to zero.

def test_question_answered_at_the_same_as_survey
   assert_equal question.answered_at.change(usec: 0), survey.answered_at.change(usec: 0)
end

describe 'question#answered_at'
   it 'is the same as survey' do 
       expect(question.answered_at.change(usec: 0)).to eq(survey.answered_at.change(usec: 0))
   end
end

Using .to_i

Alternatively, you can use the Time#to_i method, which truncates subseconds:

def test_question_answered_at_the_same_as_survey
   assert_equal question.answered_at.to_i, survey.answered_at.to_i
end

describe 'question#answered_at'
   it 'is the same as survey' do 
       expect(question.answered_at.to_i).to eq(survey.answered_at.to_i)
   end
end

Using .round

You can use from Ruby the Time#round where you can specific how to round the seconds value and doing Time#round is equivalent to Time#round(0) that means without milliseconds:

def test_answer_filled_at_the_same_as_survey  
  assert_equal(
    question.answered_at.round, 
    survey.answered_at.round
  )
end

describe 'question#answered_at' do
  it 'is the same as survey' do   
    expect(
      question.answered_at.round
    ).to eq(survey.answered_at.round
  end  
end

Another option only for RSpec will be be_within

In RSpec there is a specific helper called be_within which will convert Time to float and then check if the value is within a delta:

describe 'question#answered_at' do
  it 'is the same as survey' do   
    expect(question.answered_at.round).to be_within(1).of(survey.answered_at)
  end  
end

In Minitest there is assert_in_delta

A similar helper exists in Minitest called assert_in_delta that also transforms to float and then compare it if it is withing a delta:

def test_answer_filled_at_the_same_as_survey  
  assert_in_delta(
    question.answered_at,
    survey.answered_at,
    1.0
  )
end

Using .iso8601

I recommend using iso8601 for this comparison:

def test_question_answered_at_the_same_as_survey
   assert_equal question.answered_at.iso8601, survey.answered_at.iso8601
end

describe 'question#answered_at'
   it 'is the same as survey' do 
       expect(question.answered_at.iso8601).to eq(survey.answered_at.iso8601)
   end
end

In Rails, you can also use to_fs(:iso8601):

def test_question_answered_at_the_same_as_survey
   assert_equal question.answered_at.to_fs(:iso8601), survey.answered_at.to_fs(:iso8601)
end

describe 'question#answered_at'
   it 'is the same as survey' do 
       expect(question.answered_at.to_fs(:iso8601)).to eq(survey.answered_at.to_fs(:iso8601))
   end
end

Why use .iso8601 or .to_fs(:iso8601)

First, ISO8601 is a widely adopted standard, so its behavior is consistent across Ruby and Rails implementations.

Second, using time.iso8601 is more descriptive than time.change(usec: 0), making the comparison method clearer and supporting consistent conventions in the codebase.

Third, this approach allows you to compare with fixed time values as well:

assert_equal question.answered_at.iso8601, "2025-10-07T13:35:25+03:00"
expect(question.answered_at.iso8601).to eq "2025-10-07T13:35:25+03:00"

I know that someone might say well to understand what iso8601 does tyou have to know about it. But here I think it is a normal expectation for an web engineer to know about ISO8601 standard when working with time.

Of course you should choose the one that works best for you.

👉 If you like this article and want it in your inbox each week, subscribe to my newsletter. You’ll find ideas on Ruby, software development, software testing, building products and workshops, plus notes on creativity, tech trends, and whatever else sparks my curiosity.

👐 Want to improve your developer testing skills? Visit goodenoughtesting.com/articles to discover resources on testing for developers.

👉 Join my Short Ruby Newsletter for weekly Ruby updates and visit rubyandrails.info, a directory of Ruby learning content.

🤝 Connect with me on Linkedin, Bluesky, Ruby.social, , and Twitter, where I mostly post about Ruby and Ruby on Rails.

🎥 Follow my YouTube channel for short videos about Ruby and Rails.

Note: The code in this article was tested on Ruby 3.4.1

Defining getters to access instance variables

In most codebases that I saw, the primary use of an attr_reader is to provide public access to an instance variable by defining an attr_reader like this:

class Link
  attr_reader :url 

  def initialize(url)
    @url = url
  end  
end

Funny thing you can define getters using string if you want to and Ruby will convert it to symbol and define the same method:

class Link
  attr_reader 'url'

  def initialize(url)
    @url = url
  end  
end

link = Link.new("https://shortruby.com")
puts link.methods.include?(:url) # true

You can also use attr to define a getter:

class Link
  attr :url 

  def initialize(url)
    @url = url
  end  
end
link = Link.new("https://shortruby.com")
puts link.methods.include?(:url) # true
puts link.methods.include?(:url=) # false

There was also the option to use attr :url, true to define a setter but that is deprecated. Also doing attr :url, false is deprecated. So only attr :url remains which is equivalent to attr_reader :url

I think using attr_reader is better because the name of the method describes what is does.

You can define a private getter

If you want to you can define a private getter like this:

class Link
  def initialize(url)
    @url = url
  end  

  private 

  attr_reader :url 
end

And my plan in this article is to try to show why you should do this and what advantages it might bring you. I am not saying you should do this all the time, but I think it could be a case of using getters also inside the object where you are defining it.

A short intermission about private and public methods

When I think about a Ruby object I try to minimize the public methods that it exposes. My line of thinking is that all methods should be private unless there is a real reason to make that method public.

When making a method public you are signing a contract with another developer that you will keep that method the same for as long as possible (the same parameters, the same return, the same effects …). So I think the default position should be to limit your liabilities.

A getter is a method so when you think about defining getters you should think if you really need to expose them and make them public.

Accessing undefined instance variables

As my main assertion here is to use getters when accesing instance variables inside the current object, I think it is important to talk a bit about instance variables and what is their value when they are not created:

class Simple
  def is_it_defined?
    instance_variable_defined?(:@this_does_not_exists)
  end

  def value
    @this_does_not_exists
  end
end

simple = Simple.new
puts simple.is_it_defined? # => false
puts simple.value.inspect # => nil

We know that if an instance variable is not initialized/defined but it is directly accessed it will return nil but will not throw an error.

This opens the case of some bugs related to checking truthiness:

class Simple
  def initialize(payload)
    @payload = payload
  end

  def run
    if @paylod
      puts "Run with payload"
    else 
      puts "Without payload"
    end
  end
end

Notice I wrote @paylod instead of @payload and so the result will be:

Simple.new("Something").run

# Got => Without payload ❌

# Expected => Run with payload

Let’s try a second example, this one a bit more complex:

class InvoiceBuilder
  PREFIXES_FOR_EUR = ["INV", "I"]

  def initialize(prefix)
    @prefix = prefix
  end

  def currency
    return "EUR" if PREFIXES_FOR_EUR.include?(@prefix)

    "USD" 
  end
end

If we run two tests it will pass:

invoice_number_builder = InvoiceBuilder.new("INV")
puts invoice_number_builder.currency
# => EUR 

invoice_number_builder = InvoiceBuilder.new("CUSTOM")
puts invoice_number_builder.currency
# => USD

Again what if there will be a typo (notice the variable @prefx in the currency method:

class InvoiceBuilder
  PREFIXES_FOR_EUR = ["INV", "I"]

  def initialize(prefix)
    @prefix = prefix
  end

  def currency
    return "EUR" if PREFIXES_FOR_EUR.include?(@prefx)

    "USD" 
  end
end

The same tests will fail:

invoice_number_builder = InvoiceBuilder.new("INV")
puts invoice_number_builder.currency
# => USD ❌

invoice_number_builder = InvoiceBuilder.new("CUSTOM")
puts invoice_number_builder.currency
# => USD

The case for using a getter

Even if you don’t plan to expose the getter as a public interface you can define a getter and use it inside the object:

class InvoiceBuilder
  PREFIXES_FOR_EUR = ["INV", "I"]

  def initialize(prefix)
    @prefix = prefix
  end

  def currency
    return "EUR" if PREFIXES_FOR_EUR.include?(prefix)

    "USD"
  end

  private 

  attr_reader :prefix
end

And in case there is a typo like the following one:

class InvoiceBuilder
  PREFIXES_FOR_EUR = ["INV", "I"]

  def initialize(prefix)
    @prefix = prefix
  end

  def currency
    return "EUR" if PREFIXES_FOR_EUR.include?(prefx)

    "USD"
  end

  private 

  attr_reader :prefix
end

When running the following code:

invoice_builder = InvoiceBuilder.new("INV")
puts invoice_builder.currency

We will get a very clear error:

test-with-attr-reader.rb:9:in 'InvoiceBuilder#currency': 
undefined local variable or method 'prefx' for an instance of InvoiceBuilder (NameError)

    return "EUR" if PREFIXES_FOR_EUR.include?(prefx)
                                              ^^^^^
 Did you mean?  prefix
               @prefix
        from test-with-attr-reader.rb:20:in '<main>'

Notice the difference:

• In the version with instance variable the execution silently returned an apparent valid response

• In the version with the getter the execution will raise an exception and will also tell us exactly where the typo is located.

Protecting against mistakes with tests

You can of course protect against these kind of mistakes by writing some functional tests like the following ones (I am using here Minitest but the test framework does not make any difference).

class InvoiceBuilderTest < Minitest::Test
  def test_currency_returns_eur_for_known_prefixes
    prefix = "INV"
    builder = InvoiceBuilder.new(prefix)

    assert_equal "EUR", builder.currency
  end

  def test_currency_returns_usd_for_unknown_prefixes
    prefix = "CUSTOM"
    builder = InvoiceBuilder.new(prefix)

    assert_equal "USD", builder.currency
  end
end

And if there is a typo in case of the version with the instrance variable if we run it we will get:

# Running:
.F
Finished in 0.000339s, 5899.7052 runs/s, 5899.7052 assertions/s.

  1) Failure:
InvoiceBuilderTest#test_currency_returns_eur_for_known_prefixes [instance_variable_with_typo.rb:30]:
Expected: "EUR"
  Actual: "USD"

2 runs, 2 assertions, 1 failures, 0 errors, 0 skips

How to use this in Rails

When talking about Rails I generally think being close to defaults is the sane choice. Still you can use this technique there too with either a getter or with a local variable instead of an instance variable.

Having an ERB file like this:

<% if @payment %>
  <p>Payment exists!</p>
<% else %>
  <p>No payment found.</p>
<% end %>

You can rewrite it like this:

<% if payment %>
  <p>Payment exists!</p>
<% else %>
  <p>No payment found.</p>
<% end %>

And then you can pass in the controller the payment using locals:

class PaymentsController < ActionController::Base
  def show
    @payment = Object.new

    render locals: { payment: payment }
  end

  private

    attr_reader :payment
end

In case there is for example a typo in ERB:

<% if paymnt %>
  <p>Payment exists!</p>
<% else %>
  <p>No payment found.</p>
<% end %>

When you run your tests (or the web app and access that page) you will get an error that will look like this:

ActionView::Template::Error (undefined local variable or method 'paymnt' for an instance of #<Class:0x0000000121ad6228>)
Caused by: NameError (undefined local variable or method 'paymnt' for an instance of #<Class:0x0000000121ad6228>)

Information for: ActionView::Template::Error (undefined local variable or method 'paymnt' for an instance of #<Class:0x0000000121ad6228>):
    1: <% if paymnt %>
    2:   <p>Payment exists!</p>
    3: <% else %>
    4:   <p>No payment found.</p>

app/views/payments/show.html.erb:1
app/controllers/payments_controller.rb:5:in 'PaymentsController#show'

Of course when doing this in a Rails controller you can get the benefit of having this nice error that tells you where you are trying to use a method that does not exists by sending local variables from the controller:

class PaymentsController < ApplicationController
  def show
    payment = Object.new

    render locals: { payment: payment }
  end
end

This is much more simpler than writing an instance variable.

In the end the change that you have to explicitly call render with locals if you are not already calling it and pass it local variables instead of setting an instance variable.

def show
- @payment = Object.new
+ payment = Object.new
+ render locals: { payment: payment }
end

One note before we move on: This is not the default Rails way so before start doing this think carefully if you plan to adopt this on your entire codebase. The

Why prefer methods instead of instance variables?

Summarising the main reasons that I see for prefering method calls instead of instance variables (or in case of the Rails example local variables with render locals):

1. Fails fast because it throws an exception

2. Ruby will point to the exact line of code that failed so identifying the root cause of the exception is easier

If you're worried about performance, in most cases, the difference isn't significant. Here is a benchmark I run on my laptop (M3 Pro 32GB):

Simple time benchmark (lower is better):
                               user     system      total        real
Instance variable access:  0.024115   0.000012   0.024127 (  0.024128)
Getter access:             0.027965   0.000010   0.027975 (  0.027979)

Iterations per second (higher is better):
ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +PRISM [arm64-darwin23]
Warming up --------------------------------------
Instance variable access:
                         3.571M i/100ms
      Getter access:     3.215M i/100ms
Calculating -------------------------------------
Instance variable access:
                         35.951M (± 1.0%) i/s   (27.82 ns/i) -    182.110M in   5.065990s
      Getter access:     31.687M (± 1.1%) i/s   (31.56 ns/i) -    160.749M in   5.073622s

Comparison:
Instance variable access:: 35951125.5 i/s
      Getter access:: 31687428.0 i/s - 1.13x  slower

You are already doing this in some cases

I want to assert that this change is not so big. Because you are already doing this in a couple of cases:

1. Predicates

2. Memoization and Lazy Initiatialization

For example when having an instance variable that is used as a boolean we mostly write a method to make it a predicate. See in this example the vat_included? method:

class InvoiceBuilder
  VAT_PERCENTAGE = 0.19

  def initialize(total:, vat_included:)
    @total = total
    @vat_included = vat_included
  end

  def amount
    return total unless vat_included? 

    (total - (total * VAT_PERCENTAGE)).truncate(2)
  end

  private 

    attr_reader :total

    def vat_included?
      @vat_included
    end
end

In case of memoization we do something like this (see the products method):

class Invoice  
  def initialize(product_ids:)
    @product_ids = product_ids
  end

  def total       = products.sum { _1.price } 
  def print_items = products.each { "#{it.name} | #{it.unit} | #{it.quantity}" }

  private 

    attr_reader :product_ids

    def products 
      @products ||= Product.where(id: product_ids).order(name: :asc)
    end
end

Some conclusion

The typing mistakes I presented here are easy to spot because the examples are very simple. I think this is how code should look like: simple, with few lines of code if possible. If you have code like this there is no need to adopt this technique becuase you will be able to spot a mistake very easily.

But generally, code can be more complex, making mistakes harder to find. You'll need tests to catch cases like checking truthiness against nil values. Be aware of developer confirmation bias when writing tests, as this can make tests appear correct when they're not. Protect against these issues by setting Ruby to raise an exception. This aligns with the shift-left philosophy of catching bugs early, giving you quick and clear feedback on these typing mistakes.

👉 If you like this article and want it in your inbox each week, subscribe to my newsletter. You’ll find ideas on Ruby, software development, software testing, building products and workshops, plus notes on creativity, tech trends, and whatever else sparks my curiosity.

👐 Want to improve your developer testing skills? Visit goodenoughtesting.com/articles to discover resources on testing for developers.

👉 Join my Short Ruby Newsletter for weekly Ruby updates and visit rubyandrails.info, a directory of Ruby learning content.

🤝 Connect with me on Linkedin, Bluesky, Ruby.social, , and Twitter, where I mostly post about Ruby and Ruby on Rails.

🎥 Follow my YouTube channel for short videos about Ruby and Rails.

• How to create value objects in Ruby - the idiomatic way

• Example of value objects using Ruby's Data class

Here, I will talk about the two ways you can create Data classes and compare them:

• Using the block

• Using the inheritance

How to create a Data class

You can define a new Data class using the block syntax:

Response = Data.define(:body, :status)

Looking at the current Ruby docs for Ruby version 3.4 this seems to be the way to do it or at least the documentation is using this way of creating a new Data class. If I don’t miss anything all examples there are using this syntax.

You can also define a new Data class by using the inheritance

class Response < Data.define(:body, :status)
end

The inheritance chain

The main difference between them is that the inheritance syntax is defining an extra anonimous class.

Here are the ancestors for the block syntax:

Response = Data.define(:body, :status) do
end
Response.ancestors
# [
#   Response, 
#   Data, 
#   Object, 
#   Kernel, 
#   BasicObject
# ]

The ancestors for the inheritance syntax are:

class Response < Data.define(:body, :status)
end
Response.ancestors
# [
#   Response, 
#   <Class:0x000000011b98abe0>, 
#   Data, 
#   Object, 
#   Kernel, 
#   BasicObject
# ]

Notice there an extra <Class:0x000000011b98abe0> in the inheritance chain.

This is not something specific for the Data class. It works the same way for Struct too:

Response = Struct.new(:body, :status)
Response.ancestors
# [
#   Response,
#   Struct,
#   Enumerable,
#   Object,
#   Kernel,
#   BasicObject
# ]

class Response < Struct.new(:body, :status)
end
Response.ancestors
# [
#   Response,
#   #<Class:0x000000011d3eabe8>,
#   Struct,
#   Enumerable,
#   Object,
#   Kernel,
#   BasicObject
# ]

When using block syntax with a variable instead of a constant

If you try to assign the Data define block to a variable you will see that the name for that class is not set:

Response = Data.define(:body, :status)
object = Response.new(body: {}, status: 200)
object.inspect
# => "#<data Response body={}, status=200>"

response = Data.define(:body, :status)
object = response.new(body: {}, status: 200)
object.inspect
# => "#<data body={}, status=200>"

Notice that when we inspect it when assigning to a variable it does not print the “Response” string, that is because the name is not set in case of response:

Response = Data.define(:body, :status)

Response.name 
# => "Response"

response = Data.define(:body, :status)

response.name
# => nil

Again comparing it with Struct, the same happens for Struct:

Response = Struct.new(:body, :status)

Response.name 
# => "Response"

response = Struct.new(:body, :status)

response.name
# => nil

Nested constants

What happens if we try to define some constants inside.

If I write this code:

Response = Data.define(:body, :status) do
  RateLimit = Data.define(:limit, :remaining, :retry)
end

How do I instantiate a new object for RateLimit:

• Response::RateLimit.new … ?

• RateLimite.new ?

Let’s try it out:

rate_limit = Response::RateLimit.new(limit: 10, :remaining: 4, retry: 1743564235)
# => uninitialized constant Response::RateLimit (NameError)

rate_limit = Response::RateLimit.new(limit: 10, :remaining: 4, retry: 1743564235)
# #<data RateLimit limit=10, remaining=4, retry=1743564235>

This is happening because the block does not introduce a new scope and so the constrant is defined in the outher scope.

Here is another example that does not use the Data:

Response = Class.new do
  RateLimit = Class.new do
    RETRIES = 10
  end
end

puts Response::RateLimit::RETRIES
# => uninitialized constant Response::RateLimit (NameError)

puts Response::RETRIES 
# => uninitialized constant Response::RETRIES (NameError)

puts RETRIES 
# => 10

This is not happening if you use the inheritance syntax for Data object:

class Response < Data.define(:body, :status)
  class RateLimit < Data.define(:limit, :remaining, :retry)
    RETRIES = 10
  end
end

puts Response::RateLimit::RETRIES 
# => 10

puts Response::RETRIES 
# => uninitialized constant Response::RETRIES (NameError)

puts RETRIES 
# => uninitialized constant RETRIES (NameError)

Redefining the initializer

There can be multiple times when you will try to redefine the initializer and set some default values or do some other processing in there.

In general it looks like this:

class Response < Data.define(:body, :status)
  def initialize(body: {}, status: 200)
    super
  end
end

response = Response.new(body: { message: 'Hello, world!' }, status: 200)
# => #<data Response body={message: "Hello, world!"}, status=200>

In case you will try to write the initializer with positional arguments, then you will find out it does not work:

class Response < Data.define(:body, :status)
  def initialize(body = {}, status = 200)
    super
  end
end

response = Response.new(body: { message: 'Hello, world!' }, status: 200)
# => in 'Data#initialize': wrong number of arguments (given 2, expected 0) (ArgumentError)

response = Response.new({ message: 'Hello, world!' }, 200)
# => in 'Data#initialize': wrong number of arguments (given 2, expected 0) (ArgumentError)

The documentation in Ruby master is clear about this behavior:

Note that Measure#initialize always receives keyword arguments, and that mandatory arguments are checked in initialize, not in new. This can be important for redefining initialize in order to convert arguments or provide defaults.

Just remember to always define the initializer with keyword arguments when using the Data define

Which option to choose the block or the inheritance?

I am not sure there is a clear answer.

I like the simplicity of the block definition. If you don’t plan to add too many extra methods it is so cool to define it in a single line and no need for an extra end

Response = Data.define(:body, :status)

But once you add an extra method, like some default arguments for the initializer:

Response = Data.define(:body, :status) do 
  def initialize(body: {}, status: 200) = super
end

Then it will not be a big difference in terms of lines of code needed for defining it versus the inheritance:

class Response < Data.define(:body, :status)
  def initialize(body: {}, status: 200) = super
end

Still if you care about the number of objects created in your Ruby program, remember that the inheritance is creating an extra anonimous class.

If you like this article:

👐 Interested in learning how to improve your developer testing skills? Join my live online workshop about goodenoughtesting.com - to learn test design techniques for writing effective tests

👉 Join my Short Ruby Newsletter for weekly Ruby updates from the community

🤝 Let's connect on Bluesky, Ruby.social, Linkedin, Twitter where I post mostly about Ruby and Ruby on Rails.

🎥 Follow me on my YouTube channel for short videos about Ruby/Rails

Remove boilerplate constructor code

If you are defining classes and expose the initializer parameters as getters and you plan to make them immutable, then I think you just found the most common case for using the Data class:

Instead of this:

class Link
  attr_reader :url, :source

  def initialize(url:, source:)
    @url = url
    @source = source
  end
end

I write this:

class Link < Data.define(:url, :source)
end

You can of course also write the simple form, but I do recommend the the previous way with inheritance (will followup in another article about this):

Link = Data.define(:url, :source)

When calling an external API

When calling an external API that returns JSON, I like to implement a method that returns a Response object.

Here I define a Response object with two computed properties:

• parsed_body

• success

class Response < Data.define(:body, :status, :headers)
  HTTP_SUCCESS_STATUS_CODES = (200..299)

  def success?    = HTTP_SUCCESS_STATUS_CODES.include?(status)
  def parsed_body = JSON.parse(body, symbolize_names: true)
  def failed?     = !success?
end

Mind you that you cannot memoize using instance variables inside a Data class due to immutability. If you try something like this you will get FrozenError

class Response < Data.define(:body, :status, :headers)
  def parsed_body 
    @parsed_body ||= JSON.parse(body, symbolize_names: true)
  end
end

r = Response.new(body: "{}", status: 200, headers: {})
r.parsed_body
# can't modify frozen Response: #<data Response body="{}", status=200, headers={}> (FrozenError)

A more full example might look like this using httparty gem

require 'httparty' 
require 'json'

class Response < Data.define(:body, :status, :headers)
  HTTP_SUCCESS_STATUS_CODES = (200..299)

  def success?    = HTTP_SUCCESS_STATUS_CODES.include?(status)
  def parsed_body = JSON.parse(body, symbolize_names: true)
  def failed?     = !success?
end

def get(url, query: {})
  response = HTTParty.get(url, query)
  Response.new(body: response.body, status: response.code, headers: response.headers)
end

response = get(
  'https://bsky.social/xrpc/' \
  'com.atproto.identity.resolveHandle?handle=lucianghinda.com')
puts response.parsed_body[:did] # did:plc:1362asasdah213212
puts response.success? # true

From this example you can for example expand it to add a RateLimit object:

require 'httparty' 
require 'json'

class RateLimit < Data.define(:limit, :remaining, :reset)
end

class Response < Data.define(:body, :status, :headers, :rate_limit)
  HTTP_SUCCESS_STATUS_CODES = (200..299)

  def success?    = HTTP_SUCCESS_STATUS_CODES.include?(status)
  def parsed_body = JSON.parse(body, symbolize_names: true)
  def failed?     = !success?
end

def get(url, query: {})
  response = HTTParty.get(url, query)

  rate_limit = RateLimit.new(
    limit: response.headers['ratelimit-limit'].to_i,
    remaining: response.headers['ratelimit-remaining'].to_i,
    reset: response.headers['ratelimit-reset'].to_i
  )

  Response.new(
    body: response.body,
    status: response.code,
    headers: response.headers,
    rate_limit: rate_limit
  )
end

You can even add a constructor to RateLimit for example:

class RateLimit < Data.define(:limit, :remaining, :reset)
  def self.from_headers(headers)
    limit = headers['ratelimit-limit'].to_i
    remaining = headers['ratelimit-remaining'].to_i
    reset = headers['ratelimit-reset'].to_i

    new(limit: limit, remaining: remaining, reset: reset)
  end
end

Global or public list of objects from your domain

Here is an example I found in TheOdinProject:

# Source: https://github.com/TheOdinProject/theodinproject/app/models/flag.rb

class Flag < ApplicationRecord
  Reason = Data.define(:name, :description, :value)

  REASONS = [
    { name: :broken, description: 'Link does not work', value: 10 },
    { name: :insecure, description: 'Link is not secure or safe', value: 20 },
    { name: :spam, description: 'Spam or misleading', value: 30 },
    { name: :inappropriate, description: 'Inappropriate imagery or language', value: 40 },
    { name: :other, description: 'Other', value: 50 }
  ].map { |reason| Reason.new(**reason) }
end

Furthe on you will see they are using REASONS in a Rails enum:

# Source: https://github.com/TheOdinProject/theodinproject/app/models/flag.rb

class Flag < ApplicationRecord
   enum reason: REASONS.each_with_object({}) { |reason, hash| hash[reason.name] = reason.value }
end

And then in the view as a list of choices:

<% Flag::REASONS.each do |reason| %>
  <div class="relative flex items-center">
    <div class="absolute flex h-6 items-center">
      <%= form.radio_button(
        :reason, 
        reason.name, 
        data: { test_id: "flag-reason-#{reason.name}"}, 
        class: 'h-4 w-4 border-gray-300 dark:border-gray-500 dark:bg-gray-700/50' # ...
      %>
    </div>

    <div class="pl-7 text-sm leading-6">
      <%= form.label(
        :reason, 
        reason.description, 
        value: reason.name, 
        class: 'block text-sm font-medium text-gray-700 dark:text-gray-200 dark:text-gray-200' 
      %>
    </div>
  </div>
<% end %>

If you like this article:

👐 Interested in learning how to improve your developer testing skills? Join my live online workshop about goodenoughtesting.com - to learn test design techniques for writing effective tests

👉 Join my Short Ruby Newsletter for weekly Ruby updates from the community

🤝 Let's connect on Bluesky, Ruby.social, Linkedin, Twitter where I post mostly about Ruby and Ruby on Rails.

🎥 Follow me on my YouTube channel for short videos about Ruby/Rails

Here is an exploration of how to create value-alike objects in Ruby and what I think is the modern idiomatic way.

What is a value-alike object?

If you want to read an article about this concept, I recommend Value Object by Martin Fowler. He explains this concept very well with examples and references. I invite you to read that article. It is not that long.

They are simple objects that have the following properties:

• Comparable by type and value (that means two objects having the same values as attributes and being the same class will be equal)

• Immutable (once set their attributes, they should not be allowed to be changed)

The concept is useful when you have to carry around multiple related values, and you need them together in most cases. When talking about Ruby and Ruby OOP, a value object is a simple immutable object that represents a concept in your domain and knows to respond to some simple messages like: what is the value of this property, what is your representation as a string, are you equal to this object in value and type and so on.

The simplest example is a Point that in 2D has x and y properties.

Thus, instead of carrying on a hash { x: 20, y: 30 }, you carry on an object: Point.new(x: 20, y:20) that you can interrogate and ask questions. For example, you might want to know in which quadrant the point is, and making this an object allows you to add methods to it, like quadrant

Or I can ask distance_to(another_point), and it will tell me something along the lines of Math.sqrt((x - other.x) ** 2 + (y - other.y) ** 2)

But most of the time, you need to ask that object point.x or point.y and have a good name for both the class and the attributes.

Why use a value object?

You might ask yourself, why use a value object?

Here are some arguments for using a value object:

1. Keep data together using an immutable object so you can be sure that as you pass an instance of this object through your code, nothing has changed it.

2. It is a group of values that should be together under a meaningful name

3. It is greppable, meaning you can easily find all the places in your codebase where this object is used, making it simple to refactor when needed.

When comparing a value object with using a more base structure like a Hash, the advantages over Hash are:

• Naming: the structure of the values together have a name

• Greppability: because now this structure has a name, it is easier to find it in the codebase

• Flexibility: you can add utility methods, computed properties, or predicates

The Idiomatic Ruby way since 2022

The idiomatic way to do this in Ruby should be to use Data class. Here is what Ruby's official documentation says about it:

Class Data provides a convenient way to define simple classes for value-alike objects.

We must thank Victor Shepelev for proposing this structure in Ruby and continuing the discussion about it until it was accepted and implemented.

How to define and create an instance of a Data class

Say you want to pass along an object representing an amount and save the value and the currency.

You can define this like:

Price = Data.define(:amount, :currency)

There are multiple ways to instantiate an objects from a Data class:

Using required keyword arguments

price = Price.new(amount: 50, currency: "USD")
# => #<data Price amount=50, currency="USD">

Using positional arguments

price = Price.new(50, "USD")
# => #<data Price amount=50, currency="USD">

Using alternative form construct

price = Price["50", "USD"]
# => #<data Price amount="50", currency="USD">

Using alternative construction hash-like form

price = Price[amount: "50", currency: "USD"]
# => #<data Price amount="50", currency="USD">

Properties of the Data object in Ruby

A Data object has two important properties in my view:

1. It is immutable so there are no setters defined and you cannot define setters

# You cannot change the value

price = Price.new(amount: 50, currency: "USD")

# The following will raise an exception
price.amount = 50 
# => `<main>': undefined method `amount=' for #<data Price amount=50, currency="USD"> (NoMethodError)

Even if you try to define a setter, it will not work:

Price = Data.define(:amount, :currency) do
    def amount=(new_amount)
      @amount = new_amount
    end
end

price = Price.new(amount: 50, currency: "USD")
price.amount = 100 # This will return an exception
# => in 'Price#amount=': can't modify frozen #<Class:#<Price:0x00000001259166a0>>: #<data Price amount=20, currency="USD"> (FrozenError)

2. It is comparable by type and value

Price = Data.define(:amount, :currency)

price1 = Price.new(amount: 50, currency: "USD")

price2 = Price.new(amount: 40, currency: "USD")

price3 = Price.new(amount: 50, currency: "USD")

# While these are all different objects
puts price1.object_id
puts price2.object_id
puts price3.object_id

# You will notice that price1 and price3 will be equal
price1 == price3 # true
price1 == price2 # false

It has some other properties but I think these two are the main ones that we should think about when using Data as a value object.

Changing one or many values

The only way to achieve this is to use with and create a new value object:

price_a = Price.new(amount: 50, currency: "USD")

price_b = price_a.with(amount: 100)
# => #<data Price amount=100, currency="USD">

Defining custom methods

You might notice that if you browse the documentation that the Data object has a limited number of methods: there are 10 methods specific to this object (not taking into consideration of course methods inherited from its ancestors: [Object, Kernel, BasicObject])

But you can define custom computed properties on it if you want to by passing a block to define:

Price = Data.define(:amount, :currency) do
    def to_s 
        "#{currency} #{amount}"
    end
end

price = Price.new(amount: 50, currency: "USD")
price.to_s # => "USD 50"

Default values using an initializer

In case you want to have default values, you can override the initializer like this:

Price = Data.define(:amount, :currency) do
    def initialize(amount:, currency: "USD") 
        super
    end
end

# with the shortest form possible, like
Price = Data.define(:amount, :currency) do
    def initialize(amount:, currency: "USD") = super
end

Checking the kind (or type) of the attributes

While this is not a feature of Data object, I feel like it is working nice along with it: you can check for type (or, better said, kind of the arguments) using Pattern Matching:

Price = Data.define(:amount, :currency) do
    def initialize(amount:, currency:)
        amount => Integer
        currency => String

        super
    end
end

This can be useful if you, for example want to define Currency as:

Currency = Data.define(:code, :name, :symbol, :decimal)
USD = Currency.new(code: "USD", name: "US Dollar", symbol: "$", decimal: 2)
EUR = Currency.new(code: "EUR", name: "Euro", symbol: "€", decimal: 2)

Price = Data.define(:amount, :currency) do
    def initialize(amount:, currency:)
        amount => Integer
        currency => Currency

        super
    end
end

# ✅
p1 = Price.new(amount: 10, currency: USD) 
# => #<data Price amount=10, currency=#<data Currency code="USD", name="US Dollar", symbol="$", decimal=2>>

# ❌
p2 = Price.new(amount: 10, currency: "USD")
# => in `initialize': "USD": Currency === "USD" does not return true (NoMatchingPatternError)

Data class vs Struct

You can use Struct just as well as using the Data class but it will not create immutable objects. You can of course freeze the instances but the Data object gives that for free.

In case you want to create a Struct here is how it might look like:

Price = Struct.new(:amount, :currency, keyword_init: true)

price = Price.new(amount: 50, currency: "USD")
# => <struct Price amount=50, currency="USD">

It supports also providing a block when creating the structure to add extra methods as we did it for the Data.

A bit on the immutability

Please note that the Data objects are frozen but not deep frozen. That means that if you put inside a Data object attribute a structure that is not immutable then you can change those properties.

My advice is to combine Data objects only with Data objects or immutable or immediate objects to make sure that everything remains immutable.

I recommend you to do this:

Currency = Data.define(:code, :name, :symbol, :decimal)
Price = Data.define(:amount, :currency)

EUR = Currency.new(code: "EUR", name: "EURO", symbol: "€", decimal: 2)
price = Price.new(amount: 50, currency: EUR)

price.currency.code = "MyEUR"
# undefined method 'code=' for an instance of Currency (NoMethodError)

While if you try to put there an object that can be changed like say a Struct it will allow you to change it:

Currency = Struct.new(:code, :name, :symbol, :decimal, keyword_init: true)
Price = Data.define(:amount, :currency)

EUR = Currency.new(code: "EUR", name: "EURO", symbol: "€", decimal: 2)
price = Price.new(amount: 50, currency: EUR)
# => #<data Price amount=50, currency=#<struct Currency code="EUR", name="EURO", symbol="€", decimal=2>>

price.currency.code = "MyEUR"
price
# => #<data Price amount=50, currency=#<struct Currency code="MyEUR", name="EURO", symbol="€", decimal=2>>

The same goes for putting inside a hash:

Price = Data.define(:amount, :currency)
EUR = { code: "EUR", name: "EURO", symbol: "€", decimal: 2 }

price = Price.new(amount: 50, currency: EUR)
# => #<data Price amount=50, currency={code: "EUR", name: "EURO", symbol: "€", decimal: 2}>
price.currency[:code] = "MyEUR"
price
# => #<data Price amount=50, currency={code: "MyEUR", name: "EURO", symbol: "€", decimal: 2}>

So you need to take care of freezing the objects that you put inside yourself if you want them to remain unchanged.

Trick: You can use Ractor shareable to deep freeze a Data object

This is probably not the purpose of the Ractor.make_shareable method, but it is a nice trick to try:

Currency = Struct.new(:code, :name, :symbol, :decimal, keyword_init: true)
Price = Data.define(:amount, :currency)

EUR = Currency.new(code: "EUR", name: "EURO", symbol: "€", decimal: 2)
price = Ractor.make_shareable(Price.new(amount: 50, currency: EUR))
# => #<data Price amount=50, 
# => currency=#<struct Currency code="EUR", name="EURO", symbol="€", decimal=2>>

price.currency.code = "MyEUR"
# => in '<main>': can't modify frozen 
# => Currency: #<struct Currency code="EUR", name="EURO", symbol="€", decimal=2> (FrozenError)

Some conclusions

I think the Data is a great addition to the Ruby language and I try to reach out to it everytime I need to create a value object. I like the immutability and the comparison by type and value that is created by default.

It also defines deconstruct and deconstruct_keys if you want to use the Data object in pattern matching (Struct defines them too in case you want to use Struct).

Read more

I published a followup article where I show some real world examples of value objects created with the Data class.

If you want to read more about this I recommend at least two resources:

• The feature request on the Ruby Bug Tracker: https://bugs.ruby-lang.org/issues/16122

• The great documentation about it maintain by Victor Shepelev here https://rubyreferences.github.io/rubychanges/3.2.html#data-new-immutable-value-object-class

• This article https://thoughtbot.com/blog/value-object-semantics-in-ruby that goes into details about comparabilityt of two value objects

👉 If you like this article and want it in your inbox each week, subscribe to my newsletter. You’ll find ideas on Ruby, software development, software testing, building products and workshops, plus notes on creativity, tech trends, and whatever else sparks my curiosity.

👐 Want to improve your developer testing skills? Visit goodenoughtesting.com/articles to discover resources on testing for developers.

👉 Join my Short Ruby Newsletter for weekly Ruby updates and visit rubyandrails.info, a directory of Ruby learning content.

🤝 Connect with me on Linkedin, Bluesky, Ruby.social, , and Twitter, where I mostly post about Ruby and Ruby on Rails.

🎥 Follow my YouTube channel for short videos about Ruby and Rails.

What is JSON-LD?

JSON-LD stands for JavaScript Object Notation for Linked Data. One use is adding it to web pages, allowing search engines or crawlers to understand the content structure and context better.

It is usually added in the <head> html element like this:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "http://example.com/"
}
</script>

Why use JSON-LD Schema in your blog

• Your content may show up as rich snippets in search results.

• Helps search engines to understand the data related to your blog post as you intend and with the required context.

• It may help AI to get structured data about the context of your blog post.

• Around 30% (source: searchenginejournal.com) of websites are using JSON-JD schema and adding it will improve your SEO results.

• When adding sameAs attribute for your author it might improve your presence online

But there are better blog posts that describes why is good to add JSON-LD schema:

• https://www.semrush.com/blog/schema-markup

• https://www.schemaapp.com/schema-markup/benefits-of-schema-markup/

Here is a screenshot from https://www.semrush.com/blog/schema-markup:

Google also recommends using JSON-LD schema:

Adding a JSON-LD schema for every page

We should start by adding a schema for every page on your blog. https://schema.org/WebSite is a schema specification that you should add on every page of your blog (remember this should be inside <script type="application/ld+json"> but to make the code highlight nicer I will only show the JSON part)

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Lucian Ghinda - Notes",
  "url": "https://allaboutcoding.ghinda.com",
  "author": {
    "@type": "Person",
    "name": "Lucian Ghinda",
  }
}

Add `url` to the author

Including an url in the author section helps identify the author's page on your website and aids search engines in recognizing the author's presence on your site, which could enhance the visibility of their content:

{
  // the other JSON-LD keys
  "author": {
    "@type": "Person",
    "name": "Lucian Ghinda",
+    "url": "https://allaboutcoding.ghinda.com/authors/lucian-ghinda"
  }
}

Add `sameAs` if you want to connect your website with other places

Utilize sameAs to show that two entities are fundamentally identical. Within the context of an author section, it links the author's profile on your website to their profiles on other platforms, such as social media or other locations where you maintain a page:

{
  // the other JSON-LD keys
  "author": {
    "@type": "Person",
    "name": "Lucian Ghinda",
    "url": "https://allaboutcoding.ghinda.com/authors/lucian-ghinda",
+    "sameAs": [
+      "https://bsky.app/profile/lucianghinda.com",
+      "https://www.linkedin.com/in/lucianghinda"
+    ]
  }
}

A recommended example of the schema for every page on your blog:

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Lucian Ghinda - Notes",
  "url": "https://allaboutcoding.ghinda.com",
  "author": {
    "@type": "Person",
    "name": "Lucian Ghinda",
    "sameAs": [
       "https://bsky.app/profile/lucianghinda.com",
        "https://www.linkedin.com/in/lucianghinda"
    ]
  }
}

JSON-LD Schema for inside the blog post / article

You can add multiple JSON-LD script tags in your website. You should keep the main one that is about WebSite and add inside the blog posts one about `BlogPosting` - https://schema.org/BlogPosting

<script type="application/ld+json">
{ 
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://allaboutcoding.ghinda.com/post-url"
  },
  "headline": "Why add JSON+LD to your blogpost",
  "datePublished": "2025-03-11T13:22:00+02:00",
  "dateModified": "2025-03-11T14:30:00+02:00",
}
</script>

A bit about datePublished and dateModified

Values for these two fields can be Date or DateTime. Choose one that fits you bets or that you can generate easily.

In case you usually don't update your articles, then only add `datePublished`

{ 
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://allaboutcoding.ghinda.com/post-url"
  },
  "headline": "Why add JSON+LD to your blogpost",
+  "datePublished": "2025-03-11T13:22:00+02:00",
+  "dateModified": "2025-03-11T14:30:00+02:00"
}

Then add author

You can use the same snippet as you used in the WebSite schema:

{
  // the other JSON-LD keys
  "author": {
    "@type": "Person",
    "name": "Lucian Ghinda",
    "url": "https://allaboutcoding.ghinda.com/authors/lucian-ghinda",
    "sameAs": [
      "https://bsky.app/profile/lucianghinda.com",
      "https://www.linkedin.com/in/lucianghinda"
    ]
  }
}

If you have multiple authors, then make the "author" key an array:

{
  // the other JSON-LD keys
  "author": [
    { 
      "@type": "Person", 
      "name": "Lucian Ghinda",
      // other attributes
    },  
    { 
      "@type": "Organization", 
      "name": "Short Ruby",
      // other attributes
    }  
  ]
}

JSON-LD Schema for a blog post - add publisher

The publisher key identifies the publisher of the creative work. If you have your own blog, you can list yourself as the publisher. However, if you're writing for an organization, make sure to include the organization's name instead:

{
  // the other JSON-LD keys
  "publisher": {
    "@type": "Organization",
    "name": "Short Ruby",
    "logo": {
      "@type": "ImageObject",
      "url": "https://shortruby.com/assets/logo-d8627cb3e82564f3328709589c3c1ce34b81d0afed316a0b58d27ab93bcaa9d4.png"
    }
  },
}

The final JSON-LD for the blog post

Here is how the JSON-LD schema for a blog post might look like:

{ 
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://allaboutcoding.ghinda.com/post-url"
  },
  "headline": "Why add JSON+LD to your blogpost",
  "datePublished": "2025-03-11T13:22:00+02:00",
  "dateModified": "2025-03-11T14:30:00+02:00",
  "author": {
    "@type": "Person",
    "name": "Lucian Ghinda",
    "url": "https://allaboutcoding.ghinda.com/authors/lucian-ghinda",
    "sameAs": [
      "https://bsky.app/profile/lucianghinda.com",
      "https://www.linkedin.com/in/lucianghinda"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "Short Ruby",
    "logo": {
      "@type": "ImageObject",
      "url": "https://www.exampleblog.com/logo.png"
    }
  }
}

Tools

There are many more variations of how to combine various items and this way communicate to a crawler or search engine what you want them to know about your blog.

Here are some tools you can use to validate your JSON-LD schema and check how Google parses rich snippets:

https://search.google.com/test/rich-results

https://validator.schema.org

Further reading

Avo published a very nice article about how to add the schema markup on a Rails app → Adding Structured Data to a Rails application

If you like this article:

👐 Interested in learning how to improve your developer testing skills? Join my live online workshop about goodenoughtesting.com - to learn test design techniques for writing effective tests

👉 Join my Short Ruby Newsletter for weekly Ruby updates from the community and visit rubyandrails.info, a directory with learning content about Ruby.

🤝 Let's connect on Bluesky, Ruby.social, Linkedin, Twitter where I post mostly about Ruby and Ruby on Rails.

🎥 Follow me on my YouTube channel for short videos about Ruby/Rails

I agree that monkey patching should be the last approach and used carefully. One of the most critical issues is that the code you create depends on the structure of the code you are monkey patching, thus voluntarily violating the contract that the gem's author offered.

I see monkey patching as a breach of contract with the author of a gem. In rare cases when this is necessary, the fix should be on the side that breached the contract. If you go down this route, then every time the gem is updated, you have to review the code of the gem and test your monkey patch to see if everything works as you expect it.

How to automate the check of patched Gem version

Add the following code at the beginning of your monkey patch file.

# This is an example about ActiveSupport

if Rails.env.local? || Rails.env.ci?
  if ActiveSupport.version > Gem::Version.new('8.0.0')
    raise "\n\nReview this monkey patch after upgrading \n" \
          "Path: #{__FILE__}"
  end
end

You can do the same if you have an initializer and you temporary added some settings that you know you want to remove or review after doing an update.

I found this approach in various projects I’ve worked on over the past couple of years. It can take different forms: sometimes only in CI, sometimes in a specific CI that checks compatibility, sometimes in tests, and other variations.

In case the gem does not define the version as an Gem::Version object and it might define it like this:

module MyGem
  VERSION = '1.0.1'
end

Then you should create the comparison in the following way:

if Rails.env.local? || Rails.env.ci?
- if MyGem::Version > Gem::Version.new('8.0.0')
+  if Gem::Version.new(MyGem::VERSION) > Gem::Version.new('1.0.1')
    raise "\n\nReview this monkey patch after upgrading \n" \
          "Path: #{__FILE__}"
  end
end

You should always compare with Gem::Version object because it defines the method <=> in a way that takes into consideration major, minor and patch version. Here is how that method currently looks like:

# Source: https://github.com/rubygems/rubygems/blob/master/lib/rubygems/version.rb#L360

  def <=>(other)
    return self <=> self.class.new(other) if (String === other) && self.class.correct?(other)

    return unless Gem::Version === other
    return 0 if @version == other.version || canonical_segments == other.canonical_segments

    lhsegments = canonical_segments
    rhsegments = other.canonical_segments

    lhsize = lhsegments.size
    rhsize = rhsegments.size
    limit  = (lhsize > rhsize ? lhsize : rhsize) - 1

    i = 0

    while i <= limit
      lhs = lhsegments[i] || 0
      rhs = rhsegments[i] || 0
      i += 1

      next      if lhs == rhs
      return -1 if String  === lhs && Numeric === rhs
      return  1 if Numeric === lhs && String  === rhs

      return lhs <=> rhs
    end

    0
  end

As you can notice it knows also how to compare with a String so you could probably write this code like this:

if Rails.env.local? || Rails.env.ci?
  if Gem::Version.new("1.0.1") <= MyGem::VERSION
    raise "\n\nReview this monkey patch after upgrading \n" \
          "Path: #{__FILE__}"
  end
end

But I prefer to make sure that both of them are Gem::Version objects.

If you like this article:

👐 Interested in learning how to improve your developer testing skills? Join my live online workshop about goodenoughtesting.com - to learn test design techniques for writing effective tests

👉 Join my Short Ruby Newsletter for weekly Ruby updates from the community and visit rubyandrails.info, a directory with learning content about Ruby.

🤝 Let's connect on Bluesky, Ruby.social, Linkedin, Twitter where I post mostly about Ruby and Ruby on Rails.

🎥 Follow me on my YouTube channel for short videos about Ruby/Rails