diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
index 2624069a5cc..3de1b99a571 100644
--- a/docs/dev/architecture.md
+++ b/docs/dev/architecture.md
@@ -146,6 +146,8 @@ Reading the docs of the `base_db::input` module should be useful: everything els
 
 **Architecture Invariant:** particularities of the build system are *not* the part of the ground state.
 In particular, `base_db` knows nothing about cargo.
+For example, `cfg` flags are a part of `base_db`, but `feature`s are not.
+A `foo` feature is a Cargo-level concept, which is lowered by Cargo to `--cfg feature=foo` argument on the command line.
 The `CrateGraph` structure is used to represent the dependencies between the crates abstractly.
 
 **Architecture Invariant:** `base_db` doesn't know about file system and file paths.
@@ -452,3 +454,4 @@ It is not cheap enough to enable in prod, and this is a bug which should be fixe
 
 rust-analyzer strives to be as configurable as possible while offering reasonable defaults where no configuration exists yet.
 There will always be features that some people find more annoying than helpful, so giving the users the ability to tweak or disable these is a big part of offering a good user experience.
+Mind the code--architecture gap: at the moment, we are using fewer feature flags than we really should.