diff --git a/pkgs/clan-cli/pyproject.toml b/pkgs/clan-cli/pyproject.toml
index bec9da247..969f91a40 100644
--- a/pkgs/clan-cli/pyproject.toml
+++ b/pkgs/clan-cli/pyproject.toml
@@ -34,6 +34,11 @@ log_level = "DEBUG"
 log_format = "%(message)s"
 addopts = "--cov . --cov-report term --cov-report html:.reports/html --no-cov-on-fail --durations 5 --color=yes --new-first -W error -n auto" # Add --pdb for debugging
 norecursedirs = ["clan_cli/tests/helpers", "clan_cli/nixpkgs"]
+#  All tests which evaluate any nix library code from clan-core need to use the
+#  `with_core` marker, so basically all tests which evaluate a flake with
+#  machines. In the CI pipeline we run these tests in a separate derivation
+#  depending on clan-core. All other tests do not need to depend on clan-core
+#  and can be cached more effectively.
 markers = ["impure", "with_core"]
 filterwarnings = "default::ResourceWarning"