coding-rules

Language and Repository Rules

Use the repository's formatter, linter, type system, naming conventions, and representative code patterns. Read a language reference only when it applies:

• TypeScript: references/typescript.md

Repository contracts and accepted design decisions take precedence over generic style preferences.

Minimal Change

• Implement the confirmed outcome through existing mechanisms where sufficient.
• Keep unrelated cleanup and optional hardening outside the change.
• Remove unused code encountered inside the changed responsibility when evidence shows no current consumer remains.
• Introduce an abstraction only when current callers share responsibility and change pressure.

Functions and Interfaces

• Keep one coherent responsibility per function or module.
• Use the language's idiomatic parameter and data-shape conventions.
• Make external dependencies and side effects visible at the appropriate boundary.
• Preserve public and shared contracts unless the approved scope changes them.
• Prefer simple control flow; refactor complexity when it obscures behavior or error handling.

Error Handling

• Preserve actionable error context across boundaries.
• Convert errors only where the receiving layer needs a different contract.
• Avoid logging the same error at every layer.
• Keep secrets, credentials, and unnecessary personal data out of logs and messages.
• Add fallback behavior only when a current requirement defines the degraded result.

Comments and Documentation

• Explain non-obvious intent, constraints, or trade-offs.
• Keep comments timeless and remove obsolete or commented-out code.
• Update documentation when an affected consumer would otherwise act on stale information.

Refactoring

1. Confirm the observable behavior and focused proof.
2. Make the smallest coherent structural change.
3. Run affected verification.
4. Continue only when another current problem remains.

Performance and Resources

• Measure a demonstrated bottleneck before optimizing.
• Use resource-lifecycle and data-structure patterns appropriate to the language and repository.
• Add caching, concurrency, batching, or monitoring only when a current requirement or measured problem justifies it.

Completion Check

• The implementation follows representative repository patterns or documents a necessary deviation.
• Added structure has a current consumer and purpose.
• Errors remain observable without duplicative logging or silent fallback.
• Applicable repository checks pass.