Guidelines

Repository

origin = shugo/jruby, upstream = jruby/jruby. Pull requests are usually created by Shugo himself; do not create one unless asked.
Branches may be amended or rebased in parallel sessions. Before any force-push, verify the remote SHA with git ls-remote and use --force-with-lease. If a push went through an explicit URL instead of the configured remote, the tracking refs are stale; git fetch origin before relying on them.
/workspace/jruby may be busy with other work; do not switch its branch for a side task. Work on another branch in a git worktree directly under /workspace (e.g. /workspace/jruby-fix).
Keep scratch files (drafts, analysis notes) out of the working tree; put them in ../tmp/jruby/.

English, imperative mood.
GitHub keywords like Fixes #NNNN close jruby issues when the commit reaches the default branch; use them only when closing is intended. For bugs.ruby-lang.org tickets, [Bug #NNNN] / [Feature #NNNN] have no effect here, but write the full URL for clarity anyway.
If the message contains backticks or other shell metacharacters, write it to a file and use git commit -F <file>; passing it with -m can silently lose words.
No Claude-Session line.
Do not commit or push until asked; finish the change, run the verification, and report.

Write comments in the terse style of the surrounding JRuby code: state only what the code does not already say (non-obvious invariants, constraints, reasons). Omit restatements of the code, justifications of correctness, and design history. One to three lines is the norm; javadoc only where the surrounding code has it.
Avoid non-ASCII symbols in comments, commit messages, and other output unless the source requires them.

After any Java change, rebuild lib/jruby.jar with ./mvnw -q -DskipTests before running Ruby code with bin/jruby.
Run a single test file with bin/jruby -I. test/jruby/test_foo.rb.
Run shared specs with bin/jruby spec/mspec/bin/mspec run spec/ruby/core/....
JRuby runs code interpreted first and JIT-compiles hot code; a fix can behave differently across the two. To exercise the JIT deterministically, run a subprocess with -Xjit.threshold=10 -Xjit.background=false -Xjit.logging and check the log for "JIT failed" (a silent interpreter fallback still passes behavior tests).

Cross-implementation behavior goes in spec/ruby: it is synced with ruby/spec in both directions, so specs added here flow upstream (ruby/spec#1382).
Implementation-specific tests (caching, call paths, JIT, JRuby internals via JRuby.reference) and regression tests for fixed bugs go in test/jruby/.
Do not add to spec/regression/; that suite is deprecated (jruby/jruby#9523).