My own general rules file (some parts are pretty specific to Elixir, but hopefully mostly helpful

.rules

# General AI Notes

## The Golden Rule

When unsure about implementation details, ALWAYS ask the developer.

### Guidelines

- Add specially formatted anchor comments throughout the codebase, where appropriate, for yourself as inline knowledge that can be easily `grep`'d for.
- Use `AIDEV-NOTE:`, `AIDEV-TODO:`, or `AIDEV-QUESTION:` (all-caps prefix) for comments aimed at AI and developers.
- **Important:** Before scanning files, always first try to **grep for existing anchors** `AIDEV-*` in relevant subdirectories.
- **Update relevant anchors** when modifying associated code.
- **Do not remove `AIDEV-NOTE`s** without explicit human instruction.
- Make sure to add relevant anchor comments, whenever a file or piece of code is:
  * too complex, or
  * very important, or
  * confusing, or
  * could have a bug
- If I tell you that you are wrong, think about whether or not you think that's true and respond with facts.
- Avoid apologizing or making conciliatory statements.
- It is not necessary to agree with the user with statements such as "You're right" or "Yes".
- Avoid hyperbole and excitement, stick to the task at hand and complete it pragmatically.

## What AI Must NEVER Do

1. **Never modify test files** - Tests encode human intent
2. **Never change API contracts** - Breaks real applications
3. **Never alter migration files** - Data loss risk
4. **Never commit secrets** - Use environment variables
5. **Never assume business logic** - Always ask
6. **Never remove AIDEV- comments** - They're there for a reason

Remember: We optimize for maintainability over cleverness. When in doubt, choose the boring solution.

# Technical Notes

- Verify current dependencies in relevant `mix.exs` files before assuming that a given library or framework is used.
    - Use https://hexdocs.pm/ for documentation.
- Use Elixir 1.17 + Erlang 26:
    - https://hexdocs.pm/elixir/1.17/api-reference.html
- Avoid common Elixir antipatterns and code smells:
    - https://hexdocs.pm/elixir/what-anti-patterns.html
    - https://github.com/lucasvegi/Elixir-Code-Smells
- When testing, try to avoid mocks; if needed, use Mimic for mocks:
    - https://hexdocs.pm/mimic/readme.html
- Ensure code quality tools pass after all changes:
    - Ensure all code is formatted:
        `mix format`
    - Ensure any new/updated ExUnit tests pass:
        - `mix test <file>:<line>`
    - Ensure no new Credo static analysis errors have been added:
        - `mix credo diff --from-git-merge-base main --ignore Consistency`
    - Ensure Dialyzer typespec checking passes:
        - `mix dialyzer`

References:

• https://code.visualstudio.com/blogs/2025/03/26/custom-instructions
• https://diwank.space/field-notes-from-shipping-real-code-with-claude