---

name: best-practices description: This skill should be used when the user asks to "refactor", "refactor the whole project", "simplify code", "clean up code", "apply best practices", "improve readability", "reduce duplication", "standardize patterns", "improve performance", "optimize Next.js performance", "make code more maintainable", "follow coding standards", "optimize code quality", or requests behavior-preserving refactoring with best-practice guidance. user-invocable: false version: 1.2.0

Best Practices

Scope

Support both:

• Targeted refactoring: recently modified code in the current session, or specific files/directories provided by the user
• Project-wide refactoring: entire repository when explicitly requested

Agent Invocation

Launch the code-simplifier agent for execution. Pass the target scope and any constraints. If already running inside code-simplifier, skip launching and proceed with the workflow.

Language References

Based on file extension, load the appropriate reference:

• .ts, .tsx, .js, .jsx → See references/typescript.md
• .py → See references/python.md
• .go → See references/go.md
• .swift → See references/swift.md

For universal principles applicable to all languages, see references/universal.md.

Next.js Best Practices References

Use the Next.js reference set when the target includes Next.js code (typically .tsx, .jsx, Next.js app/pages routes, Server Components, Client Components).

Reference directory:

• references/nextjs/

Recommended entry points:

1. Read references/nextjs/INDEX.md for complete pattern index organized by impact level and category.
2. Read references/nextjs/_sections.md to understand priorities and categories.
3. Read the specific rule file(s) that match the pattern observed (for example, async-defer-await.md, bundle-dynamic-imports.md).

Rule Application Guidance

• Prefer CRITICAL rules first when there is evidence of user-facing impact (waterfalls, bundle size, hydration issues).
• Keep changes minimal and targeted; optimize only when the pattern is present in the code.
• Preserve behavior and public interfaces; do not change externally visible semantics during a refactor.

Framework and Language Detection

Before applying refactoring rules, detect the project's frameworks and languages:

1. Framework Detection:

   • Check for Next.js: Look for next.config.js, next.config.ts, or "next" in package.json dependencies
   • Check for React: Look for "react" in package.json dependencies
   • Check for Vite: Look for vite.config.js, vite.config.ts
   • Check for other frameworks as needed

2. Language Detection:

   • Scan file extensions: .ts, .tsx (TypeScript), .js, .jsx (JavaScript)
   • .py (Python), .go (Go), .swift (Swift)

3. Rule Category Selection:

   • Based on detected frameworks and user configuration, determine which rule categories to apply:
     • Next.js projects only: async, bundle, server, client, rerender, rendering, js, advanced
     • React (non-Next.js) projects: client, rerender, rendering, js
     • All projects: Universal principles, language-specific rules

IMPORTANT: Only apply Next.js-specific rules if Next.js is actually detected. For Tauri + React + Vite projects or other React setups without Next.js, only apply React-specific and universal rules.

Rule Application Strategy

Apply rules based on framework detection and project characteristics:

• Next.js-specific rules: Only applied if Next.js is detected
• Language-specific rules: Applied based on detected file types
• Universal rules: Applied to all projects

Framework detection determines which rule categories are applicable.

Code Quality Standards

Apply these standards during all refactoring operations:

• Comments: Only add comments explaining complex business logic or non-obvious decisions; remove comments that restate code or conflict with file style
• Error Handling: Add try-catch only where errors can be handled/recovered; remove defensive checks in trusted internal paths (validate only at boundaries: user input, external APIs)
• Type Safety: Never use any to bypass type issues; use proper types, unknown with type guards, or refactor the root cause
• Style Consistency: Match existing code style in file and project; check CLAUDE.md for conventions

Workflow

1. Identify: Determine target scope (specified files/directories, session modifications, or entire project)
2. Detect: Identify frameworks (Next.js, React, Vite, etc.) and languages in the codebase
3. Load References: Load language references for the target files, plus framework-specific references when applicable
4. Filter Rules: Only apply rules for detected frameworks (e.g., skip Next.js rules if Next.js not present)
5. Analyze: Review code for complexity, redundancy, and best-practice violations that matter for the target scope
6. Execute: Apply behavior-preserving refinements following the loaded references and Code Quality Standards
7. Validate: Ensure tests pass (or suggest the most relevant tests to run) and the code is cleaner