Juan José Mata
157daf5176
* Document instruction inventory and preservation decisions Trace main history from September 2025 through September 2026, including earlier policy origins. Record preserved requirements, detailed-guide destinations, stale facts, harness boundaries and explicit policy-strength decisions before consolidating instruction sources. * Consolidate repository instructions into shared guidance Keep AGENTS concise and vendor neutral, move detailed conventions into shared guides, and use thin adapters with preserved Cursor scopes. Preserve the strict pre-PR checks globally and document the stronger scope, retired migration pin and rule-generation trigger. Update existing API guidance verification without changing application behavior. * Narrow the always-on Cursor UI adapter and correct the SimpleFIN comment Split the design-system guidance out of docs/llm-guides/ui.md into docs/llm-guides/design-system.md. The ui-ux-design-guidelines rule is alwaysApply: true, so importing all of ui.md loaded the Stimulus, localization and ViewComponent guidance (previously confined to scoped rules) on every Cursor session; the always-on adapter now imports only the design-system guide, matching the scope it had before the consolidation. view_conventions and stimulus_conventions keep the full UI guide. Also correct the stale Provider::Simplefin header comment: pending inclusion defaults on and is resolved by the importer (explicit argument, then SIMPLEFIN_INCLUDE_PENDING, then Setting.syncs_include_pending); the previous comment described the flag as default-off. * Read guidance files as UTF-8 in the API consistency validators The frontmatter regex match ran against content read with the locale default external encoding; the Cursor rule's description contains an em dash, so under US-ASCII (LC_ALL=C) Regexp#match raised ArgumentError, breaking the standalone no-Rails fallback the docs point contributors to. Read all checked files with an explicit UTF-8 encoding in both the standalone script and the Rails test.
3.8 KiB
Development and verification
Environment and commands
Use the Ruby version in .ruby-version and dependencies in
Gemfile / package.json.
CONTRIBUTING.md describes local and devcontainer setup.
Start environment configuration from .env.local.example
and .env.test.example; never commit secrets or local credentials.
These are command references, not permission to start servers, restart the app,
edit credentials or automatically migrate a database. Run setup/database operations
only when that environment work has been explicitly requested. In particular,
bin/setup prepares the database and restarts the app; it is not a read-only check.
| Task | Command |
|---|---|
| Initial setup | cp .env.local.example .env.local (only if the file does not exist), then bin/setup |
| Development processes | bin/dev (Rails, Sidekiq, Tailwind watcher) |
| Rails console | bin/rails console |
| Database preparation / migration | bin/rails db:prepare / bin/rails db:migrate |
| Database rollback / seed | bin/rails db:rollback / bin/rails db:seed |
| Full behavioral suite | bin/rails test |
| One file / test at a line | bin/rails test test/models/account_test.rb / bin/rails test test/models/account_test.rb:42 |
| Reset test database and test | bin/rails test:db (database-changing task) |
| System tests | DISABLE_PARALLELIZATION=true bin/rails test:system |
| Ruby lint | bin/rubocop |
| Safe Ruby autocorrection | bin/rubocop -a (-A also enables unsafe corrections) |
| JavaScript/TypeScript lint / fix | npm run lint / npm run lint:fix |
| Biome formatting check / fix | npm run format:check / npm run format |
| Security analysis | bin/brakeman --no-pager |
Lookbook is mounted at /design-system outside production; see
config/routes.rb. Letter Opener supports development
email previews. Use Docker/devcontainers where useful for consistent environments.
Before opening a pull request
Run these checks locally before every PR. All required checks must pass before PR creation; the full suite is also required to be green before pushing.
bin/rails test— the full Minitest suite is always required.DISABLE_PARALLELIZATION=true bin/rails test:system— required when system tests are applicable to the change; keep system-test additions focused on critical flows.bin/rubocop -f github -a— Ruby lint with safe autocorrection.bundle exec erb_lint ./app/**/*.erb -a— ERB lint with autocorrection.npm run lint— keep Biome clean. Usenpm run format:checkfor formatting changes andnpm run formatwhen corrections are needed.bin/brakeman --no-pager— security analysis for every PR.
Inspect autocorrections before committing; keep the diff focused. Record checks and any failures accurately. Focused tests help during development but do not replace the required full pre-PR suite.
CI has its own executable definition in .github/workflows/ci.yml
and callers. Its unit and system jobs are separate; CI runs system tests even though
the local checklist makes them conditional on applicability. Local ERB lint is an
existing additional requirement. Passing local checks does not replace the
contributor requirement for green
GitHub checks and an up-to-date branch before requesting review.
System tests in a devcontainer
The devcontainer configuration includes
Selenium Chromium and sets SELENIUM_REMOTE_URL; no local Chrome is needed there.
Run DISABLE_PARALLELIZATION=true bin/rails test:system. Watch the browser at
http://localhost:7900 or http://localhost:4444 (development password: secret).