Incremental React architecture guidelines as an agent skill
npm install react-gradual-architecture> Incremental React code organization guidelines for AI-assisted development
An agent skill that helps you organize React code without over-structuring. The core philosophy: start small (one file), extract only when it improves clarity or reuse.
This skill provides 12 practical rules across 5 categories to help you:
- Create new React features without premature structure
- Organize component files and folders incrementally
- Refactor growing components at the right time
- Decide when to extract hooks, UI, or utils
- Structure feature directories and shared code
Key principle: Apply the smallest change that restores clarity. Extract only when it improves readability or enables reuse.
Install this skill in your AI coding environment:
``bash`
npx add-skill vandriesh/react-gradual-architecture
Or manually add to your .cursor/skills/ or equivalent directory.
When working with AI coding assistants, use prompts like:
`
Create a new React authentication feature following @react-gradual-architecture principles
`
Refactor this component using @react-gradual-architecture guidelines
The skill will guide the AI to:
1. Start in a single file
2. Extract only when scanning becomes difficult
3. Organize by feature, not by type
4. Keep state local, lift only when needed
- Locality - Keep related files close to the feature
- Reuse boundaries - Wait for the second use before extracting
- Feature README - Document structure and specifications$3
- Extract when scrolling - If scanning is difficult, extract
- Hooks vs functions - Hooks for React logic, plain functions for everything else
- UI/logic/utils - Extract when concerns diverge
- Container/presentational - Separate data from UI when needed$3
- Types placement - Define types where data is born
- State placement - Keep state local, lift only as high as neededDocumentation
- Quick reference guide for AI agents
- AGENTS.md - Comprehensive guide with detailed examples (1000+ lines)
- rules/ - Individual rule files with edge cases
- examples/PROMPTS.md - Example prompts for common tasksCompatibility
- React
- Works with Cursor, GitHub Copilot, and other AI coding assistants
Examples
$3
`
Create a user profile feature following @react-gradual-architecture:
- Start in a single file
- Add display and edit functionality
- Handle data fetching
The AI will create a single
file and only extract when the file grows beyond ~100 lines or concerns diverge.$3
`
Refactor this 300-line component using @react-gradual-architecture principles:
- Extract when scanning (comprehending) becomes difficult
- Separate UI from data logic
- Keep types where data is born
This skill embraces gradual architecture - the idea that structure should emerge from needs, not be imposed upfront:
1. Start simple - One file is enough to begin
2. Extract when needed - Let pain points guide extraction
3. Organize by domain - Feature folders, not technical folders
4. Keep things close - Locality reduces cognitive load
5. Wait for patterns - Second use reveals the right abstraction
Contributions welcome! Please feel free to submit issues or pull requests.
MIT License - see LICENSE file for details.
Created by @vandriesh
- Agent Skills Specification
- Vercel Agent Skills - Inspired by Vercel's collection of agent skills