diff --git a/AGENTS.md b/AGENTS.md index 1913b13e..74c61c5e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,50 @@ This is a web application written using the Phoenix web framework. - Use `mix precommit` alias when you are done with all changes and fix any pending issues - Use the already included and available `:req` (`Req`) library for HTTP requests, **avoid** `:httpoison`, `:tesla`, and `:httpc`. Req is included by default and is the preferred HTTP client for Phoenix apps +- Always provide translations of all text that is visible in the UI +- Never put Ecto queries directly in LiveViews. Instead always put them in the appropriate context module + +### Module design and complexity + +**IMPORTANT**: When working with modules that are becoming too large or complex: + +- **Monitor module size and complexity**: If a module exceeds ~500-600 lines or contains deeply nested logic with high cyclomatic complexity, consider refactoring +- **Break out logical concerns**: Extract related functionality into separate, focused modules that handle a single responsibility +- **Use helper modules**: For complex domains, consider creating dedicated modules for specific sub-concerns: + - Positioning logic (e.g., `Tasks.Positioning`) + - Dependency management (e.g., `Tasks.Dependencies`) + - Validation logic (e.g., `Tasks.Validation`) + - Query builders (e.g., `Tasks.Queries`) +- **Extract helper functions**: When a function becomes complex (cyclomatic complexity > 9), extract complex conditional logic into smaller, well-named helper functions +- **Maintain clear module boundaries**: Each module should have a clear, single purpose with a well-defined public API +- **Document module organization**: When splitting modules, update documentation to explain the new structure and how modules relate to each other + +This approach improves: +- Code maintainability and readability +- Test isolation and coverage +- Collaboration between developers +- Ability to reason about individual components +- Credo compliance and code quality metrics + +### Quality guidelines + +**ALWAYS** follow these quality guidelines: + +- **IMPORTANT**: When you complete a task that has new functions, write unit tests for the new function +- **IMPORTANT**: When you complete a task that updates code, make sure all existing unit tests pass and write new tests if needed +- Each time you write or update a unit test run them with `mix test` and ensure they pass +- **IMPORTANT**: When you complete a task run `mix test --cover` and ensure coverage is above the threshold +- **IMPORTANT**: When you complete a task run `mix credo --strict` to check for code quality issues and fix them +- **IMPORTANT**: Run `mix dialyzer` for static type analysis — never suppress warnings, fix root causes +- **IMPORTANT**: Run `mix precommit` before committing: compiles with warnings as errors, formats, runs tests + +### Security guidelines + +**ALWAYS** follow these security guidelines: + +- **IMPORTANT**: When you add or update a dependency run `mix deps.audit` and `mix hex.audit` to check for security issues +- **IMPORTANT**: When you add or update a dependency run `mix hex.outdated` to check for outdated dependencies +- **IMPORTANT**: When you complete a task run `mix sobelow --config` to check for security issues and fix any issue ### Phoenix v1.8 guidelines @@ -26,7 +70,7 @@ custom classes must fully style the input @import "tailwindcss" source(none); @source "../css"; @source "../js"; - @source "../../lib/my_app_web"; + @source "../../lib/towerops_web"; - **Always use and maintain this import syntax** in the app.css file for projects generated with `phx.new` - **Never** use `@apply` when writing raw css @@ -34,36 +78,58 @@ custom classes must fully style the input - Out of the box **only the app.js and app.css bundles are supported** - You cannot reference an external vendor'd script `src` or link `href` in the layouts - You must import the vendor deps into app.js and app.css to use them - - **Never write inline tags within templates** + - **Never write inline `