Skip to main content
rule CX Codex

state-decouple-implementation — Claude Code rule

state-decouple-implementation — a Claude Code rule that keeps state management inside providers and exposes only a context interface to UI components. Swap useState for Zustand or a server sync without touching a single UI file.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/state-decouple-implementation.md
Open on GitHub

What state-decouple-implementation does

The rule enforces one architectural boundary: providers own all state logic, UI components only read from a context interface. A component like ChannelComposer renders Composer.Frame and its children without knowing whether data comes from local state, a global store, or a remote sync.

The rule ships with TSX examples covering the wrong pattern — a UI component calling useGlobalChannelState and useChannelSync directly — and the correct one, where ChannelProvider wraps useGlobalChannel and passes state and actions to Composer.Provider. A third example shows ForwardMessageProvider backed by useState and ChannelProvider backed by useGlobalChannel sharing the same Composer.Input without any changes to that component.

To activate it in Claude Code, place the file at .claude/rules/state-decouple-implementation.md. From that point, the agent applies the pattern when generating new components and flags direct Zustand or Redux hook calls inside UI components during review.

What it helps with

  • move state logic out of a UI component into a dedicated provider
  • replace a Zustand store with server sync without rewriting form components
  • reuse Composer.Input across providers with different data sources
  • catch state implementation leaking into the UI layer during code review
  • enforce a consistent React architecture rule for an entire codebase

Example prompts for the agent

  • Refactor ChannelComposer — extract all state into a provider following the state-decouple-implementation rule
  • Generate a ForwardMessageProvider with local useState so Composer.Input stays unchanged
  • Check components under src/features/chat for direct Zustand hook calls

How to install state-decouple-implementation

Manually: put the files in place

.claude/rules/state-decouple-implementation.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about state-decouple-implementation

How do I install state-decouple-implementation in Claude Code?

Copy the rule file to .claude/rules/state-decouple-implementation.md in your project root. Claude Code picks it up automatically on the next run.

What does the state-decouple-implementation rule do?

It keeps UI components from knowing how state is managed. The provider hides useState, Zustand, or a server sync behind a shared context interface, so UI never changes when the data source does.

Does this rule work with any state management library?

Yes — that is the point of the pattern. ForwardMessageProvider uses local useState while ChannelProvider uses useGlobalChannel; both expose the same context shape, so Composer.Input works with either.

Source text

state-decouple-implementation.md · MIT
---
title: Decouple State Management from UI
impact: MEDIUM
impactDescription: enables swapping state implementations without changing UI
tags: composition, state, architecture
---

## Decouple State Management from UI

The provider component should be the only place that knows how state is managed.
UI components consume the context interface—they don't know if state comes from
useState, Zustand, or a server sync.

**Incorrect (UI coupled to state implementation):**

```tsx
function ChannelComposer({ channelId }: { channelId: string }) {
  // UI component knows about global state implementation
  const state = useGlobalChannelState(channelId)
  const { submit, updateInput } = useChannelSync(channelId)

  return (
    <Composer.Frame>
      <Composer.Input
        value={state.input}
        onChange={(text) => sync.updateInput(text)}
      />
      <Composer.Submit onPress={() => sync.submit()} />
    </Composer.Frame>
  )
}
```

**Correct (state management isolated in provider):**

```tsx
// Provider handles all state management details
function ChannelProvider({
  channelId,
  children,
}: {
  channelId: string
  children: React.ReactNode
}) {
  const { state, update, submit } = useGlobalChannel(channelId)
  const inputRef = useRef(null)

  return (
    <Composer.Provider
      state={state}
      actions={{ update, submit }}
      meta={{ inputRef }}
    >
      {children}
    </Composer.Provider>
  )
}

// UI component only knows about the context interface
function ChannelComposer() {
  return (
    <Composer.Frame>
      <Composer.Header />
      <Composer.Input />
      <Composer.Footer>
        <Composer.Submit />
      </Composer.Footer>
    </Composer.Frame>
  )
}

// Usage
function Channel({ channelId }: { channelId: string }) {
  return (
    <ChannelProvider channelId={channelId}>
      <ChannelComposer />
    </ChannelProvider>
  )
}
```

**Different providers, same UI:**

```tsx
// Local state for ephemeral forms
function ForwardMessageProvider({ children }) {
  const [state, setState] = useState(initialState)
  const forwardMessage = useForwardMessage()

  return (
    <Composer.Provider
      state={state}
      actions={{ update: setState, submit: forwardMessage }}
    >
      {children}
    </Composer.Provider>
  )
}

// Global synced state for channels
function ChannelProvider({ channelId, children }) {
  const { state, update, submit } = useGlobalChannel(channelId)

  return (
    <Composer.Provider state={state} actions={{ update, submit }}>
      {children}
    </Composer.Provider>
  )
}
```

The same `Composer.Input` component works with both providers because it only
depends on the context interface, not the implementation.

© tech-leads-club · MIT · tech-leads-club/agent-skills

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set130

The whole set →
bundle-barrel-imports The bundle-barrel-imports rule steers imports away from barrel files and toward source modules. It helps when a package exposes many re-exports and slows loading. CX Codex +1 ★ 7,191repo stars patterns-explicit-variants patterns-explicit-variants — a rule that pushes one component per mode instead of a single component buried under boolean props. The call site then says what renders. CX Codex +1 ★ 7,191repo stars async-suspense-boundaries async-suspense-boundaries guides Claude Code to place data fetching behind Suspense boundaries so headers, sidebars, and layout shells render without blocking. CX Codex +1 ★ 7,191repo stars architecture-compound-components The architecture-compound-components rule describes splitting complex UI components into pieces that share state through context. It fits components that have accumulated render props and conditional options. CX Codex +1 ★ 7,191repo stars rerender-functional-setstate The rerender-functional-setstate rule recommends functional state updates when the next React value depends on the current one. It helps callbacks avoid stale state and unnecessary dependencies. CX Codex +1 ★ 7,191repo stars state-lift-state state-lift-state — a Claude Code rule that moves React state into a provider component, so siblings outside the main UI read and update it without prop drilling or refs. CX Codex +1 ★ 7,191repo stars js-batch-dom-css js-batch-dom-css prevents layout thrashing by separating style updates from layout queries. Helps Claude write performant DOM and React code. CX Codex +1 ★ 7,191repo stars docs-writer The docs-writer skill creates, edits, and reviews project documentation. Use it for READMEs, Markdown files, and pages under docs/. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open