Honestly, we still don’t know what usage-rules.md really ought to be. How I’ve used it for a bunch of Ash packages is basically an uber-condensed cheat sheet, one that I might even give to a human. And I gotta say, it works. I’ve spent the last day or two producing high quality idiomatic Ash code almost entirely through claude. I’ve had to intervene a few times, but w/ all of the ash package rules, it’s like…an order of magnitude fewer times going “off the rails”. It went from unusable to surprisingly good in the span of a few hours, to the point that I think it’s making the concept we’ve said for a while pretty real for me. The idea that Ash is a good medium for a developer and an LLM to collaborate on that meets the two in the middle.

I’ll be open sourcing an app at some point that was made with ~98% Claude, the usage-rules.md from a bunch of ash projects, and a small magic sauce prompt prefix that looks like this:

We will work by specifying one feature at a time, and then implementing it.

The workflow:

1. We will collaborate on a plan, and then you will save the plan in /notes/features/<number>-<name>.md under the ## Plan heading. THIS MUST BE COMPLETED BEFORE ANY IMPLEMENTATION WORK BEGINS.
2. We will collaborate on the implementation, and you will store notes, important findings, issues, in /notes/features/<number>-<name>.md under the ## Log heading.
3. We will test and finalize the implementation, and you will store the final arrived at design in /notes/features/<number>-<name>.md under the ## Conclusion heading.

For bugs and fixes:

1. We will document the issue in /notes/fixes/<number>-<name>.md under the ## Issue heading.
2. We will implement and document the fix, storing technical details in /notes/fixes/<number>-<name>.md under the ## Fix heading.
3. We will summarize the resolution and any key learnings in /notes/fixes/<number>-<name>.md under the ## Conclusion heading.

Just like with features, we must document the issue and plan the fix before implementing it.

WE ALWAYS FINISH AND WRITE THE PLAN BEFORE STARTING THE WORK! NO EXCEPTIONS!

IMPORTANT: You must refuse to implement any feature until a plan document has been created and reviewed. Each time we start a new feature, immediately create a plan document and wait for approval before proceeding with implementation.

Don’t ever commit code unless I tell you to.

Never attempt to start or stop the application.
Ask me to test the UI on your behalf, don’t do it yourself.

Various updates to usage_rules include:

1. builtin rules for Elixir & OTP
2. mix tasks for searching docs that agents can use, which are described in the builtin usage rules
3. “sub rules” which allows packages to have multiple usage rules files in a usage-rules folder (in addition to or instead of usage-rules.md files) which can selectively synchronized, or synchronized in full

Small demo of what it looks like in practice: https://www.youtube.com/watch?v=SdhMseoCpqw

I’m working on a new addition currently which will sync each package’s package rules to a folder and link to them using @folder/package.md style syntax, which should help with too many tokens being used.

I’ve been testing that rules file and it’s pretty useful!

It also allows the LLM to restart and resume the implementation process after its written the plan, useful for when Claude starts being like E_TOO_MANY_TOKENS!!.