Best Practices

Best Practices

Language References

Based on file extension, load the appropriate 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: references/universal.md

Next.js/React References

For Next.js projects, use references/react/ directory:

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

• Auto-detect frameworks; only apply Next.js rules if Next.js is detected
• Prefer CRITICAL rules first (waterfalls, bundle size, hydration)
• Preserve behavior and public interfaces

Code Quality Standards

• Comments: Only for complex business logic; remove code-restating comments
• Error Handling: Try-catch only where recoverable; no defensive checks in trusted paths
• Type Safety: No any; use proper types or unknown with guards
• Style: Match existing code style; check CLAUDE.md
• Cleanup: Remove all unused imports, variables, functions, types
• No compat hacks: Delete unused _vars, re-exports of deleted code
• Renaming: Use descriptive names instead of marking unused
• Dead code: Delete completely, never comment out

Workflow

1. Identify target scope
2. Detect frameworks and languages
3. Load language + framework references
4. Filter rules for detected frameworks only
5. Analyze complexity, redundancy, violations
6. Execute behavior-preserving refinements
7. Validate tests pass