From d3ec14f1f689f396d1969354faf0f7600b474207 Mon Sep 17 00:00:00 2001
From: Alexander ADAM <alexander.adam@vade.io>
Date: Tue, 21 Oct 2025 19:26:46 +0200
Subject: [PATCH] add `.descendants` and `.subclasses` advice

---
 README.adoc | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/README.adoc b/README.adoc
index cf59a43..bcc697b 100644
--- a/README.adoc
+++ b/README.adoc
@@ -745,6 +745,25 @@ end
 
 Check the https://github.com/norman/friendly_id[gem documentation] for more information about its usage.
 
+=== Avoid `Class#descendants` and `Class#subclasses` [[avoid-class-descendants]]
+
+Avoid using `Class#descendants` and `Class#subclasses` as they are unreliable for several reasons:
+
+* They don't know about things that have yet to be autoloaded
+* They're non-deterministic with regards to Garbage Collection of classes. If you use `Class#descendants` or `Class#subclasses` in tests, where there is a pattern to dynamically define classes, GC is unpredictable for when those classes are cleaned up and removed by the GC.
+
+[source,ruby]
+----
+# bad
+class Person < ApplicationRecord
+end
+
+class Employee < Person
+end
+
+Person.descendants # => Unreliable, may or may not include Employee
+----
+
 === `find_each` [[find-each]]
 
 Use `find_each` to iterate over a collection of AR objects.