Skip to content

rules

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

rules

README.md

.cursorrules - Quick Reference

Development standards and coding guidelines for the Research Project Template.

Files

Main Documents

  • AGENTS.md - overview and navigation (start here)
  • README.md - This file (quick reference)

Development Standards

  • error_handling.md - Exception handling patterns
  • python_logging.md - Logging standards and best practices
  • infrastructure_modules.md - Infrastructure module development guide
  • testing_standards.md - Testing patterns and coverage
  • documentation_standards.md - AGENTS.md and README.md writing guide
  • type_hints_standards.md - Type annotation patterns
  • llm_standards.md - LLM/Ollama integration patterns
  • code_style.md - Code formatting and style standards
  • git_workflow.md - Git workflow and commit standards
  • security.md - Security standards and guidelines
  • api_design.md - API design and interface standards
  • manuscript_style.md - Manuscript formatting and style standards
  • reporting.md - Reporting module standards and outputs
  • refactoring.md - Refactoring and modularization standards (clean break approach)

Key Principles

Two-Layer Architecture

  • Layer 1: Infrastructure (infrastructure/): Generic, reusable tools

    • Works with any project
    • 60% minimum test coverage required (currently achieving 83.33% - exceeds stretch goal!)
    • Can be copied to other repositories

  • Layer 2: Project (projects/): Research-specific code

    • Domain-specific algorithms and analysis
    • Uses Layer 1 tools
    • 90% minimum test coverage required (currently achieving 100% - coverage!)

Thin Orchestrator Pattern

  • Business logic: Implemented in module core.py or equivalent
  • Orchestration: Delegated to CLI wrappers and entry points (scripts/)
  • Scripts: Only coordinate, never duplicate logic
  • Key principle: "Import functions, don't implement algorithms"

Quality Standards

  • Tests: 60% infrastructure minimum, 90% project minimum (currently 83.33% infra, 100% project) with data (no mocks)
  • Types: Type hints on all public APIs and functions
  • Docs: AGENTS.md + README.md for every directory
  • Errors: Use custom exception hierarchy from infrastructure.core.runtime.exceptions
  • Logging: Unified logging via infrastructure.core.logging.logging_utils

Terminology Standards

These terms are used consistently across the codebase:

Term Definition Example
Layer 1 Infrastructure (generic) infrastructure/validation/
Layer 2 Project-specific projects/{name}/src/
Thin orchestrator Script that coordinates but doesn't implement scripts/03_render_pdf.py
Business logic Core computation and algorithms infrastructure/validation/core.py
Module Self-contained functionality infrastructure/rendering/
CLI Command-line interface infrastructure/rendering/cli.py

Quick Patterns

Imports

# Standard library first
import os
from pathlib import Path

# Infrastructure core utilities
from infrastructure.core.logging.logging_utils import get_logger
from infrastructure.core.runtime.exceptions import TemplateError

# Type hints
from typing import List, Dict, Optional

Logging

from infrastructure.core.logging.logging_utils import get_logger

logger = get_logger(__name__)
logger.debug("Debug message")
logger.info("Processing started")
logger.warning("Potential issue")
logger.error("Operation failed", exc_info=True)

Errors

from infrastructure.core.runtime.exceptions import ValidationError

try:
    result = operation()
except ValueError as e:
    raise ValidationError("Operation failed") from e

Type Hints

def process_data(items: list[str], count: int = 10) -> dict[str, int]:
    """Process data with type hints.
    
    Args:
        items: List of strings to process
        count: Number of items to process (default 10)
        
    Returns:
        Dictionary mapping item to processed count
    """
    return {item: len(item) for item in items[:count]}

Tests

import pytest

def test_feature_with_real_data():
    """Test feature using test data (no mocks)."""
    result = function({"name": "Alice", "age": 30})
    assert result["valid"] is True

def test_feature_error_condition():
    """Test that errors are raised correctly."""
    with pytest.raises(ValidationError):
        function({})  # Missing required fields

Documentation (AGENTS.md Structure)

# Module Name

## Overview
[What is this, why exists, who uses it]

## Quick Example
[5-10 lines showing usage]

## API Reference
[Key functions/classes]

## Configuration
[Config options]

## Testing
[How to run tests]

## See Also
[Related docs]

Documentation (README.md Structure)

# Module Name

[One-line description]

## Quick Start
[Minimal working example]

## Common Commands
[3-5 most used tasks]

## More Information
See [AGENTS.md](AGENTS.md) for docs

Manuscript Formatting

# Equations
\begin{equation}
\label{eq:objective}
f(x) = \sum_{i=1}^{n} w_i \phi_i(x)
\end{equation}
Using \eqref{eq:objective}...

# Figures
\begin{figure}[h]
\centering
\includegraphics[width=0.8\textwidth]{../output/figures/figure.png}
\caption{Descriptive caption.}
\label{fig:figure_name}
\end{figure}
See Figure \ref{fig:figure_name}...

# Tables
\begin{table}[h]
\centering
\begin{tabular}{|l|c|}
\hline
\textbf{Column 1} & \textbf{Column 2} \\
\hline
Data 1 & Data 2 \\
\hline
\end{tabular}
\caption{Table description.}
\label{tab:table_name}
\end{table}
Table \ref{tab:table_name} shows...

# Citations
According to \cite{author2023}, the method...
Multiple sources \cite{key1,key2,key3} show...

Checklist

Before commit:

  • Test coverage requirements met (60% infra, 90% project)
  • All tests pass
  • No linter errors
  • Docs updated
  • Type hints on all public APIs

Navigation Tips

Pick your task:

More Info