feature-arch
React feature-based architecture guidelines for scalable applications. This skill should be used when writing, reviewing, or refactoring React code to ensure proper feature organization. When invoked on a project, the agent produces a concrete target-architecture blueprint at docs/architecture/FEATURE-ARCH-TARGET.md showing the desired directory tree, per-feature public APIs, import-boundary matrix, and a numbered migration plan. Triggers on tasks involving project structure, feature organization, module boundaries, cross-feature imports, data fetching patterns, or component composition.
pproenca · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add pproenca/dot-skills --skill feature-arch技能说明
name: feature-arch description: React feature-based architecture guidelines for scalable applications. This skill should be used when writing, reviewing, or refactoring React code to ensure proper feature organization. When invoked on a project, the agent produces a concrete target-architecture blueprint at docs/architecture/FEATURE-ARCH-TARGET.md showing the desired directory tree, per-feature public APIs, import-boundary matrix, and a numbered migration plan. 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 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:
- Project context — framework, state libraries, routing model, current shape.
- Identified features — confirmed with the user, sourced from routes, docs, openspec, and code clusters.
- Target directory tree — literal paths, not pseudo-trees.
- Per-feature public APIs — exact named exports of each
index.ts. - Import-boundary matrix — N×N table of feature relationships (
allowed/forbidden/via app/via events). - State & data ownership — server-state and client-state owner per feature.
- Cross-feature communication policy — composition, events, or shared slice — with rationale.
- Numbered migration plan — file-level move/create/delete steps with S/M/L effort estimates.
- Human conformance checklist — for code review and "definition of done".
- 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:
- Gather context (package.json, src/ tree, README, CLAUDE.md, openspec/).
- Identify candidate features from routes, docs, and code clusters.
- Confirm the feature list with the user via
AskUserQuestion. - Record explicit decisions (layer model, comm mechanism, state/routing owner).
- Fill in assets/templates/feature-arch-target.md.template — every
{{placeholder}}replaced with a literal project value. - 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 typestruct-feature-self-contained- Make features self-containedstruct-shared-layer- Use shared layer for truly generic code onlystruct-flat-hierarchy- Keep directory hierarchy flatstruct-optional-segments- Include only necessary segmentsstruct-app-layer- Separate app layer from featuresstruct-domain-folders- Group features into domains at large scale
2. Import & Dependencies (CRITICAL)
import-unidirectional-flow- Enforce unidirectional import flowimport-no-cross-feature- Prohibit cross-feature importsimport-public-api- Export through public API onlyimport-avoid-barrel-files- Avoid deep barrel file re-exportsimport-path-aliases- Use consistent path aliasesimport-type-only- Use type-only imports for types
3. Module Boundaries (HIGH)
bound-feature-isolation- Enforce feature isolationbound-interface-contracts- Define explicit interface contractsbound-feature-scoped-routing- Scope routing to feature concernsbound-minimize-shared-state- Minimize shared state between featuresbound-event-based-communication- Use events for cross-feature communicationbound-feature-size- Keep features appropriately sized
4. Data Fetching (HIGH)
fquery-single-responsibility- Keep query functions single-purposefquery-colocate-with-feature- Colocate data fetching with featuresfquery-parallel-fetching- Fetch independent data in parallelfquery-avoid-n-plus-one- Avoid N+1 query patternsfquery-feature-scoped-keys- Use feature-scoped query keysfquery-server-component-fetching- Fetch at server component level