From f4a49b60a2e575b71ce105d37ce60a3d02df5856 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 14 Sep 2026 09:43:50 +0000 Subject: [PATCH 1/2] Update agents files Files updated: - AGENTS.md - .agents/skills/writing-tests/SKILL.md Co-Authored-By: Claude Opus 5 --- .agents/skills/writing-tests/SKILL.md | 27 +++++++++++++++++++++++++++ AGENTS.md | 17 ++++++++++++++--- 2 files changed, 41 insertions(+), 3 deletions(-) create mode 100644 .agents/skills/writing-tests/SKILL.md diff --git a/.agents/skills/writing-tests/SKILL.md b/.agents/skills/writing-tests/SKILL.md new file mode 100644 index 0000000..eeaf387 --- /dev/null +++ b/.agents/skills/writing-tests/SKILL.md @@ -0,0 +1,27 @@ +--- + name: writing-tests + description: Instructions and guidance on writing tests +--- +## Location +- tests are in `tests/`. +- doctests can be used instead of unit tests if the doctest fully covers the function/method's functionality. +- fixtures shared by the whole suite are located in `tests/conftest.py`; fixtures shared by the tests of one package are located in the `conftest.py` of that package's test directory. + +## Framework +- tests should assume use of the `pytest` framework. +- use appropriate features of the `pytest` framework, to include fixtures and mocking. +- a fixture that returns a class is named in CapWords, as a class is; every other fixture is named in snake_case. + +## Creating Test Datasets +- datasets should be assigned to global constants in order to facilitate external access. Tests should not access these constants directly but rather use them via fixtures which should in turn return a COPY of the constants. Note that this rule does not apply to small datasets of less than 10 rows which can be reasonably interpreted from inspection of the raw data. +- datasets shared by more than one test module are defined in a dedicated module of the test directory and exposed via fixtures in that directory's `conftest.py`. A test module must NEVER import from another test module. +- define test data to include values at the limits of where the output of tested functions/methods changes. + +## Writing tests +- tests should be written to test the INTENDED implementation with a focus on finding bugs. +- NEVER assume that the implementation is correct and that a test should pass. +- always test on and either side of limits where output changes. +- always seek to identify and test edge cases. + +## Documentation +- if including a docstring for a test then docstring should start with an imperative, for example 'Verify' or 'Test'. diff --git a/AGENTS.md b/AGENTS.md index eed7787..f6160c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,8 @@ See @pyproject.toml for project metadata and dependencies. SKILL.md update-agents-md/ SKILL.md + writing-tests/ + SKILL.md .github/ # GitHub configuration and CI/CD workflows workflows/ build-test.yml # Runs full test suite on platform/python matrix @@ -212,6 +214,10 @@ def my_func(param1: int, param2: str = "default", param3: None | str = None) -> """ ``` +#### Documentation content + +- when **revising documentation to reflect changes in implementation**, do NOT fall into the trap of documenting what's 'not the case' in the context of the previous implementation. Rather, just document what *is* the case, in the context of the revised implementation. Documentation that describes what the implementation does NOT do, in terms of a prior or erroneous implementation, is irrelevant and obfuscating to a reader who never knew of that prior implementation. Only ever make comparisons to erroneous or prior implementations if there is GOOD REASON to fear regression! + ### Comments - pay particular attention to comments starting with...: @@ -226,8 +232,13 @@ def my_func(param1: int, param2: str = "default", param3: None | str = None) -> ## Important Notes for AI Agents 1. **NEVER DO RULES**: - - Never edit the file `src/valimp/_version.py` - this is auto-generated by the build process. + - NEVER schedule a check-in unless specifically asked to. + - Never edit the file `src/valimp/_version.py` - this is auto-generated by the build process. + +2. **Do not assume that the package is coherent or free of bugs**, or that tests or documentation should be treated as gospel. If you come across a contradiction or a conflict or what you believe to be a bug, then say so. -2. **NumPy docstring style** — all new public functions/classes must use NumPy-convention docstrings and rules as defined under Docstrings section of this @AGENTS.md file. +3. **NumPy docstring style** — all new public functions/classes must use NumPy-convention docstrings and rules as defined under Docstrings section of this @AGENTS.md file. -3. **Branch naming** — git branches should follow the pattern `/` where the `` placeholder should be replaced with your colloquial name. +4. **Branch naming** — feature branches should follow the `/` pattern with the following substitutions: + - `` -> your name + - `` -> very short description of changes From bb37c64aff7a9b5b776ffdd885c40dff456434fd Mon Sep 17 00:00:00 2001 From: Marcus Read Date: Mon, 14 Sep 2026 11:57:40 +0100 Subject: [PATCH 2/2] Revise writing-tests skill. --- .agents/skills/writing-tests/SKILL.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/.agents/skills/writing-tests/SKILL.md b/.agents/skills/writing-tests/SKILL.md index eeaf387..179e5f5 100644 --- a/.agents/skills/writing-tests/SKILL.md +++ b/.agents/skills/writing-tests/SKILL.md @@ -13,8 +13,6 @@ - a fixture that returns a class is named in CapWords, as a class is; every other fixture is named in snake_case. ## Creating Test Datasets -- datasets should be assigned to global constants in order to facilitate external access. Tests should not access these constants directly but rather use them via fixtures which should in turn return a COPY of the constants. Note that this rule does not apply to small datasets of less than 10 rows which can be reasonably interpreted from inspection of the raw data. -- datasets shared by more than one test module are defined in a dedicated module of the test directory and exposed via fixtures in that directory's `conftest.py`. A test module must NEVER import from another test module. - define test data to include values at the limits of where the output of tested functions/methods changes. ## Writing tests