Revise docs/comments for the debug gem

guides/source/debugging_rails_applications.md

@@ -470,6 +470,35 @@ class variables: @@raise_on_missing_translations  @@raise_on_open_redirects
 
 You can find more commands and configuration options from its [documentation](https://github.com/ruby/debug).
 
+#### Autoloading Caveat
+
+Debugging with `debug` works fine most of the time, but there's an edge case: If you evaluate an expression in the console that autoloads a namespace defined in a file, constants in that namespace won't be found.
+
+For example, if the application has these two files:
+
+```ruby
+# hotel.rb
+class Hotel
+end
+
+# hotel/pricing.rb
+module Hotel::Pricing
+end
+```
+
+and `Hotel` is not yet loaded, then
+
+```
+(rdbg) p Hotel::Pricing
+```
+
+will raise a `NameError`. In some cases, Ruby will be able to resolve an unintended constant in a different scope.
+
+If you hit this, please restart your debugging session with eager loading enabled (`config.eager_load = true`).
+
+Stepping commands line `next`, `continue`, etc., do not present this issue. Namespaces defined implictly only by subdirectories are not subject to this issue either.
+
+See [ruby/debug#408](https://github.com/ruby/debug/issues/408) for details.
 
 Debugging with the `web-console` gem
 ------------------------------------

railties/lib/rails/generators/rails/app/templates/Gemfile.tt

@@ -44,13 +44,7 @@ gem "bootsnap", ">= 1.4.4", require: false
 <% if RUBY_ENGINE == "ruby" -%>
 
 group :development, :test do
-  # Writing `binding.irb` in a spot to debug gives you a console. If the project
-  # depends on Pry, `binding.pry` is also available. For them to work, you don't
-  # need to depend on the `debug` gem.
-  #
-  # To get a proper debugger, depend on the `debug` gem and execute `binding.b`.
-  # However, better eager load the application, because `debug` and autoloading
-  # are not fully compatible. See https://github.com/ruby/debug/issues/408.
+  # See https://edgeguides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
   gem "debug", ">= 1.0.0", platforms: %i[ mri mingw x64_mingw ]
 end
 <% end -%>