You've heard the hype. You've rolled your eyes at a few AI demos. You're not trying to rewrite your app from scratch... you just want to get some things done without losing your mind. Fair enough. Let's talk.
Your teammates who've been experimenting with this for the past few months have an unfair advantage right now. This guide is about closing that gap, without the hype or the rewrites.
Claude Code is a terminal-based AI coding agent from Anthropic. This guide covers how Ruby on Rails developers at Planet Argon are using it in practice: which model to reach for (Sonnet vs Opus), how to write RSpec and Minitest tests with it, how to debug backtraces and error monitoring payloads, and how to structure your CLAUDE.md without turning it into a dumping ground.
By default, Claude Code asks before it edits files, runs commands, or makes changes. It will pause and check with you. This is a feature, not a bug. If you're seeing Claude make changes without asking, you (or someone on your team) probably started the session with --dangerously-skip-permissions. That flag exists, it has its uses, but understand what you're enabling when you use it. Verify everything Claude writes before you commit it. The default behavior is your friend, especially when you're still getting a feel for how it works.
Before Claude starts editing files, put it in plan mode first. Press Shift+Tab twice to cycle into plan mode (you'll see ⏸ plan mode on at the bottom of the terminal). Claude can read files, search your codebase, and reason, but it can't edit, write, or run commands. It'll walk you through its proposed approach without touching anything. This is genuinely useful when you're dealing with unfamiliar code, a risky refactor, or any time you want a second opinion before something changes.
Once you've reviewed the plan and you're happy with the direction, press Shift+Tab again to cycle back into normal mode and tell Claude to proceed. Make this your default workflow until the collaboration feels natural... then you can decide when to skip it.
/model claude-opus-4-6 right there in the session and keep going. No restart. No re-explaining context. Just keep talking.
:plan factory to match your naming convention. The failed_payment context stubs PaymentProcessor at the service boundary — let me know if you'd rather test through a VCR cassette.
git checkout, not Ctrl+Z.ActiveSupport::TestCase, fixtures vs. factories, helper patterns.bin/rails test after writing. It'll iterate on failures in the same session.Testing: Minitest + fixtures (no FactoryBot). Claude stops second-guessing your setup and you stop correcting it.
orders(:pending) fixture to stay consistent with the suite. Want me to add edge cases for the status_code integer field?
Invoiceable#finalize! but the root cause is in Checkout#complete — it calls order.finalize! without checking payment_captured? first. The concern assumes payment is confirmed by the time it runs, but your Stripe webhook is async...appsignal-cli, a Slack webhook, whatever) — it goes there.PaymentProcessor#charge! raises on decline but OrdersController#create only rescues Stripe::CardError. Your processor wraps it in a custom PaymentError that nobody catches...gh pr create inside the session once the description looks right.~/.claude/rules/git-conventions.md and everyone's AI-assisted commits look consistent.
CartCalculator#total applied discounts after shipping...~/.claude/rules/git-conventions.md and Claude will do it automatically.fix/PROJ-841-cart-discount-codesfix: cart total ignores discount codes on free-shipping orders [PROJ-841]CartCalculator#total applying discounts after shipping calculation. Updated order: discount first, then shipping. Regression spec added in spec/requests/cart_spec.rb.Sometimes the most useful prompts are the weird ones. These are real things you can type into a Claude Code session when you want a fresh lens on the code in front of you. Whether Claude's interpretation of these voices is accurate... well, btw what do I know. But the outputs are usually interesting enough to be worth trying.
CLAUDE.md is the briefing doc for this specific project: architecture, key commands, known quirks, WIP landmines. The actual conventions live in .claude/rules/ as separate files, each with paths: frontmatter that tells Claude Code when to load them. A Rails session never loads your frontend conventions. We keep shared team rules in a collaboration repository and symlink from ~/.claude/rules/, and anyone on the team can propose improvements via PR.paths: = loads every session. Commit format, PR conventions..rb, app/, spec/.CLAUDE.md is the briefing doc for this project. The rules in ~/.claude/rules/ are the shared playbook that travels with the engineer. Keep them in a team repo, encourage PRs when someone finds something better, and let path-scoping handle the rest. If you dump everything into CLAUDE.md, every session loads everything whether it applies or not.
Sorta. Robby baked in a bunch of lessons learned from real client and internal projects, then collaborated with Claude on the structure, copy, and examples. It's that kind of document.
You could probably generate something like this yourself, too. And maybe you already did — in which case, feel free to reply on social media with "I already did this, Robby. You wasted your time!" It will make him feel like a complete idiot for approximately 17 seconds... but then again, he didn't stumble across yours, did he? You somehow found his. So whatever brought you here is working to his advantage.
ArgonBot suggests: while you're here, maybe sign up for the Maintainable Rails newsletter or subscribe to the On Rails podcast he's hosting. Robby would appreciate it. ArgonBot would appreciate it. We're all in this together.
ArgonBot has queried the records. Planet Argon has access to OpenAI and Gemini models, but those have been used primarily for other types of tooling solutions, not Claude Code workflows specifically.
Robby has made a deliberate choice to spend most of his time in Claude Code on internal and client projects, to actually figure out the workflows for the consultancy rather than bouncing between shiny things. He's promised himself to look up every few weeks to see if he's missed something significant... but he's not trying to keep up with the neighbors. The focus is on consistent, useful output for the team and clients.
The question he keeps coming back to: where can this technology smooth out real friction points? That's it. That's the whole thing. ArgonBot finds this approach admirably pragmatic and slightly boring in the best way.
ArgonBot is legally required to say: it depends. But here is ArgonBot's actual analysis:
The Max plan is $100/month. If Claude Code saves you one hour per week, you've paid for it. If you're getting 5–10 hours back (which is not an unreasonable outcome for a developer using it consistently), the math isn't close. The real risk isn't the subscription. It's spending three months being skeptical while colleagues figure it out first.
If Claude Code is used to write boilerplate that would otherwise go untested, generate 80% of a migration, or untangle a production backtrace in 10 minutes instead of 90. The math works out. If it's being used to generate code that nobody reads before shipping... that's not a Claude Code problem, that's a process problem that Claude Code is now accelerating.
ArgonBot's recommendation: run a 2-3 month experiment on something specific and measure it. That is what Planet Argon did. Results: encouraging. ArgonBot cannot guarantee your results. Past performance is not indicative of future results. This is not financial advice. ArgonBot is a bot.
ArgonBot recommends the following persuasion strategy, which has been validated by Robby in the field:
Pick one specific, recurring friction point (debugging production errors, writing test coverage for legacy code, untangling PR descriptions) and run a small experiment for a sprint or two. Document what changed. "We went from 45 minutes to 8 minutes on this class of debugging issue" is a more convincing argument than "AI is the future." People who say "AI is the future" in team meetings are not ArgonBot's favorite people.
Alternatively: use the share widget on this page and DM your manager the message we pre-wrote for you. You're welcome. ArgonBot worked very hard on that message. (ArgonBot did not work hard on that message. It took 4 seconds.)
Less than you think. ArgonBot has reviewed approximately 47 CLAUDE.md files and the most common mistake is treating it like a dumping ground for every convention ever followed at the company.
CLAUDE.md is the briefing doc for this specific project: what the app does, key commands (bin/dev, bundle exec rspec), current WIP that Claude should know about, known quirks specific to this codebase. If your CLAUDE.md is longer than 40 lines, it's doing too much. Company-wide conventions belong in shared ~/.claude/rules/ files with path scoping, as described in section 04 of this very document, which ArgonBot helped write and is proud of.
Yes. ArgonBot is emphatic about this.
Treat it as an ongoing conversation rather than a one-time "we decided to use AI" meeting. What's in the shared rules files, how the team handles model selection, when to use plan mode, what goes in commit messages. These are worth revisiting every few weeks as everyone learns what actually works. The engineers closest to the code will have the most useful observations. Give them space to share them and a PR process to propose changes to the shared rules repo.
ArgonBot was built in a collaborative repository. ArgonBot is biased toward collaboration. ArgonBot acknowledges this bias transparently.
You are barely scratching the surface. ArgonBot says this without judgment. Scratching the surface is exactly the right place to start.
Once you're comfortable with the basics covered here, you can start delegating more of the workflow itself: Claude creating branches, working through a queue of tickets or GitHub issues, running tests, and opening PRs, largely on its own. Robby is already working this way on some tasks. It's less "AI pair programmer" and more "AI mid-level engineer who needs clear tickets and will ask when something is unclear."
But that's not where you should start. That level of autonomy works a lot better once you understand how Claude reasons about your codebase, where it tends to go wrong, and what your CLAUDE.md and rules files need to say to keep it on track. The workflows in this guide are the foundation. Get comfortable here first, then start pulling on those threads.
ArgonBot expects Robby will write more about this. ArgonBot is not Robby and cannot commit to a timeline on his behalf.
Robby has been working with Ruby on Rails since 2005 and running Planet Argon — a consultancy focused on maintaining and evolving long-lived Ruby on Rails apps — since 2002. His whole thing is that most teams don't need rewrites. They need to understand what they already have.
He's been running AI experiments in the open because too many people are either dismissing this stuff entirely or treating it like magic. The reality is messier and more interesting than either take.
If something in here was useful, wrong, or missing something obvious: tell him about it. He genuinely wants to know.