From 19a2edde50c38412712306bf527faad6cbf81c2c Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Mon, 19 Jan 2026 17:03:03 +0000
Subject: [PATCH 1/3] iwyu: Do not export C++ headers in most cases

`IWYU pragma: export` enforces the transitive inclusion of the headers,
which undermines the purpose of IWYU.

The remained cases seem useful and could be considered separately:
- `<cassert>` in `util/check.h`
- `<filesystem>` in `util/fs.h`
- `<chrono>` in `util/time.h`
---
 src/util/strencodings.h | 4 ++--
 src/util/string.h       | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/util/strencodings.h b/src/util/strencodings.h
index 01063858047..fe0e2554c6f 100644
--- a/src/util/strencodings.h
+++ b/src/util/strencodings.h
@@ -20,8 +20,8 @@
 #include <cstdint>
 #include <limits>
 #include <optional>
-#include <string>      // IWYU pragma: export
-#include <string_view> // IWYU pragma: export
+#include <string>
+#include <string_view>
 #include <system_error>
 #include <type_traits>
 #include <vector>
diff --git a/src/util/string.h b/src/util/string.h
index 330c2a2a61e..2578e530af5 100644
--- a/src/util/string.h
+++ b/src/util/string.h
@@ -12,8 +12,8 @@
 #include <cstring>
 #include <locale>
 #include <sstream>
-#include <string>      // IWYU pragma: export
-#include <string_view> // IWYU pragma: export
+#include <string>
+#include <string_view>
 #include <vector>
 
 namespace util {

From e1a90bcecc823a4abaa2a57f393cad675a2ccbc0 Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Mon, 19 Jan 2026 17:03:11 +0000
Subject: [PATCH 2/3] iwyu: Do not export `crypto/hex_base.h` header

---
 src/core_io.cpp            | 1 +
 src/kernel/chainparams.cpp | 1 +
 src/node/blockstorage.cpp  | 1 +
 src/util/strencodings.h    | 2 +-
 4 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/core_io.cpp b/src/core_io.cpp
index a789d5ca947..d22e2251b62 100644
--- a/src/core_io.cpp
+++ b/src/core_io.cpp
@@ -9,6 +9,7 @@
 #include <consensus/amount.h>
 #include <consensus/consensus.h>
 #include <consensus/validation.h>
+#include <crypto/hex_base.h>
 #include <key_io.h>
 #include <primitives/block.h> // IWYU pragma: keep
 #include <primitives/transaction.h>
diff --git a/src/kernel/chainparams.cpp b/src/kernel/chainparams.cpp
index c25455d0f1c..16ebffb9a98 100644
--- a/src/kernel/chainparams.cpp
+++ b/src/kernel/chainparams.cpp
@@ -9,6 +9,7 @@
 #include <consensus/amount.h>
 #include <consensus/merkle.h>
 #include <consensus/params.h>
+#include <crypto/hex_base.h>
 #include <hash.h>
 #include <kernel/messagestartchars.h>
 #include <logging.h>
diff --git a/src/node/blockstorage.cpp b/src/node/blockstorage.cpp
index 84b7cfec7c7..37bf1799aa4 100644
--- a/src/node/blockstorage.cpp
+++ b/src/node/blockstorage.cpp
@@ -7,6 +7,7 @@
 #include <arith_uint256.h>
 #include <chain.h>
 #include <consensus/params.h>
+#include <crypto/hex_base.h>
 #include <dbwrapper.h>
 #include <flatfile.h>
 #include <hash.h>
diff --git a/src/util/strencodings.h b/src/util/strencodings.h
index fe0e2554c6f..b070e5b8c40 100644
--- a/src/util/strencodings.h
+++ b/src/util/strencodings.h
@@ -9,7 +9,7 @@
 #ifndef BITCOIN_UTIL_STRENCODINGS_H
 #define BITCOIN_UTIL_STRENCODINGS_H
 
-#include <crypto/hex_base.h> // IWYU pragma: export
+#include <crypto/hex_base.h>
 #include <span.h>
 #include <util/string.h>
 

From d938947b3a89a61784a72c533df623f9eb2fec49 Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Mon, 19 Jan 2026 17:03:16 +0000
Subject: [PATCH 3/3] doc: Add "Using IWYU" to Developer Notes

---
 doc/developer-notes.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index d17f8024ee4..b8a16ec0901 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -558,6 +558,21 @@ llvm-cov show \
 
 The generated coverage report can be accessed at `build/coverage_report/index.html`.
 
+### Using IWYU
+
+The [`include-what-you-use`](https://github.com/include-what-you-use/include-what-you-use) tool (IWYU)
+helps to enforce the source code organization [policy](#source-code-organization) in this repository.
+
+To ensure consistency, it is recommended to run the IWYU CI job locally rather than running the tool directly.
+
+In some cases, IWYU might suggest headers that seem unnecessary at first glance, but are actually required.
+For example, a macro may use a symbol that requires its own include. Another example is passing a string literal
+to a function that accepts a `std::string` parameter. An implicit conversion occurs at the callsite using the
+`std::string` constructor, which makes the corresponding header required. We accept these suggestions as is.
+
+Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers
+and undermines the specific purpose of IWYU.
+
 ### Performance profiling with perf
 
 Profiling is a good way to get a precise idea of where time is being spent in
@@ -1057,7 +1072,7 @@ Write scripts in Python or Rust rather than bash, when possible.
 
   - *Rationale*: Excluding headers because they are already indirectly included results in compilation
     failures when those indirect dependencies change. Furthermore, it obscures what the real code
-    dependencies are.
+    dependencies are. The [Using IWYU](#using-iwyu) section describes a tool to help enforce this.
 
 - Don't import anything into the global namespace (`using namespace ...`). Use
   fully specified types such as `std::string`.