medical-notes/AGENT.md

!!IMPORTANT RULES FOR AGENTS, NON-NEGOTIABLE

Markdown

Use Obsidian-flavored Markdown. Use fenced code blocks for code snippets, indicating the language when appropriate. Avoid extra new lines, prefer fewer new lines and compact formatting.

Coding

The rest of this document describes coding conventions to follow when writing code.

General

• Do not create comments nor docstrings when updating code unless asked.
• Do not create a summary .md file unless asked.
• Do not create a README.md file unless asked.
• When installing a new dependency, prefer to use the latest version.
• Try to reduce indentation, prefer to use early returns or continue everwhere, be excessive about it.

Python

• Use uv for handling python installations
• Use pyproject.toml to handle dependencies
• Avoid exceptions if possible
• When exceptions are necessary, use specific exception types, provide meaningful messages, and handle them appropriately.
• Exceptions try/except blocks should be as narrow as possible, try extra hard to avoid catching exceptions you did not intend to catch.
• Use type hints for all functions and methods.
• Use global constants for compiled regex patterns, capitalized and ending with _RE.
• Document regex patterns with inline comments using multiple strings inside re.compile(). This overrides the general rule against docstrings/comments.

Python unit testing:

• we should have a tests package under each implementation that has a test and the corresponding test foo/bar.py is tested in foo/bar/tests/test_bar.py
• Use pytest framework, version 9 or higher.
• Configure using pyproject.toml, avoid pytest.ini to be able to have all configuration in one place.
• Prefer parametrized tests for functions that need to be tested with multiple sets of inputs and expected outputs.
• Use the new `with subtest.test(...)´ for that purpose:

import pytest
def test_parametrized(subtests: pytest.Subtests) -> None:
    # ... setup code ...
    parameters = [...]
    for ... in parameters:
        with subtests.test(x=...):
            assert ...
    # ... tear down ... 

Django

• Prefer function based views over class based views
• Use django-stubs for type hints
• Use pytest-django for testing django applications
• Avoid comments in settings.

Style Learnings

• Stateful Parsing: For complex tasks like parsing, prefer stateful classes that share context via self to avoid passing many arguments.
• Match Statement Inlining: Prefer inlining simple, single-statement logic directly into match cases.
• Semantic Naming: Use names that reflect the domain (e.g. answer) rather than implementation details (e.g. spoiler).
• Data Propagation: Ensure all calculated metrics (like question counts) are consistently propagated to the final output structure.
• Factory Helpers: Use centralized factory methods (e.g. _create_question) to instantiate objects with many shared common fields.