📝 Add links to the agentic software engineering tutorial

veit · veit · commit e1961bc725ac · 2026-06-25T09:57:59.000+02:00
diff --git a/docs/appendix/glossary.rst b/docs/appendix/glossary.rst
@@ -653,6 +653,20 @@ Glossary
          :doc:`Python4DataScience:productive/qa/pysa` and
          :doc:`Python4DataScience:productive/qa/wily`.
 
+         .. note::
+            We also use static code analysis and linting for the generated code
+            in agent-based software development:
+
+            .. code-block:: md
+               :caption: AGENTS.md
+
+               # Code quality and linting
+               - Use ruff, ty, prek, wily for code quality and linting.
+               - Run appropriate tooling after making changes to your code to ensure it meets quality standards.
+
+            .. seealso::
+               * :ref:`agentic-software-engineering:code-quality`
+
    Dynamic test procedures
        are used to find errors when executing the source code. A distinction is
        made between :term:`whitebox <Whitebox test>` and :term:`blackbox
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,14 +12,15 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import os
+
 # If extensions (or modules to document with autodoc) are in another
 # directory, add these directories to sys.path here. If the directory is
 # relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 #
 # import sys
 # sys.path.insert(0, os.path.abspath("."))
-import os
 import re
 
 # Set canonical URL from the Read the Docs Domain
@@ -62,6 +63,10 @@
     "python3.14": ("https://docs.python.org/3.14/", None),
     "jupyter-tutorial": ("https://jupyter-tutorial.readthedocs.io/en/latest/", None),
     "Python4DataScience": ("https://www.python4data.science/en/latest/", None),
+    "agentic-software-engineering": (
+        "https://agentic-software-engineering.readthedocs.io/en/latest/",
+        None,
+    ),
     "pytest": ("https://docs.pytest.org/en/latest/", None),
     "Sybil": ("https://sybil.readthedocs.io/en/latest/", None),
 }
diff --git a/docs/document/doctest.rst b/docs/document/doctest.rst
@@ -115,6 +115,17 @@ in a docstring or in another text file are fulfilled.
       :lines: 38-
       :lineno-start: 38
 
+.. note::
+   We also have doctests written for agent-based software development:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      - Include doctests in the docstrings of your functions to provide examples
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:documentation`
+
 .. seealso::
    :doc:`doctest <python3:library/doctest>` can also be used to continuous test
    the documentation: :ref:`ci-docs`.
diff --git a/docs/document/sphinx/docstrings.rst b/docs/document/sphinx/docstrings.rst
@@ -141,6 +141,18 @@ NumPy Style Guide:
            """
            return True
 
+.. note::
+   We also frequently use the NumPy Style Guide in agent-based software
+   development:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      - Use numpy-style docstrings for all functions and classes you create.
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:documentation`
+
 .. _napoleon:
 
 ``sphinx.ext.napoleon``
diff --git a/docs/libs/install.rst b/docs/libs/install.rst
@@ -262,6 +262,20 @@ different environment using:
 :term:`uv` simplifies the creation of an initial project structure and the
 management of your dependencies.
 
+.. note::
+   Many coding agents typically use ``pip`` when installing packages or running
+   scripts. We therefore need to configure them first to use ``uv``:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      - Use `uv` to manage Python environments and dependencies.
+      - Use `uv run` to execute Python scripts and commands.
+      - Don't edit `pyproject.toml` directly. Instead, use `uv add` and `uv add --dev` to manage dependencies.
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:uv`
+
 Installation
 ~~~~~~~~~~~~
 
diff --git a/docs/logging/index.rst b/docs/logging/index.rst
@@ -37,6 +37,21 @@ What are the advantages of  ``logging`` over  ``print``?
   `logging.disabled
   <https://docs.python.org/3/library/logging.html#logging.disable>`_.
 
+
+.. note::
+   We also use logging in agent-based software development to gain a more
+   detailed insight into errors:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      # Logging
+      - Use logging to provide insight into failures. Don’t use print for debugging. Don’t use logging to hide stack traces if you are going to fail anyway.
+      - Don't hide exceptions. Let them propagate up to the caller. If you need to catch an exception, log it and re-raise it.
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:logging`
+
 .. seealso::
 
    * `loguru <https://github.com/Delgan/loguru>`_, which makes logging almost as
diff --git a/docs/test/hypothesis.rst b/docs/test/hypothesis.rst
@@ -15,6 +15,17 @@ find errors in your tests.
    The :doc:`Jupyter Tutorial <jupyter-tutorial:notebook/testing/hypothesis>`
    describes how Hypothesis can also be used in Jupyter Notebooks.
 
+.. note::
+   We also use Hypothesis in agent-based software development:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      - Use the `hypothesis` library for property-based testing when you have complex input spaces or need to test edge cases.
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:testing`
+
 Installation
 ------------
 
diff --git a/docs/test/mock.rst b/docs/test/mock.rst
@@ -385,6 +385,18 @@ parameters.
    * `“Don’t Mock What You Don’t Own”
      <https://hynek.me/articles/what-to-mock-in-5-mins/>`_ by Hynek Schlawack
 
+.. note::
+   Even in agent-based software development, we try to avoid mocking as much as
+   possible:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      - Prefer testing real code where possible. Use mocks and `monkeypatch` when absolute necessary. Try to avoid mocking as much as possible.
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:testing`
+
 Avoiding mocks with multi-level testing
 ---------------------------------------
 
diff --git a/docs/test/pytest/builtin-fixtures.rst b/docs/test/pytest/builtin-fixtures.rst
@@ -314,6 +314,18 @@ The ``monkeypatch`` fixture offers the following functions:
        it is set, the value of the environment variable is changed to
        :samp:`{VALUE} + prepend + {OLD_VALUE}`
 
+.. note::
+   In agent-based software development, we try to avoid monkey patching as much
+   as possible:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      - Prefer testing real code where possible. Use mocks and `monkeypatch` when absolute necessary. Try to avoid mocking as much as possible.
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:testing`
+
 RMonkey patching of environment variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/test/pytest/index.rst b/docs/test/pytest/index.rst
@@ -24,6 +24,20 @@ module that simplifies testing even further.
 * pytest has an extensive ecosystem with over 800 :doc:`plugins` for advanced
   testing requirements; unittest is more limited in its extensibility.
 
+.. note::
+   We also use pytest for agent-based software development:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      # Testing
+      - Use `pytest` for testing your code.
+      - Collect pytest fixtures in a `conftest.py` file to avoid duplication.
+      - When a test fails, run the last failed test first using `uv run pytest --last-failed`.
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:testing`
+
 .. seealso::
    The :doc:`Jupyter tutorial <jupyter-tutorial:notebook/testing/ipytest>`
    explains how pytest can also be used in Jupyter Notebooks.
diff --git a/docs/test/tdd.rst b/docs/test/tdd.rst
@@ -175,3 +175,16 @@ Only then does he outline the following five steps::
 #. Go back to 2 until the list is empty
 
    Test and implement until the desired behaviour is achieved.
+
+.. note::
+   We also use test-driven development when we use coding agents to assist us
+   with software development:
+
+   .. code-block:: md
+      :caption: AGENTS.md
+
+      - Use Test Driven Development (TDD) for all code you write. Write tests before writing the implementation code.
+      - When you come across a bug or regression, think hard about writing a test and also how to create code that will prevent this from a happening again in the future.
+
+   .. seealso::
+      * :ref:`agentic-software-engineering:testing`
