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.

⭐24stars🔀3forks📁View on GitHub🕐Updated Jan 1, 2026⬇️1downloads

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.
namecoding-guidelines
descriptionProvides 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


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

  1. Server Component First: Default to Server Components, use "use client" only when necessary
  2. Props Control Everything: All UI states must be controllable via props for testability
  3. Pure Functions: Extract all conditional logic from useEffect/handlers
  4. No Closure Dependencies: Pass all variables as function arguments
  5. Entity/Gateway Pattern: Separate data types (entity) from fetching logic (gateway)
  6. 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)