Agent-Skills.md

Agent Skills: Feature-Based Architecture Best Practices

React feature-based architecture guidelines for scalable applications (formerly feature-architecture). This skill should be used when writing, reviewing, or refactoring React code to ensure proper feature organization. Triggers on tasks involving project structure, feature organization, module boundaries, cross-feature imports, data fetching patterns, or component composition.

UncategorizedID: pproenca/dot-skills/feature-arch

Repository

pproenca/dot-skills
pproenca

Install this agent skill to your local

pnpm dlx add-skill https://github.com/pproenca/dot-skills/tree/HEAD/skills/.curated/feature-arch

Skill Files

Browse the full folder contents for feature-arch.

Download Skill

Loading file tree…

skills/.curated/feature-arch/SKILL.md

Skill Metadata

Name
feature-arch
Description
React feature-based architecture guidelines for scalable applications (formerly feature-architecture). This skill should be used when writing, reviewing, or refactoring React code to ensure proper feature organization. Triggers on tasks involving project structure, feature organization, module boundaries, cross-feature imports, data fetching patterns, or component composition.

Feature-Based Architecture Best Practices

Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 42 rules across 8 categories, prioritized by impact from critical (directory structure, imports) to incremental (naming conventions).

When to Apply

Reference these guidelines when:

  • Creating new features or modules
  • Organizing project directory structure
  • Setting up import rules and boundaries
  • Implementing data fetching patterns
  • Composing components from multiple features
  • Reviewing code for architecture violations

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Directory Structure | CRITICAL | struct- | | 2 | Import & Dependencies | CRITICAL | import- | | 3 | Module Boundaries | HIGH | bound- | | 4 | Data Fetching | HIGH | fquery- | | 5 | Component Organization | MEDIUM-HIGH | fcomp- | | 6 | State Management | MEDIUM | fstate- | | 7 | Testing Strategy | MEDIUM | test- | | 8 | Naming Conventions | LOW | name- |

Quick Reference

1. Directory Structure (CRITICAL)

  • struct-feature-folders - Organize by feature, not technical type
  • struct-feature-self-contained - Make features self-contained
  • struct-shared-layer - Use shared layer for truly generic code only
  • struct-flat-hierarchy - Keep directory hierarchy flat
  • struct-optional-segments - Include only necessary segments
  • struct-app-layer - Separate app layer from features

2. Import & Dependencies (CRITICAL)

  • import-unidirectional-flow - Enforce unidirectional import flow
  • import-no-cross-feature - Prohibit cross-feature imports
  • import-public-api - Export through public API only
  • import-avoid-barrel-files - Avoid deep barrel file re-exports
  • import-path-aliases - Use consistent path aliases
  • import-type-only - Use type-only imports for types

3. Module Boundaries (HIGH)

  • bound-feature-isolation - Enforce feature isolation
  • bound-interface-contracts - Define explicit interface contracts
  • bound-feature-scoped-routing - Scope routing to feature concerns
  • bound-minimize-shared-state - Minimize shared state between features
  • bound-event-based-communication - Use events for cross-feature communication
  • bound-feature-size - Keep features appropriately sized

4. Data Fetching (HIGH)

  • fquery-single-responsibility - Keep query functions single-purpose
  • fquery-colocate-with-feature - Colocate data fetching with features
  • fquery-parallel-fetching - Fetch independent data in parallel
  • fquery-avoid-n-plus-one - Avoid N+1 query patterns
  • fquery-feature-scoped-keys - Use feature-scoped query keys
  • fquery-server-component-fetching - Fetch at server component level

5. Component Organization (MEDIUM-HIGH)

  • fcomp-single-responsibility - Apply single responsibility to components
  • fcomp-composition-over-props - Prefer composition over prop drilling
  • fcomp-container-presentational - Separate container and presentational concerns
  • fcomp-props-as-data-boundary - Use props as feature boundaries
  • fcomp-colocate-styles - Colocate styles with components
  • fcomp-error-boundaries - Use feature-level error boundaries

6. State Management (MEDIUM)

  • fstate-feature-scoped-stores - Scope state stores to features
  • fstate-server-state-separation - Separate server state from client state
  • fstate-lift-minimally - Lift state only as high as necessary
  • fstate-context-sparingly - Use context sparingly for feature state
  • fstate-reset-on-unmount - Reset feature state on unmount

7. Testing Strategy (MEDIUM)

  • test-colocate-with-feature - Colocate tests with features
  • test-feature-isolation - Test features in isolation
  • test-shared-utilities - Create feature-specific test utilities
  • test-integration-at-app-layer - Write integration tests at app layer

8. Naming Conventions (LOW)

  • name-feature-naming - Use domain-driven feature names
  • name-file-conventions - Use consistent file naming conventions
  • name-descriptive-exports - Use descriptive export names

How to Use

Read individual reference files for detailed explanations and code examples:

Related Skills

  • For feature planning, see feature-spec skill
  • For data fetching, see tanstack-query skill
  • For React component patterns, see react-19 skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md