[2/4] Code with LLMs and default instructions

This will be a quick one, and if you get this one right, your coding buddies will run more smoothly on average because they will get stuck less and have clearer directions for each conversation session.

I guess for the Cursor and Co. people, it will be something like the cursor/rules file. For the state-of-the-art models like Codex, Claude Code, and Amp you'll have something like a CLAUDE.md file. This piece of information is typically ingested as context on the start-up of the conversation.

This is where you give the LLM a basic overview of your codebase and project. When you set up Claude Code for a project, there is an /init option that makes Claude analyze your project and fill the CLAUDE.md with some machine-useful context. You have to edit and fine-tune it with your own instructions about code architecture, style, and workflows. You can imagine "workflows" as instructions on how to deliver the implementation.

Some doubt the effectiveness of the file, reporting that the LLMs ignore instructions. I personally don't have high expectations of an LLM to deliver exact solutions, and following all the rules, it's just not how it works right now. I'm just happy that it delivers better on average, which I see because it stops getting stuck once I formalize a few things.

The Funnels on Rails app is a relatively new app and has a fairly small instructions file. Obviously, I can't tell how much worse the LLM would perform without the file. What I definitely know is that it did use Bullet Train's super scaffolding functionality for new functionality a couple of times, which I'm pretty sure it wouldn't have done without that context:

[...]
**Super Scaffolding**:

Bullet Train's code generation engine that creates complete CRUD interfaces. Key commands:

```bash
# Generate new model with CRUD interface
rails generate super_scaffold ModelName Team field:field_type

# Add field to existing model
rails generate super_scaffold:field ModelName field:field_type

# Available field types: text_field, trix_editor, buttons, super_select, image and more
```

Use the docs to get detailed info about how to scaffold:
https://bullettrain.co/docs/super-scaffolding

Example:
[...]

I've tweaked those instructions a bit, but it ultimately comes down to providing the LLM with the necessary context at the right time. It's no good to give it redundant context, as in this case, the LLM doesn't really need to know about super scaffolding on each startup. So that particular CLAUDE.md will need many future iterations. And what I think actually needs to happen here is that the Bullet Train docs need to be accessed by the LLM at the right time for the right info via some BT docs MCP server in the future, like the Rails MCP Server.

What I really enjoy seeing Claude Code working with are the "workflow" type of instructions. Because Claude Code is integrated within your terminal, it executes system commands seamlessly. Once it's done coding, it will usually run tests. But not all tests are run equally:

## Testing

- You MUST ALWAYS run tests using `npm test -- --run` or `npx vitest --run` to avoid watch mode!
- Never use `npm test` without the `--run` to avoid watch mode.
- Always run npx tsc --noEmit and make sure there are no type warnings and error.

For a large codebase, you probably want to instruct it to just run the individual files or test cases as a default and describe your additional setup:

## Development Workflow

### Testing

- When switching to a new branch, run `make dev-sync` and a test to seed the test db initially: `bin/test --notify-sound --no-retry --no-precompile test/controllers/api/v2/contacts_controller_test.rb:124` (after this you need to run tests in the same format with the `--skip-seeds` option)
- To run tests always use this format: `bin/test --notify-sound --no-retry --no-precompile test/controllers/api/v2/contacts_controller_test.rb:124 --skip-seeds`. If you run into a NoSeedsError, it means the test DB isn't seeded as expected and you need to rerun tests without the --skip-seeds option.
- For big test files, prefer specifying the line when running tests.

### Formatting

- After all implementation is done, you MUST ALWAYS run standardrb over all previously modified Ruby files to ensure correct code formatting with a command like this: `bundle exec standardrb --fix app/services/pages_converter.rb`

That's all I have on your LLM setup instruction files so far. Just add directions to your instructions files if you see the LLMs repeatedly getting stuck and have fun being more productive with "AI coding".

Rails builders 2 🛠️

Next week is the last chance to secure an open spot in Rails Builders 2 (free), which runs until the end of August. After that, we'll finalize the groups in the existing formations. If you know me, just give me a ping wherever we are connected. If we haven't spoken yet, press the button. 👇

Get to know call ☎️