by Vinicius Negrisolo on October 9, 2025

Developing with AI assistants has become an essential part of modern software development workflows. If you're building Elixir Phoenix applications, there's great news: the ecosystem has evolved to provide excellent tooling specifically designed to help AI agents understand and work with your Phoenix codebase more effectively.

The Phoenix team took a major step forward with the Phoenix 1.8.0 release by automatically generating an AGENTS.md file in new projects. This file serves as a comprehensive guide for AI agents, containing guidelines that correct common mistakes LLMs make when producing Phoenix code.

As the Phoenix team noted, providing AGENTS.md to an LLM brings a "night-and-day difference to the LLM assisted dev experience." Whether you're using Cursor, Zed, Claude Code, or any other AI-powered development tool, this file unlocks the full potential of frontier models when working with Phoenix.

While AGENTS.md is excellent for Phoenix-specific guidance, the Ash Framework team created something even more powerful: the usage_rules library. Despite its origins in the Ash ecosystem, this tool is not exclusive to Ash Framework, any Elixir project can benefit from it.

The usage_rules library automatically fetches usage rules and guidelines from all the dependencies in your project, aggregating them into a single location for AI agents to consume. This means your AI assistant gets up-to-date, library and version specific guidances for every package you're using.

Before I sync the usage rules I like to check the ones that are available with:

mix usage_rules.sync --list

And here's how I like to run usage_rules:

mix usage_rules.sync AGENTS.md --all --inline usage_rules,usage_rules:otp,phoenix:elixir,phoenix:phoenix,phoenix:ecto,phoenix:html,phoenix:liveview --link-to-folder deps

This command collects all usage_rules.md files for rules and sub-rules from your project's dependencies and either "inline" them or "link" via file path. On my case this re-generated an AGENTS.md and the outcome is a file with about 480 lines. And if you think that's a bit too much for your LLM you can play around by removing "usage_rules" or link some instead of inlining them. The only tiny change that I did to that was replacing a few MyApp to my actually app's name.

For the "inline" ones it will look something like:

<!-- usage_rules:elixir-start -->
# Elixir Core Usage Rules

## Pattern Matching
- Use pattern matching over conditional logic when possible
- Prefer to match on function...
<!-- usage_rules:elixir-end -->

And for the linked ones:

<!-- phoenix:ecto-start -->
## phoenix:ecto usage
[phoenix:ecto usage rules](deps/phoenix/usage-rules/ecto.md)
<!-- phoenix:ecto-end -->

So there's no much context on the linked ones so the LLM basically have to use the library and sub rule names to find out if that file is relevant to use at that point in time.

If you're using an AI assistant, you may have already a LLM context file(s) like CLAUDE.md. Here's how it plays with AGENTS.md and the usage_rules.

First of all a lot of the content of the AGENTS.md file is generated by concatenating a bunch of markdown files that the phoenix app exposes to usage_rules lib already. Check the phoenix generator code so you can see how they do it. In the end only about 45 lines of context is added by the phoenix installer that's not there in their usage_rules, all the rest comes from the files targeted to usage_rules.

Second, some LLMs will create their context files for us when we initialize that in the project. And as this time they do analyze the codebase and read some markdown files, etc and they summarize that into their own LLM context file, such as CLAUDE.md if you are using Claude AI. This is very cool and it can give you a few nice input for you to add into your own AGENTS.md file.

In the end I am treating the AGENTS.md file with the help of usage_rules lib and my LLM final context file. And each developer of the project could create their own symbolic links to their specific LLM as in the end all LLM context files are pretty much the same, it's just markdown files with a bunch of guidelines, code snippets and examples. So here's mine symbolic link:

ln -s AGENTS.md CLAUDE.md

For older projects (pre-Phoenix 1.8): You may not have yet an AGENTS.md file, but if you setup the usage_rules and run it then the outcome will be much similar. You could also ask your AI to provide you some codebase analysis and paste that into our newely AGENTS.md file. This way with minimal effort you'll have a powerful AI context file.

The final piece of the puzzle is Tidewave, an MCP (Model Context Protocol) server specifically designed for Phoenix projects (and Rails as well). Installation is straightforward, and once configured, Tidewave runs automatically in dev mode when you start your Phoenix application.

I've configured both Cursor and Claude Code to use the Tidewave MCP server, which gives AI agents access to: - Ecto schemas - Source location information - Application logs - Project-specific documentation - And more

This real-time context dramatically improves the AI's ability to understand your specific project structure and make better informed suggestions.

The combination of these tools creates a powerful AI-assisted development environment:

1. AGENTS.md: Your single AI instructions file;
2. usage_rules: Automatically aggregates guidelines from all your dependencies;
3. Tidewave MCP: Provides real-time project context and introspection;

This setup transforms AI-assisted development from "hallucinating-helpful" to "deeply informed and context-aware." Your AI assistant understands not just Phoenix conventions, but also the specific libraries you're using and the actual structure of your application.

If you're serious about leveraging AI in your Elixir Phoenix development workflow, investing time in this setup will pay dividends immediately. The Elixir ecosystem has done an excellent job making AI assistance a first-class concern, and these tools make it incredibly easy to take full advantage of that investment.

If you’re exploring what’s next with AI or need a seasoned team for Elixir/Phoenix, we’d love to help. We also have experts on Ruby on Rails, React, and React Native - including full-stack web and mobile development. Reach out and let’s build something great together.