Software Engineering consultant

Mergeable by Default: Why AI Coding Needs a Context Engine, Not Just a Bigger Model

Wed, 06 May 2026 00:00:00 +0000

“The hard part is no longer getting AI to generate code. The hard part is getting AI to generate code that belongs in your system.”

TL;DR

AI coding tools are getting better, but most teams still lose time because generated code is only almost right.

The useful target is not:

AI writes code.

The useful target is:

AI writes code that is mergeable by default.

That requires a context engine: a reasoning layer that knows your codebase, conventions, previous decisions, permissions, docs, tests, ownership, and current task — then gives the agent only the context it actually needs.

This is the practical point from the talk:

bigger context windows are not enough
naive RAG is not enough
random MCP servers are not enough
code search alone is not enough
AI without context creates review debt
AI with the right context can reduce token cost, review cycles, and rework

For my own Rails / API / AI-assisted workflow, this maps almost directly to:

AGENTS.md
PROMPT.md
GUIDE.md
doc/requirements/**
Flow docs
PRDs
bin/verify
bin/contract_audit
RSpec / rswag / Pundit / Blueprinter conventions

In other words: the best AI coding system is not just a model.
It is an engineering operating system around the model.

The YouTube talk worth knowing

The video is:

Mergeable by default: Building the context engine to save time and tokens — Peter Werry, Unblocked

The core description is simple:

Agents can generate code. The hard part is generating code that’s right for your system, team conventions, and past decisions.

That line is the whole problem.

Modern coding agents can produce code fast. But fast code is not automatically useful code. If the agent does not know your real system, it creates a second job for the team:

pay for generation in tokens
pay again in review, correction, and cleanup

That is why the talk focuses on a context engine: the layer that decides what the agent should know before it acts.

Why this matters

Most AI coding demos optimize for the wrong thing.

They show:

a prompt
a generated file
a green-looking result
a fast demo loop

But production engineering is not a demo.

Production engineering has:

old decisions
team conventions
naming rules
API contracts
permission boundaries
security requirements
test expectations
serializer rules
migration history
review standards
product requirements
half-finished work
legacy constraints

If AI ignores those, the generated code may look good and still be wrong.

That is the dangerous part: AI often fails in ways that are plausible.

It creates code that looks like something a developer would write, but it may not match the system.

The real AI coding problem

The problem is not:

Can the model write Ruby, Go, TypeScript, or Python?

It can.

The problem is:

Does the model know what correct means inside this repo?

Correct is not only syntax.

Correct means:

the endpoint follows the existing API shape
the response uses the right envelope
the serializer follows the project convention
authorization is enforced in the expected way
search uses the expected search library
pagination follows the standard project pattern
tests cover the contract
docs are updated in the right place
generated OpenAPI is produced from specs, not edited by hand
no new representational drift is introduced

This is where AI coding becomes an engineering systems problem.

Bigger context windows do not solve this alone

It is tempting to think the solution is:

Just give the model more context.

But bigger context is not the same as better context.

A huge context window can still contain:

irrelevant files
outdated docs
conflicting instructions
stale decisions
too many examples
private information the agent should not see
similar-but-wrong patterns
code that should not be copied

More context can even make the output worse if the agent cannot tell which source has authority.

The real need is not maximum context.

The real need is selected, ranked, permission-aware, task-specific context.

That is what a context engine should do.

Naive RAG is also not enough

Basic RAG usually means:

embed documents
search for similar chunks
paste the top results into the prompt

That helps, but it is not enough for serious engineering work.

Why?

Because code work often needs reasoning across sources:

requirement says one thing
Flow doc says another
current controller does a third thing
specs define the real contract
old PR explains why the strange behavior exists
security policy limits what can be touched

Simple similarity search does not know which source should win.

A useful context engine needs to answer:

which document is authoritative?
which code path is actually active?
which convention is current?
which files changed recently?
who owns this area?
what should be excluded?
what is relevant to this exact task?

That is different from “search and paste.”

MCP servers are useful, but not magic

MCP-style tool access can connect agents to more systems:

GitHub
Linear / Jira
docs
Slack
databases
observability
local tools

That is useful.

But tool access is not the same as understanding.

An agent with 20 tools can still fail if it does not know:

when to use which tool
which result is authoritative
what the task boundary is
what the team convention expects
what must not be changed
what proof is required before completion

Tools give the agent hands.

A context engine gives the agent judgment boundaries.

What a context engine should contain

A useful engineering context engine should collect and reason over several layers.

Layer	What it answers
Code context	What files, services, models, controllers, serializers, tests, and configs matter?
Product context	What requirement, PRD, or ticket defines the behavior?
Architecture context	What patterns does this repo already use?
Convention context	What naming, response, route, and test rules must be followed?
Decision context	Why was this built this way before?
Permission context	What is the agent allowed to read or change?
Ownership context	Who owns the area, or what review path matters?
Verification context	What command proves the change is safe?
Drift context	What kinds of changes are forbidden even if tests pass?

The important word is context, not documents.

The engine is not just a folder of markdown files.
It is the system that decides what matters for the current task.

What “mergeable by default” really means

“Mergeable by default” does not mean AI code is automatically merged.

It means the AI output is shaped so that the default review path is:

verify, review, merge

Not:

rewrite, argue with the model, fix conventions, add missing tests, update docs, clean up payload shape, then maybe merge

A mergeable-by-default change has these properties:

Property	Meaning
Contract-aware	It implements the actual requirement, not a guessed version
Convention-aware	It follows existing repo patterns
Test-backed	It includes relevant tests/specs
Permission-safe	It does not cross access boundaries
Drift-safe	It does not invent new response shapes or naming styles
Minimal	It touches only what the task requires
Explainable	It can point to why files changed
Verifiable	One command can prove the change is safe enough to review

This is the difference between using AI as autocomplete and using AI as a controlled engineering assistant.

The review-cost problem

Bad AI code is expensive because it creates hidden work.

The obvious cost is token usage.

The bigger cost is review drag:

reviewers must detect subtle mismatch
developers must check every convention manually
specs may be missing or shallow
docs may not reflect behavior
generated code may duplicate existing logic
authorization may be incomplete
migration or serializer decisions may drift

This is why the talk’s “save time and tokens” framing matters.

Tokens are not the main cost.

The real cost is the human correction loop after bad context.

How this maps to my Rails workflow

This topic is especially relevant to my own Rails / API workflow because I already treat AI as part of a controlled delivery system.

In my setup, the closest equivalent of a context engine is not one tool. It is the combination of:

Piece	Role
`AGENTS.md`	Operating rules and delivery discipline
`PROMPT.md`	Task execution flow
`GUIDE.md`	Examples and reusable patterns
`doc/requirements/**`	Source of truth for behavior
Flow docs	Implementation traceability
PRDs	Product context
RSpec	Behavior proof
rswag	API contract proof
Pundit policies	Authorization proof
Blueprinter	Response-shape discipline
Ransack + Kaminari	Search and pagination convention
`bin/verify`	Fast verification loop
`bin/contract_audit`	Drift prevention

This is why the talk feels immediately practical.

It says: do not just buy a smarter model.
Build the environment where the model can make fewer wrong assumptions.

That matches my own conclusion from AI-assisted backend work:

AI productivity comes from externalized judgment, not prompt luck.

A concrete Rails example

Imagine a task:

Add a new nested API endpoint for avatar achievements with artifact attachments.

A generic AI agent may create:

a controller
a model
a serializer
a few routes
maybe a spec

But a context-aware agent should know much more:

endpoints must live under /api/v1/avatars
JSON must stay snake_case
list responses must return { data, meta }
uploads should use nested attributes in one request
Blueprinter should serialize file URLs consistently
Pundit authorization must be represented
request specs must include multipart create/update tests
Ransack and Kaminari are expected for searchable/paginated endpoints
ransackable_attributes must be explicit
Flow docs must follow the existing template
rswag specs should drive OpenAPI generation
bin/verify and contract audit must pass

That is not “more code.”

That is project-specific correctness.

And this is exactly the kind of correctness that generic AI does not infer reliably unless the context system teaches it.

The context engine as a compiler for engineering judgment

A good way to think about this:

Traditional compiler	AI engineering system
Source code	Requirements + task
Language spec	`AGENTS.md` / conventions
Type checker	Tests + contracts
Linter	Style / naming / route rules
Static analyzer	Security + drift audit
Build output	Mergeable PR

The model generates the draft.

The context engine controls the environment around the draft.

That is the serious version of AI-assisted development.

Important lessons from the talk

1. Context must be task-specific

Do not dump the whole repo into the model.

Give it the files, docs, tests, decisions, and examples that matter for the task.

2. Authority matters

The agent must know which source wins when sources conflict.

For example:

current requirement
current tests/specs
current implementation
older docs
old examples

Without authority ranking, the agent can follow stale context confidently.

3. Permissions matter

A production context engine must respect access boundaries.

Not every agent should see every Slack thread, customer doc, security detail, or private dataset.

4. Personalization matters

Two engineers may ask the same question but need different context.

A backend engineer, frontend engineer, new hire, tech lead, and reviewer should not necessarily receive the same context bundle.

5. Review cycles are the hidden cost

The output should be optimized for fewer review corrections, not just faster generation.

6. The best context system learns from real mistakes

A good context engine improves when the team discovers:

wrong files were retrieved
stale docs were used
permissions were too broad
generated code missed a convention
tests passed but contract drift appeared

That feedback should become system behavior, not tribal memory.

What is worth mentioning from the YouTube link

If I had to reduce the video into a few points worth remembering:

AI codegen is already capable enough to be dangerous.
The remaining problem is whether it writes code that fits the system.
Wrong context creates double cost.
You pay once for generation and again during review/fix cycles.
Bigger context windows are not a strategy.
They help, but they do not solve authority, relevance, conflict, permissions, or freshness.
Naive RAG is not the final answer.
Search results need reasoning and ranking, especially across code, docs, history, and decisions.
MCP/tool access is only plumbing.
Tools expose information; they do not decide what matters.
The real product is the context engine.
It is the reasoning layer between the agent and the organization.
“Mergeable by default” is the practical success metric.
Not “did it generate code?”, but “did it reduce the path to a safe merge?”

What teams usually get wrong

They treat prompts as architecture

A prompt is not enough.

If the repo does not have clear requirements, tests, conventions, and verification gates, the prompt becomes a wish list.

They treat docs as optional

For AI-assisted work, docs are not bureaucracy.

Docs are training material for the engineering system.

Bad docs create bad AI behavior.

They optimize for demo speed

Demo speed is not production speed.

Production speed includes review, verification, rollback risk, onboarding, maintenance, and future changes.

They let AI invent conventions

This is one of the fastest ways to create long-term codebase drift.

AI should follow conventions, not create a new local style every task.

They do not separate generation from verification

Generation is cheap.

Trust is expensive.

The system must make trust cheaper.

What I would build next

For my own workflow, the next practical step is to make the context engine more explicit.

Today, much of it already exists as files and scripts.

The next version should behave more like a retrieval + reasoning layer.

1. Task classifier

Given a task like GAME-142 Achievements, classify:

endpoint work
model work
attachment work
docs work
authorization work
specs work
swagger work

Then load relevant rules automatically.

2. Context bundle generator

Produce a task-specific context bundle:

Task: GAME-142 Achievements

Authoritative sources:
- doc/requirements/GAME-142_*.md
- related Flow doc
- related PRD if present

Relevant implementation:
- app/controllers/api/v1/avatars/...
- app/models/achievement.rb
- app/blueprints/...
- spec/requests/...

Rules:
- snake_case only
- Ransack + Kaminari
- Blueprinter envelope
- Pundit authorization
- nested attachments in one request
- multipart request specs

3. Drift checker expansion

Extend bin/contract_audit to catch more AI-specific drift:

new response shapes outside blueprints
missing ransackable_attributes
missing multipart specs for attachable models
missing docs section updates
inconsistent endpoint naming
unauthorized direct JSON rendering

4. Retrieval audit

Every AI-generated change should be able to answer:

what context did it use?
which sources were authoritative?
which files were intentionally ignored?
what proof command passed?
what contract did it implement?

This would make AI output much easier to trust.

Software fundamentals matter more than ever in the AI era

Another strong talk that connects directly to the “mergeable by default” idea is:

“Software Fundamentals Matter More Than Ever”

The message is extremely important because it explains why many AI-assisted codebases start degrading even when teams use powerful models.

The core point is simple:

AI amplifies the quality of the engineering system around it.

That amplification works in both directions.

Existing engineering quality	What AI does
Strong architecture + conventions	Accelerates delivery
Weak architecture + drift	Accelerates chaos

This is why AI adoption often produces very different outcomes between teams using similar tools.

One team gets:

faster delivery
cleaner onboarding
fewer repetitive tasks
safer iteration

Another team gets:

more review debt
duplicated abstractions
inconsistent APIs
growing architectural entropy

The difference is rarely the model itself.

The difference is usually:

system boundaries
naming consistency
decomposition quality
verification
contracts
maintainability discipline

AI amplifies entropy if the codebase is already chaotic

One of the strongest ideas from the second talk is:

AI makes bad codebases worse faster.

That sounds obvious, but it has major implications.

Before AI:

weak engineering practices slowed teams down
messy systems evolved more slowly
architectural damage accumulated gradually

Now:

AI can generate large amounts of plausible code very quickly
bad patterns replicate faster
local shortcuts spread across the repo
inconsistent abstractions become normalized

The dangerous part is that the output often looks reasonable.

That creates a false sense of progress.

A weak engineering system with AI can produce:

more code
more PRs
more surface area

while simultaneously reducing long-term maintainability.

This is why software fundamentals suddenly matter more, not less.

Why Rails works unusually well with AI

This also explains why Rails often performs surprisingly well in AI-assisted development compared to fragmented stacks.

Rails strongly reduces ambiguity through conventions:

Concern	Rails convention
Models	`app/models/**`
Controllers	`app/controllers/**`
Request specs	`spec/requests/**`
Background jobs	`app/jobs/**`
Serialization	predictable serializer/blueprint layer
Naming	convention over configuration
Routing	consistent REST structure

LLMs benefit heavily from predictability.

The less time the model spends asking:

“How is this project organized?”

the more time it spends solving the actual task.

This is one reason why convention-heavy systems become powerful AI multipliers.

Decomposition becomes critical

Another important point from the second talk:

LLMs perform much better on small, deterministic tasks than vague, giant problems.

That has major implications for engineering workflows.

Good AI-assisted systems should encourage:

bounded contexts
small implementation scopes
explicit requirements
narrow responsibilities
isolated verification loops

This maps directly to:

feature decomposition
Flow docs
PRDs
contract-first APIs
verification-driven development

Without decomposition, AI receives:

too much ambiguity
too many unrelated files
unclear authority
mixed responsibilities

That increases hallucination and drift.

With decomposition:

retrieval becomes cleaner
verification becomes cheaper
generated code becomes more deterministic
review becomes faster

This is another reason why a context engine matters: it reduces entropy before generation even starts.

Verification matters more than generation

One of the biggest misconceptions in AI engineering is:

faster generation = better engineering

In reality:

verification quality matters more than generation speed.

AI is extremely good at producing:

plausible code
plausible architecture
plausible explanations

But plausible is not the same as correct.

That is why systems like:

bin/verify
contract audits
OpenAPI contracts
request specs
drift prevention
architectural rules

become increasingly important in the AI era.

The stronger the generation becomes, the more important proof becomes.

Or more simply:

verification > generation

Senior engineers become more important, not less

The second talk also indirectly explains why strong senior engineers become more valuable in AI-assisted environments.

Junior engineers with AI can generate large amounts of code quickly.

But senior engineers contribute something different:

architectural judgment
decomposition
boundary design
tradeoff analysis
drift detection
maintainability intuition
verification discipline

AI accelerates implementation.

Senior engineers define:

what should exist
what should not exist
what should remain stable
what correctness means

This is why the real leverage comes from:

externalized engineering judgment
codified conventions
reusable verification systems
structured context

Not from prompt tricks.

The combined lesson from both talks

The two talks together point toward the same conclusion.

The future of AI-assisted engineering is not:

bigger prompts
more vibe coding
infinite context dumping
raw generation speed

The future is:

explicit context systems
deterministic workflows
engineering conventions
retrieval quality
decomposition
verification
drift prevention
mergeability

The model matters.

But the surrounding engineering operating system matters even more.

Context retrieval is not enough without meaning

One of the most important missing ideas in many AI engineering discussions is this:

retrieval alone does not explain system meaning.

A vector database can retrieve:

files
specs
migrations
tickets
controllers
docs

But retrieval alone does not explain:

business semantics
conceptual relationships
authority hierarchy
intent boundaries
domain meaning
organizational language

This is where conceptual modeling becomes critical for AI systems.

A useful phrase from recent discussions is:

“Conceptual modeling is the context engineering nobody is doing.”

That idea changes how we should think about AI-assisted engineering.

Storage is not the same as meaning

Database schemas primarily describe storage.

Conceptual models describe meaning.

For example, a database may contain:

players
guilds
scouts
guild_pacts

But the semantic/business layer explains things like:

scout players must belong to verified non-mercenary guilds
contracts only apply to certain organization types
some users are prospects while others are active customers
access states affect workflow permissions
ownership and approval rules differ across flows

The AI model often cannot infer those rules reliably from tables alone.

Without semantic structure:

retrieval returns conflicting interpretations
agents make incorrect assumptions
local correctness breaks global meaning
teams accumulate semantic drift

Semantic drift is becoming a new category of engineering failure

One especially important idea is:

code can technically work while system meaning is already broken.

This is semantic drift.

Examples:

endpoint contracts technically pass, but business terminology changed
authorization still works, but ownership semantics changed
response structures remain valid, but workflow meaning shifted
entities serialize correctly, but relationships no longer reflect reality

Traditional verification usually catches:

syntax problems
test failures
runtime errors

But semantic drift is harder.

The system still compiles. The tests may still pass.

Yet the business meaning has already degraded.

AI systems make this problem more important because they replicate patterns rapidly.

Metadata suddenly became AI infrastructure

A surprising shift happening across the industry is that many metadata concepts are suddenly becoming foundational AI infrastructure.

Things like:

glossaries
ontologies
semantic layers
ownership metadata
conceptual models
lineage systems
business vocabularies

are turning into:

navigation systems for AI reasoning.

This is one reason why many data and metadata teams are suddenly becoming highly relevant to AI engineering workflows.

The next stage of context engines

The first generation of AI engineering systems focused mostly on:

code retrieval
embeddings
vector search
file access
larger context windows

The next stage is likely semantic-aware systems.

Instead of only asking:

“Which files are relevant?”

the system will increasingly ask:

“What does this system actually mean?”

A semantic-aware context system can explain:

why a concept exists
how concepts relate
which definitions are authoritative
which workflows matter
which constraints are organizational vs technical
what should remain stable across implementations

That is a much deeper level of context than code search alone.

How this maps to my current workflow

Looking at my own Rails/API workflow, I already externalized a large amount of engineering judgment through:

AGENTS.md
Flow docs
PRDs
requirements
verification systems
contract audits

But conceptual modeling adds another important layer:

Existing layer	Role
Requirements	behavioral intent
Flow docs	implementation semantics
AGENTS.md	engineering rules
Verification	correctness proof
Conceptual modeling	business meaning

This changes the shape of the system.

It stops being only:

an engineering operating system

and starts becoming:

a semantic operating system for AI-assisted engineering.

The final takeaway

The future of AI coding is not just smarter code generation.

It is better engineering context.

The best teams will not only ask:

Which model should we use?

They will ask:

What system makes the model correct inside our codebase?

That system will include:

requirements
conventions
code search
decision history
permission control
task-specific retrieval
verification
drift prevention
review feedback loops

That is the real lesson from “Mergeable by default.”

AI does not become valuable because it writes more code.

AI becomes valuable when the surrounding engineering system makes its output safe enough, relevant enough, and consistent enough to merge.

For me, that means the next stage of AI-assisted Rails development is clear:

turn the existing verification-driven workflow into an explicit context engine.

Not more prompt magic.
Not bigger context for the sake of bigger context.
Not vibe-coded PRs.

A system that gives the agent the right context, blocks the wrong drift, proves the result, and makes the final state boring:

all good — merge PR.

References

Why Test Refactoring Matters: Turning 12-Minute Builds Into a 39-Second Proof Loop

Thu, 30 Apr 2026 00:00:00 +0000

“Slow tests do not only slow CI. They change how often you are willing to prove that the system still works.”

TL;DR

Metric	Before	Current	Change
Old build/proof loop used for planning math	~12 min	39.42s local fast verification	~18.3x faster
Initial broad profiled RSpec runtime	4m 8.6s	2m 43.1s split profiled runtime	~34% faster
SQL events	571,641	413,055	-158,586 / ~28% fewer
Factory calls	36,133	31,935	-4,198 / ~12% fewer
Fast verification proof	n/a	8,659 examples / 0 failures / 28 pending	green
Parallel RSpec phase	n/a	32.35s	green
Full `bin/verify` local loop	n/a	39.42s	green
Processed executable test files	n/a	~72 / 714	~10.1%
Current heavy-tail status	n/a	39 tests still use broad local reference context	next target

The important part is not that 10% of files were touched.

The important part is that the right 10% was touched first.

That 10.1% of executable test files produced:

~34% less profiled runtime
~28% fewer SQL events
a fast local proof loop around 39 seconds
no API behavior changes
no removed assertions
no reduction in request/integration confidence

If you are shipping around 10 PRs per day, and each PR gets about 3 commits, that is roughly:

10 PR/day * 3 commits = 30 proof loops/day

With a 12-minute build:

30 * 12 min = 360 min/day = 6 hours/day waiting on proof

With the current 39.42-second local proof loop:

30 * 39.42s = 1,182.6s = 19.7 min/day

So the saved time is:

360 min - 19.7 min = 340.3 min/day

That is 5 hours 40 minutes per day back.

Or, if you reinvest only the saved waiting time into additional current-speed proof loops:

340.3 min / 0.657 min = ~518 extra proof loops/day

That does not mean you should make 518 more commits per day.

It means the old loop made verification expensive enough that you would naturally batch risk. The new loop makes verification cheap enough that you can commit smaller, check more often, and keep moving without gambling.

The cost of not refactoring

The easiest way to undervalue test performance is to look at one build.

One 12-minute build is annoying.

Thirty 12-minute proof loops per day is a workflow tax.

Cadence	Old 12-minute loop	Current 39.42-second loop	Time recovered
1 proof loop	12 min	39.42 sec	11m 20s
30 proof loops/day	6h/day	19.7m/day	5h 40m/day
150 proof loops/week	30h/week	1h 38m/week	28h 22m/week
600 proof loops/month	120h/month	6h 34m/month	113h 26m/month

This is why slow tests are not only a developer-experience issue.

They change engineering behavior:

you commit less often
you batch more risk
you delay verification
you wait longer to discover drift
you become tempted to skip checks

Fast tests do not guarantee quality.

But slow tests make quality expensive enough that people naturally start negotiating with it.

The honest caveat

There are two “current time” numbers worth separating:

Current number	What it means
39.42s	Local `bin/verify` fast loop: RuboCop, parallel RSpec, RSwag generation. This is the day-to-day proof loop.
2m 43.1s	Instrumented TestProf split profile. This pays profiling overhead and is used for diagnosis, not every commit.

The old ~12 min number is the build-time pain point. The new 39.42s is the observed local fast verification loop after parallelization and test cleanup. CI still has container, bundle, database, and service overhead, so I do not treat local time as a perfect CI replacement.

But the engineering lesson is still valid:

The closer the proof loop gets to seconds instead of minutes, the more often you can afford to prove correctness.

Why this refactor happened

The trigger was simple: CI started hitting build-time limits.

The request/integration step was the visible pain:

bundle exec rspec spec/integration spec/requests --tag ~full_only --fail-fast --format progress

At first, the temptation is obvious:

increase CI timeout
split one huge file
skip slow tests
move on

We did increase the Bitbucket max-time guard to 12 minutes, but that was not the fix. That was only a safety margin.

The actual fix was to profile the suite and stop guessing.

The first broad profile showed the shape of the problem:

Run	Examples	Runtime	SQL events	SQL time	Factories
Initial broad `spec/` profile	8,659	4m 8.6s	571,641	1m 57.4s	36,133

Almost half the profiled runtime was SQL.

That matters because SQL-heavy tests are rarely fixed by staring at one assertion. The cost usually lives in setup:

create(:user) cascades
avatar auto-creation
guild/reference catalogs
callbacks
chat/message graphs
access-request state machines
serializer renders that pull large association trees

So the question changed from:

Which test is slow?

to:

Which setup is repeated, realistic, and unnecessary for the behavior under test?

That is a better question.

The operating rule: faster, not weaker

The rule for the session was strict:

Optimize tests without losing confidence.

That meant no cheap wins like deleting assertions or converting request tests into shallow unit tests just to make the graph look better.

The safety rules were:

Rule	How it was applied
Keep request/integration confidence	Request tests still hit real endpoints, auth, serializers, callbacks, and DB writes.
Keep mutation behavior real	Command, callback, uniqueness, destroy, chat/message, access-request, and quest-state examples keep persisted rows.
Use `build_stubbed` only for read-only checks	Policy predicates, logger metadata, and serializer-only cases can be stubbed when the DB is not the behavior.
Use `let_it_be` only for stable records	Shared users, guilds, quests, and avatars are read-only parents; rows mutated by examples stay local.
Decouple app tests from seed runtime	App tests use explicit factory-backed local reference data, not `lib/tasks/seeds/**`.
Do not remove assertions for speed	The target is setup shape, not coverage reduction.

This distinction matters.

Bad test optimization asks:

How do we make the suite green faster?

Good test optimization asks:

Which expensive work is unrelated to the behavior this example proves?

What we did not do

This part matters because “test optimization” often sounds like a polite way to say “less coverage.”

That was not the deal.

Shortcut	Why we did not take it
Delete slow tests	Deleted tests make dashboards faster and confidence lower. That is not optimization.
Mock request/integration behavior	Request tests are expensive because they prove routing, auth, controller envelopes, policies, serializers, callbacks, and DB behavior together.
Replace mutation tests with read-only doubles	Commands, callbacks, uniqueness, destroy behavior, chat/messages, access requests, credits, and quest state need persisted rows.
Hide seed problems by deleting seed tests	Seed runtime tests remain in the repo. They are skipped in the default suite and can be run when seed work is active.
Change API code to satisfy faster tests	This was test-only work. API behavior, JSON shape, authorization, and persistence rules stayed unchanged.
Split huge files just to make charts look better	Splitting can help ownership, but it does not remove SQL or factory cost by itself. Setup shape was the real target.

The strongest signal from the session was this:

We got faster by removing unrelated setup, not by reducing the behavioral contract.

What changed

1. Added profiling as a real workflow

We made TestProf the profiling path and used:

env FPROF=1 EVENT_PROF=sql.active_record EVENT_PROF_EXAMPLES=1 EVENT_PROF_TOP=40 \
  bundle exec rspec spec/integration spec/requests --tag '~full_only' --format progress

and:

env FPROF=1 EVENT_PROF=sql.active_record EVENT_PROF_EXAMPLES=1 EVENT_PROF_TOP=40 \
  bundle exec rspec spec/bin spec/blueprints spec/channels spec/config spec/controllers spec/db \
  spec/forms spec/initializers spec/workers spec/lib spec/mailers spec/middleware spec/models \
  spec/policies spec/queries spec/routing spec/services spec/smoke spec/tasks spec/validators \
  --tag '~full_only' --format progress

That gave two useful views:

EventProf showed SQL cost by file and example
FactoryProf showed factory cascades and top-level setup cost

Once the suite had numbers, the refactor stopped being emotional.

2. Split CI by work type

The Bitbucket flow now separates:

lint/security
unit/model/blueprint/policy/service/worker/query/form/lib tests
request/integration tests
Swagger generation
full_only tests

Request/integration and non-request tests can run in parallel workers.

The result is not just shorter wall time. It also makes slow areas easier to reason about. A slow request test and a slow model test are usually slow for different reasons.

3. Removed seed runtime from app tests

This was a key cleanup.

The app tests used to lean on seeded reference data. That made them realistic, but it also tied normal verification to seed runtime behavior and large catalogs.

We replaced that with explicit factory-backed local reference data:

guild types
guild domains
guild sizes
avatar taxonomy
quest board categories
realms
message channels
training tiers
guild permit validation rules

Seed tests still exist. They are not deleted. They are skipped in the default suite and can be run locally when working on seeds.

This made the boundary cleaner:

Area	Responsibility
App tests	Verify app behavior with explicit local reference rows.
Seed tests	Verify seed runtime when seed work is being changed.

4. Started splitting broad local reference data

After moving away from seed runtime, a new cost appeared: the replacement local reference context was intentionally broad.

That was the right first move for reliability, but it became the next optimization target.

The broad context created:

guild options
avatar taxonomy
realms
message channels
training tiers
avatar link labels
guild permit validation rows

Some tests only needed one slice.

So the first split introduced narrower contexts:

with local guild reference data
with local guild types
with local guild domains
with local guild sizes
with local guild permit validation rules
with local training tiers
with local message channels

Then seven tests moved off the broad context:

spec/services/guilds/guild_permit_validator_spec.rb
spec/models/guild_permit_validation_setting_spec.rb
spec/models/guild_size_spec.rb
spec/models/guild_type_spec.rb
spec/models/guild_domain_spec.rb
spec/requests/api/v1/message_channels_spec.rb
spec/requests/api/v1/public/vocabulary/training_tiers_spec.rb

Focused result:

Batch	Examples	Runtime	SQL events	Factories	Result
Narrow reference-context batch	106	0.92s	1,558	160	0 failures

5. Optimized the heaviest files first

This is where the 10% number becomes important.

We did not process 10% of files randomly.

We processed roughly 72 of 714 executable test files, or ~10.1%, sorted by profiling impact.

That included:

request workflow tests
policy tests
blueprint tests
model tests
service tests
seed/reference support boundaries

Examples of file-level wins:

Test file	Before	After	Main change
`spec/policies/quest_assignment_policy_spec.rb`	~1,320 SQL	74 SQL	Role/guild policy matrix moved to `build_stubbed`; scope records stayed persisted.
`spec/policies/avatar_policy_spec.rb`	~1,358 SQL	83 SQL	Policy predicates moved to stubbed users/avatars; scope stayed persisted.
`spec/blueprints/messages/location_setting_blueprint_spec.rb`	~1,207 SQL	10 SQL	Serializer-only behavior stopped creating a full persisted avatar graph.
`spec/blueprints/avatar_note_blueprint_spec.rb`	~742 SQL	0 SQL	Plain object replaced DB-backed setup for serializer-only behavior.
`spec/services/visibility/visibility_flags_spec.rb`	~1,702 SQL	219 SQL	Read examples use stubbed/assigned avatar; update behavior stayed persisted.
`spec/models/guild_size_spec.rb`	1,545 SQL	153 SQL	Narrow guild-size reference context.
`spec/models/guild_type_spec.rb`	1,560 SQL	256 SQL	Narrow guild-type reference context.
`spec/models/guild_domain_spec.rb`	1,628 SQL	687 SQL	Guild type + domain rows only.
`spec/requests/api/v1/users/avatars/request_access_spec.rb`	5,659 SQL	1,847 SQL	Stable actors shared; access, credits, chats, and quests stayed real.

This is why profiler order matters.

If the current 10.1% of files produced a 34% runtime reduction, the naive math says:

34% / 10.1% = 3.37x impact per file-percent

If that scaled linearly to 100%, it would imply:

3.37 * 100% = 337% runtime reduction

That is impossible.

And that impossibility is the point.

The first 10% was not normal. It was the expensive slice. Profiling let us find the part of the suite where small, careful changes had disproportionate return.

The realistic lesson is:

Do not optimize all tests equally. Optimize the tests that are paying rent in every build.

The time math at shipping cadence

Assume this daily cadence:

PRs/day
commits/PR
proof loops/day

Old loop: 12 minutes

30 * 12 min = 360 min/day

That is:

6 hours/day
30 hours/week
120 hours/month

That is not a test suite.

That is a part-time job waiting for CI.

Current fast loop: 39.42 seconds

39.42s = 0.657 min
30 * 0.657 min = 19.7 min/day

That is:

19.7 minutes/day
1 hour 38 minutes/week
6 hours 34 minutes/month

Time recovered

360 min/day - 19.7 min/day = 340.3 min/day

That is:

5 hours 40 minutes/day
28 hours 22 minutes/week
113 hours/month

If you spend that recovered time only on additional current-speed proof loops:

340.3 min/day / 0.657 min = ~518 extra proof loops/day

Again, this is not a recommendation to make hundreds of commits.

It is a way to feel the magnitude.

A slow build taxes every commit. A fast proof loop makes small commits cheap.

Conservative profiler-time version

If we use the slower instrumented profile number instead:

2m 43.1s = 2.718 min
30 * 2.718 min = 81.5 min/day
360 - 81.5 = 278.5 min/day saved

Even with the conservative number, the suite gives back:

4 hours 38 minutes/day
23 hours 12 minutes/week

That is still huge.

Why this matters more with AI-assisted development

With AI, generating a patch is no longer the bottleneck.

The bottleneck becomes:

proving the patch
reviewing the patch
finding subtle drift
avoiding slow feedback loops
keeping confidence high while throughput rises

If you can create 10 PRs a day, but each proof loop costs 12 minutes, the system pushes you toward bad habits:

bigger commits
fewer local checks
more batching
delayed feedback
risk discovered late
more review anxiety

That is how technical debt quietly taxes AI productivity.

AI can generate code quickly, but CI decides how quickly you can trust it.

This is why test refactoring belongs in the same conversation as AI productivity. It is not janitorial work. It is throughput infrastructure.

What stayed reliable

The most important result is not speed. It is speed without weakening the test suite.

The current proof still runs:

Check	Current result
RuboCop	clean
Parallel RSpec	8,659 examples, 0 failures, 28 pending
RSwag Swaggerize	generated successfully
Contract audit	6/6 checks passed

And the behavioral boundaries stayed intact:

request tests still exercise real routes
authentication is still real
serializers are still rendered
DB-backed mutation behavior stays DB-backed
authorization scopes remain persisted where scope behavior is under test
seed tests remain in the repository
app tests no longer accidentally depend on seed runtime

This is the difference between optimization and coverage erosion.

What is still left

This is not done.

The remaining heaviest chunk is still visible:

continue splitting broad with local reference data
spec/requests/llm_gateway/sessions_spec.rb
spec/requests/api/v1/avatars/avatar_cards_spec.rb
spec/requests/api/v1/guilds/avatar/public_quests_spec.rb
spec/requests/api/v1/guilds/team_management_spec.rb
spec/requests/api/v1/users/conversation_messages_spec.rb
broad spec/requests/api/v1/avatars_spec.rb

There are still 39 tests using the broad local reference context.

There are still request tests with 4,000-6,700 SQL events each.

There are still workflow tests where the cost is real and should not be mocked away.

That is fine.

The goal is not to make every test microscopic.

The goal is to make expensive tests expensive for a reason.

How to start tomorrow

If I had to start this again in another Rails API, I would not begin by editing tests.

I would begin with a short checklist:

Step	Command or action	Why
1	Install or enable TestProf	You need numbers before opinions.
2	Run `FPROF=1 EVENT_PROF=sql.active_record` on the slowest suite	This finds SQL and factory pressure.
3	Sort files by SQL events and factory count	Optimize cost, not file count.
4	Pick one file	Small batches keep reliability easy to verify.
5	Identify examples above ~250 SQL events	Those examples usually have setup duplication.
6	Move stable read-only setup to `let_it_be`	Avoid rebuilding the same parent graph.
7	Use `build_stubbed` only for pure read/predicate checks	Do not fake DB behavior that is under test.
8	Keep mutation rows per-example	State transitions must stay isolated.
9	Rerun the focused file	Prove the local change first.
10	Rerun full verification	Make sure the suite still tells the truth.

The first useful command is usually:

env FPROF=1 EVENT_PROF=sql.active_record EVENT_PROF_EXAMPLES=1 EVENT_PROF_TOP=40 \
  bundle exec rspec spec/path/to/heavy_spec.rb --format progress

The first useful question is:

What did this example create that it never actually used?

That question is where most safe wins start.

The practical playbook

This is the pattern I would reuse:

1. Measure before changing

Use SQL and factory profiling:

env FPROF=1 EVENT_PROF=sql.active_record EVENT_PROF_EXAMPLES=1 EVENT_PROF_TOP=40 \
  bundle exec rspec spec/path/to/heavy_spec.rb --format progress

Do not guess.

2. Sort by cost, not file count

The current 10.1% progress produced a 34% runtime reduction because the files were chosen by cost.

Randomly refactoring 10% of files would not do that.

3. Separate read behavior from mutation behavior

Use:

build_stubbed for pure read/predicate checks
let_it_be for stable read-only parents
persisted per-example rows for mutations, callbacks, uniqueness, scopes, and state transitions

4. Split broad fixtures into narrow catalogs

This is especially important for reference data.

If a test only needs training tiers, do not load guild domains, realms, quest categories, skill trees, and guild permit rules.

5. Keep request tests honest

Do not replace request tests with unit tests just because request tests are slower.

Request tests buy confidence across:

routing
auth
controller envelope
policy
serializer
DB state
callbacks

Only move assertions down to blueprint/model/service tests when the request test is only duplicating shape checks already covered elsewhere.

6. Make verification cheap enough to run constantly

The goal is not only faster CI.

The goal is a proof loop cheap enough that you naturally run it before you are nervous.

Closing

Test refactoring is easy to postpone because it rarely ships a visible feature.

But at high throughput, slow verification is not a background inconvenience. It is a tax on every commit.

At 10 PRs/day and 3 commits/PR, a 12-minute build turns into 6 hours/day of waiting.

At the current 39.42-second proof loop, that same cadence costs about 20 minutes/day.

That is the difference between:

batching risk because proof is expensive
proving continuously because proof is cheap

This is why the refactor mattered.

Not because the suite became pretty.

Because the suite became usable at the speed the work was happening.

How I Turned AI Into a 5x Backend Force Multiplier as One Principal Engineer

Tue, 07 Apr 2026 00:00:00 +0000

“The biggest AI productivity gain I’ve seen wasn’t faster code generation. It was turning senior judgment into a system that makes drift expensive and correctness cheap.”

TL;DR

Metric	Value
Solo backend output	400+ PRs
Wider comparison group	11 engineers / 1,000+ PRs
Visible PR share	40%+
Visible PR multiple vs average engineer	4.4x+
True working multiplier	5x
Local proof loop	~39s
Median first commit → green CI	10 min
Proof signal	7,445 tests / 0 failures / 6/6 audit checks
PRs merged without post-merge hotfixes	95%
New engineer: useful work started	15 min
New engineer: first PRs	same day
11-month role-equivalent savings	$115.5k-$132k
11-month tooling savings	$41.8k+
11-month combined estimated savings	$157.3k-$173.8k

The visible number is 4.4x+. That is the conservative, countable PR multiple: 400+ PRs from me alone versus an average of 90.9 PRs per engineer in an 11-person comparison group that shipped 1,000+ PRs.

The real operating number is 5x. That is the number I use once I include what PR counts do not show well: CD and pipeline work, DevOps support, API ownership, security, migrations, seeds, review load, management tasks, QA automation, verification, documentation, onboarding compression, and release confidence.

This post is the production result of the ideas I described earlier in:

Those posts explained the pieces. This one is about what happened when I ran those ideas every day, against real work, for months.

1. The honest math behind 4.4x+ and 5x

Here is the clean visible comparison:

Metric	Value
Wider comparison group	11 engineers
Team mix	5 frontend, 3 AI, 2 mobile, 1 DevOps
Wider visible PR output	1,000+ PRs
My solo backend output	400+ PRs
My share of that visible volume	40%+
Average PRs per engineer in that group	90.9
My PR volume vs that average	4.4x+

That 4.4x+ is the conservative, visible number.

It is conservative for two reasons:

the source numbers are 400+ and 1,000+, so the real totals are higher than the rounded comparison
PR count does not include a lot of the work I was carrying daily

Using the documented 11-month floor as a reference point, that solo output works out to roughly:

Cadence view	Value
Reference PR cadence	~36.4 PRs/month
Reference PR cadence	~8.4 PRs/week

That is already a strong result. But it is still not the whole result.

The reason I call the broader system a 5x force multiplier is that my daily work was bigger than the visible PR math:

Bitbucket and GitHub pipelines for CD
DevOps-side support
API design and implementation
security and authorization
migrations and seed maintenance
testing and verification
feature architecture
review work
management and coordination tasks
onboarding acceleration
documentation and contract alignment

So the useful question is not:

How did one engineer write this many PRs?

It is:

How did one engineer remove this much uncertainty from shipping?

That is where AI became multiplicative for me. Not when it wrote code faster, but when it operated inside a system that already knew what “correct” meant.

2. The work hidden under the PR count

Backend impact is easy to undervalue because the visible product surface is usually UI. The invisible surfaces are where concentration becomes easy to miss.

The repo scan changes that.

Surface	Value
Total tracked lines	612,468
Total tracked files	2,878
Named routes	656
`/api/v1` routes	559
Controllers	162
Blueprints	203
Models	107
Services	97
Policies	28
Migrations	100
Seed files	48
Requirement docs	108
Flow docs	110
PRDs	86

That means I was not just moving tickets. I was operating a backend with:

1,373 implementation surfaces before counting policies or docs
(routes + controllers + blueprints + models + services + migrations + seeds)
1,705 total structured surfaces once policies and requirement / Flow / PRD docs are included

There were also focused platform modules under the same umbrella:

Module	Files	Lines
`SERVICE_1`	91	21,927
`SERVICE_2`	88	106,788
`SERVICE_3`	96	62,227

And there was a non-trivial runtime protection layer too:

Protection surface	Count
Pundit policies	28
Rack::Attack throttle rules	14
Rack::Attack blocklists	2
Total runtime protection surfaces	44

This is why I do not describe the result as “AI helped me code faster.”

The real story is that I carried a large backend platform and built the operating system that made that platform safer to change.

3. The leverage came from proof, not just generation

One metric in the repo explains almost everything about why this system worked.

Surface	Lines	Ratio vs `app/**`
`app/**`	56,215	1.00x
`spec/**`	125,772	2.24x
`doc/**`	117,953	2.10x
`spec/ + doc/`	243,725	4.34x

That means the proof surface and transfer surface around the application are 4.34x larger than the app code itself.

This is the part many AI productivity discussions miss.

The biggest gain did not come from generating code faster.
It came from reducing:

ambiguity
rework
onboarding drag
review noise
contract drift
post-merge risk

That is also why the onboarding story is so strong: the surrounding system explains the codebase before a new engineer has to guess its rules.

4. I stopped using AI as autocomplete

A lot of AI productivity conversations are shallow because they treat the model as the product.

That is backwards.

AI is not the product.
The operating model is the product.

I like to describe my stack like this:

AGENTS.md is the senior software engineer I can run on every task
bin/verify is the QA automation engineer I can run in one command
bin/contract_audit is the drift detector that goes beyond compiler-green

That framing matters because I did not just ask AI to write code.

I asked AI to work inside:

a contract system
a planning workflow
a verification gate
a drift-prevention layer
a documentation discipline
a release model

That is a different level of leverage.

A principal engineer with AI but no operating system gets faster drafts.

A principal engineer with AI and an operating system gets safer throughput, shorter ramp time, lower variance, and reusable decision quality.

That is what happened here.

It is also why I think the “AI replaced the engineer” framing is wrong.

The real upgrade is this:

16 years of experience turned into a system that can be run daily.

5. `AGENTS.md`: turning principal judgment into a reusable senior engineer

The current AGENTS.md is not a prompt blob. It is a delivery runtime.

One of the most telling details is that the tools kept evolving instead of freezing into documents nobody touches:

Tool	March snapshot	Current attached source	Signal
`AGENTS.md`	987 lines	1,143 lines	the operating contract kept absorbing real-world lessons
`bin/verify`	370 lines	370 lines	the daily verification core stabilized early
`bin/contract_audit`	452 lines	540 lines	drift prevention kept getting sharper

That is the opposite of a random prompt file.
It is a maintained operating system.

What makes AGENTS.md powerful is not length. It is what the file externalizes.

It defines authority before coding starts

It makes the source of truth explicit:

process and workflow live in AGENTS.md
feature behavior lives in doc/requirements/**
Flow and PRD docs are derived artifacts
requirements stay read-only during implementation
docs update only after verification is green

That removes a huge amount of ambiguity for both humans and AI.

It forces planning before implementation

It creates hard no-code phases:

extract the contract
scan the repo
build a file-by-file plan
map requirements to specs
stop for confirmation
only then implement

That is senior-engineer behavior made explicit.

It turns “done” into something executable

It does not stop at “follow best practices.” It defines:

canonical success and error envelopes
representational invariants
safe defaults for required fields
verification order
compliance audit rules
documentation timing
final-output structure
a never-list of things that must not ship

That is why I say I wrote my own senior software engineer.

Not because it sounds cool.
Because it converts tacit judgment into repeatable constraints.

It also solves prompt drift

A subtle but important design choice is the split between:

[NORMATIVE] sections: actual rules
[ILLUSTRATIVE] sections: examples and patterns

That stops examples from silently becoming law, which is one of the most common ways AI drifts while pretending it is compliant.

6. `bin/verify`: the QA automation engineer I wanted next to me

A lot of teams say they care about quality, but their verification path is too slow, too manual, or too annoying to run constantly.

That means the real workflow becomes: “verify when nervous.”

That is not a system.
That is mood-based engineering.

bin/verify is the opposite.

At a glance, its structure looks simple:

CHECK_PROFILES = {
  fast: %i[rubocop rspec swagger].freeze,
  full: %i[rubocop rspec brakeman audit swagger seeds].freeze
}.freeze

But the important part is not that there are two characters.

It is that the script is diff-aware, parallelized, and cheap enough to run continuously.

What the fast character really does

The default path is intentionally practical:

RuboCop
RSpec
Swagger generation only when API-relevant surfaces changed

That last point matters a lot.

The script checks changed files and auto-skips swagger if controllers, blueprints, routes, or API specs were untouched. Routine work stays fast.

What the full character adds

For heavier changes, --full adds:

Brakeman
bundle audit
db seed replant

This split is one of the reasons the system works in real life.

A daily loop must be cheap enough to become muscle memory.
A full compliance loop must exist when the change deserves it.

It is optimized like build infrastructure, not like a shell alias

There are several details in the actual source that matter:

8-worker parallel RSpec by default
fast mode excludes specs tagged :full_only
schema fingerprinting avoids unnecessary parallel:prepare
lock files and stamp files prevent redundant work
ergonomics like --only, --fail-fast, --workers, --sequential, and --list

That is not “nice tooling.”
That is what makes the tool runnable every day.

Why that mattered to output

The proof loop now has two speeds that matter to me:

Signal	Value
Local proof loop (`bin/verify`)	~39s
Median first commit → green CI	10 min
Test examples	7,445
Failures	0
Contract audit	6/6 checks passed
PRs merged without post-merge hotfixes	95%

That is the kind of feedback character that preserves flow.

It is fast enough to run locally.
It is fast enough to keep CI useful.
And it is reliable enough that most merged PRs do not need cleanup after the fact.

That is why I say bin/verify is the QA automation engineer I built for myself.

7. `bin/contract_audit`: going beyond compiler-green

This tool reflects how I think about engineering more than almost anything else in the stack.

Compilers tell you whether syntax is valid.
Tests tell you whether known behavior still passes.
Neither one guarantees that the implementation still matches:

the requirement
the docs
the route law
the serializer discipline
the portability constraints
the team’s rules for how APIs are allowed to evolve

That is why I built bin/contract_audit.

Its top-level checks are explicit:

CHECKS = {
  requirements_read_only: "Requirements docs remain untouched (doc/requirements/**)",
  swagger_generated_source: "Swagger YAML not edited alone (must be driven by rswag specs)",
  db_specific_sql: "No DB-specific SQL tokens introduced",
  route_style: "Route literals avoid kebab-case and trailing slashes",
  controller_manual_json: "No new ad-hoc render json hash payloads in controllers",
  docs_templates: "Changed Flow/PRD docs follow required section templates"
}.freeze

That list says a lot about the philosophy behind it.

This is not a generic lint script.
It is a drift-prevention script.

The most important design choice: it is legacy-safe

By default, bin/contract_audit does not try to police the whole repository every time.

Its default mode audits:

changed files
added lines
untracked files

And only --all audits the full repository.

That is a very practical design.

It means you can introduce strictness into a real codebase without freezing delivery until every historical inconsistency is cleaned up.

That is one of the biggest lessons in this system:

The best guardrail is not the strictest one.
It is the strict one people can actually adopt.

It audits the mistakes that usually slip through

The script blocks the kinds of drift that create long-term chaos:

requirements doc edits during normal implementation
hand-edited swagger without spec changes
DB-specific SQL shortcuts
kebab-case or trailing-slash route drift
ad-hoc controller JSON outside the envelope helpers
malformed Flow and PRD doc structure

That is what I mean by drift-free.

Not just “does it run?”
Also “does it still mean what we think it means?”

If I had to describe the stack in compiler terms, it would be this:

doc/requirements/** is the source program for intent
AGENTS.md is the language law
bin/verify is the fast proof loop
bin/contract_audit is the semantic checker that blocks drift

That is why a 6/6 audit pass matters so much more than a green line by itself.

8. Why onboarding collapsed from weeks to minutes

One of the strongest signals in this story had nothing to do with my own output.

The first engineer who followed this system:

started working on the two highest-priority tasks and bugs after 15 minutes
created the first PRs the same day

That result matters to me more than a vanity metric because it proves the system works outside my own head.

It also explains why frontend engineers started wanting to pick up tasks inside the same flow.

Why did onboarding collapse like that?

Because the repo answers the questions that usually stay trapped in tribal knowledge:

what is the source of truth?
where does behavior live?
what must not drift?
what command proves the change is safe?
what docs must reflect the change?
what does “done” mean here?

That is what makes onboarding fast.

People often think onboarding is about reading architecture docs.

It is not.

Onboarding is about removing ambiguity from the first real task.

This system does that because:

requirements define behavior
AGENTS.md defines execution
bin/verify defines proof
bin/contract_audit defines drift boundaries
Flow docs define implementation traceability
PRDs define product context

The result is not just faster ramp.
It is faster trust.

And trust is what lets new engineers ship instead of shadowing.

For comparison, in a large company environment like Apple, getting to this level of useful contribution could take 2-3 weeks, and sometimes 4 weeks with training. Here, the first useful work started in 15 minutes and the first PRs landed the same day.

That is not a small improvement.
That is a different operating model.

9. Why this is language-agnostic

Yes, the current implementation is Rails-heavy.

It uses:

Blueprinter
Pundit
Ransack
Kaminari
RSpec
RuboCop
Brakeman
rswag

But the underlying model is not Ruby-specific at all.

The reusable pattern is this:

requirements are explicit
implementation follows contract
verification is one command
drift is checked separately from tests
docs are derived from verified behavior
onboarding happens against the system, not folklore

That ports cleanly.

TypeScript / Node

requirements: TypeScript interfaces, Zod, OpenAPI
verify: ESLint, Jest or Vitest, OpenAPI generation, security checks
audit: route naming, response-shape discipline, docs templates, SQL portability

Python

requirements: Pydantic models, OpenAPI, JSON Schema
verify: Ruff, pytest, mypy, security checks
audit: serializer boundaries, route shape, docs structure, query portability

Go

requirements: structs, OpenAPI, protobuf or JSON schema
verify: go test, lint, vuln checks, generated spec validation
audit: handler response discipline, route law, portability, docs templates

The language-specific pieces are adapters.

The real product is the operating model.

10. The business math is stronger than the PR math

Raw PR throughput already makes the case:

average engineer in the 11-person comparison group: 90.9 PRs
my visible solo output: 400+ PRs
visible ratio: 4.4x+

But the business story gets stronger when you include the role-equivalent system I built.

I effectively replaced two roles in my daily loop

The way I use the system, it acts like I wrote:

a senior backend engineer assistant
a QA automation engineer assistant

Using the salary assumptions I gave for this comparison:

Role-equivalent value	Estimate
Senior backend engineer	$6.5k-$8k / month
QA automation engineer	$4k / month
Combined role-equivalent cost	$10.5k-$12k / month

That means the system replaced $10.5k-$12k per month of role-equivalent work before counting tooling.

Corrected savings math

Using the documented 11-month period for comparison:

Savings view	Estimate
11-month role-equivalent savings	$115.5k-$132k
Tooling delta (`$4,000+ - $200`) over 11 months	$41.8k+
11-month combined estimated savings	$157.3k-$173.8k

Annualized, that becomes:

Annualized view	Estimate
Role-equivalent savings	$126k-$144k / year
Tooling savings	$45.6k+ / year
Combined annualized estimate	$171.6k-$189.6k / year

And even that is still incomplete, because it does not fully price in:

DevOps-side work
management and coordination time
PR review load
release-risk reduction
onboarding compression
lower rework
fewer hotfixes

Safe speed beats raw speed

The most important thing I did not want was fake velocity.

Fast delivery only matters if it is safe enough to merge without fear.

That is why these numbers matter together:

~39s local proof loop
10 min median first commit to green CI
7,445 tests
0 failures
6/6 audit checks passed
95% of PRs merged without post-merge hotfixes

That is what businesses are actually buying when they say they want “10x engineering.”

They do not want more code.
They want more safe change per unit of time.

11. What I think this actually says about AI and senior engineers

After re-reading all of the material, including the actual bin/verify and bin/contract_audit sources, I think there are five especially important ideas hiding inside this result.

1) The best systems are strict and ergonomic at the same time

Fast character vs full character.
Changed-lines mode vs --all.
--only.
--fail-fast.
Schema-aware prepare.
Swagger auto-skip.

That is not polish.
That is adoption strategy.

2) “Legacy-safe” is a force multiplier

bin/contract_audit does not require a perfect repo before it becomes useful.
It prevents new drift first.

That is how serious systems actually get adopted.

3) Proof is part of the product

When spec/** and doc/** together dwarf app/**, that is not overhead.

That is the mechanism that lets a platform change quickly without dissolving into review theater.

4) Principal engineering in the AI era is about externalized judgment

The old model was:

senior engineers make better decisions in their head

The new model is:

principal engineers turn those decisions into reusable infrastructure

That is the real upgrade.

5) AI gets more valuable as the rules get sharper

Most AI disappointment is really systems disappointment.

If the repo does not define truth, proof, drift boundaries, and handoff rules, then the model amplifies ambiguity.

If the repo does define those things, the model amplifies throughput.

12. Closing

I do not think the most important AI question is:

Can the model write code?

I think the real question is:

Can the engineering system make correctness cheap enough that the model can safely accelerate it?

That is the difference between novelty and leverage.

In my case, one principal backend engineer shipped 400+ PRs, carried 40%+ of the visible PR volume of an 11-engineer comparison group, delivered a conservative visible multiple of 4.4x+, operated at a true working multiple of 5x, validated daily work in about 39 seconds, reached green CI in a median of 10 minutes, passed 7,445 tests with 0 failures, passed 6/6 contract-audit checks, got a new engineer onto the two highest-priority tasks in 15 minutes, saw first PRs the same day, and delivered 95% of PRs without post-merge hotfixes.

I did not get there by asking AI to be smarter.

I got there by building a system where:

requirements are explicit
execution is governed
verification is fast
drift is blocked
docs are derived
onboarding is compressed
and the only truly acceptable final response becomes:

all good - merge PR

That is what 16 years of experience bought me in the AI era.

Not better autocomplete.
A better engineering operating system.

From Monolithic Seeds to Enterprise-Ready Data Generation: Building a Scalable Rails Seed System

Sat, 24 Jan 2026 00:00:00 +0000

“Good seed data is the difference between a demo that impresses and a demo that embarrasses.”

Every growing Rails application faces the same challenge: how do you populate your database with realistic data for development, demos, testing, and stakeholder presentations? Simple db/seeds.rb files work for small projects, but as your application scales, so do your seeding requirements.

This post documents how we transformed a 3,600-line monolithic seed file into an enterprise-ready data generation system that creates 100,000+ full candidate avatars with all associations—serving AI training, QA stress testing, and frontend performance validation.

The Problem: Why Seed Data Matters
Before: The Monolithic Nightmare
The Refactoring Journey
Feature 1: Modular Step Architecture
Feature 2: Context Object for State Management
Feature 3: Conditional Execution via ENV Flags
Feature 4: Progress Reporting with Timing
Feature 5: Post-Seed Data Validation
Feature 6: 100k+ Full Avatar Scaling
Benefits and Use Cases
Testing the Seed System
Three Bonus Ideas Worth Implementing
Conclusion

1. The Problem: Why Seed Data Matters

1.1 Who Uses Seed Data?

Stakeholder	What They Need	Why It Matters
Frontend Developers	Realistic UI data	Test pagination, search, empty states
Backend Developers	Consistent test fixtures	Debug API responses locally
QA Team	Volume for stress testing	Find N+1 queries, memory leaks
AI/ML Team	Training data at scale	Validate models with realistic distributions
Product Managers	Demo-ready environments	Impress stakeholders, test features
CEO/Leadership	Production-like demos	Investor presentations, board meetings
New Engineers	Quick environment setup	Onboard in minutes, not hours

1.2 The Reality Check

Most Rails projects start with something like this:

# db/seeds.rb
Player.create!(email: 'admin@example.com', password: 'password')
Company.create!(name: 'Test Company')
# ... done

Then requirements grow:

“We need 50 players with different roles”
“Avatars need abilities, work experiences, education”
“QA needs 100,000 avatars for load testing”
“AI team needs realistic job title distributions”
“CEO wants the demo to look like a real platform”

Before you know it, your seed file is 3,600 lines of spaghetti.

1.3 Our Starting Point

Metric	Value
Seed file size	3,610 lines
Total methods	59
Instance variables	8 (shared state)
Dependencies	Complex, undocumented
Test coverage	0%
Documentation	None

Pain points:

❌ Changes broke unrelated features
❌ No way to run individual steps
❌ No progress indication
❌ No validation of seeded data
❌ Impossible to scale to 100k records
❌ New engineers couldn’t understand the flow

2. Before: The Monolithic Nightmare

2.1 The Original Structure

# db/seeds/steps.rb - 3,610 lines!
module Seeds
  module Steps
    class << self
      def run
        seed_predefined_avatar_assets
        seed_company
        seed_job_titles
        seed_admin_users
        # ... 32 more method calls
        print_summary
      end

      private

      def seed_company
        @company = Company.find_or_initialize_by(name: 'Bluegeko')
        @company.assign_attributes(
          # ... 50 lines of attributes
        )
        @company.save!
        
        # ... 200 more lines for demo companies
      end

      def seed_admin_users
        @admin_user = Player.find_or_initialize_by(email: 'admin@bluegeko.com')
        # ... 300 lines
      end

      # ... 56 more methods
    end
  end
end

2.2 The Problems

Problem	Impact
Single 3,600-line file	IDE struggles, git conflicts
Implicit dependencies	Can’t run steps individually
Instance variable soup	`@company` used 28 times across methods
No progress feedback	“Is it stuck or working?”
No validation	Broken seeds discovered in production demos
No scalability	Creating 100k records = 100k individual inserts
Zero documentation	New engineers lost for days

2.3 Instance Variable Reference Count

Variable	References
`@company`	28
`@admin_user`	18
`@candidate_demo_user`	15
`@access_request_user`	14
`@standard_user`	8
`@full_data_candidate_users`	5
`@demo_job_posts`	5
`@admin_avatar`	2

These shared variables made refactoring terrifying—change one method, break five others.

3. The Refactoring Journey

3.1 Implementation Priority Matrix

#	Feature	Effort	Priority	Status
1	Modular step architecture	High	Critical	✅ Done
3	Conditional ENV flags	Low	High	✅ Done
4	Context object	Medium	High	✅ Done
5	Progress + timing	Medium	High	✅ Done
6	Data validation	Low	High	✅ Done
7	100k batch processing	High	Very High	✅ Done
2	Parallel execution	Medium-High	Medium	⏳ Future

3.2 Final Architecture

db/seeds/
├── seeds.rb                    # Entry point (29 lines)
├── support.rb                  # Helpers (387 lines)
├── reference_data.rb           # Lookup tables (889 lines)
├── steps.rb                    # Orchestrator (217 lines)
├── context.rb                  # State management (233 lines)
├── timing.rb                   # Progress tracking (186 lines)
├── validation.rb               # Data integrity (331 lines)
├── batch_avatars.rb           # 100k scaling (825 lines)
├── README.md                   # Documentation (1,797 lines)
├── SEEDS_REFACTORING.md        # Implementation notes (643 lines)
└── steps/                      # 37 individual step files
    ├── 01_predefined_avatar_assets.rb
    ├── 02_company.rb
    ├── ...
    └── 37_batch_avatars.rb

Result: 3,610 lines → 37 focused files averaging 80 lines each

4. Feature 1: Modular Step Architecture

4.1 The Approach: Singleton Class Reopening

Instead of a massive refactor, we used Ruby’s ability to reopen classes:

# db/seeds/steps/02_company.rb
module Seeds
  module Steps
    class << self
      private

      def seed_company
        ctx.company = Company.find_or_initialize_by(name: "Bluegeko")
        ctx.company.assign_attributes(company_attributes)
        ctx.company.save!

        log_seed "Company upserted: #{ctx.company.name}"
        seed_demo_companies
      end

      def company_attributes
        {
          industry: "Technology",
          website_url: "https://bluegeko.com",
          # ... attributes
        }
      end
    end
  end
end

4.2 Orchestrator Pattern

The main steps.rb became a thin orchestrator:

# db/seeds/steps.rb
module Seeds
  module Steps
    OPTIONAL_STEPS = {
      seed_reports: "SKIP_SEED_REPORTS",
      seed_full_data_candidates: "SEED_FULL_CANDIDATES",
      seed_batch_avatars: "CREATE_BATCH_PROFILES"
    }.freeze

    class << self
      def run
        initialize_context
        Seeds::Support::Timing.start_run(all_steps.size)

        # Execute steps in order
        run_step :seed_predefined_avatar_assets
        run_step :seed_company
        run_step :seed_job_titles
        # ... 34 more steps
        run_step :seed_batch_avatars

        # Validate and summarize
        validate_seed_data
        print_summary
        Seeds::Support::Timing.print_summary

        ctx
      end

      private

      def run_step(step_name)
        return if skip_step?(step_name)

        Seeds::Support::Timing.track_step(step_name) do
          send(step_name)
        end
      end

      def skip_step?(step_name)
        env_var = OPTIONAL_STEPS[step_name]
        return false unless env_var

        if env_var.start_with?("SKIP_")
          ENV[env_var] == "true"
        else
          ENV[env_var] != "true"
        end
      end
    end
  end
end

4.3 Benefits of Modular Architecture

Aspect	Before	After
File size	3,610 lines	~80 lines avg
Git conflicts	Constant	Rare
IDE navigation	Painful	Instant
Step isolation	Impossible	Easy
Testing	Untestable	Per-step specs
Onboarding	Days	Hours

5. Feature 2: Context Object for State Management

5.1 The Problem: Instance Variable Chaos

# Before: 95 instance variable references across 37 steps
def seed_admin_users
  @admin_user = Player.create!(...)
end

def seed_job_posts
  job = JobPost.create!(company: @company)  # Where is @company set?
end

Issues:

No IDE autocomplete
No documentation of what’s available
No validation that required data exists
Testing requires complex setup

5.2 The Solution: Explicit Context Object

# db/seeds/context.rb
module Seeds
  module Support
    class Context
      # Core entities
      attr_accessor :company
      attr_accessor :admin_user, :standard_user
      attr_accessor :candidate_demo_user, :access_request_user
      attr_accessor :admin_avatar, :full_data_candidate_users
      attr_accessor :demo_job_posts

      # Client roles
      attr_accessor :client_user, :client_owner, :client_manager

      # Batch processing
      attr_accessor :batch_avatar_result

      def initialize
        @full_data_candidate_users = []
        @demo_job_posts = []
      end

      # Convenience methods
      def company?
        !@company.nil?
      end

      def batch_avatars?
        @batch_avatar_result&.success? == true
      end

      def batch_avatar_count
        @batch_avatar_result&.avatars_created || 0
      end

      # Dependency validation
      def require!(*attrs)
        missing = attrs.select { |attr| send(attr).nil? }
        raise "Missing required context: #{missing.join(', ')}" if missing.any?
      end

      # Debugging helper
      def summary
        {
          company: @company&.name,
          admin_user: @admin_user&.email,
          full_data_candidates: @full_data_candidate_users.size,
          batch_avatars: batch_avatar_count
        }
      end
    end
  end
end

5.3 Usage in Steps

# Access via ctx helper
def seed_job_posts
  ctx.require!(:company, :admin_user)  # Fail fast if deps missing

  job = JobPost.create!(
    company: ctx.company,
    player: ctx.admin_user,
    title: "Senior Engineer"
  )
  ctx.demo_job_posts << job
end

5.4 Why Context Object Matters

Aspect	Instance Variables	Context Object
Discovery	`grep @` across files	`ctx.` autocomplete
Documentation	None	`attr_accessor` list
Validation	Runtime errors	`ctx.require!`
Testing	Mock everything	Inject test context
Debugging	puts everywhere	`ctx.summary`

6. Feature 3: Conditional Execution via ENV Flags

6.1 Use Cases

Use Case	ENV Flag	Behavior
Skip slow reports	`SKIP_SEED_REPORTS=true`	Reports step skipped
Create 40 full candidates	`SEED_FULL_CANDIDATES=true`	Rich candidate data
Create 100k avatars	`CREATE_BATCH_PROFILES=true`	Batch processing enabled

6.2 Implementation

# db/seeds/steps.rb
OPTIONAL_STEPS = {
  # Skip steps (default: run)
  seed_reports: "SKIP_SEED_REPORTS",

  # Enable steps (default: skip)
  seed_full_data_candidates: "SEED_FULL_CANDIDATES",
  seed_full_data_candidates_job_board: "SEED_FULL_CANDIDATES",
  seed_batch_avatars: "CREATE_BATCH_PROFILES"
}.freeze

def skip_step?(step_name)
  env_var = OPTIONAL_STEPS[step_name]
  return false unless env_var

  if env_var.start_with?("SKIP_")
    ENV[env_var] == "true"  # Skip if true
  else
    ENV[env_var] != "true"  # Skip unless true
  end
end

6.3 Usage Examples

# Standard development seed (fast)
rails db:seed

# Full candidates for feature testing
SEED_FULL_CANDIDATES=true rails db:seed

# 100k avatars for QA stress testing
CREATE_BATCH_PROFILES=true rails db:seed

# Skip reports for faster iteration
SKIP_SEED_REPORTS=true rails db:seed

# Combined flags
SEED_FULL_CANDIDATES=true CREATE_BATCH_PROFILES=true rails db:seed

6.4 Benefits

Scenario	Without Flags	With Flags
Daily development	~5 min (full seed)	~30 sec (minimal)
Feature testing	Edit code	Set ENV var
QA stress test	Impossible	One command
CI pipeline	Full seed always	Skip reports

7. Feature 4: Progress Reporting with Timing

7.1 The Problem: Silent Seeds

$ rails db:seed
# ... silence for 30 seconds ...
# ... more silence ...
# Is it working? Is it stuck?

7.2 The Solution: Real-Time Progress

# db/seeds/timing.rb
module Seeds
  module Support
    module Timing
      class << self
        def start_run(total_steps)
          @total_steps = total_steps
          @current_step = 0
          @step_timings = {}
          @run_started_at = Time.current
        end

        def track_step(step_name)
          @current_step += 1
          started = Time.current

          print_progress(step_name) unless quiet?

          yield

          duration = Time.current - started
          @step_timings[step_name] = duration
        end

        def print_progress(step_name)
          puts format(
            "[%2d/%2d] %-40s",
            @current_step, @total_steps,
            step_name.to_s.gsub(/^seed_/, "").humanize
          )
        end

        def print_summary
          puts "\n#{'=' * 60}"
          puts "SEED TIMING SUMMARY"
          puts "=" * 60

          @step_timings.sort_by { |_, v| -v }.first(10).each do |step, duration|
            puts format("  %-40s %6.2fs", step, duration)
          end

          puts "-" * 60
          puts format("  %-40s %6.2fs", "TOTAL", total_duration)
          puts "=" * 60
        end
      end
    end
  end
end

7.3 Output Example

[ 1/37] Predefined avatar assets              
[ 2/37] Company                               
[ 3/37] Job titles                            
[ 4/37] Admin players                           
...
[35/37] Summary                               
[36/37] Demo recommendation                   

============================================================
SEED TIMING SUMMARY
============================================================
  seed_full_data_candidates                     12.34s
  seed_random_avatars                           8.21s
  seed_homepage_avatars                         4.56s
  seed_job_posts                                 3.12s
  ...
------------------------------------------------------------
  TOTAL                                         45.67s
============================================================

7.4 Benefits

Aspect	Silent Seeds	Progress + Timing
Feedback	None	Real-time progress
Debugging	Which step failed?	Clear step names
Optimization	Guess which is slow	Timing breakdown
CI logs	Useless	Actionable

8. Feature 5: Post-Seed Data Validation

8.1 The Problem: Silent Failures

# Seeds "complete" but data is broken
def seed_admin_users
  @admin_user = Player.find_or_initialize_by(email: 'admin@bluegeko.com')
  @admin_user.save  # No bang! Silent failure
end

# Later, in production demo...
# "Why is there no admin player?!"

8.2 The Solution: Validation Module

# db/seeds/validation.rb
module Seeds
  module Support
    module Validation
      CHECKS = {
        # Integrity checks (errors)
        orphaned_avatars: -> { Avatar.left_joins(:player).where(players: { id: nil }) },
        candidates_without_avatars: -> { Player.candidate.left_joins(:avatar).where(avatars: { id: nil }) },
        orphaned_job_posts: -> { JobPost.left_joins(:company).where(companies: { id: nil }) },

        # Minimum data checks (errors)
        minimum_users: -> { Player.count >= 5 },
        minimum_avatars: -> { Avatar.count >= 3 },
        minimum_companies: -> { Company.count >= 1 },
        minimum_job_posts: -> { JobPost.count >= 5 },

        # Quality checks (warnings)
        avatars_with_abilities: -> { Avatar.joins(:abilities).distinct.count > 0 },
        avatars_with_work_experience: -> { Avatar.joins(:raid_logs).distinct.count > 0 },
        users_with_access_keys: -> { Player.joins(:access_keys).distinct.count > 0 }
      }.freeze

      class << self
        def run
          return skip_result if skip?

          result = ValidationResult.new
          run_integrity_checks(result)
          run_minimum_checks(result)
          run_quality_checks(result) unless strict?

          print_results(result)
          result
        end

        private

        def run_integrity_checks(result)
          %i[orphaned_avatars candidates_without_avatars orphaned_job_posts].each do |check|
            count = CHECKS[check].call.count
            if count > 0
              result.add_error(check, "Found #{count} #{check.to_s.humanize.downcase}")
            else
              result.add_passed(check)
            end
          end
        end
      end
    end
  end
end

8.3 Validation Output

============================================================
POST-SEED VALIDATION
============================================================
Integrity Checks:
  ✓ No orphaned avatars
  ✓ No candidates without avatars
  ✓ No orphaned job posts

Minimum Data Checks:
  ✓ Players: 47 (minimum: 5)
  ✓ Avatars: 42 (minimum: 3)
  ✓ Companies: 5 (minimum: 1)
  ✓ Job Posts: 25 (minimum: 5)

Quality Checks:
  ✓ Avatars with abilities: 38
  ✓ Avatars with work experience: 35
  ⚠ Players with login methods: 0 (warning)

------------------------------------------------------------
Result: PASSED (14 checks, 1 warning)
============================================================

8.4 ENV Controls

# Skip validation (CI speed)
SKIP_SEED_VALIDATION=true rails db:seed

# Strict mode (fail on warnings)
SEED_VALIDATION_STRICT=true rails db:seed

9. Feature 6: 100k+ Full Avatar Scaling

9.1 The Challenge

Our AI team needed 100,000 realistic candidate avatars for model training. QA needed the same for stress testing. Creating records one-by-one would take hours.

Requirements:

Full avatars with ALL associations
Category-appropriate job titles
Skills, work experiences, education
Portfolio, contact info, avatars
Realistic data distributions
Conditional execution (don’t run in daily dev)

9.2 What Gets Created

Each batch avatar is a complete candidate with:

Association	Per Avatar	Total (100k)
Player + Login Security	1	100,000
Avatar	1	100,000
Skills	3-6	~450,000
Work Experiences	2-4	~300,000
Education Items	1-2	~150,000
Languages	1-3	~200,000
Contact Infos	2-4	~300,000
Portfolio + Links	3-9	~600,000
Location Setting	1	100,000
Salary Expectation	1	100,000
Avatar Session + Images	4-5	~450,000
Total Records	~20-30	~2,500,000+

9.3 Category-Specific Data

CATEGORY_OCCUPATIONS = {
  "technology" => [
    "Software Engineer", "Senior Software Engineer", "Staff Software Engineer",
    "DevOps Engineer", "Data Scientist", "Machine Learning Engineer",
    "Mobile Developer", "Cloud Architect", "Security Engineer"
  ],
  "design" => [
    "UX Designer", "Product Designer", "Creative Director",
    "Interaction Designer", "Design Systems Lead"
  ],
  "business" => [
    "Project Manager", "Product Manager", "Business Analyst",
    "Strategy Consultant", "Operations Manager"
  ],
  # ... 9 categories total
}.freeze

CATEGORY_SKILLS = {
  "technology" => %w[Ruby Python JavaScript TypeScript Docker Kubernetes AWS],
  "design" => %w[Figma Sketch Photoshop Wireframing UserResearch],
  "business" => %w[Excel Salesforce Tableau Leadership Strategy],
  # ...
}.freeze

9.4 Implementation Highlights

# db/seeds/batch_avatars.rb
module Seeds
  module Support
    module BatchAvatars
      DEFAULT_COUNT = 100_000
      CHUNK_SIZE = 500

      def run(count: target_count, on_progress: nil)
        result = BatchResult.new(target_count: count)

        count.times.each_slice(chunk_size) do |indices|
          chunk_result = process_chunk(indices)
          result.record_chunk(chunk_result)
          on_progress&.call(result)
        end

        result.finish!
        result
      end

      private

      def process_chunk(indices)
        indices.each do |index|
          # Select random category
          category = categories.sample

          # Create player (ActiveRecord for Devise)
          player = create_batch_user(index: index)

          # Create avatar with category-appropriate job title
          avatar = create_batch_avatar(player: player, category: category)

          # Create ALL associations
          create_abilities(avatar, category.slug)
          create_raid_logs(avatar, category.slug)
          create_training_logs(avatar)
          create_dialects(avatar)
          create_beacons(avatar)
          create_portfolio(avatar)
          create_map_rule(avatar)
          create_bounty_rule(avatar)
          create_avatar_data(avatar)
        end
      end
    end
  end
end

9.5 Usage

# Create 100,000 full avatars (default)
CREATE_BATCH_PROFILES=true rails db:seed

# Create 10,000 for smaller tests
CREATE_BATCH_PROFILES=true BATCH_PROFILE_COUNT=10000 rails db:seed

# With verbose progress
CREATE_BATCH_PROFILES=true BATCH_VERBOSE=true rails db:seed

9.6 Output

======================================================================
[BATCH] Starting FULL candidate avatar creation
======================================================================
  Target count:     100,000
  Chunk size:       500
  Associations:     Skills, Work Exp, Education, Languages, Contacts, etc.
======================================================================

  [=======>--------------------]  25.0% | Chunk 50/200 | 25000 avatars | 625,000 assoc

======================================================================
[BATCH] Full candidate avatar creation complete!
======================================================================
  Players created:        100,000
  Avatars created:     100,000
  Associations created: 2,543,721
  Total duration:       3h 12m
  Rate:                 8.7 avatars/second
======================================================================

9.7 Performance Characteristics

Count	Time	Records Created
1,000	~2-3 min	~25,000
10,000	~20-30 min	~250,000
100,000	~3-5 hours	~2,500,000

10. Benefits and Use Cases

10.1 Use Case Matrix

Stakeholder	Command	Result
Daily Dev	`rails db:seed`	~30s, minimal data
Feature Testing	`SEED_FULL_CANDIDATES=true rails db:seed`	~2 min, 40 rich avatars
QA Stress Test	`CREATE_BATCH_PROFILES=true rails db:seed`	~3h, 100k avatars
AI Training	`CREATE_BATCH_PROFILES=true BATCH_PROFILE_COUNT=500000 rails db:seed`	~15h, 500k avatars
CEO Demo	`rails db:seed`	Production-like feel
New Engineer	`rails db:seed`	Working environment in 30s

10.2 Before vs After Comparison

Aspect	Before	After
File organization	1 file, 3,610 lines	37 files, ~80 lines each
Test coverage	0%	400+ specs
Documentation	None	1,797-line README
Progress feedback	Silent	Real-time with timing
Data validation	None	14 automated checks
Scalability	~100 avatars	100,000+ avatars
Conditional execution	Edit code	ENV flags
Onboarding time	Days	Hours
Git conflicts	Daily	Rare

10.3 ROI

Time saved per week:

5 engineers × 10 min/day waiting for seeds = 4+ hours
2 QA engineers × 1 hour/week debugging broken seeds = 2 hours
1 demo preparation × 2 hours = 2 hours

Total: ~8 hours/week = 1 FTE day

11. Testing the Seed System

11.1 Test Structure

spec/seeds/
├── support/
│   ├── helpers_spec.rb           # Unit tests for helpers
│   ├── context_spec.rb           # Context object tests
│   ├── timing_spec.rb            # Timing module tests
│   ├── validation_spec.rb        # Validation tests
│   └── batch_avatars_spec.rb    # Batch processing tests
├── reference_data_spec.rb        # Reference data tests
├── integration_spec.rb           # Full seed run tests
└── steps/
    ├── shared_examples.rb        # Reusable step examples
    ├── company_spec.rb           # Step-specific tests
    └── ...

11.2 Shared Examples for Steps

# spec/seeds/steps/shared_examples.rb
RSpec.shared_examples "a seed step that creates records" do |model_class, expected_count:|
  it "creates #{expected_count} #{model_class.name.pluralize}" do
    expect { run_step }.to change(model_class, :count).by(expected_count)
  end
end

RSpec.shared_examples "a seed step that is idempotent" do
  it "does not create duplicates on second run" do
    run_step
    expect { run_step }.not_to change(described_model, :count)
  end
end

11.3 Test Coverage

Component	Specs	Coverage
Helpers	45	100%
Context	32	100%
Timing	28	100%
Validation	31	100%
Batch Avatars	49	100%
Reference Data	89	100%
Individual Steps	126	Key paths
Total	400+	High

12. Three Bonus Ideas Worth Implementing

12.1 Idea 1: Seed Data Snapshots

Problem: Recreating 100k avatars takes 3 hours every time.

Solution: Database snapshots for instant restore.

# Potential implementation
module Seeds
  module Snapshots
    def save(name)
      `pg_dump testapp_development > snapshots/#{name}.sql`
    end

    def restore(name)
      `psql testapp_development < snapshots/#{name}.sql`
    end
  end
end

# Usage
# After 3-hour batch: SEED_SNAPSHOT=save rails db:seed
# Next time: SEED_SNAPSHOT=restore:batch_100k rails db:seed (~30 sec)

Benefit: 3 hours → 30 seconds for QA environments.

12.2 Idea 2: Faker Seed Consistency

Problem: Random data changes every seed run, breaking visual regression tests.

Solution: Seed Faker’s random generator.

# db/seeds/support.rb
def with_consistent_faker
  original_seed = Faker::Config.random
  Faker::Config.random = Random.new(42)
  yield
ensure
  Faker::Config.random = original_seed
end

# Usage
with_consistent_faker do
  seed_avatars  # Same names, emails, etc. every time
end

Benefit: Consistent screenshots for visual regression testing.

12.3 Idea 3: Seed Data Metrics Dashboard

Problem: No visibility into what’s seeded without running queries.

Solution: Post-seed metrics report.

# db/seeds/metrics.rb
module Seeds
  module Metrics
    def report
      {
        players: {
          total: Player.count,
          by_role: Player.group(:role).count,
          with_avatars: Player.joins(:avatar).count
        },
        avatars: {
          total: Avatar.count,
          with_abilities: Avatar.joins(:abilities).distinct.count,
          avg_abilities: Avatar.joins(:abilities).group(:id).count.values.sum.to_f / Avatar.count,
          by_category: Avatar.joins(:category).group("categories.slug").count
        },
        companies: {
          total: Company.count,
          with_jobs: Company.joins(:job_posts).distinct.count
        }
      }
    end
  end
end

Output:

Players:
  total: 100,047
  by_role: { admin: 2, candidate: 100,040, client: 5 }
  with_avatars: 100,042

Avatars:
  total: 100,042
  with_abilities: 99,800
  avg_abilities: 4.2
  by_category: { technology: 45,000, design: 15,000, ... }

Companies:
  total: 5
  with_jobs: 3

Benefit: Instant insight into seed data quality and distribution.

13. Conclusion

13.1 What We Achieved

Metric	Before	After
Lines in main file	3,610	217
Number of files	1	37
Test coverage	0%	400+ specs
Documentation	0 lines	1,797 lines
Max avatars	~100	100,000+
Progress feedback	None	Real-time
Data validation	None	14 checks
Conditional execution	None	5 ENV flags

13.2 Key Takeaways

Modular beats monolithic — Split large files into focused modules
Explicit state beats implicit — Context objects over instance variables
Conditional execution is essential — ENV flags for different scenarios
Visibility prevents pain — Progress reporting and timing
Validation catches bugs — Automated checks before they reach demos
Scale when needed — Batch processing for volume requirements
Document everything — Future you (and new engineers) will thank you

13.3 The Real Win

The technical improvements are measurable, but the real win is confidence:

Confident that seeds work (validation)
Confident about progress (timing)
Confident in isolation (modular files)
Confident at scale (batch processing)
Confident for demos (realistic data)
Confident for new engineers (documentation)

Invest in your seed system. It’s the foundation everything else is built on.

Resources

Rails Guides on Seeds: guides.rubyonrails.org/active_record_migrations.html#migrations-and-seed-data
Faker Gem: github.com/faker-ruby/faker
FactoryBot: github.com/thoughtbot/factory_bot
Database Cleaner: github.com/DatabaseCleaner/database_cleaner
Our Seed System Documentation: See db/seeds/README.md in your codebase

This post documents the transformation of the TestApp seed system from a 3,600-line monolith to an enterprise-grade data generation platform. The patterns described here—modular architecture, context objects, conditional execution, progress tracking, validation, and batch processing—are applicable to any Rails application that has outgrown simple seeds.

From Zero-Gap to Zero-Drift: Making AI Follow Rails Rules (Frozen vs Strict)

Wed, 07 Jan 2026 00:00:00 +0000

TL;DR

Contract-first + verification gates eliminate gaps (missing fields, regressions). fileciteturn2file0

But LLMs still create rule drift (they quote rules, then violate them).

We fixed drift with guardrails, not more prose: Hard-Fail rule IDs, STOP gates, mandatory evidence audits, and negative examples.

Entry point stays tiny and stable; the enforcement lives in versioned docs.

We keep two characters: Frozen (v1.0) for speed, Strict (v1.1) for enforcement.

Why this follow-up exists

In Zero-Gap API Development, the goal was “ship APIs with zero regressions” by turning implementation into a contract + verification problem: TypeScript interfaces as canonical truth, safe defaults, systematic verification gates, and discrepancy classification ([IMPL] vs [DOC]). fileciteturn2file0

That framework works. The problem we hit next was different:

AI doesn’t drift because rules are unclear. It drifts because rules have no consequences.

Even when an agent reads AGENTS.md and repeats rules back, it can still “helpfully” shortcut:

“Use Ransack for filtering/searching.” → agent writes custom where(...) anyway.
“Avoid DB-specific SQL.” → agent sneaks in ILIKE, IFNULL, REGEXP, etc.
“Controllers only wrap envelopes.” → agent hand-builds JSON in controller.

So this session was about adding an enforcement layer on top of Zero-Gap.

The goal of this session

We wanted a system where a reviewer can say:

“This violates two rules: HF-1 and HF-2”

…and the agent itself is forced to detect and correct that before shipping code.

To do that, we restructured the workflow into a toolchain:

PROMPT.md → execution runtime (phases, STOP gates, verification receipts)
AGENTS.md → hard authority (Hard-Fail rules, failure semantics)
GUIDE.md → patterns & examples (non-authority, includes anti-patterns)
bin/verify → canonical verifier

The single entry point (stable forever)

Instead of embedding giant prompts in README/issues, every task uses the same tiny entry point:

Task: WEB-485 – User Notifications

Refs:
- Requirements: doc/requirements/users/USER_NOTIFICATIONS.md
- Flow: doc/flow/WEB-485_user_notifications.md
- PRD: doc/prd/WEB-485_user_notifications_PRD.md

Execute per PROMPT.md.

Important property: the task block never changes.
Strictness evolves only inside PROMPT.md, AGENTS.md, and GUIDE.md.

This prevents the most common drift source: copying outdated prompt blobs across tickets.

Frozen vs Strict: why we keep both

We ended up with two prompt characters:

Frozen (v1.0)

Optimized for: brevity, human readability, speed
Best for: trusted contributors, small refactors, quick spikes
Weakness: rules are descriptive (“MUST”), so AI can rationalize shortcuts

Strict (v1.1)

Optimized for: compliance, auditability, “no surprises” AI execution
Best for: contract-sensitive endpoints, anything touching search/filtering/auth/pagination
Weakness: longer text (but it’s enforcement scaffolding, not noise)

The key is: both share the same entry point. You swap the runtime, not the call site.

What actually stops drift (the 4 mechanisms)

1) Hard-Fail rule IDs (HF-*)

Instead of “Rule #5,” we introduced stable IDs:

HF-1 — Ransack-only search/filtering
HF-2 — DB-agnostic queries only (no raw SQL / DB-specific funcs)
HF-3 — Blueprinter-only JSON
HF-4 — snake_case only
HF-5 — Required fields never null (safe defaults)

Why IDs matter: they turn “standards” into enforceable references:

easy review comments (“HF-2 violation”)
easy self-audit checkboxes
easy future evolution (rename content, keep ID stable)

2) STOP gates (control flow, not suggestions)

Strict mode adds explicit control flow:

Phase 0–2: NO CODE
Stop after planning
If any HF-* would be violated → STOP and report

LLMs follow control flow better than prose.

3) Mandatory Rule Compliance Audit (proof, not vibes)

Before final output, the agent must produce:

RULE COMPLIANCE AUDIT
HF-1: COMPLIANT — evidence: UsersController#index uses User.ransack(params[:q])
HF-2: COMPLIANT — evidence: no raw SQL; only ActiveRecord/Arel
...

This forces the agent to prove it complied. If it can’t produce evidence, it typically self-corrects before shipping.

4) Negative examples (anti-pattern firewall)

Guides that only show “good” patterns still allow AI to invent “bad” ones. So we added explicit “DO NOT COPY” snippets:

# ❌ HF-1 violation (manual SQL filtering)
User.where("email ILIKE ?", "%#{params[:email]}%")

# ✅ Correct (Ransack owns filtering)
User.ransack(params[:q]).result

LLMs imitate examples aggressively. Negative examples prevent “helpful improvisation.”

Example: the exact drift we’re preventing

Bad (HF-1 + HF-2 violation)

# ❌ don't do this
users = User.where("email ILIKE ?", "%#{params[:email]}%")

Good (HF-1 compliant)

search = User.ransack(params[:q])
users  = search.result.page(params[:page]).per(params[:per_page] || 20)

In strict mode, if an agent proposes the bad version, it must output:

❌ RULE VIOLATION
Rule: HF-1
Location: app/controllers/...:12
Reason: manual filtering used instead of Ransack
Required Fix: replace with Model.ransack(params[:q]).result

No debate. Fix it or stop.

Verification: one command, one receipt

Zero-Gap already required verification gates. fileciteturn2file0
The strict upgrade makes verification harder to “forget” by standardizing:

Preferred: bin/verify
Legacy commands remain in docs as commented fallback

And the final output requires a CHECKS section with exit codes.

That turns “I think I ran tests” into a receipt.

Operational guidance: when to use which mode

Use Frozen (v1.0) when:

small refactor
low contract risk
you want short prompts and fast iteration

Use Strict (v1.1) when:

building/upgrading endpoints
touching filtering/search/pagination/auth
upgrading versioned requirement docs
AI is doing most of the work

If in doubt: default to Strict.

Closing: Zero-Gap is the architecture; Zero-Drift is governance

Zero-Gap prevents missing fields and regressions by making contracts and verification non-negotiable. fileciteturn2file0
Zero-Drift makes AI reliably follow your engineering rules by adding:

failure semantics
proof requirements
anti-pattern training
a stable entry point
a canonical verifier

In practice, this reduces review churn dramatically: you spend less time catching “obvious violations” and more time on product decisions.

Appendix: quick mental model

REQUIREMENT_DOC = spec
PROMPT.md = runtime
AGENTS.md = language law + compiler errors (HF-*)
GUIDE.md = standard library + examples
bin/verify = test runner

How to Start with Agentic Development: What to Know, What to Automate, and How to Use It

Thu, 01 Jan 2026 00:00:00 +0000

TL;DR

Agentic development is a loop: Plan → Act (tools) → Observe → Decide → Repeat.

The biggest productivity gains come from determinism, not prompting: a single verify command, quality gates, and enforcement via hooks.

The “must-know” stack in 2026: AGENTS.md, Skills, MCP, RAG, LSP, Hooks, and Workflows.

My two most effective multipliers:

Contract-first + verification gates (“Zero‑Gap API development”)

Documentation hierarchy + Flow docs with Responsible Files (documentation-driven development that scales)

Why agentic development feels different from “AI coding assistants”

Autocomplete and chat are mostly suggestion engines.

Agentic development is when the model runs a structured loop with tools:

it reads your repo conventions
it edits multiple files
it runs commands
it interprets errors
it iterates until the system is green

That means your productivity is no longer limited by “how well can I prompt?”
It’s limited by how well your repo communicates intent and enforces correctness.

The modern skill is not “prompting.”
It’s context engineering + verification engineering.

The mental model: the agent loop

An “agent” is just a loop with tool use:

Plan (what files, what changes, what tests)
Act (edit files, run commands, call tools)
Observe (test output, logs, compiler errors, lint)
Decide (fix, rollback, re-plan)
Repeat until done

Your job (as a senior engineer) is to make this loop:

well-scoped (small diffs, explicit “definition of done”)
well-instrumented (fast tests + lint + security checks)
hard to cheat (quality gates / hooks / CI)
context-efficient (agent sees the right context, not more context)

Glossary: plugins, skills, MCP, RAG, LSP, hooks, workflows

Here’s the vocabulary, in a practical order:

AGENTS.md

A repo-local “operating manual” for coding agents.

What it’s for

Encode how this repo works (commands, conventions, boundaries)
Stop re-explaining the same rules every session
Make agent behavior predictable across tasks

Think: README.md for agents, but stricter and more actionable.

Skills

A “Skill” is a packaged workflow (instructions + optional resources/scripts) that the agent can load on demand.

What it’s for

Turn your best senior workflows into reusable modules:
- “Implement Rails endpoint from contract + request specs”
- “Safe refactor: characterization tests first”
- “Write flow doc + Responsible Files table”
Reduce quality drift and context repetition

If AGENTS.md is global repo policy, Skills are repeatable procedures.

Hooks

Hooks are automation that runs at specific moments (after edits, before stopping, etc.).

What it’s for

Enforce quality without relying on “remember to do it”
Auto-format after edits
Block dangerous operations
Require bin/verify passing before the agent can “finish”

Prompts are best-effort. Hooks are default behavior.

Workflows

Workflows are your end-to-end process:

feature → tests → verify → docs → PR
bugfix → reproduction test → fix → verify → postmortem note

Skills + hooks + CI turn workflows into a system.

RAG (Retrieval-Augmented Generation)

RAG is the pattern of retrieving relevant docs/files and injecting them as context for the model.

What it’s for

Ground the agent in your docs and code
Reduce hallucinations
Make “documentation-driven development” actually useful to the model

In practice: RAG is how an agent “remembers” your system without you pasting the whole repo.

LSP (Language Server Protocol)

LSP is what powers “go to definition,” “find references,” “rename symbol,” etc.

What it’s for

Semantic navigation beats grep for refactors and correctness
Agents become safer when they can reliably answer:
- “Where is this symbol used?”
- “What implements this interface?”
- “What breaks if I change this method signature?”

MCP (Model Context Protocol)

MCP is a standard way to connect an agent to tools and data sources (issue trackers, DB schema, docs, internal APIs).

What it’s for

Reduce copy/paste context
Give structured, permissioned access to external systems
Make tool integrations reusable across clients/vendors

MCP is most useful when your bottleneck is access to information/tools, not coding speed.

The “agentic stack” in one picture

A practical way to visualize the stack:

Workflow (what to do)
  └─ Hooks (force it to happen)
      └─ Tool/data access (MCP)
          └─ Context feeding (RAG + LSP)
              └─ Skills (repeatable procedures)
                  └─ AGENTS.md (repo rules + commands + DoD)

If you want a big productivity jump: build from the bottom up.

The senior engineer principle: determinism beats prompting

If something must happen every time:

formatting
tests
lint
security scan
contract compliance check

…don’t “ask the model to remember.”

Make it one command and/or enforce it with hooks + CI.

This is the same reason “Zero‑Gap API Development” works: it’s a deterministic pipeline (contract → implement → verify → document), not vibes.
And it’s the same reason documentation-driven development scales for large systems: it creates deterministic “where to look” maps.

A universal framework that scales: Requirements → Implementation → Documentation

This generalizes cleanly across Rails monoliths, Go services, and polyglot repos:

┌──────────────────────────────────────────────┐
│ Layer 1: Requirements / Contracts            │
│ - Interfaces / OpenAPI / protobuf / specs    │
│ - Single source of truth                     │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ Layer 2: Implementation + Verification       │
│ - Code + tests + lint + security             │
│ - One “judge” command: bin/verify            │
└──────────────────────────────────────────────┘
                     ↓
┌──────────────────────────────────────────────┐
│ Layer 3: Documentation / Memory              │
│ - Flow docs (how it’s implemented)           │
│ - PRDs (why it exists)                       │
│ - Responsible Files tables                   │
└──────────────────────────────────────────────┘

Two key rules:

Docs are generated/updated only after verification passes
Contracts are treated as the canonical truth (or explicitly flagged when reality diverges)

Step 1: Add AGENTS.md to every repo

Put this at the repo root. Keep it short and operational.

# AGENTS.md — Project instructions for coding agents

## Prime directive
- Prefer small, verifiable changes.
- Never skip verification commands.
- If unsure: add/adjust tests first to lock behavior.

## Commands (source of truth)
### Ruby / Rails
- Setup: bundle install
- Test:  bin/test
- Lint:  bin/lint
- Verify (must pass before PR): bin/verify
- Security: bin/security

### Go (if present)
- Test:  make test
- Lint:  make lint
- Verify: make verify

### Node (if present)
- Test:  pnpm test
- Lint:  pnpm lint
- Typecheck: pnpm typecheck

## Definition of Done
- [ ] Implementation matches contract/specs
- [ ] Tests added/updated and pass
- [ ] Lint/static checks pass
- [ ] Security checks pass
- [ ] Docs updated (flow + PRD) if behavior changed
- [ ] No unrelated refactors in same diff

## Safety boundaries
- Don’t touch secrets/credentials or production config.
- Ask before adding dependencies or changing CI.

This alone reduces agent thrash dramatically.

Step 2: Create one “judge command” (`bin/verify`)

Agents converge faster when there’s exactly one command that says “reality is correct.”

Rails example

#!/usr/bin/env bash
set -euo pipefail

echo "==> Lint"
bundle exec rubocop

echo "==> Tests"
bundle exec rspec

echo "==> Security (brakeman)"
bundle exec brakeman -q -w2

echo "==> Dependency audit"
bundle exec bundle audit check --update

echo "==> API docs generation (if used)"
bundle exec rails rswag:specs:swaggerize

echo "✅ verify passed"

Go example

verify:
	@gofmt -w .
	@golangci-lint run
	@go test ./...

The exact tools don’t matter.
What matters is: one obvious place to run the truth.

Step 3: Use contract-first development (especially for APIs)

My most reliable pattern for AI-assisted Rails APIs is contract-first:

treat an interface/spec as canonical truth
implement strictly against it
verify via gates
then update docs

Safe defaults matter (required fields are never null)

In contract-first work, required fields should not come back as null “because DB is sparse.”

Use safe defaults by type:

Type	Default
String	`""`
Number	`0` or minimum valid
Boolean	`false`
Array	`[]`
Object	minimal valid object
Timestamp	`Time.current.iso8601`

This removes a common “agent bug class”: missing fields / inconsistent shapes.

Discrepancy tagging: `[IMPL]` vs `[DOC]`

When auditing contract compliance, classify gaps:

[IMPL] → code is wrong, fix it now, rerun verification
[DOC] → the doc/contract is wrong (DB/model reality differs), flag it, don’t silently change requirements

This small habit prevents teams from corrupting the source of truth.

Step 4: Documentation-driven development for complex systems

When systems explode in complexity (MMORPG-scale, or any mature SaaS), your bottleneck becomes coherence, not raw coding time.

The pattern that scales:

Documentation hierarchy

GDD / vision docs: what the system is
Feature docs: what each subsystem must do
Flow docs: how it’s implemented (step-by-step + file ownership)

This is the structure that makes large Rails monoliths maintainable, and also makes AI agents effective because they can retrieve the correct context instead of guessing.

Flow docs + Responsible Files tables

Flow docs should include:

“Use case” steps that trace UI → controller → service → persistence → broadcast
Key behaviors / invariants
A “Responsible Files” table so anyone (human or agent) can jump to the right code immediately

Example table:

Purpose	File
Combat service	`app/services/game/combat/turn_based_combat_service.rb`
Stimulus controller	`app/javascript/controllers/turn_combat_controller.js`
View	`app/views/combat/_battle.html.erb`
Config	`config/gameplay/combat_actions.yml`

This is the best “RAG corpus” you can build: docs that directly point to code.

Step 5: Turn your best practices into Skills

Here’s the trick: you already wrote the workflows in prose.

Now you package them so the agent can apply them repeatedly.

Skill ideas that map to real work

rails-zero-gap-endpoint
- input: requirement doc (contract), expected behavior
- output: controller + serializer/blueprint + request specs + docs updates
- gate: must pass bin/verify
flow-doc-maintainer
- update flow steps
- update Responsible Files table
- append version history (never overwrite)
safe-refactor
- add characterization tests first
- refactor
- rerun verify
- summarize risk and coverage
go-service-skeleton
- standard layout (cmd/, internal/, pkg/)
- health, metrics, config, structured logging
- make verify/test/lint

Skill template (conceptual)

# SKILL.md
name: rails-zero-gap-endpoint
description: Implements a Rails API endpoint from a contract/spec with tests, verification, and doc updates.

## Steps
1. Read contract/spec in doc/requirements/**.
2. Identify response shapes and status codes.
3. Implement with serializers/blueprints.
4. Add request specs (success + error cases).
5. Run bin/verify; fix until green.
6. Update flow doc + PRD notes; append version history.

The point is not “more features.”
The point is standardizing your best engineering behavior.

Step 6: Add hooks so quality is automatic

Once bin/verify exists, hooks become a superpower.

High ROI hooks:

Format after edits
Block sensitive files
Don’t stop until verify passes
Auto-add a short change log entry for docs

This is how you get “ship faster” and “ship safer” at the same time.

When to use RAG vs LSP vs MCP

Use RAG when you have good docs but agents don’t see them

If you already maintain:

contracts/specs
flow docs
ADRs
runbooks

…RAG turns that into a searchable memory.

Best practice: write docs in chunks that can be retrieved (short sections, clear headings, explicit file names).

Use LSP when correctness depends on understanding symbol relationships

Refactors, renames, interface changes → you want semantic certainty.

Use MCP when the bottleneck is tool/data access

If your “context” lives outside the repo:

DB schema details
tickets/PRDs in trackers
dashboards/logs
internal service catalogs

…MCP makes that safe and standardized.

A practical daily workflow that compounds productivity

Feature workflow

Define/confirm contract/spec (or acceptance criteria)
Agent generates a plan: files + tests + risks
Implement smallest vertical slice
Run bin/verify until green
Audit for gaps ([IMPL] / [DOC])
Update flow doc + PRD notes

Bugfix workflow

Reproduce + write failing test
Minimal fix
bin/verify
Add a short note to flow doc/runbook if it’s a recurring class

Refactor workflow

Add characterization tests (freeze behavior)
Refactor
bin/verify
Optional: second agent acts as a paranoid reviewer (coverage + edge cases)

A 60-minute “starter kit” checklist

If you want immediate impact, do this in your next repo:

Add AGENTS.md
Add bin/verify (one truth command)
Add bin/test, bin/lint, bin/security, bin/format
Add /doc/ map in README (what doc is where)
Add 1 Skill for your most common task
Add 1–2 hooks to enforce formatting + verify
In CI: run bin/verify (same as local)

This is the shortest path to “significantly increase daily process.”

Closing: the real multiplier is the system

AI doesn’t make a team fast.
A fast feedback loop makes a team fast.

Agentic development works when:

Truth is easy to check (bin/verify)
Intent is easy to find (contracts + flow docs + Responsible Files)
Quality is enforced (hooks + CI)
Workflows are reusable (Skills)

Once those exist, models become replaceable.
Your process stays.

From 5-Minute Timeouts to Sub-3-Minute Builds: A Complete Guide to Rails RSpec CI Optimization

Wed, 10 Dec 2025 00:00:00 +0000

“A fast test suite isn’t a luxury—it’s the difference between deploying confidently and deploying nervously.”

Our Bitbucket Pipeline was timing out at 5 minutes. With 338 spec files, 456 RSwag integration tests, and growing, we needed a systematic approach to optimization—not just quick fixes.

This post documents how we reduced our CI build time by 60% through parallel execution, factory optimization, intelligent pipeline architecture, and eliminating hidden I/O bottlenecks.

The Problem: Death by Timeout
Diagnostic Analysis
Pipeline Architecture Optimization
Parallel Test Execution
Factory Optimization
File I/O Elimination
Test Profiling Infrastructure
RSpec Configuration Tuning
Results and Metrics
Ongoing Optimization Strategy

1. The Problem: Death by Timeout

1.1 The Symptoms

Our Bitbucket Pipeline build started failing with this error:

Exceeded build time limit of 5 minutes.
Error key: agent.step.time-limit-exceeded

The logs showed tests completing, but swagger generation pushed us over the limit:

bundle exec rspec --tag ~ci_skip --format documentation  # ~4:30
bundle exec rails rswag:specs:swaggerize                  # +0:45 = TIMEOUT

1.2 The Root Causes

After analysis, we identified multiple compounding issues:

Issue	Impact	Root Cause
Sequential execution	100%	Single-threaded test run
RSwag runs tests twice	+50%	Swagger generation re-executes integration specs
Eager factory creation	+15%	252 `let!` calls creating records unnecessarily
Disk I/O in factories	+10%	File.open for every attachment
No parallelization	100%	All 338 specs in one process
Verbose output	+5%	`--format documentation` slower than `--format progress`

1.3 Our Starting Point

Metric	Value
Total spec files	338
Integration specs (RSwag)	64
`run_test!` calls	456
Factory `create()` calls in integration	~502
Eager `let!` evaluations	252
Pipeline timeout	5 minutes
Actual runtime	5+ minutes (timeout)

2. Diagnostic Analysis

2.1 Understanding the Codebase

Before optimizing, we audited the entire test suite:

# Count spec files
find spec -name "*_spec.rb" | wc -l
# => 338

# Count integration specs (RSwag)
find spec/integration -name "*_spec.rb" | wc -l
# => 64

# Count run_test! calls
grep -c "run_test!" spec/integration/*.rb | awk -F: '{sum += $2} END {print sum}'
# => 456

# Count eager evaluations
grep -c "let!" spec/integration/*.rb | awk -F: '{sum += $2} END {print sum}'
# => 252

# Find largest spec files
find spec -name "*_spec.rb" -exec wc -l {} + | sort -n | tail -10

Key finding: companies_spec.rb was 1,476 lines—a maintenance and performance problem.

2.2 Identifying Bottlenecks

We identified these optimization opportunities:

1. Pipeline Architecture

Tests ran sequentially in a single step
Lint, security, and tests couldn’t run in parallel
RSwag swagger generation was blocking

2. Test Execution

No parallel test execution (parallel_tests gem missing)
No --fail-fast flag to stop on first failure
Verbose output format slowing things down

3. Factory Usage

let! used where let would suffice
Duplicate factory creation in each response block
File I/O for every attachment creation

4. Profiling

No visibility into slow tests
No factory usage profiling
No SQL query profiling

3. Pipeline Architecture Optimization

3.1 The Problem: Sequential Steps

Our original pipeline ran everything sequentially:

# Before: Everything in sequence
pipelines:
  default:
    - parallel:
        steps:
          - step:
              name: Lint & Security
              # ... linting
          - step:
              name: RSpec + DB prepare
              script:
                - bundle exec rspec --tag ~ci_skip --format documentation
                - bundle exec rails rswag:specs:swaggerize  # Re-runs integration specs!

Issues:

Single test step runs all 338 specs sequentially
rswag:specs:swaggerize re-runs integration specs for swagger generation
No separation of fast vs slow tests

3.2 The Solution: Three-Way Parallelization

We split the pipeline into three parallel test steps:

# After: Parallel execution by test type
image: ruby:3.4

options:
  size: 4x
  max-time: 10  # Increased from 5 to 10 minutes

definitions:
  caches:
    bundler: vendor/bundle
    bootsnap: tmp/cache/bootsnap  # NEW: Cache Rails boot
  services:
    postgres:
      image: postgres:16
      variables:
        POSTGRES_DB: testapp_test
        POSTGRES_USER: postgres
        POSTGRES_PASSWORD: password

pipelines:
  default:
    - parallel:
        steps:
          # Step 1: Linting & Security (no database needed)
          - step:
              name: Lint & Security
              caches:
                - bundler
              script:
                - bundle exec rubocop
                - bundle exec brakeman -q -w2
                - bundle exec bundle audit check --update

          # Step 2: Fast specs (models, blueprints, policies)
          - step:
              name: Unit & Model Tests
              services:
                - postgres
              caches:
                - bundler
                - bootsnap
              script:
                - bundle exec rspec spec/models spec/blueprints spec/policies \
                    spec/services spec/jobs --tag ~ci_skip --fail-fast --format progress

          # Step 3: Integration specs + Swagger generation
          - step:
              name: Integration Tests + Swagger
              services:
                - postgres
              caches:
                - bundler
                - bootsnap
              script:
                - bundle exec rspec spec/integration spec/requests \
                    --tag ~ci_skip --fail-fast --format progress
                - bundle exec rails rswag:specs:swaggerize

    # Sequential step after parallel completes
    - step:
        name: Verify Seeds
        services:
          - postgres
        caches:
          - bundler
        script:
          - bundle exec rails db:seed:replant

3.3 Key Changes Explained

Change	Before	After	Impact
Timeout	5 min	10 min	Safety margin
Parallel steps	2	3	~40% faster
Test splitting	None	Unit vs Integration	Better parallelization
Bootsnap cache	Missing	Added	Faster Rails boot
Output format	`documentation`	`progress`	Less I/O overhead
Fail behavior	Run all	`--fail-fast`	Fail faster

3.4 Why Split Unit and Integration Tests?

Unit tests (models, policies, services):

Fast to execute (minimal database interaction)
Many small files
Good candidates for parallel execution

Integration tests (RSwag, requests):

Slower (full request/response cycle)
Generate Swagger documentation
Benefit from running together for swagger generation

By splitting them, we:

Get faster feedback on unit test failures
Keep swagger generation with its source specs
Allow better cache utilization

4. Parallel Test Execution

4.1 Adding parallel_tests Gem

The parallel_tests gem runs specs across multiple CPU cores:

# Gemfile
group :test do
  gem "parallel_tests"
  gem "test-prof"  # Profiling
end

4.2 Pipeline Integration

For multi-process execution in CI:

# Option A: parallel_tests with database per process
script:
  - bundle exec rake parallel:create parallel:prepare
  - bundle exec parallel_rspec spec/ --tag ~ci_skip -n 4

# Option B: Simple parallel within steps (what we chose)
# Each parallel step runs a subset of specs

We chose Option B because:

Bitbucket Pipelines already provides step-level parallelism
Simpler database setup (one DB per step)
Easier to debug failures
Cache utilization is better with separate steps

4.3 Local Development Usage

For local development, parallel_tests shines:

# Run all specs across 4 cores
bundle exec parallel_rspec spec/ -n 4

# Run with specific pattern
bundle exec parallel_rspec spec/models -n auto

# Avatar parallel execution
PROFILE=1 bundle exec parallel_rspec spec/

5. Factory Optimization

5.1 The Problem: Eager Evaluation

Our integration specs used let! excessively:

# Before: Every response block creates its own fixtures
path '/api/v1/projects' do
  response '200', 'successful' do
    let!(:player)    { create(:player) }     # Created immediately
    let!(:avatar) { create(:avatar) }  # Created immediately
    let!(:project) { create(:project) }  # Created immediately
    run_test!
  end

  response '422', 'validation error' do
    let!(:player)    { create(:player) }     # DUPLICATE creation!
    let!(:avatar) { create(:avatar) }  # DUPLICATE creation!
    run_test!
  end
end

Issues:

let! creates records even if not referenced
Each response block creates duplicate fixtures
252 eager evaluations across integration specs

5.2 The Solution: Lazy Evaluation

Convert let! to let where the lazy evaluation chain works:

# After: Lazy evaluation with explicit eager loading only when needed
path '/api/v1/projects' do
  response '200', 'successful' do
    let(:player)    { create(:player) }
    let(:avatar) { create(:avatar, player: player) }
    # Project must exist before request - keep as let!
    let!(:project) { create(:project, avatar: avatar) }

    let(:Authorization) { "Bearer #{jwt_for(player)}" }  # References player → triggers creation
    let(:avatar_id) { avatar.id }  # References avatar → triggers creation

    run_test!
  end
end

The key insight: let is lazy—it only creates records when first accessed. If Authorization references player, and avatar_id references avatar, the chain triggers automatically.

Use let! only when:

Record must exist in database before the request
No other let references it
It’s tested via side effects (e.g., count changes)

5.3 Before vs After: projects_spec.rb

# Before: 26 let! calls
response '200', 'successful' do
  let!(:player)    { create(:player) }
  let!(:avatar) { create(:avatar, player: player) }
  let!(:project) { Project.create!(avatar: avatar, ...) }
  # ...
end

# After: 5 let! calls (only for records that must pre-exist)
response '200', 'successful' do
  let(:player)    { create(:player) }
  let(:avatar) { create(:avatar, player: player) }
  let!(:project) { Project.create!(avatar: avatar, ...) }
  # ...
end

Reduction: 26 → 5 eager evaluations in one file.

5.4 Shared Contexts for Common Patterns

For repeated patterns, use shared contexts:

# spec/support/shared_examples/company_authenticated_context.rb
RSpec.shared_context 'authenticated company player' do
  let(:company) { create(:company) }
  let(:company_owner) { create(:player, :client, company: company, company_role: :owner) }
  let(:Authorization) { "Bearer #{jwt_for(company_owner)}" }
  let(:company_id) { company.id }
end

# Usage in specs
RSpec.describe 'Companies API' do
  include_context 'authenticated company player'

  path '/api/v1/companies/{company_id}/avatar' do
    # company, company_owner, Authorization, company_id all available
    # Created lazily when first accessed
  end
end

6. File I/O Elimination

6.1 The Problem: Disk Reads for Every Attachment

Our attachment factory read from disk on every creation:

# Before: Disk I/O for every attachment
factory :attachment do
  after(:build) do |attachment|
    next if attachment.file.attached?

    attachment.file.attach(
      io: File.open(Rails.root.join("spec/fixtures/files/image.png")),  # DISK I/O!
      filename: "image.png",
      content_type: "image/png"
    )
  end
end

Impact:

85+ create(:attachment) calls across specs
Each call reads from disk
~0.5-2ms per read adds up

6.2 The Solution: In-Memory Minimal Files

We created minimal valid files stored in memory:

# spec/support/minimal_files.rb
module MinimalFiles
  # Minimal valid 1x1 transparent PNG (67 bytes)
  PNG = [
    0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,  # PNG signature
    0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52,  # IHDR chunk
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,  # 1x1 dimensions
    0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53,  # 8-bit RGB
    0xDE, 0x00, 0x00, 0x00, 0x0C, 0x49, 0x44, 0x41,  # IDAT chunk
    0x54, 0x08, 0xD7, 0x63, 0xF8, 0x0F, 0x00, 0x00,  # Compressed data
    0x01, 0x01, 0x00, 0x05, 0x18, 0xD8, 0x4E, 0x00,  # CRC
    0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, 0xAE,  # IEND chunk
    0x42, 0x60, 0x82                                  # CRC
  ].pack("C*").freeze

  # Minimal valid PDF (193 bytes)
  PDF = <<~PDF.freeze
    %PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/MediaBox[0 0 612 792]/Parent 2 0 R>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    178
    %%EOF
  PDF

  def self.io_for(type)
    case type.to_sym
    when :png, :image, :avatar, :real_image
      StringIO.new(PNG)
    when :pdf, :file, :document
      StringIO.new(PDF)
    else
      StringIO.new(PDF)
    end
  end

  def self.content_type_for(type)
    case type.to_sym
    when :png, :image, :avatar, :real_image then "image/png"
    else "application/pdf"
    end
  end

  def self.filename_for(type)
    case type.to_sym
    when :png, :image, :avatar, :real_image then "image.png"
    else "test.pdf"
    end
  end
end

6.3 Updated Factory

# spec/factories/attachments.rb
factory :attachment do
  after(:build) do |attachment|
    next if attachment.file.attached?

    file_type = case attachment.attachment_type
                when "image", "avatar", "real_image" then :image
                else :pdf
                end

    # In-memory file - no disk I/O!
    attachment.file.attach(
      io: MinimalFiles.io_for(file_type),
      filename: MinimalFiles.filename_for(file_type),
      content_type: MinimalFiles.content_type_for(file_type)
    )
  end
end

6.4 Why This Is Safe

Concerns we addressed:

“Will validations still work?”
- Yes! The files have valid headers (PNG signature, PDF structure)
- Content-type validation passes
“What about fixture_file_upload in request specs?”
- Unchanged! Request specs that test actual upload behavior still use fixture_file_upload
- Only factory-created attachments use in-memory files
“Is 67 bytes enough for a valid image?”
- Yes! It’s a valid 1x1 transparent PNG
- Any library reading it will parse it correctly

6.5 Performance Impact

Operation	Before	After	Improvement
Read fixture file	~0.5-2ms	~0.01ms	50-200x
Memory allocation	File buffer	String	Minimal
I/O operations	Disk read	None	Eliminated

7. Test Profiling Infrastructure

7.1 Adding test-prof Gem

The test-prof gem provides deep insights into test performance:

# Gemfile
group :test do
  gem "test-prof"
end

7.2 TestProf Configuration

# spec/support/test_prof.rb
if defined?(TestProf)
  # FactoryProf: Avatar factory usage
  TestProf::FactoryProf.configure do |config|
    config.mode = :flamegraph if ENV["FPROF_FLAMEGRAPH"]
  end

  # EventProf: Avatar SQL queries and factory creates
  TestProf::EventProf.configure do |config|
    config.per_example = true if ENV["EVENT_PROF_EXAMPLES"]
  end
end

# Native FactoryBot profiling (no TestProf required)
if ENV["FACTORY_PROF"]
  RSpec.configure do |config|
    factory_stats = Hash.new { |h, k| h[k] = { count: 0, time: 0.0 } }

    config.before(:suite) do
      ActiveSupport::Notifications.subscribe("factory_bot.run_factory") do |*args|
        event = ActiveSupport::Notifications::Event.new(*args)
        factory_stats[event.payload[:name]][:count] += 1
        factory_stats[event.payload[:name]][:time] += event.duration
      end
    end

    config.after(:suite) do
      puts "\n\n=== FactoryBot Profiling Report ==="
      puts "%-40s %10s %15s" % ["Factory", "Count", "Time (ms)"]
      puts "-" * 67

      factory_stats.sort_by { |_, v| -v[:time] }.first(20).each do |name, stats|
        puts "%-40s %10d %15.2f" % [name, stats[:count], stats[:time]]
      end
    end
  end
end

7.3 Profiling Commands

# Avatar slow examples (show top 10)
PROFILE=1 bundle exec rspec

# Avatar factory usage (find N+1 factories)
FPROF=1 bundle exec rspec

# Avatar factory usage with flamegraph
FPROF=1 FPROF_FLAMEGRAPH=1 bundle exec rspec

# Avatar SQL queries
EVENT_PROF=sql.active_record bundle exec rspec

# Avatar factory create events
EVENT_PROF=factory.create bundle exec rspec

# Native factory profiling
FACTORY_PROF=1 bundle exec rspec

# Combined: slow examples + factory stats
PROFILE=1 FACTORY_PROF=1 bundle exec rspec

7.4 Sample Factory Avatar Output

=== FactoryBot Profiling Report ===
Factory                                      Count       Time (ms)
-------------------------------------------------------------------
player                                           156         1234.56
avatar                                        142          987.65
company                                         89          654.32
attachment                                      85          432.10
job_post                                        45          321.00
company_benefit                                 34          210.50
...
-------------------------------------------------------------------
TOTAL                                          892         5432.10

What to look for:

Factories with high count but low time → OK
Factories with low count but high time → Optimize factory
Factories called more than expected → Check for cascades

7.5 TestProf’s let_it_be

For specs that can share fixtures across examples:

# spec/rails_helper.rb
require 'test_prof/recipes/rspec/let_it_be'

# Usage in specs
RSpec.describe AvatarBlueprint do
  # Created once for ALL examples in this describe block
  let_it_be(:player) { create(:player) }
  let_it_be(:avatar) { create(:avatar, player: player) }

  it "serializes id" do
    # player and avatar are reused, not recreated
    expect(described_class.render_as_hash(avatar)).to include(id: avatar.id)
  end

  it "serializes username" do
    # Same player and avatar from above
    expect(described_class.render_as_hash(avatar)).to include(username: avatar.username)
  end
end

Use let_it_be when:

Fixtures are read-only in all examples
Examples don’t modify the records
You have many examples using the same data

8. RSpec Configuration Tuning

8.1 Updated spec_helper.rb

# spec/spec_helper.rb
RSpec.configure do |config|
  # Focus on tagged examples during development
  config.filter_run_when_matching :focus

  # Persist example status for --only-failures
  config.example_status_persistence_file_path = "spec/examples.txt"

  # Avatar slow examples (enable via PROFILE=1)
  config.avatar_examples = ENV["PROFILE"] ? 10 : false

  # Random order to surface order dependencies
  config.order = :random
  Kernel.srand config.seed
end

8.2 Key Configuration Choices

Setting	Value	Rationale
`avatar_examples`	Conditional	Only avatar when explicitly requested
`order`	`:random`	Surface hidden dependencies
`example_status_persistence`	Enabled	Support `--only-failures`
`filter_run_when_matching :focus`	Enabled	Focus on tagged tests during dev

8.3 .rspec File

--require spec_helper

Keep it minimal. Command-line options are easier to manage in CI.

9. Results and Metrics

9.1 Before vs After Comparison

Metric	Before	After	Improvement
Pipeline timeout	5 min	10 min	2x headroom
Parallel steps	2	3	50% more parallelism
Actual build time	5+ min (timeout)	~3 min	60% faster
`let!` calls	252	~150	40% reduction
Disk I/O per run	85+ file reads	0	Eliminated
Test output	Verbose	Progress	Less I/O
Fail behavior	Run all	Fail-fast	Faster feedback

9.2 Pipeline Execution Timeline

Before:

[Lint & Security] ████████░░░░░░░░░░ 2:00
                  [RSpec + Swagger] ██████████████████ 5:00+ TIMEOUT!

After:

[Lint & Security] ████████░░░░░░░░░░ 2:00
[Unit Tests]      ████████░░░░░░░░░░ 1:30
[Integration]     ████████████░░░░░░ 2:30
                           [Seeds]  ████░░░░░░░░░░░░░░ 0:30
─────────────────────────────────────────────────────────────
Total wall time: ~3:00 (limited by slowest parallel step)

9.3 What We Shipped

Component	Files Changed
Gemfile	Added `parallel_tests`, `test-prof`
bitbucket-pipelines.yml	Restructured to 3 parallel steps
spec/spec_helper.rb	Enabled profiling, focus filtering
spec/rails_helper.rb	Added TestProf recipes
spec/support/test_prof.rb	New profiling configuration
spec/support/minimal_files.rb	New in-memory file module
spec/factories/attachments.rb	Use MinimalFiles
spec/factories/gallery_images.rb	Use MinimalFiles
spec/integration/projects_spec.rb	Convert let! → let
spec/integration/working_knowledge_spec.rb	Convert let! → let
spec/support/shared_examples/*	New shared contexts
spec/support/shared_schemas/*	Extracted common schemas

10. Ongoing Optimization Strategy

10.1 Monitoring Commands

Run these periodically to identify new bottlenecks:

# Find slowest 10 examples
PROFILE=1 bundle exec rspec

# Find factory N+1 issues
FPROF=1 bundle exec rspec

# Identify SQL-heavy tests
EVENT_PROF=sql.active_record bundle exec rspec

# Check factory creation counts
FACTORY_PROF=1 bundle exec rspec

10.2 Guidelines for New Tests

Prefer let over let! unless record must pre-exist
Use shared contexts for repeated patterns
Keep integration specs focused — one endpoint per file if large
Use let_it_be for read-only fixtures in model/blueprint specs
Avoid factory cascades — use build_stubbed when possible

10.3 CI Pipeline Guidelines

Split by test type — Unit vs Integration
Use --fail-fast in CI — Fail fast, fix fast
Cache aggressively — Bundler, Bootsnap, build artifacts
Monitor build times — Set alerts for regression

10.4 Future Optimizations

If builds slow down again:

Add more parallel steps — Split integration by domain
Use parallel_tests within steps — Multi-process per step
Consider test splitting by timing — Distribute by historical runtime
Evaluate CI provider — GitHub Actions has better parallelization

Key Takeaways

Avatar before optimizing — Measure, don’t guess
Parallelize at multiple levels — Pipeline steps + test processes
Lazy evaluation is your friend — let over let!
Eliminate I/O — In-memory beats disk every time
Fail fast — --fail-fast saves minutes on broken builds
Split wisely — Unit tests separate from integration
Cache everything — Bundler, Bootsnap, build artifacts
Document your profiling — Future you will thank present you

The Real Win

The 60% speed improvement is great, but the real win is confidence. Fast tests mean:

Developers run tests locally more often
CI catches issues before they merge
Deployments happen without anxiety
The test suite stays fast as the codebase grows

Slow tests become ignored tests. Ignored tests become broken tests. Broken tests become production bugs.

Invest in your test infrastructure. It pays dividends every single day.

Resources

parallel_tests: github.com/grosser/parallel_tests
test-prof: test-prof.evilmartians.io
RSpec Best Practices: betterspecs.org
FactoryBot Optimization: thoughtbot/factory_bot
Bitbucket Pipelines Reference: support.atlassian.com/bitbucket-cloud/docs/bitbucket-pipelines-configuration-reference
GitHub Actions for Rails: docs.github.com/actions

This post documents the optimization of the TestApp API test suite from timeout failures to sub-3-minute builds. The patterns described here—parallel execution, factory optimization, I/O elimination, and profiling infrastructure—are applicable to any Rails application with a growing test suite.

Turning Neverlands Into Design Fuel: A Browser Bot + GPT-5.1 Game Analyst

Sat, 06 Dec 2025 00:00:00 +0000

TL;DR

We built a browser bot + GPT-5.1 analyst that logs into neverlands.ru, captures real game screens, and turns them into structured JSON.

The goal is game design research, not automation: extract systems, loops, and UX patterns to feed your own GDD.

Everything runs locally: credentials live in .env, GPT only ever sees HTML snapshots, not your password.

The stack is small and explicit: Node 18 + Playwright + dotenv + OpenAI API, wired through a few focused TypeScript scripts.

Why build a bot for Neverlands?

Neverlands is a long-running browser MMORPG with mature systems: inventory, combat, economy, events, social layers. Instead of cloning it, we want to study it:

What progression and compulsion loops does it use?
How are shops, currencies, and sinks structured?
Which UI patterns make the game readable (or confusing)?

Doing this manually is slow. Screenshots pile up, notes get messy, and you miss subtle connections. The solution: a repeatable pipeline that:

Logs into your account.
Visits interesting screens (home, character, inventory, shop, PvP…).
Saves HTML + screenshots.
Asks GPT-5.1 to extract features and player needs into machine-readable JSON.

Those JSON files become the raw material for your game design document, where you remix Neverlands-inspired ideas into your own world.

Architecture at a glance

The repo is intentionally small:

bot/        # Playwright automation
  login.ts  # log in + save session
  crawl.ts  # visit screens + save HTML/PNG

analyzer/
  analyzeScreens.ts  # send HTML to GPT-5.1 using promt.md

data/
  session/   # Playwright storage state
  raw/       # captured HTML + screenshots
  analysis/  # GPT JSON outputs

promt.md     # "game design analyst" prompt template
doc/         # human docs (setup, usage, dev)

The heart of the system is promt.md: a prompt that tells GPT-5.1 to behave like a game design analyst. For each HTML snapshot it:

Identifies visible systems/features (e.g., daily quests, energy, shop widgets).
Describes how they seem to work from the UI.
Classifies the player need they target (progression, social, mastery, etc.).
Suggests how you might adapt the idea for your own MMORPG.

Outputs are strict JSON, so you can script on top of them later.

Technical implementation

bot/login.ts uses Playwright to open http://www.neverlands.ru/, fill the login form, and save a session:

Credentials come from .env via dotenv:
- NEVERLANDS_USERNAME, NEVERLANDS_PASSWORD.
Form selectors are configurable:
- NEVERLANDS_USERNAME_SELECTOR, NEVERLANDS_PASSWORD_SELECTOR, NEVERLANDS_SUBMIT_SELECTOR.
The URL is normalized so any https://neverlands.ru is rewritten to http://www.neverlands.ru/.
On success, storage state is written to data/session/neverlands.json.

You run it with:

npm run login

2. Crawling key game screens

bot/crawl.ts reuses the saved session to open specific URLs and capture HTML + PNG:

Screens are defined as a small list of { id, url }.
For each screen, we:
- page.goto(url, { waitUntil: 'networkidle' }).
- Save DOM: data/raw/<id>.html.
- Save screenshot: data/raw/<id>.png.

You can start with home, then add pages like inventory, character, shop, or any internal route Neverlands exposes.

Run the crawl:

npm run crawl

3. GPT-5.1 analysis

analyzer/analyzeScreens.ts reads every *.html file in data/raw/, then calls the OpenAI Chat Completions API:

Uses OPENAI_API_KEY from .env.
Defaults to OPENAI_MODEL=gpt-5.1 (configurable).
Loads promt.md as the system message.
Sends the HTML as the user message.
Requests response_format: json_object to keep outputs parseable.

Each result is saved as data/analysis/<screen>-<hash>.json, giving you versioned feature maps per screen.

Run analysis:

npm run analyze

From JSON to a game design document

Once you have JSON outputs, you’re holding a Neverlands feature index. Typical next steps:

Group features by system: combat, economy, social, events, meta.
Identify loops: daily quests → currencies → shops → upgrades.
Tag ideas as keep / adapt / avoid for your own game.

Because the analysis is structured, it’s easy to:

Generate Markdown “inspiration cards” per feature.
Build tables comparing Neverlands to other games you crawl later.
Feed the JSON back into another GPT-5.1 pass to draft full sections of your GDD.

The bot doesn’t design the game for you—but it amplifies your research so you can spend time on synthesis, not screenshot wrangling.

Safety, ToS, and scope

Even though neverlands.ru allows bots, we built this stack with a conservative mindset:

Credentials live only in .env on your machine.
GPT never sees your password or cookies, only HTML.
The intended use is analysis, not auto-play or farming.
Screen lists are small and intentional, not full-site crawlers.

If you adapt this to other games, always re-check each game’s ToS and keep your rate of requests reasonable.

Where to go next

With the core pipeline in place, the most interesting work is ahead:

Add more screens and flows (e.g., onboarding, high-level PvP, events).
Enrich promt.md with new fields (risk flags, UX pain points, monetization patterns).
Build a small UI or static site to browse the analyzed features.
Compare Neverlands against other browser MMORPGs using the same pipeline.

The end goal: a living game design document for your own project, grounded in real, battle-tested systems—but with your own take on what makes them fun.

From Rails Spaghetti to Structured Code: Integrating dry-rb into Your API

Thu, 04 Dec 2025 00:00:00 +0000

“The best code isn’t clever—it’s obvious. dry-rb makes Rails code obvious.”

Every Rails developer has written code that works but feels wrong. Manual type coercion scattered across controllers. Validation logic duplicated between models and services. Deeply nested conditionals handling success and failure cases. Configuration constants scattered across files. Side effects mixed with business logic. These patterns work, but they accumulate into technical debt.

After shipping dozens of API endpoints, we integrated dry-rb into our Rails API. This post documents the transformation—with real before/after examples showing how each gem improves specific code patterns.

The Problem: Rails Patterns That Don’t Scale
The Solution: dry-rb Gem Suite
dry-types: Type-Safe Enums and Coercion
dry-struct: Immutable Data Structures
dry-monads: Functional Error Handling
dry-validation: Contract-Based Validation
dry-container + dry-auto_inject: Dependency Injection
dry-matcher: Pattern Matching for Results
dry-configurable: Thread-Safe Configuration
dry-initializer: Declarative Parameter DSL
dry-events: Pub/Sub Event System
Other dry-rb Gems Worth Exploring
Benefits and Tradeoffs
Conclusion

1. The Problem: Rails Patterns That Don’t Scale

1.1 The “Rails Way” Has Limits

Rails conventions are excellent for getting started quickly. But as applications grow, certain patterns become problematic:

Pattern	Works For	Breaks When
Hash params everywhere	Simple CRUD	Complex nested data structures
ActiveRecord validations	Model-level rules	Cross-field business logic
Controller conditionals	Simple flows	Multiple success/failure paths
Manual type coercion	Occasional use	Dozens of fields need processing
Class method calls	Small apps	Testing requires stubbing globals
Scattered constants	One-off values	Configuration needs structure
Inline side effects	Simple actions	Need audit trail or event-driven architecture

1.2 Real Example: Avatar Actions Payload

We needed to serialize client-specific avatar data. Here’s what the original code looked like:

# Original: 70+ lines of manual validation and coercion
def build_actions_payload(options)
  actions = extract_actions_data(options)
  result = {}

  # Manual enum validation
  status = actions[:access_status].to_s
  result[:access_status] = ACCESS_STATUS_VALUES.include?(status) ? status : "none"

  # Manual boolean coercion
  result[:avatar_viewed] = actions[:avatar_viewed] == true
  result[:is_saved] = actions[:is_saved] == true

  # Manual conditional inclusion
  if actions[:thumb_status].present?
    thumb = actions[:thumb_status].to_s
    result[:thumb_status] = thumb if THUMB_STATUS_VALUES.include?(thumb)
  end

  if actions[:applied_at].present?
    value = actions[:applied_at]
    result[:applied_at] = value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
  end

  if actions.key?(:access_expired)
    result[:access_expired] = actions[:access_expired] == true
  end

  if actions[:access_end_reason].present?
    reason = actions[:access_end_reason].to_s
    result[:access_end_reason] = reason if ACCESS_END_REASON_VALUES.include?(reason)
  end

  # ... 30 more lines
  result
end

Problems:

❌ Manual type coercion (to_s, == true) repeated everywhere
❌ Validation scattered (constants + inline checks)
❌ Hard to test—tightly coupled to Blueprint
❌ No type safety—wrong data silently coerced
❌ Verbose—business logic drowns in boilerplate

2. The Solution: dry-rb Gem Suite

The dry-rb ecosystem provides focused, composable gems for common problems:

Gem	Purpose	Replaces
dry-types	Type definitions with constraints	Manual enum validation
dry-struct	Immutable typed objects	Hash manipulation
dry-monads	Functional result handling	try/rescue + conditionals
dry-validation	Contract-based validation	Scattered validation logic
dry-schema	Schema coercion	Strong parameters edge cases
dry-container	Dependency registry	Global class references
dry-auto_inject	Constructor injection	Manual dependency passing
dry-matcher	Result pattern matching	Case statements on results
dry-configurable	Thread-safe configuration	Scattered constants
dry-initializer	Param/option DSL	Boilerplate initialize methods
dry-events	Pub/sub event system	Inline side effects

Our Gemfile Addition

# Gemfile
# Dry-rb gems for structured types, validation, and functional patterns
gem "dry-types", "~> 1.7"
gem "dry-struct", "~> 1.6"
gem "dry-monads", "~> 1.6"
gem "dry-validation", "~> 1.11"
gem "dry-schema", "~> 1.14"
gem "dry-container", "~> 0.11"
gem "dry-auto_inject", "~> 0.9"
gem "dry-matcher", "~> 1.0"
gem "dry-configurable", "~> 1.2"
gem "dry-initializer", "~> 3.1"
gem "dry-events", "~> 1.0"

3. dry-types: Type-Safe Enums and Coercion

3.1 The Problem: Scattered Constants and Manual Checks

# Before: Constants scattered, validation repeated
class AvatarBlueprint < ApplicationBlueprint
  ACCESS_STATUS_VALUES = %w[none requested approved denied removed shared].freeze
  THUMB_STATUS_VALUES = %w[liked disliked].freeze
  ACCESS_END_REASON_VALUES = %w[expired declined blocked removed].freeze

  def build_actions_payload(options)
    status = actions[:access_status].to_s
    result[:access_status] = ACCESS_STATUS_VALUES.include?(status) ? status : "none"
    # Repeated for every enum field...
  end
end

Issues:

Constants defined in one class, used elsewhere
Validation logic duplicated wherever enums are checked
No automatic coercion or defaults

3.2 The Solution: Centralized Type Registry

# app/types.rb
require "dry/types"

module Types
  include Dry.Types()

  # Common types with safe defaults
  SafeBool = Types::Bool.fallback(false)
  OptionalString = Types::String.optional
  OptionalInteger = Types::Integer.optional

  # ISO8601 timestamp coercion
  ISO8601String = Types::String.optional.constructor do |value|
    next nil if value.nil?
    case value
    when Time, DateTime, ActiveSupport::TimeWithZone
      value.iso8601
    else
      value.to_s
    end
  end

  # Avatar Actions enums - SINGLE SOURCE OF TRUTH
  module Avatars
    ACCESS_STATUS_VALUES = %w[none requested approved denied removed shared].freeze
    AccessStatus = Types::String.enum(*ACCESS_STATUS_VALUES).fallback("none")

    THUMB_STATUS_VALUES = %w[liked disliked].freeze
    ThumbStatus = Types::String.enum(*THUMB_STATUS_VALUES).optional

    ACCESS_END_REASON_VALUES = %w[expired declined blocked removed].freeze
    AccessEndReason = Types::String.enum(*ACCESS_END_REASON_VALUES).optional
  end
end

Benefits:

✅ Enums defined once, reusable everywhere
✅ Built-in validation (invalid values → constraint error or fallback)
✅ Automatic coercion with .constructor
✅ Safe defaults with .fallback()
✅ Self-documenting—type definitions are specifications

3.3 Usage Examples

# Enum validation is automatic
Types::Avatars::AccessStatus["approved"]  # => "approved"
Types::Avatars::AccessStatus["invalid"]   # => "none" (fallback)
Types::Avatars::AccessStatus[nil]         # => "none" (fallback)

# Boolean coercion with fallback
Types::SafeBool[true]   # => true
Types::SafeBool[nil]    # => false (fallback, not nil!)

# Timestamp coercion
Types::ISO8601String[Time.current]           # => "2025-12-04T09:30:00Z"
Types::ISO8601String["2025-12-04T09:30:00Z"] # => "2025-12-04T09:30:00Z"
Types::ISO8601String[nil]                    # => nil

4. dry-struct: Immutable Data Structures

4.1 The Problem: Hash Manipulation Everywhere

# Before: Raw hash with manual processing
def build_actions
  actions = {}
  actions[:access_status] = compute_access_status
  actions[:avatar_viewed] = compute_avatar_viewed
  actions[:is_saved] = compute_is_saved
  # No guarantee of structure
  # Caller must know what keys exist
  # Mutable—anyone can modify
  actions
end

Issues:

No schema—structure discovered at runtime
Mutable—data can change unexpectedly
Manual coercion needed when consuming
No IDE autocompletion

4.2 The Solution: Typed Immutable Struct

# app/structs/avatars/actions.rb
require "dry/struct"

module Avatars
  class Actions < Dry::Struct
    # Allow string keys from input hash
    transform_keys(&:to_sym)

    # Required fields with defaults (always present in payload)
    attribute? :access_status, Types::Avatars::AccessStatus.default("none".freeze)
    attribute? :avatar_viewed, Types::SafeBool.default(false)
    attribute? :is_saved, Types::SafeBool.default(false)

    # Optional fields (only in payload when present)
    attribute? :note, Types::OptionalString
    attribute? :thumb_status, Types::Avatars::ThumbStatus
    attribute? :applied_at, Types::ISO8601String
    attribute? :access_expired, Types::Bool.optional
    attribute? :access_end_reason, Types::Avatars::AccessEndReason
    attribute? :chat_id, Types::OptionalInteger
    attribute? :is_shared, Types::Bool.optional

    # Clean serialization for API response
    def to_payload
      payload = {
        access_status: access_status,
        avatar_viewed: avatar_viewed,
        is_saved: is_saved
      }

      # Add optional fields only when present
      payload[:note] = note if note.present?
      payload[:thumb_status] = thumb_status if thumb_status.present?
      payload[:applied_at] = applied_at if applied_at.present?
      payload[:access_expired] = access_expired unless access_expired.nil?
      payload[:access_end_reason] = access_end_reason if access_end_reason.present?
      payload[:chat_id] = chat_id if chat_id.present?
      payload[:is_shared] = true if is_shared == true

      payload
    end
  end
end

4.3 Before vs After Comparison

Before (manual hash building):

# 70+ lines scattered across service and blueprint
def build_actions_payload(options)
  actions = extract_actions_data(options)
  result = {}
  status = actions[:access_status].to_s
  result[:access_status] = ACCESS_STATUS_VALUES.include?(status) ? status : "none"
  result[:avatar_viewed] = actions[:avatar_viewed] == true
  # ... 60 more lines of manual processing
end

After (struct instantiation):

# Service creates struct
actions = Avatars::Actions.new(
  access_status: compute_access_status,
  avatar_viewed: compute_avatar_viewed,
  is_saved: compute_is_saved,
  chat_id: find_chat_room&.id
)

# Blueprint just calls to_payload
field :actions do |_avatar, options|
  options.dig(:context, :actions).to_payload
end

Reduction: 70+ lines → ~15 lines

4.4 Benefits of dry-struct

Aspect	Raw Hash	Dry::Struct
Schema	Implicit	Explicit, documented
Type safety	None	Enforced at construction
Defaults	Manual	Declarative
Mutability	Mutable	Immutable
IDE support	None	Autocomplete attributes
Testability	Test whole flow	Test struct in isolation

5. dry-monads: Functional Error Handling

5.1 The Problem: Nested Conditionals

# Before: Conditional soup
def call
  return nil unless avatar.present?
  return nil unless client_user.present?
  return nil unless client_user.client?
  return nil unless avatar_user.present?

  # Happy path finally...
  build_actions
rescue StandardError => e
  Rails.logger.error(e)
  nil
end

Issues:

Early returns obscure happy path
Error information lost (just returns nil)
Caller can’t distinguish “no data” from “error”
No composability

5.2 The Solution: Result Monad

# app/services/avatars/actions_builder.rb
require "dry/monads"

module Avatars
  class ActionsBuilder
    include Dry::Monads[:result]

    def call
      return Success(default_actions_struct) unless valid_context?

      Success(build_actions_struct)
    end

    private

    def valid_context?
      avatar.present? &&
        client_user.present? &&
        client_user.client? &&
        avatar_user.present?
    end

    def default_actions_struct
      Avatars::Actions.new(
        access_status: "none",
        avatar_viewed: false,
        is_saved: false
      )
    end

    def build_actions_struct
      Avatars::Actions.new(
        access_status: compute_access_status,
        avatar_viewed: compute_avatar_viewed,
        # ... other fields
      )
    end
  end
end

5.3 Controller Integration

# app/controllers/api/v1/game_controller.rb
def show
  flags = visibility_flags.get(@avatar)
  context = { visibility_flags: flags, host: request.base_url }

  if current_user&.client?
    result = actions_builder.call(avatar: @avatar, client_user: current_user)
    context[:actions] = result.value! if result.success?
  end

  render json: { data: AvatarBlueprint.render_as_hash(@avatar, context: context) }
end

5.4 Pattern Matching with Results

# For more complex flows, pattern match on Result
result = ActionsBuilder.call(avatar: @avatar, client_user: current_user)

case result
in Success(actions)
  render_success(actions.to_payload)
in Failure[:invalid_context, reason]
  Rails.logger.warn("Invalid context: #{reason}")
  render_default_actions
in Failure[:database_error, exception]
  Sentry.capture_exception(exception)
  head :internal_server_error
end

5.5 Composing Multiple Operations

# Chain operations that might fail
class ProcessOrder
  include Dry::Monads[:result, :do]

  def call(order_params)
    order = yield validate_order(order_params)
    player = yield find_user(order.player_id)
    payment = yield charge_payment(player, order.total)
    yield send_confirmation(player, order, payment)

    Success(order)
  end

  private

  def validate_order(params)
    # Returns Success(order) or Failure([:validation, errors])
  end

  def charge_payment(player, amount)
    # Returns Success(payment) or Failure([:payment_failed, reason])
  end
end

The yield keyword automatically unwraps Success values and short-circuits on Failure.

6. dry-validation: Contract-Based Validation

6.1 The Problem: Validation Logic Everywhere

# Before: Validation scattered across controller, model, and service
class ItemsController < ApplicationController
  def create
    # Controller validation
    return render_error("Title required") if params[:title].blank?
    return render_error("Invalid status") unless VALID_STATUSES.include?(params[:status])

    @item = Item.new(item_params)
    # Model validation runs here too...
  end
end

class Item < ApplicationRecord
  # Model validation
  validates :title, presence: true
  validates :status, inclusion: { in: VALID_STATUSES }
  validate :price_must_be_positive_for_published
end

Issues:

Validation logic duplicated (controller + model)
Cross-field rules awkward in ActiveRecord
Hard to test validation in isolation
Error messages inconsistent

6.2 The Solution: Validation Contracts

# app/contracts/avatars/actions_contract.rb
require "dry/validation"

module Avatars
  class ActionsContract < Dry::Validation::Contract
    # Schema definition - coerces and validates structure
    params do
      optional(:access_status).filled(:string)
      optional(:avatar_viewed).filled(:bool)
      optional(:is_saved).filled(:bool)
      optional(:note).maybe(:string)
      optional(:thumb_status).maybe(:string)
      optional(:access_expired).maybe(:bool)
      optional(:access_end_reason).maybe(:string)
      optional(:chat_id).maybe(:integer)
    end

    # Enum validation rules
    rule(:access_status) do
      next if value.nil?
      unless Types::Avatars::ACCESS_STATUS_VALUES.include?(value)
        key.failure("must be one of: #{Types::Avatars::ACCESS_STATUS_VALUES.join(', ')}")
      end
    end

    rule(:thumb_status) do
      next if value.nil?
      unless Types::Avatars::THUMB_STATUS_VALUES.include?(value)
        key.failure("must be one of: #{Types::Avatars::THUMB_STATUS_VALUES.join(', ')}")
      end
    end

    # Cross-field validation
    rule(:access_end_reason, :access_expired) do
      if values[:access_end_reason].present? && values[:access_expired] != true
        key(:access_end_reason).failure("requires access_expired to be true")
      end
    end
  end
end

6.3 Using Contracts

contract = Avatars::ActionsContract.new
result = contract.call(params.to_unsafe_h)

if result.success?
  # Validated and coerced data
  actions = Avatars::Actions.new(result.to_h)
else
  # Structured errors
  render json: { errors: result.errors.to_h }, status: :unprocessable_entity
end

6.4 Contract vs Model Validation

Aspect	ActiveRecord Validation	Dry::Validation Contract
When runs	Before save	Before touching model
Cross-field rules	Custom validators	Declarative `rule` blocks
Testability	Requires model instance	Pure Ruby, no DB
Reusability	Tied to model	Standalone class
Error format	Rails format	Customizable
Coercion	Limited	Built-in via schema

Use both: Contracts for input validation (API layer), ActiveRecord for data integrity (persistence layer).

7. dry-container + dry-auto_inject: Dependency Injection

7.1 The Problem: Hard-Coded Dependencies

# Before: Tight coupling to class names
class GameController < ApplicationController
  def show
    flags = Visibility::AvatarVisibilityFlags.get(@avatar)
    result = Avatars::ActionsBuilder.call(avatar: @avatar, client_user: current_user)
    # ...
  end
end

# Testing requires stubbing constants
RSpec.describe GameController do
  before do
    allow(Visibility::AvatarVisibilityFlags).to receive(:get).and_return({})
    allow(Avatars::ActionsBuilder).to receive(:call).and_return(Success({}))
  end
end

Issues:

Can’t easily swap implementations
Testing requires monkey-patching
Dependencies hidden in method bodies
No central registry of services

7.2 The Solution: Container + Injection

# app/container.rb
require "dry/container"
require "dry/auto_inject"

class AppContainer
  extend Dry::Container::Mixin

  # Register services
  register(:actions_builder) { Avatars::ActionsBuilder }
  register(:visibility_flags) { Visibility::AvatarVisibilityFlags }

  # Future additions
  # register(:email_service) { EmailService.new }
  # register(:payment_gateway) { Stripe::Client.new(ENV['STRIPE_KEY']) }
end

# For POROs (constructor injection)
Import = Dry::AutoInject(AppContainer)

# For Rails controllers (memoized accessors)
module Deps
  def self.included(base)
    base.class_eval do
      AppContainer.keys.each do |key|
        define_method(key) do
          @_deps_cache ||= {}
          @_deps_cache[key] ||= AppContainer[key]
        end
      end
    end
  end
end

7.3 Controller with Injection

# app/controllers/api/v1/game_controller.rb
class GameController < ApplicationController
  include Deps  # Inject all registered dependencies

  def show
    flags = visibility_flags.get(@avatar)           # Use injected service
    result = actions_builder.call(...)               # Use injected builder
    # ...
  end
end

7.4 Testing with Injection

# Spec: Easy stubbing via dependency override
RSpec.describe GameController do
  let(:mock_builder) { double("ActionsBuilder") }
  let(:mock_flags) { double("VisibilityFlags") }

  before do
    # Override container registrations for test
    AppContainer.stub(:actions_builder, mock_builder)
    AppContainer.stub(:visibility_flags, mock_flags)
  end

  it "uses injected dependencies" do
    expect(mock_flags).to receive(:get).and_return({})
    expect(mock_builder).to receive(:call).and_return(Success(default_actions))

    get :show, params: { id: avatar.id }
  end
end

7.5 Benefits of Dependency Injection

Without DI	With DI
`ClassName.call(...)` scattered	Centralized registry
Test with `allow(ClassName)`	Test with mock injection
Change implementation = change every caller	Change registration only
Dependencies implicit	Dependencies explicit

8. dry-matcher: Pattern Matching for Results

8.1 The Problem: Verbose Result Handling

# Before: Manual success/failure checks
def show
  result = actions_builder.call(avatar: @avatar, client_user: current_user)

  if result.success?
    context[:actions] = result.value!
  else
    case result.failure
    when :not_found
      head :not_found
    when :unauthorized
      head :unauthorized
    else
      render json: { error: result.failure }, status: :unprocessable_entity
    end
  end
end

Issues:

Verbose conditional logic
Easy to forget failure cases
Not composable
Repeated patterns across controllers

8.2 The Solution: Pattern Matching Concern

# app/controllers/concerns/result_matchable.rb
require "dry/matcher/result_matcher"

module ResultMatchable
  extend ActiveSupport::Concern

  included do
    class_attribute :result_matcher, default: Dry::Matcher::ResultMatcher
  end

  # Match on a Dry::Monads::Result with pattern matching
  def match_result(result, &block)
    result_matcher.call(result, &block)
  end

  # Extract value from Success or return nil for Failure
  def unwrap_result(result)
    result.success? ? result.value! : nil
  end

  # Returns [success?, value_or_error]
  def result_tuple(result)
    if result.success?
      [true, result.value!]
    else
      [false, result.failure]
    end
  end
end

8.3 Controller with Pattern Matching

# app/controllers/api/v1/game_controller.rb
class GameController < ApplicationController
  include ResultMatchable  # Add pattern matching

  def show
    result = actions_builder.call(avatar: @avatar, client_user: current_user)

    # Simple extraction
    context[:actions] = unwrap_result(result)

    # Or full pattern matching for complex flows
    match_result(result) do |m|
      m.success { |actions| context[:actions] = actions }
      m.failure(:not_found) { head :not_found; return }
      m.failure(:unauthorized) { head :unauthorized; return }
      m.failure { |error| Rails.logger.warn("Actions failed: #{error}") }
    end

    render json: { data: AvatarBlueprint.render_as_hash(@avatar, context: context) }
  end
end

8.4 Before vs After

Before:

# 15 lines of conditional logic
if result.success?
  context[:actions] = result.value!
else
  case result.failure
  when :not_found then head :not_found
  when :unauthorized then head :unauthorized
  else render_error(result.failure)
  end
end

After:

# 1 line for simple cases
context[:actions] = unwrap_result(result)

# Or declarative matching for complex cases
match_result(result) do |m|
  m.success { |v| context[:actions] = v }
  m.failure(:not_found) { head :not_found }
  m.failure { |e| render_error(e) }
end

8.5 Benefits

Without dry-matcher	With dry-matcher
`if/case` statements	Declarative blocks
Easy to miss cases	Exhaustive matching
Scattered handling	Centralized concern
Hard to test branches	Each handler testable

9. dry-configurable: Thread-Safe Configuration

9.1 The Problem: Scattered Constants

# Before: Constants scattered across files
class AvatarBlueprint < ApplicationBlueprint
  ACCESS_STATUS_VALUES = %w[none requested approved denied removed shared].freeze
  CACHE_TTL = 5.minutes
end

class AccessRequest < ApplicationRecord
  EXPIRY_DAYS = 30
end

class GameController < ApplicationController
  MAX_PER_PAGE = 100
end

Issues:

Configuration scattered across classes
Hard to find all config values
No nesting or organization
Testing requires constant stubbing
Not thread-safe for dynamic changes

9.2 The Solution: Centralized Configuration

# app/config/avatar_config.rb
require "dry/configurable"

class AvatarConfig
  extend Dry::Configurable

  # Actions settings
  setting :actions do
    setting :cache_ttl, default: 5.minutes
    setting :default_access_status, default: "none"
    setting :default_avatar_viewed, default: false
    setting :default_is_saved, default: false

    setting :access_status_values, default: %w[none requested approved denied removed shared].freeze
    setting :thumb_status_values, default: %w[liked disliked].freeze
    setting :access_end_reason_values, default: %w[expired declined blocked removed].freeze

    setting :status_mapping, default: {
      "pending" => "requested",
      "approved" => "approved",
      "declined" => "denied",
      "blocked" => "denied",
      "expired" => "removed"
    }.freeze
  end

  # Visibility settings
  setting :visibility do
    setting :default_mode, default: "visible"
    setting :modes, default: %w[visible semi_anonymous fully_anonymous].freeze
  end

  # Access request settings
  setting :access do
    setting :request_expiry_days, default: 30
    setting :auto_approve_verified_companies, default: false
    setting :max_pending_per_company, default: 100
  end

  # Event publishing settings
  setting :events do
    setting :publish_avatar_views, default: true
    setting :publish_access_events, default: true
  end
end

9.3 Usage in Code

# Access nested settings with dot notation
AvatarConfig.config.actions.cache_ttl           # => 5.minutes
AvatarConfig.config.actions.status_mapping      # => {"pending" => "requested", ...}
AvatarConfig.config.visibility.default_mode     # => "visible"
AvatarConfig.config.access.request_expiry_days  # => 30

# Use in service objects
class ActionsBuilder
  def default_actions_struct
    Avatars::Actions.new(
      access_status: config.default_access_status,
      avatar_viewed: config.default_avatar_viewed,
      is_saved: config.default_is_saved
    )
  end

  private

  def config
    AvatarConfig.config.actions
  end
end

9.4 Testing with Configuration

RSpec.describe ActionsBuilder do
  # Override config for test
  before do
    allow(AvatarConfig.config.actions).to receive(:cache_ttl).and_return(0)
  end

  # Or use configure block
  around do |example|
    original = AvatarConfig.config.actions.cache_ttl
    AvatarConfig.configure { |c| c.actions.cache_ttl = 0 }
    example.run
    AvatarConfig.configure { |c| c.actions.cache_ttl = original }
  end
end

9.5 Before vs After

Before:

# Hunt through 10 files to find all avatar-related constants
grep -r "CACHE_TTL\|EXPIRY_DAYS\|MAX_" app/

After:

# One file, organized by domain
AvatarConfig.config  # => nested configuration tree

9.6 Benefits

Scattered Constants	dry-configurable
Find: grep across codebase	Find: one file
Organize: N/A	Organize: nested settings
Test: stub constants	Test: configure block
Thread-safe: No	Thread-safe: Yes
Document: comments	Document: structure IS docs

10. dry-initializer: Declarative Parameter DSL

10.1 The Problem: Boilerplate Initialize Methods

# Before: Manual parameter handling
class ActionsBuilder
  def initialize(avatar:, client_user:)
    @avatar = avatar
    @client_user = client_user
    @avatar_user = avatar&.player
  end

  def self.call(avatar:, client_user:)
    new(avatar: avatar, client_user: client_user).call
  end

  private

  attr_reader :avatar, :client_user, :avatar_user
end

Issues:

Boilerplate @x = x assignments
Manual attr_reader for each param
No type coercion
No default values
self.call pattern repeated everywhere

10.2 The Solution: Declarative Parameters

# app/services/avatars/actions_builder.rb
require "dry/initializer"

module Avatars
  class ActionsBuilder
    extend Dry::Initializer

    # Required parameters
    param :avatar
    param :client_user

    # Derived option with default
    option :avatar_user, default: proc { avatar&.player }

    def self.call(avatar:, client_user:)
      new(avatar, client_user).call
    end

    def call
      return Success(default_actions_struct) unless valid_context?
      Success(build_actions_struct)
    end

    # params are accessible directly - no attr_reader needed
    private

    def valid_context?
      avatar.present? && client_user.present? && client_user.client?
    end
  end
end

10.3 Advanced Features

class OrderProcessor
  extend Dry::Initializer

  # Required param with type coercion
  param :order_id, Types::Integer

  # Optional param with default
  param :notify, default: proc { true }

  # Named options (keyword args)
  option :logger, default: proc { Rails.logger }
  option :mailer, default: proc { OrderMailer }

  # Type-checked option
  option :priority, Types::String.enum("low", "normal", "high"), default: proc { "normal" }

  # Reader visibility
  option :api_key, reader: :private

  def call
    logger.info("Processing order #{order_id} with priority #{priority}")
    # ...
  end
end

# Usage
processor = OrderProcessor.new(123, true, priority: "high")
processor.order_id  # => 123
processor.priority  # => "high"

10.4 Before vs After

Before (19 lines):

class ActionsBuilder
  def initialize(avatar:, client_user:)
    @avatar = avatar
    @client_user = client_user
    @avatar_user = avatar&.player
  end

  def self.call(avatar:, client_user:)
    new(avatar: avatar, client_user: client_user).call
  end

  private

  attr_reader :avatar, :client_user, :avatar_user

  def call
    # ...
  end
end

After (10 lines):

class ActionsBuilder
  extend Dry::Initializer

  param :avatar
  param :client_user
  option :avatar_user, default: proc { avatar&.player }

  def self.call(avatar:, client_user:)
    new(avatar, client_user).call
  end

  def call
    # ...
  end
end

10.5 Benefits

Manual Initialize	dry-initializer
`@x = x` boilerplate	Declarative `param`/`option`
Manual `attr_reader`	Auto-generated readers
No type coercion	Built-in type support
No defaults DSL	`default: proc { }`
All public readers	`reader: :private` option

11. dry-events: Pub/Sub Event System

11.1 The Problem: Inline Side Effects

# Before: Side effects mixed with business logic
class GameController < ApplicationController
  def show
    @avatar = Avatar.find(params[:id])

    # Business logic
    context = build_context(@avatar)

    # Side effect #1: Analytics
    Analytics.track("avatar_viewed", {
      avatar_id: @avatar.id,
      viewer_id: current_user&.id
    })

    # Side effect #2: Logging
    AuditLog.create!(
      action: "avatar_view",
      resource: @avatar,
      player: current_user
    )

    # Side effect #3: Cache warming
    AvatarCacheWarmer.perform_async(@avatar.id) if should_warm_cache?

    render json: { data: AvatarBlueprint.render_as_hash(@avatar, context: context) }
  end
end

Issues:

Controller bloated with side effects
Hard to test business logic in isolation
Adding new side effects = modifying controller
Side effects tightly coupled to triggering code
No audit trail of “what events exist”

11.2 The Solution: Event Publisher

# app/events/publisher.rb
require "dry/events"

class EventPublisher
  include Dry::Events::Publisher[:app]

  # Avatar events
  register_event("avatar.viewed")
  register_event("avatar.actions_computed")

  # Access request events
  register_event("access.requested")
  register_event("access.approved")
  register_event("access.declined")

  # Chat events
  register_event("chat.room_accessed")

  class << self
    def instance
      @instance ||= new
    end

    def publish(event_name, payload = {})
      return unless should_publish?(event_name)

      instance.publish(event_name, payload.merge(published_at: Time.current))
    end

    def subscribe(listener_or_event, &block)
      if block_given?
        instance.subscribe(listener_or_event, &block)
      else
        instance.subscribe(listener_or_event)
      end
    end

    private

    def should_publish?(event_name)
      return false unless AvatarConfig.config.events.publish_avatar_views if event_name.start_with?("avatar.")
      return false unless AvatarConfig.config.events.publish_access_events if event_name.start_with?("access.")
      true
    end
  end
end

11.3 Publishing Events

# app/controllers/api/v1/game_controller.rb
class GameController < ApplicationController
  def show
    @avatar = Avatar.find(params[:id])
    context = build_context(@avatar)

    # Publish event - side effects handled by subscribers
    EventPublisher.publish("avatar.viewed", {
      avatar_id: @avatar.id,
      viewer_id: current_user&.id,
      viewer_role: current_user&.role
    })

    render json: { data: AvatarBlueprint.render_as_hash(@avatar, context: context) }
  end
end

# app/services/avatars/actions_builder.rb
class ActionsBuilder
  def call
    actions = build_actions_struct

    # Publish event with computed data
    EventPublisher.publish("avatar.actions_computed", {
      avatar_id: avatar.id,
      client_player_id: client_user.id,
      access_status: actions.access_status,
      has_chat: actions.chat_id.present?
    })

    Success(actions)
  end
end

11.4 Subscribing to Events

# config/initializers/event_subscribers.rb

# Block-based subscriber
EventPublisher.subscribe("avatar.viewed") do |event|
  Analytics.track("avatar_view", event.payload)
end

# Object-based subscriber
class AuditListener
  def on_avatar_viewed(event)
    AuditLog.create!(
      action: "avatar_view",
      resource_type: "Avatar",
      resource_id: event.payload[:avatar_id],
      player_id: event.payload[:viewer_id],
      occurred_at: event.payload[:published_at]
    )
  end

  def on_access_requested(event)
    AuditLog.create!(action: "access_request", **event.payload)
  end

  def on_access_approved(event)
    AuditLog.create!(action: "access_approval", **event.payload)
  end
end

EventPublisher.subscribe(AuditListener.new)

# Conditional subscriber
class CacheWarmerListener
  def on_avatar_viewed(event)
    return unless should_warm_cache?(event.payload[:avatar_id])

    AvatarCacheWarmer.perform_async(event.payload[:avatar_id])
  end

  private

  def should_warm_cache?(avatar_id)
    # Logic to determine if cache should be warmed
  end
end

EventPublisher.subscribe(CacheWarmerListener.new)

11.5 Before vs After

Before (controller with inline side effects):

def show
  @avatar = Avatar.find(params[:id])

  # Side effect #1
  Analytics.track("avatar_viewed", { avatar_id: @avatar.id })

  # Side effect #2
  AuditLog.create!(action: "avatar_view", resource: @avatar)

  # Side effect #3
  AvatarCacheWarmer.perform_async(@avatar.id)

  render json: { data: AvatarBlueprint.render_as_hash(@avatar) }
end

After (clean controller, events handle side effects):

def show
  @avatar = Avatar.find(params[:id])

  EventPublisher.publish("avatar.viewed", {
    avatar_id: @avatar.id,
    viewer_id: current_user&.id
  })

  render json: { data: AvatarBlueprint.render_as_hash(@avatar) }
end

11.6 Testing Events

RSpec.describe GameController do
  describe "GET #show" do
    it "publishes avatar.viewed event" do
      expect(EventPublisher).to receive(:publish).with(
        "avatar.viewed",
        hash_including(avatar_id: avatar.id, viewer_id: player.id)
      )

      get :show, params: { id: avatar.id }
    end
  end
end

RSpec.describe AuditListener do
  describe "#on_avatar_viewed" do
    let(:event) { double(payload: { avatar_id: 1, viewer_id: 2, published_at: Time.current }) }

    it "creates audit log entry" do
      expect { subject.on_avatar_viewed(event) }.to change(AuditLog, :count).by(1)
    end
  end
end

11.7 Benefits

Inline Side Effects	dry-events
Mixed with business logic	Separated via pub/sub
Hard to test in isolation	Each listener testable
Adding effects = modify caller	Adding effects = new subscriber
No event catalog	`register_event` documents all
Tight coupling	Loose coupling
Synchronous only	Async-ready (queue subscribers)

12. Other dry-rb Gems Worth Exploring

12.1 dry-transaction: Multi-Step Business Operations

Perfect for complex workflows like order processing or player registration:

# app/transactions/create_order.rb
class CreateOrder
  include Dry::Transaction

  step :validate
  step :create_order
  step :charge_payment
  step :send_confirmation

  private

  def validate(input)
    contract = OrderContract.new
    result = contract.call(input)
    result.success? ? Success(result.to_h) : Failure(result.errors)
  end

  def create_order(input)
    order = Order.create!(input)
    Success(order)
  rescue ActiveRecord::RecordInvalid => e
    Failure(e.message)
  end

  def charge_payment(order)
    # Payment logic...
    Success(order)
  end

  def send_confirmation(order)
    OrderMailer.confirmation(order).deliver_later
    Success(order)
  end
end

# Usage
result = CreateOrder.new.call(order_params)
result.success? # => true/false

12.2 dry-effects: Algebraic Effects

Advanced: dependency injection via effects (alternative to dry-container):

class ProcessPayment
  include Dry::Effects.Reader(:current_user)
  include Dry::Effects.Resolve(:payment_gateway)

  def call(amount)
    gateway = resolve(:payment_gateway)
    gateway.charge(current_user, amount)
  end
end

# Provide effects at call site
result = Dry::Effects.handler.with(
  current_user: player,
  resolve: { payment_gateway: StripeGateway.new }
) { ProcessPayment.new.call(100) }

12.3 Gem Selection Guide

Gem	When to Use	Complexity
dry-types	Any project (foundational)	Low
dry-struct	Data transfer objects, value objects	Low
dry-configurable	Configuration management	Low
dry-initializer	Service object parameters	Low
dry-monads	Service objects with failures	Medium
dry-validation	API input validation	Medium
dry-container	Large apps, testing focus	Medium
dry-matcher	Result pattern matching	Medium
dry-events	Event-driven architecture	Medium
dry-transaction	Multi-step workflows	Medium
dry-effects	Advanced FP patterns	High

13. Benefits and Tradeoffs

13.1 Benefits

1. Explicit Over Implicit

# Before: What can access_status be? Check the code...
result[:access_status] = ACCESS_STATUS_VALUES.include?(status) ? status : "none"

# After: The type IS the documentation
attribute :access_status, Types::Avatars::AccessStatus  # Enum is explicit

2. Testability

# Before: Test through controller/blueprint
it "returns correct access_status" do
  get "/avatars/1", headers: auth_headers
  expect(response.body).to include('"access_status":"approved"')
end

# After: Unit test the struct directly
it "coerces invalid status to none" do
  actions = Avatars::Actions.new(access_status: "invalid")
  expect(actions.access_status).to eq("none")
end

3. Composability

# Combine types to build complex structures
CompanyAvatar = Types::Hash.schema(
  name: Types::String,
  employees: Types::Array.of(EmployeeStruct),
  settings: Types::Hash.schema(
    visibility: Types::Avatars::VisibilityMode,
    features: Types::Array.of(Types::String)
  )
)

4. Error Messages

# dry-validation provides structured errors
contract.call(thumb_status: "invalid").errors.to_h
# => { thumb_status: ["must be one of: liked, disliked"] }

5. Event-Driven Architecture

# Before: Side effects scattered in controllers
Analytics.track(...)
AuditLog.create!(...)
CacheWarmer.perform_async(...)

# After: Single event, multiple handlers
EventPublisher.publish("avatar.viewed", { ... })

6. Centralized Configuration

# Before: grep -r "CACHE_TTL" app/
# After: AvatarConfig.config.actions.cache_ttl

13.2 Tradeoffs

1. Learning Curve

Team needs to learn dry-rb idioms
Functional programming concepts (monads, composition)
More files/classes than “Rails way”

2. Indirection

Types defined in one place, used in another
Following data flow requires understanding container
Events may be handled far from where they’re published

3. Overhead for Simple Cases

# For a simple boolean flag, this is overkill:
attribute :is_active, Types::Bool.default(false)

# This is fine:
attr_accessor :is_active

4. Gems Add Dependencies

11 gems for full suite
Version compatibility to manage
Bundle size increases

13.3 When to Use dry-rb

✅ Good Fit:

APIs with complex data contracts
Services with multiple failure modes
Apps where testability is priority
Teams comfortable with FP concepts
Large apps with many developers
Event-driven or audit-heavy systems

❌ Poor Fit:

Simple CRUD apps
Prototypes/MVPs
Teams unfamiliar with FP
Performance-critical hot paths (slight overhead)

14. Conclusion

Integrating dry-rb into our Rails API transformed code that “worked” into code that’s obvious, testable, and maintainable:

Metric	Before	After
Actions payload code	70+ lines	15 lines
Type validation	Manual per-field	Declarative
Error handling	try/rescue + nil	Result monad
Dependencies	Hard-coded classes	Injected
Configuration	Scattered constants	Centralized
Side effects	Inline in controllers	Event-driven
Service parameters	Manual initialize	Declarative DSL
Result handling	if/case statements	Pattern matching
Test isolation	Integration only	Unit + integration
Gems used	0	11

Key Takeaways

Start with dry-types — It’s foundational and low-risk
Add dry-struct for data transfer — Especially for API responses
Use dry-monads in services — Replace boolean/nil returns
Add dry-validation for API inputs — Before data hits your models
Use dry-configurable early — Centralize config before it scatters
Add dry-initializer to services — Reduce boilerplate immediately
Introduce dry-container gradually — When testing pain increases
Add dry-matcher for cleaner controllers — Pattern matching is elegant
Use dry-events for side effects — Decouple analytics, logging, notifications
Don’t over-engineer — A simple hash is fine for simple data

The Return on Investment

The initial investment—learning curves, refactoring, new patterns—pays dividends in:

Fewer bugs — Type mismatches caught at construction, not runtime
Faster debugging — Follow explicit contracts, not implicit conventions
Easier onboarding — Types and events document themselves
Confident refactoring — Change implementation, types verify compatibility
Testable architecture — Unit test components in isolation
Scalable patterns — Event-driven architecture grows with your app

dry-rb doesn’t replace Rails conventions—it complements them where they fall short. Use the right tool for each job.

Resources

dry-rb Official Site: dry-rb.org
dry-rb GitHub: github.com/dry-rb
dry-types Documentation: dry-rb.org/gems/dry-types
dry-monads Documentation: dry-rb.org/gems/dry-monads
dry-validation Documentation: dry-rb.org/gems/dry-validation
dry-events Documentation: dry-rb.org/gems/dry-events
dry-configurable Documentation: dry-rb.org/gems/dry-configurable
dry-initializer Documentation: dry-rb.org/gems/dry-initializer
dry-matcher Documentation: dry-rb.org/gems/dry-matcher
Trailblazer (alternative): trailblazer.to (uses dry-rb under the hood)

This post documents our integration of 11 dry-rb gems into the TestApp API. The patterns described here reduced our Avatar Actions payload logic from 70+ lines to 15, improved test coverage, established event-driven architecture, and created patterns that scale across 100+ endpoints.

From MySQL to PostgreSQL: A Practical Migration Guide for Rails APIs

Wed, 03 Dec 2025 00:00:00 +0000

“The best time to write database-agnostic code is from day one. The second best time is before your migration.”

When we started building the TestApp API, we chose MySQL for its familiarity and ease of setup. As our requirements grew—AI vector embeddings, geospatial queries, graph routing—we realized PostgreSQL wasn’t just an alternative, it was a necessity.

This post documents our migration journey and shares the patterns that made it nearly painless.

Why We Migrated
The Database-Agnostic Foundation
The Migration Process
PostgreSQL vs MySQL: A Technical Comparison
Advanced PostgreSQL Features
Multi-Schema Architecture
Migration Tips and Lessons Learned

1. Why We Migrated

1.1 The Growing Feature Requirements

Our application started as a straightforward REST API. Over time, we needed:

Requirement	MySQL Solution	PostgreSQL Solution
Vector similarity search (AI)	External service (Pinecone, Weaviate)	Native `pgvector` extension
Geospatial queries	Limited spatial functions	PostGIS (industry standard)
Graph routing	External graph DB	pgRouting extension
Full-text search	Basic FULLTEXT	Powerful tsvector/tsquery
JSON querying	JSON functions (limited)	JSONB with GIN indexes

The math was simple: Three external services vs. one PostgreSQL instance.

1.2 The Hidden Costs of Multiple Databases

Running MySQL + Pinecone + a graph database meant:

3x infrastructure complexity — More services to monitor, scale, and pay for
Data synchronization overhead — Keeping vector embeddings in sync with source data
Network latency — Cross-service queries add milliseconds
Operational burden — Different backup strategies, different failure modes

PostgreSQL with extensions gave us one database to rule them all.

1.3 Our Starting Point

Before migration, our codebase analysis revealed:

Category	Count	Status
MySQL-specific SQL	1 function	Required fix
JSON columns	45	Upgrade to JSONB
Check constraints	11	Already compatible
Raw SQL queries	15+	Already compatible
Configuration files	4	Required update

98% of our code was already database-agnostic. This wasn’t luck—it was intentional architecture.

2. The Database-Agnostic Foundation

2.1 Why Database-Agnostic Code Matters

Writing database-agnostic code isn’t about planning to switch databases. It’s about:

Portability — Your code works on any database Rails supports
Testability — SQLite in CI, PostgreSQL in production
Maintainability — Standard patterns are easier to understand
Future-proofing — Requirements change; your code adapts

2.2 The Rules We Follow

Our AGENTS.md (development guidelines) includes this rule:

Rule #9: Database-agnostic queries. Use Arel and ActiveRecord abstractions instead of raw SQL or database-specific syntax. This ensures portability when migrating databases.

2.3 Patterns That Work Everywhere

✅ Use ActiveRecord Query Interface

# Good: Works on any database
Player.where(status: :active)
    .where("created_at > ?", 1.week.ago)
    .order(created_at: :desc)
    .limit(10)

✅ Use Arel for Complex Queries

# Good: Database-agnostic date ranges
class CreditTransaction < ApplicationRecord
  scope :by_requested_dates, ->(dates) {
    ranges = Array(dates).filter_map do |date|
      year, month = date.split("-").map(&:to_i)
      start_date = Time.zone.local(year, month, 1).beginning_of_day
      end_date = start_date.end_of_month.end_of_day
      arel_table[:created_at].between(start_date..end_date)
    end
    where(ranges.reduce(:or))
  }
end

✅ Use Standard SQL Functions

# Good: LOWER, COALESCE, CASE work everywhere
scope :search, ->(term) {
  where("LOWER(name) LIKE :term OR LOWER(email) LIKE :term",
        term: "%#{term.downcase}%")
}

# Good: COALESCE for fallbacks
order(Arel.sql("COALESCE(last_message_at, created_at) DESC"))

# Good: CASE for conditional ordering
order(Arel.sql("CASE WHEN status = 'urgent' THEN 0 ELSE 1 END"))

✅ Process Dates in Ruby

# Good: Fetch timestamps, format in Ruby
def self.date_buckets_for(player, field:)
  pluck(field)
    .filter_map { |timestamp| timestamp&.strftime("%Y-%m") }
    .uniq
    .first(24)
end

2.4 Patterns to Avoid

❌ MySQL-Specific Functions

# Bad: DATE_FORMAT is MySQL-only
month_sql = "DATE_FORMAT(created_at, '%Y-%m')"

# PostgreSQL equivalent: TO_CHAR(created_at, 'YYYY-MM')
# Better: Process in Ruby (see above)

❌ Database-Specific Syntax

# Bad: MySQL's IFNULL
where("IFNULL(deleted_at, NOW()) > ?", 1.day.ago)

# Good: Standard COALESCE
where("COALESCE(deleted_at, CURRENT_TIMESTAMP) > ?", 1.day.ago)

❌ String Concatenation Operators

# Bad: MySQL uses CONCAT(), PostgreSQL uses ||
select("CONCAT(first_name, ' ', last_name) AS full_name")

# Good: Use Ruby
def full_name
  "#{first_name} #{last_name}"
end

3. The Migration Process

3.1 Pre-Migration Audit

Before touching any configuration, we audited the entire codebase:

# Find MySQL-specific SQL
grep -r "DATE_FORMAT\|GROUP_CONCAT\|IFNULL\|BINARY\s" app/

# Find raw SQL that might be problematic
grep -r "\.where.*Arel\.sql\|execute\|connection\." app/

# Check for MySQL gem references
grep -r "mysql" Gemfile config/

Our findings:

Issue	Location	Fix
`DATE_FORMAT`	`app/models/access_request.rb`	Rewrote using Ruby
`mysql2` gem	`Gemfile`	Replaced with `pg`
MySQL config	`config/database.yml`	Rewrote for PostgreSQL
Docker MySQL	`docker-compose.dev.yml`	Replaced with PostgreSQL

3.2 The Critical Fix

The only code change required was in access_request.rb:

# Before: MySQL-specific
def self.date_buckets_for(player, field:)
  column = field.to_s
  qcol = connection.quote_column_name(column)
  month_sql = "DATE_FORMAT(#{qcol}, '%Y-%m')"  # ❌ MySQL-only

  for_user(player)
    .group(Arel.sql(month_sql))
    .pluck(Arel.sql(month_sql))
end

# After: Database-agnostic Ruby
def self.date_buckets_for(player, field:)
  column = field.to_s
  return [] unless DATE_BUCKET_FIELDS.include?(column)

  for_user(player)
    .where.not(column => nil)
    .order(column => :desc)
    .limit(500)
    .pluck(column)
    .filter_map { |timestamp| timestamp&.strftime("%Y-%m") }
    .uniq
    .first(24)
    .filter_map do |month|
      start_at = Time.zone.parse("#{month}-01")
      next unless start_at

      {
        id: month,
        name: start_at.strftime("%B %Y"),
        from: start_at.beginning_of_month.beginning_of_day.iso8601,
        to: start_at.end_of_month.end_of_day.iso8601
      }
    end
end

3.3 Configuration Changes

Gemfile:

# Remove
gem 'mysql2', '~> 0.5.6'

# Add
gem 'pg', '~> 1.5'

config/database.yml:

default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= ENV.fetch("RAILS_MAX_THREADS", 5) %>
  username: <%= ENV.fetch("POSTGRES_USER", "postgres") %>
  password: <%= ENV.fetch("POSTGRES_PASSWORD", "") %>
  host: <%= ENV.fetch("POSTGRES_HOST", "127.0.0.1") %>
  port: <%= ENV.fetch("POSTGRES_PORT", 5432) %>

development:
  <<: *default
  database: testapp_development

test:
  <<: *default
  database: testapp_test

production:
  <<: *default
  database: <%= ENV["POSTGRES_DB"] %>

docker-compose.dev.yml:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: testapp_development
    ports:
      - "5433:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 20
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

3.4 JSON to JSONB Migration

MySQL’s JSON type works, but PostgreSQL’s JSONB is superior:

# In migration files, change:
t.json :metadata

# To:
t.jsonb :metadata, default: {}

Why JSONB?

Feature	JSON	JSONB
Storage	Text (parsed each query)	Binary (pre-parsed)
Indexing	❌ Not supported	✅ GIN indexes
Operators	Basic	Rich (`@>`, `?`, `?\|`, `?&`)
Query speed	Slower	Faster
Write speed	Faster	Slightly slower

JSONB Query Examples:

# Find avatars with specific skill in JSONB array
Avatar.where("abilities @> ?", ['ruby'].to_json)

# Find players with specific setting
Player.where("settings -> 'notifications' ->> 'email' = ?", 'true')

# Check if key exists
Product.where("metadata ? 'featured'")

3.5 Running the Migration

# 1. Update gems
bundle install

# 2. Create databases
rails db:create

# 3. Run migrations
rails db:migrate

# 4. Verify schema
rails db:schema:dump

# 5. Run test suite
bundle exec rspec

# 6. Seed development data
rails db:seed

Total downtime: Zero (for development). Production required a maintenance window for data migration.

4. PostgreSQL vs MySQL: A Technical Comparison

4.1 Feature Comparison

Feature	MySQL	PostgreSQL
JSON Support	JSON type, basic functions	JSONB with GIN indexes, rich operators
Full-Text Search	FULLTEXT indexes	tsvector/tsquery, ranking, dictionaries
Geospatial	Basic spatial	PostGIS (industry standard)
Vector Search	❌ None	pgvector extension
Graph Queries	❌ None	pgRouting, Apache AGE
Arrays	❌ None	Native array types with operators
Range Types	❌ None	int4range, daterange, etc.
Check Constraints	✅ Supported	✅ Supported
Partial Indexes	❌ None	✅ Supported
Expression Indexes	❌ Limited	✅ Full support
CTEs (WITH queries)	✅ Basic	✅ Recursive, materialized
Window Functions	✅ Supported	✅ More advanced
UPSERT	`ON DUPLICATE KEY`	`ON CONFLICT` (more flexible)
Transactions	✅ InnoDB	✅ MVCC
Replication	✅ Built-in	✅ Streaming, logical

4.2 Performance Characteristics

MySQL Strengths:

Simple read-heavy workloads
Large-scale web applications with basic queries
When you need maximum reads/second on simple queries

PostgreSQL Strengths:

Complex queries with many joins
Write-heavy workloads (better MVCC)
Data integrity (stricter by default)
Advanced data types and indexing

4.3 Why PostgreSQL Won for Us

1. One Database for Everything

Instead of:

MySQL (primary data)
  + Pinecone (vector search)
  + Neo4j (graph queries)
  + Elasticsearch (full-text)

We have:

PostgreSQL
  + pgvector (vector search)
  + pgRouting (graph queries)
  + Built-in full-text search

2. Better Data Integrity

-- PostgreSQL: Strict by default
INSERT INTO players (email) VALUES ('not-an-email');
-- ERROR: violates check constraint

-- MySQL: Often silently truncates or converts
INSERT INTO players (name) VALUES ('this string is way too long for the column');
-- Silently truncated (depending on sql_mode)

3. Superior Indexing

# Partial index: Only index active players
add_index :players, :email, where: "status = 'active'"

# Expression index: Index lowercased emails
add_index :players, "LOWER(email)"

# GIN index on JSONB for fast JSON queries
add_index :avatars, :abilities, using: :gin

4. Native Array Support

# PostgreSQL array columns
t.string :tags, array: true, default: []

# Query arrays
Avatar.where("'ruby' = ANY(tags)")
Avatar.where("tags @> ARRAY[?]", ['ruby', 'rails'])

5. Advanced PostgreSQL Features

5.1 pgvector: AI Vector Embeddings

Store and query vector embeddings directly in PostgreSQL:

# Enable extension
class EnablePgvector < ActiveRecord::Migration[8.0]
  def change
    enable_extension 'vector'
  end
end

# Add vector column
class AddEmbeddingToAvatars < ActiveRecord::Migration[8.0]
  def change
    add_column :avatars, :embedding, :vector, limit: 1536  # OpenAI dimension
    add_index :avatars, :embedding, using: :ivfflat, opclass: :vector_cosine_ops
  end
end

# app/models/avatar.rb
class Avatar < ApplicationRecord
  def self.similar_to(embedding, limit: 10)
    where.not(embedding: nil)
      .order(Arel.sql("embedding <=> '#{embedding}'"))
      .limit(limit)
  end
end

# Usage
similar_avatars = Avatar.similar_to(openai_embedding, limit: 5)

5.2 PostGIS: Geospatial Queries

# Enable extension
enable_extension 'postgis'

# Add geography column
add_column :locations, :coordinates, :st_point, geographic: true
add_index :locations, :coordinates, using: :gist

# Find locations within 10km
Location.where(
  "ST_DWithin(coordinates, ST_MakePoint(?, ?)::geography, ?)",
  longitude, latitude, 10_000  # meters
)

5.3 pgRouting: Graph Algorithms

# Find shortest path between locations
execute <<-SQL
  SELECT * FROM pgr_dijkstra(
    'SELECT id, source, target, cost FROM edges',
    #{start_node},
    #{end_node},
    directed := true
  )
SQL

5.4 Full-Text Search

# Add tsvector column
add_column :articles, :searchable, :tsvector
add_index :articles, :searchable, using: :gin

# Keep it updated with a trigger
execute <<-SQL
  CREATE TRIGGER articles_searchable_update
  BEFORE INSERT OR UPDATE ON articles
  FOR EACH ROW EXECUTE FUNCTION
  tsvector_update_trigger(searchable, 'pg_catalog.english', title, body);
SQL

# Search with ranking
Article.where("searchable @@ plainto_tsquery('english', ?)", query)
       .order(Arel.sql("ts_rank(searchable, plainto_tsquery('english', '#{query}')) DESC"))

6. Multi-Schema Architecture

6.1 What Are PostgreSQL Schemas?

PostgreSQL schemas are namespaces within a single database. Think of them as folders for your tables:

database: testapp_production
├── public (default schema)
│   ├── players
│   ├── avatars
│   └── companies
├── analytics
│   ├── events
│   ├── page_views
│   └── conversions
├── audit
│   ├── player_actions
│   └── api_requests
└── cache
    ├── cached_avatars
    └── cached_searches

6.2 Benefits of Multi-Schema Architecture

1. Logical Separation Without Multiple Databases

# One connection pool, multiple schemas
class AnalyticsEvent < ApplicationRecord
  self.table_name = 'analytics.events'
end

class AuditLog < ApplicationRecord
  self.table_name = 'audit.player_actions'
end

2. Different Permissions Per Schema

-- Analytics team can only access analytics schema
GRANT USAGE ON SCHEMA analytics TO analytics_role;
GRANT SELECT ON ALL TABLES IN SCHEMA analytics TO analytics_role;

-- No access to public schema
REVOKE ALL ON SCHEMA public FROM analytics_role;

3. Simplified Backup Strategies

# Backup only the audit schema
pg_dump -n audit testapp_production > audit_backup.sql

# Backup everything except cache
pg_dump -N cache testapp_production > production_backup.sql

4. Schema-Level Maintenance

-- Truncate all cache tables without affecting production
TRUNCATE TABLE cache.cached_avatars, cache.cached_searches;

-- Drop and recreate analytics schema
DROP SCHEMA analytics CASCADE;
CREATE SCHEMA analytics;

6.3 Setting Up Multi-Schema in Rails

Migration to create schemas:

class CreateAnalyticsSchema < ActiveRecord::Migration[8.0]
  def up
    execute "CREATE SCHEMA IF NOT EXISTS analytics"
    execute "CREATE SCHEMA IF NOT EXISTS audit"
    execute "CREATE SCHEMA IF NOT EXISTS cache"
  end

  def down
    execute "DROP SCHEMA IF EXISTS cache CASCADE"
    execute "DROP SCHEMA IF EXISTS audit CASCADE"
    execute "DROP SCHEMA IF EXISTS analytics CASCADE"
  end
end

Models with schema prefixes:

# app/models/analytics/event.rb
module Analytics
  class Event < ApplicationRecord
    self.table_name = 'analytics.events'
  end
end

# app/models/audit/player_action.rb
module Audit
  class UserAction < ApplicationRecord
    self.table_name = 'audit.player_actions'
  end
end

Cross-schema queries work seamlessly:

# Join across schemas
Player.joins("JOIN audit.player_actions ON audit.player_actions.player_id = players.id")
    .where("audit.player_actions.action = ?", "login")

6.4 Schemas vs. Multiple Databases

Aspect	Multiple Databases	Multiple Schemas
Connection pools	Separate per DB	Shared
Cross-queries	Complex/impossible	Native JOINs
Transactions	Distributed (2PC)	Single transaction
Backups	Per database	Per schema or together
Permissions	Database-level	Schema-level (granular)
Migrations	Separate per DB	Single migration
Complexity	Higher	Lower
Rails support	Multiple configs	Single config

Our recommendation: Use schemas for logical separation within the same application. Use separate databases only for truly isolated services or multi-tenant SaaS.

6.5 When to Use Each Pattern

Use Multiple Schemas When:

Separating concerns (analytics, audit, cache)
Different retention policies per data type
Granular permission control needed
Data is related and needs cross-queries

Use Multiple Databases When:

Complete data isolation required (multi-tenant)
Different scaling requirements
Regulatory compliance requires separation
Microservices with independent lifecycles

7. Migration Tips and Lessons Learned

7.1 Before You Start

1. Audit your codebase thoroughly

# Find all raw SQL
grep -rn "execute\|\.sql\|Arel\.sql" app/ --include="*.rb"

# Find MySQL-specific functions
grep -rn "DATE_FORMAT\|IFNULL\|GROUP_CONCAT\|BINARY\|STRAIGHT_JOIN" app/

# Check gems for MySQL dependencies
bundle exec gem dependency mysql2

2. Run tests on PostgreSQL locally first

# config/database.yml for CI
test:
  adapter: postgresql
  database: myapp_test

3. Document all discrepancies

Create a migration checklist (like our mysql_to_postgresql.md) tracking every issue found.

7.2 Data Migration Strategies

Option A: Fresh Start (Recommended for Development)

# On PostgreSQL
rails db:create db:migrate db:seed

Option B: pgloader (For Production Data)

# Install pgloader
brew install pgloader  # or apt-get

# Create migration script
cat > migrate.load << 'EOF'
LOAD DATABASE
  FROM mysql://root:password@localhost/myapp_production
  INTO postgresql://postgres@localhost/myapp_production

WITH include drop, create tables, create indexes, reset sequences

SET work_mem to '16MB', maintenance_work_mem to '512 MB'

CAST type datetime to timestamptz using zero-dates-to-null,
     type date to date using zero-dates-to-null

ALTER SCHEMA 'myapp_production' RENAME TO 'public';
EOF

# Run migration
pgloader migrate.load

Option C: Rails-Native Export/Import

# Export from MySQL
namespace :export do
  task players: :environment do
    File.open('players.json', 'w') do |f|
      Player.find_each { |u| f.puts u.to_json }
    end
  end
end

# Import to PostgreSQL
namespace :import do
  task players: :environment do
    File.readlines('players.json').each do |line|
      Player.create!(JSON.parse(line))
    end
  end
end

7.3 Common Gotchas

1. Auto-increment vs. SERIAL

MySQL uses AUTO_INCREMENT, PostgreSQL uses SERIAL or IDENTITY. Rails handles this automatically, but check sequences after migration:

-- Fix sequence if IDs are out of sync
SELECT setval('users_id_seq', (SELECT MAX(id) FROM players));

2. Boolean Handling

MySQL often stores booleans as TINYINT(1). PostgreSQL uses native BOOLEAN:

# May need explicit casting in raw SQL
where("active = true")  # PostgreSQL
where("active = 1")     # MySQL

3. Case Sensitivity

PostgreSQL string comparisons are case-sensitive by default:

# MySQL: case-insensitive by default
Player.where(email: 'Test@Example.com')  # Finds test@example.com

# PostgreSQL: case-sensitive
Player.where("LOWER(email) = LOWER(?)", 'Test@Example.com')
# Or use citext extension for case-insensitive columns

4. Group By Strictness

PostgreSQL requires all non-aggregated columns in GROUP BY:

# MySQL: Allows this (picks arbitrary value)
select("players.*, COUNT(orders.id)")
  .joins(:orders)
  .group("players.id")

# PostgreSQL: Must include all selected columns
select("players.id, players.email, COUNT(orders.id)")
  .joins(:orders)
  .group("players.id, players.email")

7.4 Post-Migration Checklist

# 1. Verify all tests pass
bundle exec rspec

# 2. Check for deprecation warnings
RAILS_ENV=test rails runner "puts ActiveRecord::Base.connection.adapter_name"

# 3. Regenerate schema
rails db:schema:dump

# 4. Verify schema.rb has PostgreSQL syntax
grep "create_table" db/schema.rb | head

# 5. Run security scan
bundle exec brakeman -q -w2

# 6. Regenerate API documentation
bundle exec rails rswag:specs:swaggerize

# 7. Performance baseline
rails runner "Benchmark.measure { Player.count }"

7.5 Lessons We Learned

1. Write database-agnostic code from day one

The single MySQL-specific function we had took 30 minutes to rewrite. If we’d had dozens, it would have been a multi-day effort.

2. Use JSONB defaults in migrations

# Always specify defaults for JSONB
t.jsonb :settings, default: {}
t.jsonb :tags, default: []

3. Leverage PostgreSQL-specific features gradually

Don’t rewrite everything immediately. Start with:

JSONB for new features
Partial indexes for performance
Full-text search when needed

4. Monitor query performance post-migration

PostgreSQL’s query planner is different. Some queries may need new indexes:

# Add explain logging in development
ActiveRecord::Base.logger = Logger.new(STDOUT)
Player.where(status: :active).explain

5. Document your extensions

# db/migrate/001_enable_extensions.rb
class EnableExtensions < ActiveRecord::Migration[8.0]
  def change
    # Core extensions we use
    enable_extension 'pgcrypto'  # UUID generation
    enable_extension 'citext'    # Case-insensitive text

    # Feature-specific (enable when needed)
    # enable_extension 'vector'   # AI embeddings
    # enable_extension 'postgis'  # Geospatial
  end
end

Conclusion

Migrating from MySQL to PostgreSQL doesn’t have to be painful. With database-agnostic code patterns and a systematic approach, our migration required:

1 code fix (DATE_FORMAT → Ruby)
4 configuration file updates
0 model changes (beyond JSON → JSONB)
0 downtime (for development)

The benefits far outweigh the effort:

Before (MySQL + Services)	After (PostgreSQL)
3+ external services	1 database
Multiple connection pools	Single pool
Cross-service latency	Native queries
Complex sync logic	Referential integrity
Higher infrastructure cost	Lower cost

PostgreSQL isn’t just a MySQL replacement—it’s a platform for building sophisticated applications. With extensions like pgvector, PostGIS, and pgRouting, you can consolidate your entire data layer into a single, powerful database.

Key Takeaways

Write database-agnostic code — Use ActiveRecord/Arel, avoid raw SQL functions
Audit before migrating — Find MySQL-specific code early
Use JSONB over JSON — Better indexing, better queries
Consider schemas over databases — Simpler architecture, better performance
Leverage PostgreSQL features — Partial indexes, arrays, full-text search
Plan for extensions — pgvector, PostGIS, pgRouting when needed
Test thoroughly — Run your full suite on PostgreSQL before production

The best database is the one that grows with your needs. PostgreSQL does exactly that.

Resources

PostgreSQL Official Docs: postgresql.org/docs
pgvector Extension: github.com/pgvector/pgvector
PostGIS Documentation: postgis.net/docs
pgRouting Documentation: pgrouting.org
Rails PostgreSQL Guide: guides.rubyonrails.org/active_record_postgresql.html
pgloader: pgloader.io

This post documents our migration of the TestApp API from MySQL to PostgreSQL. The patterns described here enabled a migration with minimal code changes and zero regressions—proving that investment in database-agnostic code pays dividends when requirements evolve.