Skip to contents

Artalytics R Packages – AGENTS Guidelines

Source: AGENTS.md

Development standards for AI agents (GitHub Copilot, Cursor, Claude, etc.) working with Artalytics R packages.

Environment Variables

See README.md for the complete list.

Each deployment environment sets variables directly - no config switching needed.

Package Hierarchy

artcore          <- Foundation (no internal deps)
  └── artutils   <- Utilities (depends on artcore only)
       └── mod*  <- Shiny modules (depend on artutils)

Directory Structure

Standard R package layout: - R/ - Source code - man/ - Generated docs (roxygen2) - tests/testthat/ - Unit tests - inst/ - Additional installed files - .github/workflows/ - CI workflows

Coding Standards

  • data.table over tidyverse for data manipulation
  • Native pipe |> (R 4.1+), not magrittr
  • stringr for string operations
  • snake_case for names
  • roxygen2 for all exported functions

Testing

  • testthat edition 3
  • Only test exported functions directly
  • Internal functions covered through exported callers
  • Use withr::local_*() helpers for cleanup

Test Isolation Rules

Rule Why
Mock inside test_that() only Top-level mocks bleed into other tests
Use local_*() helpers Automatic cleanup on exit
Keep state inside blocks Tests must run in any order

Build

devtools::document()  # Update NAMESPACE and man/
devtools::test()      # Run tests
devtools::check()     # Full R CMD check

All packages must pass R CMD check without errors or warnings.

Assets

All assets stored in DigitalOcean Spaces (CDN). No local artdata directory.

Use artcore CDN functions: - cdn_asset_url() - Get asset URLs - write_art_*() - Upload assets - has_object(), has_prefix() - Check existence