feature-arch

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