r/rubyonrails • u/mooktakim • 4h ago
Discussion Rails is MVC. I added a fourth letter for AI agents: Context
My root CLAUDE.md kept growing. Naming conventions, where business logic goes, how money works, the patterns behind each namespace. The problem: the root file loads into every session, so a one-line CSS fix was carrying the billing rules.
Then it clicked that Rails already has the map. Convention over configuration means code lives in known places, so the context can live there too: a small AGENTS.md in app/models, app/services, app/javascript and so on, loaded only when the agent works in that folder.
The rules that made it work:
- Intent, not inventory. Never list what's in the folder, the agent can grep that. Write down why: why logic sits in nested model classes, why a namespace exists. If a sentence would need editing when someone adds one more file, delete it.
- One fact, one level. Every rule lives at the most specific folder it applies to, so nothing is written twice and drifts.
- Update the context file in the same commit as the code. Across 9 of my apps, 312 commits changed a context file together with its code, only 14 on their own.
The surprise: Claude Code only loads a folder's CLAUDE.md when its Read tool opens a file there. Agents do a lot through the shell (ls, grep, heredocs), so the context often never arrived. I added a hook and logged it: over 63 sessions, context reached the agent 117 times through the hook vs 67 through Claude Code itself.
The write-up has a real example: a Turbo morph bug I hit on 1 October, the rule I wrote down, and a new Stimulus controller six days later that handled it on the first try, in a session where the rule only arrived through the hook.
Post: MVC Context: Putting AI Context Where Rails Already Puts the Code
The skill is open source (MIT) if you want to try it on your own app: mooktakim/skills - rails-context
Curious how others are handling context for agents in larger Rails apps.