best-practices

Best Practices

Language References

Each file extension maps to a specific reference:

• .ts, .js — references/typescript.md
• .tsx, .jsx — references/typescript.md + references/react/react.md
• .py — references/python.md + references/python/INDEX.md
• .go — references/go.md
• .swift — references/swift.md

Universal principles are in references/universal.md.

Next.js/React References

For Next.js projects, the references/react/ directory provides:

1. references/react/rules/INDEX.md — pattern index by impact level
2. references/react/rules/_sections.md — priorities and categories
3. Specific rule files matching observed patterns

Rule Application

• Framework-specific rules (e.g., Next.js) apply only when that framework is detected
• CRITICAL rules have highest priority: waterfalls, bundle size, hydration
• All refactoring MUST preserve behavior and public interfaces

Code Quality Standards

• Comments: Only for complex business logic; code-restating comments are unnecessary
• Error Handling: Try-catch only where recoverable; no defensive checks in trusted paths
• Type Safety: No any; proper types or unknown with guards are required
• Style: Existing code style and CLAUDE.md conventions take precedence
• Cleanup: Unused imports, variables, functions, and types are removed
• No compat hacks: Unused _vars and re-exports of deleted code are deleted
• Renaming: Descriptive names are preferred over marking as unused
• Dead code: Dead code is deleted, never commented out
• File Organization: Single Responsibility applies at file level; files with multiple concerns are candidates for splitting (see references/universal.md)