Agent RulesAgent Rules
LI

Library Architecture

Library design patterns, API surface, versioning, and distribution

Groovy
Architecture
library
Use in BuilderAll Groovy Options

Details

Language / Topic
groovyGroovy
Category
Architecture

Rules

balanced
- Design a minimal, intuitive public API. Every exported symbol is a commitment — keep the surface area small.
- Follow semantic versioning strictly: breaking changes = major, new features = minor, bug fixes = patch.
- Write comprehensive documentation: README with quick start, API reference, migration guides between major versions.
- Ship both ESM and CJS (for JS/TS) or the idiomatic package format for your language. Support tree-shaking.
- Use the facade pattern: expose a clean public API that hides internal complexity. Internal modules should not be importable.
- Deprecate before removing. Mark APIs as deprecated for at least one major version before removal. Include migration path in deprecation message.
- Write examples for every public function. Examples serve as both documentation and regression tests.
- Minimize dependencies. Every dependency is a liability — it can break, have vulnerabilities, or conflict with user deps.
- Version your error types. Users may match on error kinds, so changing error variants is a breaking change.
- Support both sync and async patterns where applicable. Do not force async on users who do not need it.