real-world-rails: 200+ Production Rails Codebases in One Repository

What problem real-world-rails solves, and for whom

Reading one Rails application teaches you that application's conventions. Reading two hundred teaches you which conventions are common and which are one team's habit. That second kind of knowledge is what real-world-rails is built to make accessible. The repository collects more than 200 active open source Rails apps and engines in a single place, and the README frames the payoff plainly: aggregated production codebases have always been useful for learning, and the project argues they became far more useful once AI coding agents could search them.

The intended audience is narrow but real. It is for Rails developers who want to see how background job retry logic, multi-tenancy, PDF generation, soft deletes or authentication are implemented across many production codebases rather than in a single tutorial. It is also for people driving an AI agent over that corpus, since the README's example prompts are written as questions to an agent rather than as shell commands. If you want a scaffolded starter app, this is not that. The repository is a library of source code, not a generator.

How the submodule layout actually works

The mechanism is git submodules. The repository is not a monorepo containing 200 copies of other projects' source; it is a parent repository whose .gitmodules file points at each upstream project, and the top-level entries include apps/, engines/, bin/, skills/ and repos.md. Cloning the parent gives you the pointers, not the code. The code arrives when the submodules are initialized.

That distinction drives most of the project's operational behaviour. Because each app stays its own repository, upstream history, branches and licences remain intact and you can update a single submodule without touching the others. The cost is that a fresh clone is nearly empty of Rails code until setup runs, and that the parent repository's own git operations do not touch the contents of the submodules. The README's update instructions reflect this: after pulling, you run a separate submodule update step.

repos.md holds the full list of included apps and engines with descriptions, so it is the file to read before deciding whether the corpus covers your question. The analyses/ directory is git-ignored and exists so your own notes and pattern comparisons stay out of commits and pull requests.

Installing real-world-rails and running a first search

The README states that git-lfs must be installed first, linking to git-lfs.com. Then clone the repository and run the setup script from inside it:

git clone [email protected]:steveclarke/real-world-rails.git
cd real-world-rails/
bin/setup

bin/setup initializes and downloads all submodules using a shallow clone. The README puts that at approximately 10 GB of disk space. Passing --full clones complete git history instead, which the README estimates at roughly 29 GB. The script also accepts --reset to re-download all submodules, and the README notes that --reset is what you use to switch between the default and --full modes.

Once the download finishes, bin/status reports how many apps are initialized. That is the check to run before trusting anything else, because a partial clone looks like a working checkout until you search it.

bin/status

After that, the workflow is either an AI agent pointed at the directory or plain grep. The README's own examples of what to ask an agent include "how do these apps implement background job retry logic?" and "compare authentication implementations across apps using Devise vs. custom auth". With an agent that can read files, those questions run against the actual source in apps/ and engines/.

The agent skill and the weekly submodule PR

Two pieces of automation deserve separate attention. The first is the /real-world-rails skill for AI coding agents, which the README says teaches an agent to search across all 200+ codebases to research how production apps solve architectural problems. It installs through the skills CLI:

npx skills add steveclarke/real-world-rails

After installing it, the README suggests prompts such as "how do Rails apps handle multi-tenancy?" or "research background job patterns across real world rails apps". This is the project's answer to the manual-grep era it describes: instead of writing Ruby scripts to walk the tree, you delegate the walk to an agent.

The second is the update path. Submodules are updated automatically by a GitHub Action that runs weekly and opens a pull request. Once that PR is merged, the README says a consumer only needs to pull and update submodules:

git pull
git submodule update

If you do not want to wait for the weekly action, bin/update pulls latest changes and moves all submodules to their latest remote commits. There is also bin/verify, which checks that each submodule repository still exists on GitHub and has not been moved or renamed. That script requires the gh CLI, so it is not available in a bare environment.

Disk, network and the wrong-tool cases

The obvious limitation is size. Ten gigabytes for a shallow clone and twenty-nine for full history is not a rounding error on a laptop with a small SSD, and it is worse on a metered connection because setup downloads every repository at once. There is no documented way to fetch only the apps you care about; the README presents setup as all-or-nothing, with --reset as the mode switch. If you need three apps, cloning three repositories by hand is faster and cheaper.

The second limitation is that this is a research corpus, not a running environment. Nothing in the README suggests the apps are configured to boot, and each one carries its own dependencies, database requirements and Ruby version. You are reading code, not executing it. Anyone who expects to start a server after bin/setup will be disappointed.

The third is currency. The weekly action keeps submodules near upstream, but the parent repository's own record of what is included depends on that action running and the resulting PR being merged. bin/verify exists precisely because upstream repositories get moved or renamed, which breaks a submodule pointer. If a pointer breaks, the affected app is simply unavailable until it is fixed.

How it compares with real-world-ruby-apps and sibling collections

The README lists sibling collections directly, and the differences are structural rather than cosmetic. Real World Ruby Apps, by jeromedalbert, is a Ruby collection rather than a Rails-specific one, so it reaches beyond the framework. Real World Sinatra covers a different framework entirely. Real World Django applies the same idea to Python, and Real World Nuxt, maintained by the same author as this repository, applies it to a JavaScript framework.

The meaningful comparison is real-world-ruby-apps versus real-world-rails. If your question is about Rails conventions specifically, the Rails-only corpus is the tighter signal, because every codebase in it shares the framework's structure and you are comparing application decisions rather than framework choices. If your question is about Ruby idioms, a broader Ruby collection will surface code this repository never includes. Neither is a superset of the other, and the README treats them as complementary rather than competing.

Maintenance, licence and what to verify before you commit

The repository is not archived and the last push was on 2026-09-07, so it is current. There are no retrieved releases, which is consistent with a project that ships scripts and submodule pointers rather than versioned artifacts. The practical upgrade cost is bandwidth, not code: bin/update moves submodules to their latest remote commits, and the weekly GitHub Action proposes those moves as a pull request. Running bin/update yourself bypasses the review step, which means an upstream force-push or restructure lands in your working tree without warning.

The parent repository is MIT licensed, and that is the whole of the licence story for the collection itself. It does not extend to the submodules. Each app and engine is a separate repository with its own licence, and because git submodules preserve that separation, the licences stay distinct. Reading code and copying it into your own project are different acts, and the MIT file at the top level does not authorise the second one. Check the licence inside the specific submodule you intend to reuse from.

Before adopting, verify three things: that git-lfs is installed, that bin/status reports the expected number of initialized apps after setup, and that the apps you actually care about appear in repos.md. If disk space is tight, decide between the shallow default and --full before running setup, since switching later means re-downloading everything.

Editorial conclusion

Adopt real-world-rails if you want to study how production Rails apps actually implement background jobs, multi-tenancy, soft deletes or authentication, and you have roughly 10 GB to spare plus git-lfs installed. Skip it if you need one runnable example app, if you are on a metered connection, or if you want a curated tutorial rather than raw source. Before committing, run bin/status after bin/setup to confirm the submodules initialized, and check repos.md to see whether the specific apps you care about are actually included.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. steveclarke/real-world-rails on GitHub