Notes on Agentic Coding (+ Rails)

• I try to run ~5 agent sessions in parallel.
• I use `claude --dangerously-skip-permissions`, it's not feasible to get asked for random permissions by 5 sessions in parallel all the time.
• I run all sessions in the same branch - I can't bother with git worktrees. Also, when you let Claude automatically git commit (see next point), this works fairly well.
• I tell Claude to automatically git commit (in the CLAUDE.md).
• I try to re-use the same session for minor changes to the Rails app, mainly to the UI. This is very useful because that session likely has enough context (files) loaded to make the changes fairly quickly, i.e. spinning up a new session would be slower.
• For tasks which sound parallelizable, prompt claude to "paralellize with agents" - this can lead to some huge speed-ups (and similarly huge token usage). Very useful e.g. for cleaning up data in yaml or json files.
• Generally speaking, with ~5 sessions in parallel, I become the "human orchestrator". So let's say if there's one session which is doing a huge refactor, then I need to make sure that the other 4 sessions aren't actively modifying files right now; instead, they themselves could be writing plans for bigger tasks to be implemented after the refactor is done. But, best case, each session is working on separate files in the code base. Somewhat interesting that you run into the same "coordination problem" like with humans here.
• Taking a screenshots (which end up on the desktop in macOS) and then prompting Claude Code to "take a look at the most recent screenshot on my desktop" is a pretty solid method for improving the feedback loop - no need to type out problems, just let Claude take a look and fix it.
• Dictation is faster than typing for prompting, I use handy.computer.

## Code Style

- Follow rubocop-rails-omakase conventions (see `.rubocop.yml`)
- Rails defaults: convention over configuration
- Prefer Hotwire (Turbo Frames/Streams + Stimulus) over custom JS
- Use importmap for JS dependencies — no npm/yarn

## Conventions

- **Migrations:** For v1, all tables go in a single migration file `db/migrate/0001_create_initial_schema.rb`. Don't create separate migration files per table.
- **Resetting the database:** Use `bin/rails db:migrate:reset && bin/rails db:seed` to drop, recreate, re-migrate, and reseed. Always seed after resetting.
- **Enums over strings:** Prefer Rails enums (integer columns) over string columns for status/type fields. Use `enum :field_name, { ... }, prefix: :field_name` to get scoped predicate methods and avoid name collisions.
- **Turbo first:** Follow Rails 8 conventions — use Turbo Frames and Turbo Streams/broadcasts wherever appropriate to avoid full page reloads and provide smooth, in-place UI updates.
- **SVGs as files:** Never inline SVG markup in views. Instead, save SVGs to `app/assets/svgs/` and use `inline_svg_tag "name.svg"` to render them. This keeps views clean and SVGs reusable.
- **Gemfile comments:** Every user-added gem (i.e. not Rails defaults) must have a short inline comment explaining its purpose, e.g. `# OpenAI API client` above `gem "ruby-openai"`.
- **Git commits:** Commit after completing changes without waiting to be asked. Use concise, descriptive commit messages.

• Claude seems to prefer writing custom JS instead of Turbo stuff - Turbo is better.
• `rails db:migrate:reset` is a rather new addition with Rails 8 for regenerating the schema (and database) when changing existing migrations. Very useful for projects which are not deployed yet if you're writing all your initial migrations into one file, just like Basecamp did that for Campfire.
• Claude weirdly often doesn't use enums - prompt it to do so.
• Same with SVG files - with the inline_svg gem, those can be handled in a DRY way, so we should do that.

• If you're deep inside of a long debugging and discussion session, consider prompting Claude to write everything so far to a markdown file as context is running out. Then, /clear to start a new session and @-reference the markdown file, continuing where you left off.
• Having a TODO.md in your project is quite useful - that way, Claude doesn't have to re-read the entire product every time when you ask it for what you could build next.