diff --git a/Lib/fontTools/otlLib/optimize/gpos.py b/Lib/fontTools/otlLib/optimize/gpos.py
index 3d3f83908..79873fadb 100644
--- a/Lib/fontTools/otlLib/optimize/gpos.py
+++ b/Lib/fontTools/otlLib/optimize/gpos.py
@@ -9,6 +9,9 @@ from fontTools.misc.intTools import bit_count, bit_indices
 from fontTools.ttLib import TTFont
 from fontTools.ttLib.tables import otBase, otTables
 
+# NOTE: activating this optimization via the environment variable is
+# experimental and may not be supported once an alternative mechanism
+# is in place. See: https://github.com/fonttools/fonttools/issues/2349
 GPOS_COMPACT_MODE_ENV_KEY = "FONTTOOLS_GPOS_COMPACT_MODE"
 GPOS_COMPACT_MODE_DEFAULT = "0"
 
diff --git a/Tests/otlLib/optimize_test.py b/Tests/otlLib/optimize_test.py
index db1cac5c3..40cf389e3 100644
--- a/Tests/otlLib/optimize_test.py
+++ b/Tests/otlLib/optimize_test.py
@@ -163,6 +163,9 @@ def test_optimization_mode(
 
     env = {}
     if mode is not None:
+        # NOTE: activating this optimization via the environment variable is
+        # experimental and may not be supported once an alternative mechanism
+        # is in place. See: https://github.com/fonttools/fonttools/issues/2349
         env["FONTTOOLS_GPOS_COMPACT_MODE"] = str(mode)
     with set_env(**env):
         fb = FontBuilder(1000)