diff --git a/docs/users/how_tos/compilation_database.md b/docs/users/how_tos/compilation_database.md
index 073ae91a72501..037d2ddb0352f 100644
--- a/docs/users/how_tos/compilation_database.md
+++ b/docs/users/how_tos/compilation_database.md
@@ -3,7 +3,13 @@ id: compilation_database
 title: Compilation databases
 ---
 
-# Generating compilation databases
+# Compilation databases
+
+Compilation databases are JSON files that Clang-based tooling (e.g.
+clangd and clang-tidy) consume to know what flags (in particular related
+to include paths) are used to build C++ files.
+
+## Generating compilation databases
 
 You can generate compilation databases for consumption by tools such as clangd
 and clang-tidy by running the following BXL script:
@@ -43,3 +49,23 @@ ln -sf $(buck2 bxl comp_db.bxl:gen -- --targets ...) $(git rev-parse --show-topl
 Providing better ergonomics for BXL scripts (such as enabling something like
 `buck2 comp_db`) is being discussed
 [here](https://github.com/facebook/buck2/issues/86).
+
+## Tools jumping to `buck-out`
+
+You may notice that your tools (e.g. clangd's Go To Definition feature)
+jump to symlinks into `buck-out`, rather than into the source tree.
+
+This is often problematic, because `buck-out` is not under source
+control (so all VCS-related editor tools fail), and text editors
+typically handle those symlinks poorly (e.g. VS Code will keep separate
+tabs for the symlink and the source header, and Vim will reuse an
+existing symlink buffer even when explicitly opening the source header).
+
+The fix for this is to use header maps instead. To enable header maps,
+set `header_mode = HeaderMode("header_map_only")` in your
+`CxxToolchainInfo`.
+
+Note that header maps are not supported by GCC. This should not be a
+problem since compilation databases are Clang technology, but you can
+setup a [build constraint](../../rule_authors/configurations.md) and
+conditionally set the header mode based on it if needed.
diff --git a/prelude/cxx/tools/compilation_database.bxl b/prelude/cxx/tools/compilation_database.bxl
index 655f58b2e67e1..6f9a08f2812ff 100644
--- a/prelude/cxx/tools/compilation_database.bxl
+++ b/prelude/cxx/tools/compilation_database.bxl
@@ -12,10 +12,6 @@ load("@prelude//utils:utils.bzl", "flatten")
 
 def _make_entry(ctx: bxl.Context, target: Label, compile_command: CxxSrcCompileCommand, add_target_name: bool) -> dict:
     args = compile_command.cxx_compile_cmd.base_compile_cmd.copy()
-
-    # This prevents clangd from jumping into `buck-out` when using Go To
-    # Definition, which significantly improves user experience.
-    args.add(["-I", "."])
     args.add(compile_command.cxx_compile_cmd.argsfile.cmd_form)
     args.add(compile_command.args)
     ctx.output.ensure_multiple(args)