Document configuration rationale

When adding or modifying configuration files, always include clear comments or documentation explaining the reasoning behind non-obvious choices, especially when suppressing warnings, excluding files, or making decisions that deviate from defaults.

Configuration decisions often involve trade-offs or address specific operational issues that may not be immediately apparent to other developers. Documenting the rationale helps prevent future confusion and accidental reversions.

Examples of good documentation:

# .npmrc
# Suppress workspace cycle warnings for dev dependencies in test code
ignore-workspace-cycles=true

# Keep pre/post script behavior during migration to minimize changes
enable-pre-post-scripts=true

# .eslintignore
# Exclude lock file to prevent CI formatting loops between pnpm and Prettier
pnpm-lock.yaml

This practice is particularly important for suppressions, exclusions, and migration-related configurations where the reasoning may not be obvious from the configuration itself.