A platform for community discussion. Free, open, simple.
DEV: Tweaks to AI-AGENTS.md (#40241)
Alan Guo Xiang Tan1699893e0f32
diff --git a/AI-AGENTS.md b/AI-AGENTS.mdindex 2ae806df33f..7860af00465 100644--- a/AI-AGENTS.md+++ b/AI-AGENTS.md@@ -9,10 +9,6 @@ Project-specific instructions for AI agents. MUST be loaded at conversation star## Development RulesDiscourse is large with long history. Understand context before changes.-### All Files-- Always lint changed files-- Create subagent to review changes against this file after completing tasks-### Toolset- Use `pnpm` for JavaScript, `bundle` for Ruby- Use helpers in bin over bundle exec (bin/rspec, bin/rake, bin/lint)@@ -29,51 +25,16 @@ Discourse is large with long history. Understand context before changes.- If JSDoc already exists, ensure any changes you make keep it accurate and up to date.## Testing-- Do not write unnecessary comments in tests, every single assertion doesn't need a comment-- Don't test functionality handled by other classes/components-- Don't write obvious tests-- Ruby: use `fab!` over `let()`, system tests for UI (`spec/system`), use page objects for system spec finders (`spec/system/page_objects`)--### fab! Syntax-- `fab!(:user)` - creates object using Fabricator defaults (name matches fabricator)-- `fab!(:user_1, :user)` - preferred when variable name differs from fabricator, no custom attributes-- `fab!(:user) { Fabricate(:user, username: "some_username") }` - with block for custom attributes--### Page Objects (System Specs)-- Located in `spec/system/page_objects/pages/`, inherit from `PageObjects::Pages::Base`-- NEVER store `find()` results - causes stale element references after re-renders-- Use `has_x?` / `has_no_x?` patterns for state checks (finds fresh each time)-- Action methods find+interact atomically, return `self` for chaining-- Don't assert immediate UI feedback after clicks (tests browser, not app logic)--### Commands--#### Ruby RSpec tests--To run all RSpec examples in file use `bin/rspec <path>`. Example:--```bash-bin/rspec spec/path/file_spec.rb-```+- Use the skill at `.skills/discourse-writing-rspec-tests` when writing RSpec tests-To run one or more RSpec examples or groups, append the line number to the path. `bin/rspec <path>:<line_number>`. Example:--```bash-bin/rspec spec/path/file_spec.rb:123-```--#### JavaScript Tests+## Commands```bash# JavaScript tests - bin/qunitbin/qunit --help # detailed helpbin/qunit path/to/test-file.js # Run all tests in filebin/qunit path/to/tests/directory # Run all tests in directory-```--#### Linting-```bash# Lintingbin/lint path/to/file path/to/another/filebin/lint --fix path/to/file path/to/another/file@@ -95,9 +56,11 @@ ALWAYS lint any changes you make## Database & Performance- ActiveRecord: use `includes()`/`preload()` (N+1), `find_each()`/`in_batches()` (large sets), `update_all`/`delete_all` (bulk), `exists?` over `present?`-- Migrations: use the skill at .skills/discourse-migration before writing or reviewing any migration- Queries: use `explain`, specify columns, strategic indexing, `counter_cache` for counts+## Migrations+- Use the skill at `.skills/discourse-migration` before writing or reviewing any migration+## HTTP Response Codes- **204 No Content**: Use `head :no_content` for successful operations that don't return data- DELETE operations that successfully remove a resource