Skip to content

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.md
index 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 Rules
Discourse 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/qunit
bin/qunit --help # detailed help
bin/qunit path/to/test-file.js # Run all tests in file
bin/qunit path/to/tests/directory # Run all tests in directory
-```
-
-#### Linting
-```bash
# Linting
bin/lint path/to/file path/to/another/file
bin/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