coding-guidelines
Comprehensive React component coding guidelines, refactoring principles, and architectural patterns. **CRITICAL**: Focuses on patterns AI commonly fails to implement correctly, especially testability, props control, and component responsibility separation. Reference this skill when implementing or refactoring React components during Phase 2.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for React and Next.js development, focusing on professional-grade architectural patterns and code quality. It offers specialized guidance on implementing Server Components, ensuring component testability through strict props control, and managing complex side effects with useEffect best practices. By enforcing the Entity/Gateway pattern and clear directory structures, it helps developers build scalable, maintainable, and highly testable frontend applications while avoiding common AI-generated code pitfalls.
Use Cases
- Refactoring legacy React components to improve testability by extracting business logic into pure functions and ensuring all UI states are controllable via props.
- Architecting Next.js applications using the App Router to correctly implement Server Components and async data fetching patterns.
- Optimizing React performance and reliability by auditing useEffect hooks, managing reactive dependencies, and preventing unnecessary re-renders.
- Establishing a standardized project directory structure and naming convention (Entity/Gateway pattern) for large-scale enterprise frontend codebases.
- Developing robust testing strategies and Storybook documentation using the AAA (Arrange-Act-Assert) pattern to ensure high branch coverage and UI consistency.
| name | coding-guidelines |
|---|---|
| description | Provides React/Next.js component guidelines focusing on testability, Server Components, entity/gateway pattern, and directory structure. Use when implementing components, refactoring code, organizing project structure, extracting conditional branches, or ensuring code quality standards. |
Coding Guidelines
Guidelines for React/Next.js development focusing on testability, Server Components, and proper architecture. Each guideline file contains principles, code examples, and anti-patterns to avoid.
Quick Reference
- Server Components & Data Fetching → server-components.md
- Testability & Props Control → testability.md
- useEffect Guidelines & Dependencies → useeffect-guidelines.md
- Architecture & Patterns → architecture.md
- Test Guidelines (Vitest/RTL) → test-guidelines.md
- Storybook Guidelines → storybook-guidelines.md
When to Use What
Server Components
When: Writing server-side data fetching or async components Read: server-components.md
Key topics:
- Server Component Pattern (async/await, Suspense)
- Promise Handling (.then().catch() vs try-catch)
- When NOT to use "use client"
Testability
When: Writing "use client" components, useEffect, or event handlers Read: testability.md
Key topics:
- Props Control (all states controllable via props)
- Closure Variable Dependencies (extract to pure functions)
- Conditional Branch Extraction (JSX → components, useEffect → pure functions)
useEffect Guidelines & Dependencies
When: Deciding whether to use useEffect, managing dependencies, or avoiding unnecessary re-renders Read: useeffect-guidelines.md
Key topics:
- When you DON'T need useEffect (data transformation, expensive calculations)
- When you DO need useEffect (external system synchronization)
- Event handlers vs Effects decision framework
- Data fetching patterns and race conditions
- Separating reactive and non-reactive logic
- Managing dependencies (updater functions, useEffectEvent, avoiding objects/functions)
- Reactive values and dependency array rules
- Never suppress the exhaustive-deps linter
Architecture
When: Creating files, functions, or organizing code structure Read: architecture.md
Key topics:
- Directory Structure (component collocation, naming)
- Entity/Gateway Pattern (data types and fetching)
- Function Extraction (action-based design)
- Presenter Pattern (conditional text)
Test Guidelines
When: Creating or updating test code during Phase 2 (Testing & Stories) Read: test-guidelines.md
Key topics:
- AAA Pattern (Arrange-Act-Assert)
- Test Structure (describe/test descriptions in Japanese)
- Coverage Standards (branch coverage, exception paths)
- React Testing Library best practices
- Snapshot testing guidelines
Storybook Guidelines
When: Creating Storybook stories for components with conditional rendering during Phase 2 (Testing & Stories) Read: storybook-guidelines.md
Key topics:
- Story Creation Rules (conditional branching focus)
- Meta Configuration (minimal setup)
- Event Handlers (fn() usage)
- Anti-patterns to avoid
Core Principles
- Server Component First: Default to Server Components, use "use client" only when necessary
- Props Control Everything: All UI states must be controllable via props for testability
- Pure Functions: Extract all conditional logic from useEffect/handlers
- No Closure Dependencies: Pass all variables as function arguments
- Entity/Gateway Pattern: Separate data types (entity) from fetching logic (gateway)
- Collocate Functions: Place function files at same level as components, no utils/ directories
Quick Decision Tree
Are you writing a component?
├─ Does it need interactivity? (onClick, useState, useEffect)
│ ├─ YES → "use client" required
│ │ ├─ Using useEffect?
│ │ │ └─ Read: useeffect-guidelines.md (Do you really need it? + Managing dependencies)
│ │ └─ Read: testability.md
│ └─ NO → Server Component (default)
│ └─ Read: server-components.md
│
├─ Does it fetch data?
│ └─ Read: server-components.md + architecture.md (Entity/Gateway)
│
├─ Are you organizing files/functions?
│ └─ Read: architecture.md (Directory Structure)
│
├─ Are you writing tests?
│ └─ Read: test-guidelines.md (AAA Pattern, Coverage, RTL)
│
└─ Are you creating Storybook stories?
└─ Read: storybook-guidelines.md (Conditional Branching, Story Structure)