You ask a coding agent to add a new carrier integration to your Rails app. Twenty minutes later you have a pull request that inherits from LegacyCarrierSync, a class written in 2018 that the team stopped using years ago. The agent did not hallucinate it. It opened app/, found four different ways your codebase connects to a shipping carrier, and picked one that looked plausible. A new hire would have done the same thing in their second week.
Many long-lived Rails apps end up in this situation. Every generation of the team left a pattern behind, the old patterns never went away, and the people who knew which one is current learned to step around the rest. That knowledge lives in heads and in Slack threads. Agents can't see either of those, so they read the repository as evidence, and the repository says all four answers are equally valid.
The fix is to make the repository show which pattern is current and to make the old ones hard to copy, which is cheaper than it sounds.
Why do coding agents keep copying old patterns in a Rails app?
Say you run a logistics app that receives shipment updates from carriers. The first integrations were written as CarrierImportJob subclasses that polled an FTP server. Then somebody read a blog post about service objects and built LegacyCarrierSync (it was called CarrierSync back then). A few years later a third approach appeared in app/connectors/, inspired by a different blog post. Today the team writes Carriers::Integration subclasses in app/integrations/carriers/, and that base class handles validation, retries and logging.
Each of those choices made sense at the time. The problem is that all four still run in production, all four have tests, and in the editor they all look the same. Code doesn't come with a label that says "deliberate decision", "constraint that expired in 2020" or "experiment nobody finished", so a newcomer has no way to tell them apart.
People compensate for this. After a few months you know which directory is current, which README section is fiction, and who to ask before you touch billing. When a newcomer asks why there are four integration styles, you say "yeah, that's a bit weird, don't worry about it", and six months later they say the same thing to the next person. The warnings get passed on by word of mouth, and nobody remembers the reasons anymore.
An agent never hears those warnings. Every time its context is cleared, it searches again, infers again, and spends tokens getting back to what the team already knows. When it lands on the wrong example, it shows you a workaround your team stopped noticing long ago.
Is cleaning up the codebase part of the job or a distraction?
Most engineers are hired to close tickets, so time spent on the environment around the tickets feels like time stolen from "real work". In practice, a large share of professional software work happens inside decisions that somebody else made. Andrea Goulet of Corgibytes has a name for people who like that kind of work: menders, as opposed to makers, who prefer building something new. If you have ever enjoyed a comment from 2013 that says "temporary workaround, remove after launch", you are probably a mender.
Kent Beck's Tidy First? (O'Reilly, 2023) gives the classic rule here: before a hard change, make the change easy, and keep the tidying separate from the behavior change. That rule assumed tidying was expensive because a human had to do it. With an agent, tidying is nearly free to produce. One ticket can turn into five pull requests with refactors, new tests, docs and a dependency bump, and every one of them still has to be read, understood and reviewed by someone.
Fred Brooks described the same trap in The Mythical Man-Month in 1975, when he showed that adding people adds coordination cost faster than it adds output. An agent alone can now create that coordination cost, because it produces more change than the team can absorb, so the bottleneck moves from writing code to deciding what belongs in the system. Work that makes those decisions cheaper is part of the job.
How to pick one pattern when the team has four
In the carrier example, the hard part is social. Nobody on the team created the first three patterns, many of the original authors have left, and nobody feels entitled to declare the old ones dead. So every new integration restarts the debate, or worse, picks whichever example the author opened first.
Somebody has to say "from now on we do it this way" and pick the pattern that fits the system you have now well enough to document, generate, test and review the same way every time. A useful question for the team is "if you had to build a new carrier integration tomorrow, what would you reach for?" In our example the answer is Carriers::Integration.
Write that decision down, then make sure new code can't follow any of the other three.
How to turn the chosen pattern into a Rails generator
Telling people "copy the most recent integration" works until the most recent one is an experiment. A generator turns the team's decision into something executable. Humans and agents run the same command, so reviewers always see the same file layout. Rails ships a generator for generators, which creates the skeleton in lib/generators/:
bin/rails generate generator carrier
That gives you lib/generators/carrier/carrier_generator.rb, a USAGE file, an empty templates/ directory and a test skeleton in test/lib/generators/carrier_generator_test.rb. Fill in the generator class:
# lib/generators/carrier/carrier_generator.rb
class CarrierGenerator < Rails::Generators::NamedBase
source_root File.expand_path("templates", __dir__)
desc "Creates a carrier integration that follows the Carriers::Integration pattern"
def create_integration
template "integration.rb.tt", "app/integrations/carriers/#{file_name}.rb"
end
def create_test
template "integration_test.rb.tt", "test/integrations/carriers/#{file_name}_test.rb"
end
def create_sample_payload
template "payload.json.tt", "test/fixtures/files/carriers/#{file_name}/delivered.json"
end
end
Rails::Generators::NamedBase means the generator takes a name as its first argument and gives you helpers derived from it: file_name is the snake_case form (dhl_express) and class_name is the camelized one (DhlExpress). Every public method runs in the order it is defined, so the generator creates the integration, then its test, then a sample payload fixture. template renders an ERB file from source_root and writes the result to the destination path given as the second argument. The .tt suffix is the Rails convention for generator templates.
The integration template carries the team's current expectations:
<%# lib/generators/carrier/templates/integration.rb.tt %>
module Carriers
class <%= class_name %> < Carriers::Integration
# Map the raw carrier payload to ShipmentEvent attributes.
# Validation, retries and logging live in Carriers::Integration.
def normalize(payload)
{
tracking_number: payload.fetch("tracking_number"),
status: payload.fetch("status"),
occurred_at: Time.iso8601(payload.fetch("timestamp"))
}
end
end
end
Every generated file now says where the shared behavior lives, so neither a human nor an agent will reimplement retries in a new integration. The test template and the JSON fixture follow the same idea: the generated test loads delivered.json through file_fixture and asserts the normalized status, so a new integration starts with one passing test instead of zero.
Running it looks like this:
bin/rails generate carrier dhl_express
create app/integrations/carriers/dhl_express.rb
create test/integrations/carriers/dhl_express_test.rb
create test/fixtures/files/carriers/dhl_express/delivered.json
A rule in the docs or a canonical example still has to be read and interpreted, while a generator hands you the starting files directly. Rails does the same with bin/rails generate model, and a custom generator applies it to your own conventions.
How to stop new code from using the retired patterns
A generator makes the right path easy, but the three old patterns are still sitting in app/, and agents and new hires will keep copying them. You can't migrate them all this sprint, but you can stop the number from growing. A ratchet test does that: it allows the files that already use a retired pattern and fails on any new one.
# test/architecture/carrier_patterns_test.rb
require "test_helper"
class CarrierPatternsTest < ActiveSupport::TestCase
# Files that still use a retired pattern. This list may only shrink:
# migrate a file, then delete its line here.
LEGACY_FILES = %w[
app/services/carrier_sync/ups.rb
app/jobs/import_gls_shipments_job.rb
].freeze
RETIRED = /<\s*(LegacyCarrierSync|CarrierImportJob)\b/
def files_using_retired_patterns
Dir.glob(Rails.root.join("app/**/*.rb")).filter_map do |path|
relative = path.delete_prefix("#{Rails.root}/")
relative if File.read(path).match?(RETIRED)
end
end
test "new code does not use a retired carrier pattern" do
added = files_using_retired_patterns - LEGACY_FILES
assert_empty added, <<~MSG
#{added.join(", ")} uses a retired carrier pattern.
Start new carriers with: bin/rails generate carrier NAME
MSG
end
test "migrated files are removed from LEGACY_FILES" do
migrated = LEGACY_FILES - files_using_retired_patterns
assert_empty migrated, "Delete these lines from LEGACY_FILES: #{migrated.join(", ")}"
end
end
files_using_retired_patterns scans every Ruby file under app/ for a class that inherits from one of the retired base classes and returns repository-relative paths. The first test subtracts the allowed list, so anything left over is new code using an old pattern. The second test works in the other direction: when someone migrates ups.rb to Carriers::Integration but forgets to update the list, it fails and tells them which line to delete. Without it, the list would slowly fill up with entries that no longer mean anything.
When an agent adds class Carriers::Dpd < LegacyCarrierSync, the test fails with:
app/integrations/carriers/dpd.rb uses a retired carrier pattern.
Start new carriers with: bin/rails generate carrier NAME
The agent reads that output, runs the generator and fixes its own pull request before anyone reviews it. An agent can skip a sentence in a docs file, but it has to act on a failing test that names the fix. The regular expression is deliberately simple, so it will miss creative inheritance through a mixin. That's fine for a ratchet, because its job is to catch the common copy-paste case.
When the last legacy file is migrated, delete the old base classes too. That leaves one less example for agents and new hires to copy.
How to find out why weird code exists before you delete it
Some old code is still needed, so before deleting anything you need evidence to tell intentional weirdness apart from forgotten weirdness. A simple loop helps here: wonder, unpack, tinker and share. Robby Russell describes it, under the name WUTS, in his Rails World 2026 keynote, together with the letter-to-your-replacement exercise that comes later in this article.
Wondering is the small "huh?" moment. Say you find this in the shipments API:
class ShipmentsController < ApplicationController
before_action :coerce_legacy_pickup_date
private
# Accepts "dd.mm.yyyy" pickup dates from old clients.
# Remove once the 2019 iOS app is retired.
def coerce_legacy_pickup_date
raw = params[:pickup_on]
return unless raw.is_a?(String) && raw.match?(/\A\d{2}\.\d{2}\.\d{4}\z/)
ActiveSupport::Notifications.instrument(
"legacy_pickup_date.api",
user_agent: request.user_agent,
api_client_id: request.headers["X-Api-Client"]
)
params[:pickup_on] = Date.strptime(raw, "%d.%m.%Y").iso8601
end
end
You are fairly sure that the 2019 iOS app was shut down before you joined. Deleting the filter is tempting. Unpacking means doing the homework first. git log -S coerce_legacy_pickup_date lists every commit that added or removed that string, and the oldest one is where it came from. Read the pull request linked to it and check production logs. If the history doesn't explain it, ask whoever wrote it, even if they left the company. It costs one short message, and the worst outcome is no reply.
Tinkering is the smallest reversible change that gives you information. The ActiveSupport::Notifications.instrument call above is that change. It doesn't alter the behavior, and it emits an event every time the legacy branch actually runs. Subscribe to it in an initializer:
# config/initializers/legacy_usage.rb
ActiveSupport::Notifications.subscribe("legacy_pickup_date.api") do |event|
Rails.logger.info(
"[legacy] pickup_date client=#{event.payload[:api_client_id]} " \
"ua=#{event.payload[:user_agent]}"
)
end
A block with one argument receives an ActiveSupport::Notifications::Event, and event.payload is the hash you passed to instrument. A request with a legacy date then leaves a line like this in the log:
[legacy] pickup_date client=4127 ua=AcmeScanner/2.1
Imagine that a week of logs shows forty such requests, none from an iOS app, all from a warehouse partner's barcode scanner integration. The behavior stays exactly as it was, but now you know why it exists and who depends on it.
Sharing is the step teams skip most often. "I learned something weird today" in Slack doesn't count. Put the knowledge back where the next reader will find it, which in this case is the comment itself:
# Accepts "dd.mm.yyyy" pickup dates. Still sent by the Acme warehouse
# scanner (api client 4127). The iOS app stopped using this format in 2021.
# Remove after Acme moves to ISO 8601 dates.
The next person, or the next agent, reads one comment and doesn't have to repeat your week of investigation. For bigger discoveries, such as what really happens when Shipment#save runs its callbacks, a Mermaid diagram committed next to the code does the same job.
How to find the friction your team stopped noticing
Two exercises help you spot the workarounds you no longer notice.
The first one is watching. Sit next to a colleague while they do an ordinary task and keep your hands off the keyboard. Notice where they pause, what they repeat, which command they avoid, and which private workaround they reach for without thinking. Then do the same with an agent session: read the transcript and note where it searched three times for the same thing, ran a command that is known to be broken, or opened a retired example. Agents haven't learned your workarounds yet, so they hit every one of them.
The second exercise is a letter to your replacement. Imagine it is your last day and you have to write to whoever takes over: "Welcome. This is mostly a normal Rails app, except..." What would you warn them about? Which commands should they never run? Which parts depend on knowledge that isn't written down anywhere? Ask two colleagues to write their own letters and compare them. Where the letters differ, you have found knowledge that lives in one head.
The letter has an obvious home today. AGENTS.md is a plain Markdown file in the repository root that coding agents read for project instructions. Codex, Cursor, Gemini CLI, Aider, Zed and GitHub Copilot's coding agent support it, among others. Claude Code reads it as well from version 2.1.277 onward, as long as there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. If you already have a CLAUDE.md, put an @AGENTS.md import at the top of it. A section built from the letter could look like this:
## Retired patterns (do not copy)
- `LegacyCarrierSync`, `CarrierImportJob` and `app/connectors/`: new carriers use
`bin/rails generate carrier NAME`. `test/architecture` enforces this.
## Looks wrong, is intentional
- `ShipmentsController#coerce_legacy_pickup_date` still serves api client 4127.
Do not remove it without checking the `[legacy] pickup_date` log lines.
## Commands
- `bin/rails test test/architecture` runs the pattern checks in seconds.
- Never run `bin/rails db:seed` locally: it calls the real carrier sandbox APIs.
Use `bin/rails dev:sample_data` instead.
Keep this file short and specific. A rule that a test can enforce belongs in a test, with the docs only pointing to it. What stays in AGENTS.md is the context no test can express.
How to make feedback fast and trustworthy for agents
Most teams share rules nobody wrote down: don't run the full suite locally because it takes 25 minutes, don't trust staging, ignore the three warnings at the top of the test output. Agents inherit those rules without the explanation. An agent waiting on a 40-minute CI run wastes that time and the tokens around it, and an agent that can't tell a flaky failure from a real one may act on a failure that means nothing.
So look for where people wait: a check that takes 40 minutes when five would do, an error message that sends people digging through old Slack threads, or a failure that shows up after the author has moved to another task. Not every check has to be instant, and some belong closer to production. The architecture test above is a good example of the cheap end: it runs in seconds, gives a precise message and doesn't depend on any records, so an agent can run it after every change.
Why making mistakes cheap to undo beats trying to prevent them
Trying to prevent every mistake sounds responsible, but it doesn't work as a way to run a team. When one migration or one forgotten config value means three engineers debugging production for two days, the team learns a lesson: be careful, don't touch that, wait until Monday. That fear becomes part of your environment, and people stop experimenting because they are managing risk.
The fix is to make recovery cheaper. Feature flags let you turn a change off without a deploy. Reversible migrations, and a gem like strong_migrations from Andrew Kane that blocks the dangerous ones in development, make the database less scary. Preview environments and smaller deploys shrink the blast radius. With those in place, people and agents are more willing to try things.
A checklist for your next ticket
You don't need a platform team or a quarter-long project to start. Pick one friction point that you, a colleague or an agent hit repeatedly, and work through it:
- Name the friction and find one more person who feels it.
- Decide which pattern is current and write that decision down.
- Encode the decision in a generator, so the right path is a single command.
- Add a ratchet test that allows existing legacy files and blocks new ones, with the fix in the failure message.
- Before deleting anything weird, instrument it and read the history.
- Put what you learned back into the repository: a comment, a diagram, or a line in
AGENTS.md. - Delete retired patterns once the ratchet list reaches zero.
If someone asks why you spent a day on this instead of a feature, point at the agent sessions. Tokens burned on the same workaround show up on an invoice. If you want to find the next hotspot systematically, the legacy Rails codebase audit method is a good next step.
FAQ
Does Claude Code read AGENTS.md?
Yes, from version 2.1.277. By default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. If you keep both files, add @AGENTS.md at the top of CLAUDE.md so both tools share one source.
Is a custom Rails generator worth it for a small team?
If the team creates the same kind of file more than a few times a year, yes. The generator in this article is about 15 lines plus templates, and it pays off the first time an agent or a new hire uses it instead of copying a retired example. For something you create once a year, a short note in AGENTS.md is enough.
Should I delete legacy code that coding agents keep copying?
Delete it once nothing depends on it, and verify that with instrumentation rather than with comments. Until then, freeze it with a ratchet test and list it under retired patterns in AGENTS.md, so it stops spreading while it still runs.
Where do architecture tests like this belong in a Rails app?
A test/architecture directory works well. It keeps these checks separate from behavior tests, and the directory is fast enough to run on its own with bin/rails test test/architecture.
Happy mending!
