Do not autoformat AGENTS.md as it contains generated blocks
This commit is contained in:
Claudio Ortolina
@@ -29,15 +29,13 @@ Before exploring the codebase for any task, read `docs/architecture.md`. Do this
|
||||
|
||||
<!-- usage-rules-start -->
|
||||
<!-- usage_rules-start -->
|
||||
|
||||
## 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,6 +54,7 @@ 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
|
||||
@@ -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-end -->
|
||||
<!-- usage_rules:elixir-start -->
|
||||
|
||||
## 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:elixir-end -->
|
||||
<!-- usage_rules:otp-start -->
|
||||
|
||||
## 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:otp-end -->
|
||||
<!-- usage_rules-start -->
|
||||
|
||||
## 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,6 +187,7 @@ 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
|
||||
@@ -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-end -->
|
||||
<!-- usage_rules:elixir-start -->
|
||||
|
||||
## 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
|
||||
|
||||
<!-- usage_rules:elixir-end -->
|
||||
<!-- mdex-start -->
|
||||
|
||||
## mdex usage
|
||||
|
||||
_Fast and extensible Markdown for Elixir_
|
||||
|
||||
@deps/mdex/usage-rules.md
|
||||
|
||||
<!-- mdex-end -->
|
||||
<!-- usage-rules-end -->
|
||||
|
||||
|
||||
@@ -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 ---
|
||||
|
||||
Reference in New Issue
Block a user