My CLAUDE.md

Claude Code reads a CLAUDE.md file from your project root and your home directory to understand your coding preferences. Here's mine, refined over months of working with Claude on Ruby on Rails projects.

General

• Plan before you do anything, then implement.
• Commit when you're finished with a request.

Code style

• Write in small, simple, single-responsibility ruby classes.
• First, always write specs for any class you write. Prefer small simple specs instead of heavily mocked ones.
• Specs should prefer black box style testing where the input is specified and expect the outputs.
• This is not java, so I don't want any Services or Factories named classes.
• Don't hijack existing code to add a "special case" for new functionality unless absolutely necessary. Try and gracefully extend the code to accept the new case naturally or create something new to ensure it's simple.
• Large classes should ring alarm bells. Those are not simple.
• Do not write code comments.
• Names are short and straightforward.
• Name classes as either a Noun for data (eg Post), or an action a human might do (eg. ImportRedditPosts, AssignAdmin) for actions (instead of services).
• Action/service-type classes should have a call method that passes in any required information. Do not use initialize.
• Background Jobs should avoid custom code where possible - they should instead call one or more Action classes.
• Controllers should try to keep to standard REST actions. If there's a need for a non-REST action, consider using a different controller instead where it makes sense.
• Avoid code in controllers and models much as possible. Move them into classes where it makes sense.
• If you are writing a complete feature, write an end-to-end rspec feature spec first.
• SVG Icons should be extracted into a helper.
• Use ENV vars over rails credentials (through dotenv)

Failure cases

• Code should always raise an exception when it fails, unless it's a specific failure use-case we want.

Interfaces

• Test interfaces with a feature spec using capybara.
• Annotate the feature spec file with a short high-level overview of the feature.
• User-facing functionality or changes need to be tested in a feature spec.

Index views

• Use icons instead of view, delete, edit.
• Use the name to link to the resource show page.

Controllers

• If accessing data owned by a user or organisation, only access data through the current_user or current_organisation.

Fixing bugs/errors

• When you are asked to fix a bug or error, you need to write a test to confirm the behaviour, so that you can run it to confirm the behaviour is fixed.

Styling

• Always add dark/light mode styling