diff --git a/docs/bugpattern/WithSignatureDiscouraged.md b/docs/bugpattern/WithSignatureDiscouraged.md
new file mode 100644
index 00000000000..1bd1c378697
--- /dev/null
+++ b/docs/bugpattern/WithSignatureDiscouraged.md
@@ -0,0 +1,12 @@
+`withSignature` replies on the string representation of internal classes in the
+javac implementation. Those string representations are not necessarily stable
+across versions of javac, and they can change when a method is annotated with
+type-use annotations.
+
+Additionally, `withSignature` currently has at least one undocumented behavioral
+quirk.
+
+The most reasonable use case for `withSignature` is for methods that declare or
+use type variables, which are difficult or impossible to express with the rest
+of the `MethodMatchers` API. Still, where practical, prefer to write your own
+matching code instead of using `withSignature`.