Always provide clear documentation and implementation for caching strategies, including key generation, invalidation policies, and default behaviors. When implementing caching:
Choose appropriate cache keys that balance specificity and reusability:
For CI environments, consider using commit SHA with restore-keys fallback:
```yaml
Explain what happens when cache configuration is missing
Specify available cache sources and their permissions (e.g., local vs. remote)
Describe the behavior of cache invalidation
Make cache behavior predictable and configurable:
Allow users to control cache sources (e.g., --cache=local:rw,remote:r)
Provide clear indicators when caching is enabled/disabled
Document which artifacts will be cached by default
Proper cache strategy documentation prevents unexpected behavior, improves performance, and gives users control over how and where their data is cached.
