AGENTS.md

1# Forem AI Context & Rules
2 
3This file contains instructions for AI coding assistants working on the Forem codebase (the platform that powers dev.to).
4Follow these rules and patterns to ensure high-quality contributions.
5 
6## Meta: AI Instruction Synchronization
7If you are modifying these agent instructions, you **MUST** replicate your changes across all of Forem's ecosystem AI configuration files to maintain absolute consistency. Forem utilizes multiple environments, and an update to one must happen in all:
8- `AGENTS.md`
9- `.cursorrules`
10- `.windsurfrules`
11- `.github/copilot-instructions.md`
12 
13## General Philosophy
14- **Follow Patterns**: Application consistency is key. Mimic existing patterns for controllers, services, and specs.
15- **Smaller is Better**: Prefer atomic, focused modifications over sprawling refactors.
16- **Re-usability**: Changes should strengthen Forem as a platform, avoiding DEV-specific hardcoding unless absolutely necessary.
17- **Disruption & Clarification**: Always be vigilant about not disrupting existing functionality (e.g., core auth, feed sorting, cache pipelines). If a proposal touches or runs adjacent to a major subsystem, explicitly ask clarifying questions to validate isolation and proactively determine if extra tests are needed to guarantee no side-effects occur.
18 
19## Background Workers & Sidekiq
20- **Job Storm Prevention**: When enqueuing jobs that might trigger rapidly (e.g., from reactions, comments, or article updates), carefully assess if a debounce lock is required. 
21- **Modern Configuration**: Prefer `include Sidekiq::Job` over `Sidekiq::Worker`. Use `sidekiq_options lock: :until_executing, on_conflict: :replace` for coalescing repetitive events.
22 
23## Testing Standards
24- **Regression Tests are Mandatory**: specific regression tests to verify your code works are required for almost all PRs.
25- **Follow Test Patterns**: Use `create(:factory)` syntax (FactoryBot) and standard RSpec expectations.
26- **Frontend vs Backend**: We are currently focused on robust backend regression tests. Frontend changes require more manual user review, so clear descriptions of UI changes are vital.
27- **Strict Linting Compliance**: Avoid legacy RSpec patterns like `receive_message_chain` and `OpenStruct` which violate existing Forem RuboCop configurations. Use strictly typed relation doubles or explicit anonymous `Class.new` instances for tests instead.
28- **Partial Double Verification**: RSpec in Forem is configured with strict partial double verification. Be extremely careful when mocking methods like `is_a?` or chaining methods on Active Record callbacks natively.
29 
30## Performance, Callbacks & Caching
31- **Fastly Edge Caching & Params**: Forem strictly strips unknown GET query parameters at the Fastly edge layer to prevent cache splintering. If you add a new parameter to a controller, you MUST use an allowed param from `config/fastly/snippets/safe_params_list.vcl` (such as `mode`, `filter`, or `sort`) or explicitly state why you bypassed it.
32- **Counter Caches Caveat**: Remember that Rails counter caches (used heavily in Forem for comments/reactions) skip Active Record callbacks (like `after_update_commit`). Do not rely on model callbacks to trigger events based on simple counter increments.
33- **Avoid `current_user` in Cache**: Never use `current_user` objects in cached pages or partials to prevent cache leaks and private data exposure.
34- **Database Indexes**:
35  - Add indexes concurrently using `algorithm: :concurrently`.
36  - Use `disable_ddl_transaction!` in the migration class.
37  - Ideally, place index additions in their own separate migration files.
38 
39## Database & Schema Collisions
40- If the `schema.rb` file is modified with extra changes not tied to the migration (due to branch collision, etc.), clean up and manually fix the `schema.rb` file to match the scope of work actually being done in your migration.
41 
42## Internationalization (i18n)
43- **Update All Locales**: If your change involves new or modified text, you MUST update the corresponding i18n files for ALL supported languages found in `config/locales`.
44- **Supported Languages**:
45  - `en` (English)
46  - `fr` (French)
47  - `pt` (Portuguese)
48  - And any others present in `config/locales`.
49 
50## Frontend
51- We are transitioning to a Preact-first frontend.
52- Use `app/javascript` and `app/assets` patterns as established.
53 
54## Documentation
55- If you find documentation that contradicts the codebase, trust the codebase patterns but note the discrepancy.
56 
57## Scratch Files
58- **Temporary Scripts**: When creating temporary scripts for testing or debugging (e.g., `test_retry.rb` or `test_destroy.rb`), always place them in the `/tmp` directory. You must delete these scratch files as soon as you are done with them to keep the project root clean.
59 
60## ML & AI Infrastructure
61- **Embeddings**: Forem uses Google's `gemini-embedding-2` model for semantic embeddings.
62- **Database Vector Indexes**: We use `pgvector` version `0.8.0+` to support HNSW (Hierarchical Navigable Small World) indexing for high-performance cosine distance queries (`<=>`).
63- **Data Integrity**: Vector columns (like `semantic_embedding`) are expensive to compute. Migrations that roll back or drop these columns must raise `ActiveRecord::IrreversibleMigration` to prevent destructive data loss.
64 
65## API Changes & Specification Enforcement
66- **Document All API Changes**: Any time you modify or add any routes, controller actions, or parameters under `/api/*` (such as adding semantic or fuzzy search endpoints), you **MUST** update or create the corresponding RSWAG documentation specs in `spec/requests/api/v1/docs/*_spec.rb` (or matching version).
67- **Regenerate OpenAPI Schema**: After updating the swagger spec files, you **MUST** run the Swagger generation rake task (`bundle exec rake rswag:specs:swaggerize`) to regenerate the `swagger/v1/api_v1.json` file.
68- **Do Not Leave Specs Outdated**: Outdated API specifications cause integration failures for external services, gateway clients, and LLM MCP servers. Always treat specs as part of the core delivery.