feature-arch

Files (51)

• AGENTS.md
• README.md
• SKILL.md
• _template.md · assets/templates/
• feature-arch-target.md.template · assets/templates/
• metadata.json
• _blueprint-process.md · references/
• _sections.md · references/
• bound-event-based-communication.md · references/
• bound-feature-isolation.md · references/
• bound-feature-scoped-routing.md · references/
• bound-feature-size.md · references/
• bound-interface-contracts.md · references/
• bound-minimize-shared-state.md · references/
• fcomp-colocate-styles.md · references/
• fcomp-composition-over-props.md · references/
• fcomp-container-presentational.md · references/
• fcomp-error-boundaries.md · references/
• fcomp-props-as-data-boundary.md · references/
• fcomp-single-responsibility.md · references/
• fquery-avoid-n-plus-one.md · references/
• fquery-colocate-with-feature.md · references/
• fquery-feature-scoped-keys.md · references/
• fquery-parallel-fetching.md · references/
• fquery-server-component-fetching.md · references/
• fquery-single-responsibility.md · references/
• fstate-context-sparingly.md · references/
• fstate-feature-scoped-stores.md · references/
• fstate-lift-minimally.md · references/
• fstate-reset-on-unmount.md · references/
• fstate-server-state-separation.md · references/
• import-avoid-barrel-files.md · references/
• import-no-cross-feature.md · references/
• import-path-aliases.md · references/
• import-public-api.md · references/
• import-type-only.md · references/
• import-unidirectional-flow.md · references/
• name-descriptive-exports.md · references/
• name-feature-naming.md · references/
• name-file-conventions.md · references/
• struct-app-layer.md · references/
• struct-domain-folders.md · references/
• struct-feature-folders.md · references/
• struct-feature-self-contained.md · references/
• struct-flat-hierarchy.md · references/
• struct-optional-segments.md · references/
• struct-shared-layer.md · references/
• test-colocate-with-feature.md · references/
• test-feature-isolation.md · references/
• test-integration-at-app-layer.md · references/
• test-shared-utilities.md · references/

SKILL.md (first lines)

# 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](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](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

| 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
- `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

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills