diff --git a/AGENTS.md b/AGENTS.md index e2ddce18..4ba7113b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,15 +29,13 @@ Before exploring the codebase for any task, read `docs/architecture.md`. Do this - ## 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_. +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 @@ -56,9 +54,10 @@ mix usage_rules.docs Enum.zip 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 +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: @@ -76,27 +75,23 @@ mix usage_rules.search_docs "making requests" -p req 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 @@ -109,7 +104,6 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - 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` @@ -117,7 +111,6 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - 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 @@ -130,7 +123,6 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - 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 @@ -143,32 +135,26 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - ## usage_rules:otp usage - # OTP Usage Rules ## GenServer Best Practices - - Keep state simple and serializable - Handle all expected messages explicitly - Use `handle_continue/2` for post-init work - Implement proper cleanup in `terminate/2` when necessary ## Process Communication - - Use `GenServer.call/3` for synchronous requests expecting replies - Use `GenServer.cast/2` for fire-and-forget messages. - When in doubt, use `call` over `cast`, to ensure back-pressure - Set appropriate timeouts for `call/3` operations ## Fault Tolerance - - Set up processes such that they can handle crashing and being restarted by supervisors - Use `:max_restarts` and `:max_seconds` to prevent restart loops ## Task and Async - - Use `Task.Supervisor` for better fault tolerance - Handle task failures with `Task.yield/2` or `Task.shutdown/2` - Set appropriate task timeouts @@ -176,15 +162,13 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - ## 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_. +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 @@ -203,9 +187,10 @@ mix usage_rules.docs Enum.zip 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 +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: @@ -223,27 +208,23 @@ mix usage_rules.search_docs "making requests" -p req 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 @@ -256,7 +237,6 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - 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` @@ -264,7 +244,6 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - 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 @@ -277,7 +256,6 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - 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 @@ -290,13 +268,10 @@ mix usage_rules.search_docs "Enum.zip" --query-by title - ## mdex usage - _Fast and extensible Markdown for Elixir_ @deps/mdex/usage-rules.md - diff --git a/scripts/dev/precommit b/scripts/dev/precommit index e573e791..1d175142 100755 --- a/scripts/dev/precommit +++ b/scripts/dev/precommit @@ -61,9 +61,9 @@ if $SKIP_GATE || staged_lines | grep -qE '^assets/|^\.pi/extensions/.*\.(ts|js|j fi # --- Documentation --- -if $SKIP_GATE || staged_lines | grep -qE '^docs/|^README\.md$|^AGENTS\.md$'; then +if $SKIP_GATE || staged_lines | grep -qE '^docs/|^README\.md$'; then debug_msg "Checking docs formatting..." - prettier --check 'docs/**/*.md' 'docs/**/*.livemd' 'README.md' 'AGENTS.md' + prettier --check 'docs/**/*.md' 'docs/**/*.livemd' 'README.md' fi # --- Backlog ---