Feature-Based Architecture Best Practices

Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 43 rules across 8 categories, prioritized by impact from critical (directory structure, imports) to incremental (naming conventions). When invoked on a real project, the skill produces a project-specific blueprint that anchors every decision in those rules.

Primary Output: The Target Architecture Blueprint

When an agent invokes this skill on a real project, the deliverable is a single markdown file persisted at docs/architecture/FEATURE-ARCH-TARGET.md (or the repo's existing docs location). The blueprint contains:

1. Project context — framework, state libraries, routing model, current shape.
2. Identified features — confirmed with the user, sourced from routes, docs, openspec, and code clusters.
3. Target directory tree — literal paths, not pseudo-trees.
4. Per-feature public APIs — exact named exports of each index.ts.
5. Import-boundary matrix — N×N table of feature relationships (allowed / forbidden / via app / via events).
6. State & data ownership — server-state and client-state owner per feature.
7. Cross-feature communication policy — composition, events, or shared slice — with rationale.
8. Numbered migration plan — file-level move/create/delete steps with S/M/L effort estimates.
9. Human conformance checklist — for code review and "definition of done".
10. Open questions — anything that needs a human decision before migration.

Every section cites the specific rules below that govern its decisions, so the blueprint stays a projection of this skill — not a parallel authority.

How the agent generates the blueprint

Follow the process in references/_blueprint-process.md. Summary:

1. Gather context (package.json, src/ tree, README, CLAUDE.md, openspec/).
2. Identify candidate features from routes, docs, and code clusters.
3. Confirm the feature list with the user via AskUserQuestion.
4. Record explicit decisions (layer model, comm mechanism, state/routing owner).
5. Fill in assets/templates/feature-arch-target.md.template — every {{placeholder}} replaced with a literal project value.
6. Hand off: print path, summarise feature/step counts, list top-3 risks, suggest next action. Do not start executing migration steps in the same turn.

For very small projects (under ~10 source files), produce a one-page seed structure instead and note that a full blueprint should follow after the 2nd–3rd feature exists.

When to Apply

Reference these guidelines when:

• A project asks for a feature-based architecture target (generate the blueprint).
• 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

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
• struct-domain-folders - Group features into domains at large scale

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:

• Blueprint process - How to derive a project-specific target architecture
• Blueprint template - Template the agent fills in to produce the end-state document
• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules
• Individual rules: references/{prefix}-{slug}.md

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