From b895c9817fd88cb02722fe65c8d33cde2a954dff Mon Sep 17 00:00:00 2001 From: Claudio Ortolina Date: Wed, 27 May 2026 23:16:21 +0300 Subject: [PATCH] Remove duplicated usage_rules blocks in AGENTS.md --- AGENTS.md | 106 ------------------------------------------------------ mix.exs | 3 +- 2 files changed, 1 insertion(+), 108 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bcef36a0..177029e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -172,112 +172,6 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - Use `Task.async_stream/3` for concurrent enumeration with back-pressure - -## usage_rules usage -_A config-driven dev tool for Elixir projects to manage AGENTS.md files and agent skills from dependencies_ - -## Using Usage Rules - -Many packages have usage rules, which you should *thoroughly* consult before taking any -action. These usage rules contain guidelines and rules *directly from the package authors*. -They are your best source of knowledge for making decisions. - -## Modules & functions in the current app and dependencies - -When looking for docs for modules & functions that are dependencies of the current project, -or for Elixir itself, use `mix usage_rules.docs` - -``` -# Search a whole module -mix usage_rules.docs Enum - -# Search a specific function -mix usage_rules.docs Enum.zip - -# Search a specific function & arity -mix usage_rules.docs Enum.zip/1 -``` - - -## Searching Documentation - -You should also consult the documentation of any tools you are using, early and often. The best -way to accomplish this is to use the `usage_rules.search_docs` mix task. Once you have -found what you are looking for, use the links in the search results to get more detail. For example: - -``` -# Search docs for all packages in the current application, including Elixir -mix usage_rules.search_docs Enum.zip - -# Search docs for specific packages -mix usage_rules.search_docs Req.get -p req - -# Search docs for multi-word queries -mix usage_rules.search_docs "making requests" -p req - -# Search only in titles (useful for finding specific functions/modules) -mix usage_rules.search_docs "Enum.zip" --query-by title -``` - - - - -## usage_rules:elixir usage -# Elixir Core Usage Rules - -## Pattern Matching -- Use pattern matching over conditional logic when possible -- Prefer to match on function heads instead of using `if`/`else` or `case` in function bodies -- `%{}` matches ANY map, not just empty maps. Use `map_size(map) == 0` guard to check for truly empty maps - -## Error Handling -- Use `{:ok, result}` and `{:error, reason}` tuples for operations that can fail -- Avoid raising exceptions for control flow -- Use `with` for chaining operations that return `{:ok, _}` or `{:error, _}` - -## Common Mistakes to Avoid -- Elixir has no `return` statement, nor early returns. The last expression in a block is always returned. -- Don't use `Enum` functions on large collections when `Stream` is more appropriate -- Avoid nested `case` statements - refactor to a single `case`, `with` or separate functions -- Don't use `String.to_atom/1` on user input (memory leak risk) -- Lists and enumerables cannot be indexed with brackets. Use pattern matching or `Enum` functions -- Prefer `Enum` functions like `Enum.reduce` over recursion -- When recursion is necessary, prefer to use pattern matching in function heads for base case detection -- Using the process dictionary is typically a sign of unidiomatic code -- Only use macros if explicitly requested -- There are many useful standard library functions, prefer to use them where possible - -## Function Design -- Use guard clauses: `when is_binary(name) and byte_size(name) > 0` -- Prefer multiple function clauses over complex conditional logic -- Name functions descriptively: `calculate_total_price/2` not `calc/2` -- Predicate function names should not start with `is` and should end in a question mark. -- Names like `is_thing` should be reserved for guards - -## Data Structures -- Use structs over maps when the shape is known: `defstruct [:name, :age]` -- Prefer keyword lists for options: `[timeout: 5000, retries: 3]` -- Use maps for dynamic key-value data -- Prefer to prepend to lists `[new | list]` not `list ++ [new]` - -## Mix Tasks - -- Use `mix help` to list available mix tasks -- Use `mix help task_name` to get docs for an individual task -- Read the docs and options fully before using tasks - -## Testing -- Run tests in a specific file with `mix test test/my_test.exs` and a specific test with the line number `mix test path/to/test.exs:123` -- Limit the number of failed tests with `mix test --max-failures n` -- Use `@tag` to tag specific tests, and `mix test --only tag` to run only those tests -- Use `assert_raise` for testing expected exceptions: `assert_raise ArgumentError, fn -> invalid_function() end` -- Use `mix help test` to for full documentation on running tests - -## Debugging - -- Use `dbg/1` to print values while debugging. This will display the formatted value and other relevant information in the console. - - ## mdex usage _Fast and extensible Markdown for Elixir_ diff --git a/mix.exs b/mix.exs index 95550dff..2cd039d9 100644 --- a/mix.exs +++ b/mix.exs @@ -225,8 +225,7 @@ defmodule MusicLibrary.MixProject do [ file: "AGENTS.md", usage_rules: [ - "usage_rules:all", - :elixir, + :usage_rules, {:mdex, link: :at} ], skills: [