# Feature Based Design

> Pragmatic grouping by business domain - optimized for speed, low cognitive load, and modular growth.

- Skill: `lucas-martino/feature-based-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lucas-martino/feature-based-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucas-martino/feature-based-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: lucas-martino (https://skillmd.com/u/lucas-martino)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lucas-martino/feature-based-design

---


# Feature-Based Design

**Context:** Architecture for frontend.
**Focus:** "Cohesion over Layers". Organizing the application by business modules (Features) to make the codebase intuitive and easy to navigate for small to medium-sized teams.
**Strengths:** Rapid development, low learning curve, high discoverability, and "Evolutionary" (easy to migrate to Micro-frontends later).
**Weaknesses:** Risk of "Shared Folder" bloat, potential for circular dependencies between features if not monitored.

---

## 1 The Modular Structure
The agent must enforce the organization of code into self-contained business modules:

1.  **Global Shared (src/components, src/hooks, src/utils):**
    * Truly generic elements (e.g., `Button`, `Input`, `useDebounce`).
    * **Constraint:** Zero business logic. Must be usable in any future project.
2.  **Feature Modules (src/modules/[feature-name]):**
    * The core of the app. Each folder is a mini-application.
    * Internal structure:
        - `/components`: UI elements exclusive to this feature.
        - `/hooks`: Logic and state management (Zustand/Context) exclusive to this feature.
        - `/services`: API calls and data transformation for this feature.
        - `/[Feature]Page.tsx`: The entry point/container for the module.
3.  **App Core (src/main.tsx, src/routes):**
    * Orchestrates the modules. Handles routing and global providers.

---

## 2 Mandatory Heuristics
-   **Local-First:** If a component is only used in "Checkout", it **must** live in `modules/checkout/components`. Moving to `shared` is a last resort.
-   **The "Rule of Three":** Only move a component or utility to the global `shared` folder if it is used by at least three different modules.
-   **Flat Module Hierarchy:** Modules should ideally be siblings. Avoid deep nesting of modules within modules to keep the pathing simple.
-   **Barrel Exports:** Each module should use an `index.ts` to expose its Page or public components, hiding internal implementation details.

---

## 3 Rejection Criteria (Hard Fails)
-   **Technical Layer Folders:** Creating top-level folders like `/controllers`, `/models`, or `/views` (The "Categorization by Type" anti-pattern).
-   **Cross-Feature Leakage:** `modules/billing` importing a private component from `modules/auth`. Only public API (via index.ts) or Shared elements can be imported.
-   **Fat Shared Folder:** Putting feature-specific logic (e.g., `ProductPriceFormatter`) inside the global `utils` folder.
-   **Circular Dependencies:** Module A importing Module B, which in turn imports Module A.

---

## 4 Review Checklist
* [ ] Is the code for this feature contained within a single directory?
* [ ] Can I delete a module folder without breaking the compilation of other modules (except for shared utils)?
* [ ] Does the `shared` folder contain only "Dumb Components" and generic helpers?
* [ ] Is the data fetching logic (API) located within the module it serves?
* [ ] Is the project structure flat enough that a new dev can find a feature in < 5 seconds?