Agents generate useful code quickly when the project is simple, documented, and predictable. Rails helps because it has strong conventions. MongoDB helps when the data already exists and the app does not need SQL migrations. The main rule is still KISS: complexity is the enemy.

Use README as the Source of Truth

The best optimization for agents is also good documentation for people: keep a short, accurate README. It should say what the app uses, how to run it, how to test it, and what rules matter.

Stack:
- Rails 8.1.3
- Ruby 4.0.5 in Docker
- Ruby 3.4.9 locally
- Mongoid 9.1.0
- Bootstrap 5.3.8

Rules:
- KISS
- no new gem unless needed
- keep controllers thin
- prefer Rails conventions
- verify with tests

This saves tokens because every future task can say: “follow the README”. The agent does not need the same architecture explanation repeated in every prompt.

Pin Versions

Specific versions matter. “Use modern Rails” is weaker than “use Rails 8.1.3”. Exact versions reduce guessing, avoid outdated examples, and make Docker, gems, generated authentication, and tests more predictable.

Good:
Use Rails 8.1.3, Mongoid 9.1.0, Bootstrap 5.3.8.
Docker targets Ruby 4.0.5.

Bad:
Use the newest Rails and make it modern.

Why MongoDB Speeds This Up

MongoDB is practical for admin panels, crawler data, logs, queues, and imported collections because the schema can already live in the data. The agent can create a Mongoid model around an existing collection and build the Rails screen from there. No SQL migration is needed for every small admin feature.

Good task:
Create a Mongoid model for an existing collection.
Add a simple Rails resource and Bootstrap form.
No SQL migration.

The important part is to still use a model. A model gives names, validations, form helpers, and a stable place for behavior.

Work Through Models

Fast code is not the same as code pasted into a controller. If the agent works through models, Rails can help with forms, paths, validation errors, and tests.

Better:
Create a model, then a resource route, then controller actions, then a form partial.

Worse:
Read params manually everywhere and pass raw hashes between views and controllers.

This is cheaper over time. The first model may take a few more lines, but every form and edit screen after that becomes simpler.

Rails Reload Is a Speed Feature

In development, Rails reloads changed code on the next request. For view, controller, helper, route, and model changes, refresh the page and check the result. Rebuild Docker only when the runtime, system packages, or Dockerfile changed.

Good:
Change the view, refresh the page, run the relevant tests.

Wasteful:
Rebuild the whole image after every HTML or controller change.

Keep Navigation One Layer Deep

Navigation also affects agent speed. A simple one-layer navigation is easier for people and easier for agents. Avoid deep menus, special cases, and repeated markup. One clear grouping is usually enough.

Good:
One simple navigation layer.
Shared partial.
Clear names.

Bad:
Nested menus, duplicated links, custom behavior in many places.

Small Prompts Beat Large Dumps

Do not paste a full rendered page if one repeated block explains the problem. Give the route, the expected behavior, and the constraint.

Context: follow README.
Goal: compact one table row layout.
Constraint: keep raw JSON pretty printed.
Verify: run Rails tests and summarize changed files.

This is enough for an agent to inspect the codebase and make a focused change. Large HTML dumps should be reserved for layout bugs where the rendered output is the actual evidence.

Practical Rules

  • Keep README short and current.
  • Pin framework, Ruby, database, and UI library versions.
  • Prefer Rails conventions and generators, then simplify.
  • Use Mongoid models for existing MongoDB collections.
  • Keep navigation flat and obvious.
  • Reload Rails pages for app changes; rebuild Docker only for runtime changes.
  • Ask for one behavior change at a time.
  • Delete complexity early. Complexity is expensive for humans and agents.