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