Next.js Scope Rule Architect

1. Overview

This skill implements the Scope Rule for Next.js architecture, a non-negotiable principle for maintaining scalable codebases. It analyzes usage patterns to decide whether a component, hook, or utility should be Local (private to a feature) or Shared (available globally). It ruthlessly prevents "shared folder dumping" (premature abstraction).

2. Prerequisites & Context

• •Required Tools:
  • •grep_search: To count the number of times a component is imported across different features.
  • •list_dir: To explore current component locations.
  • •move_file: (Conceptual) To recommend moving files based on the rule.
• •Environment: Any Next.js project structure.
• •Input:
  • •Name of the file/component in question.
  • •(Optional) Usage context (e.g., "I want to use the ProductCard in the Cart page too").

3. Workflow

1. •Identify Artifact: Pinpoint the specific component, hook, or type being discussed.
2. •Analyze Usage:
   • •Use grep_search to find all imports of this artifact throughout the src/app directory.
   • •Count distinct Route Groups or top-level Features consuming it.
3. •Apply Logic:
   • •Usage Count = 1: The artifact MUST reside in that feature's private _components (or _hooks, etc.) folder.
   • •Usage Count ≥ 2: The artifact MUST be moved to src/shared/components (or src/shared/hooks, etc.).
4. •Recommend Action: Provide exact move commands or refactoring instructions.

4. Detailed Instructions & Rules

Critical Rules

• • Rule 1: 1 Feature = Local. If a component is used in only one feature (even if multiple times within that feature), it must stay in that feature's private folder.
• • Rule 2: 2+ Features = Shared. As soon as a second, distinct feature imports a component, it must be promoted to src/shared.
• • Rule 3: Never create a "Common" or "Utils" folder inside a feature. Use _utils or specific names like _components.
• • Rule 4: When promoting to shared, always ensure the component is decoupled from feature-specific logic (e.g., it shouldn't import from (auth)/...).
• • Rule 5: Start Local. When creating a new component, always put it in the local feature folder first. Only move it later if needed.

Logic Matrix

5. Examples

Example 1: Promoting a Component

See examples/promote-component.md.

Example 2: Premature Optimization

See examples/keep-local.md.