developing-packages-r

运用现代 tidyverse 风格构建稳健的 R 包。当您需要创建或维护 R 包、设计 API 接口、选择依赖库、实施输入校验、编写错误信息，或在内部函数与对外暴露函数之间做出取舍时，这一技能将助您游刃有余。本技能囊括依赖策略、tidyverse API 设计模式、校验方法、结合 cli/rlang 进行错误处理、测试层级划分，以及文档编写的优先级考量。

SKILL.md

--- frontmatter

name: developing-packages-r
description: |
  Building robust R packages with modern tidyverse patterns. Use this skill when creating or maintaining R packages, designing APIs, choosing dependencies, implementing input validation, writing error messages, or deciding between internal and exported functions. Covers dependency strategy, tidyverse API design patterns, validation approaches, error handling with cli/rlang, testing levels, and documentation priorities.

Developing Packages R

This skill covers building robust R packages with modern patterns and best practices.

Dependency Strategy

When to Add Dependencies vs Base R

Add dependency when:

•Significant functionality gain
•Maintenance burden reduction
•User experience improvement
•Complex implementation (regex, dates, web)

Use base R when:

•Simple utility functions
•Package will be widely used (minimize deps)
•Dependency is large for small benefit
•Base R solution is straightforward

See dependency-decisions.md for example decisions.

Tidyverse Dependency Guidelines

Category	Packages	Guidance
Core (usually worth it)	dplyr, purrr, stringr, tidyr	Complex manipulation, functional programming
Specialized (evaluate carefully)	lubridate, forcats, readr, ggplot2	Only if heavy usage
Heavy (use sparingly)	tidyverse, shiny	Meta-package or interactive apps only

API Design Patterns

Modern Tidyverse API

See api-design.md for:

•Use .by for per-operation grouping
•Use {{ }} for user-provided columns
•Use ... for flexible arguments
•Return consistent types (tibbles, not data.frames)

Input Validation Strategy

Validation level depends on function type:

Function Type	Validation Level
User-facing	Comprehensive - check all inputs
Internal	Minimal - assume valid, check invariants
vctrs-based	Type-stable - automatic checking

See validation-patterns.md for examples.

Error Handling Patterns

Good error messages are:

•Specific - say what went wrong
•Actionable - say how to fix it
•Traceable - include function context

See error-handling.md for:

•cli package for user-friendly messages
•rlang for developer tools
•Including function name in errors

Internal vs Exported Functions

Export Function When:

•Users will call it directly
•Other packages might want to extend it
•Part of the core package functionality
•Stable API that won't change often

Keep Function Internal When:

•Implementation detail that may change
•Only used within package
•Complex implementation helpers
•Would clutter user-facing API

See internal-vs-exported.md for examples.

Testing Strategy

Testing Levels

Level	Purpose	Example
Unit tests	Individual functions	Edge cases, error handling
Integration tests	Workflow combinations	End-to-end pipelines
Property-based tests	Invariants	Function properties hold

See testing-patterns.md for examples.

Documentation Priorities

Must Document:

•All exported functions
•Complex algorithms or formulas
•Non-obvious parameter interactions
•Examples of typical usage

Can Skip Documentation:

•Simple internal helpers
•Obvious parameter meanings
•Functions that just call other functions

source: Sarah Johnson's gist https://gist.github.com/sj-io/3828d64d0969f2a0f05297e59e6c15ad