app-renderer-systems
Guides creation and modification of domain feature systems organized under a systems/ directory. Covers directory layout, API service layer patterns, TanStack Query hooks (queries, mutations, optimistic updates), React context and XState store conventions, hook organization, and public API barrel exports. Use when adding a new domain system, extending an existing one, or fixing bugs in a system-layer codebase. Don't use for generic React component work, backend API implementation, or codebases not organized around a systems/ domain pattern.
- License 许可
- MIT
- 最近更新
- 2026-07-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- app-renderer-systems
- metadata
- { "author": "Pedro Nauck", "github": "https://github.com/pedronauck", "repository": "https://github.com/pedronauck/skills" }
- description
- Guides creation and modification of domain feature systems organized under a systems/ directory. Covers directory layout, API service layer patterns, TanStack Query hooks (queries, mutations, optimistic updates), React context and XState store conventions, hook organization, and public API barrel exports. Use when adding a new domain system, extending an existing one, or fixing bugs in a system-layer codebase. Don't use for generic React component work, backend API implementation, or codebases not organized around a systems/ domain pattern.
- allowed-tools
- Read, Grep, Glob
02 资源文件 2
- 参考文档references/directory-layout.md4.6 KB
- 参考文档references/patterns.md15.7 KB
03 SKILL.md 正文
Feature Systems Guide
A "system" is a self-contained, domain-driven module that owns everything related to one domain: its API calls, query layer, hooks, components, and public API. Systems live under a systems/<domain>/ directory.
Read references/directory-layout.md for the full directory structure and naming conventions.
Read references/patterns.md for annotated implementation patterns per layer.
Quick Reference
Mandatory Companion Skills
Activate alongside this skill — systems span multiple technical domains:
| Situation | Activate |
|---|---|
| Any hook or component | react + tanstack-query-best-practices |
| Data fetching/caching | tanstack-query-best-practices |
| Mutations | tanstack-query-best-practices |
| XState store | xstate |
| Utility functions | es-toolkit |
| Writing/fixing tests | test-antipatterns + vitest |
| Bug fix | systematic-debugging + no-workarounds |
System Directory at a Glance
systems/<domain>/
├── index.ts # Public API barrel — required for every system
├── types.ts # TypeScript types for this domain
├── adapters/ # API service layer (HTTP calls, error types)
│ └── <domain>-api.ts
├── lib/ # Pure utilities, schemas, constants, query keys
│ ├── query-keys.ts # TanStack Query key factory
│ ├── query-options.ts # Reusable queryOptions / mutationOptions
│ ├── <domain>-schemas.ts
│ └── constants.ts
├── hooks/ # React hooks (queries, mutations, view-models)
│ ├── __tests__/
│ ├── use-<action>.ts # Query hooks
│ ├── use-create-<entity>.ts # Mutation hooks
│ ├── use-update-<entity>.ts
│ ├── use-delete-<entity>.ts
│ └── use-<domain>-view-model.ts
├── contexts/ # React contexts + providers
│ └── <domain>-context.tsx
├── stores/ # XState stores (complex async state machines)
│ └── <domain>-store.ts
├── components/ # React UI components
│ ├── stories/
│ └── index.ts
└── guards/ # Route guards / access checks
Step-by-Step: Creating a New System
Step 1 — Define types.ts
- Export clean domain types; never expose raw API response shapes.
- Derive from the project's API contract types when available.
- Document complex aggregated types with JSDoc explaining derivation rules and invariants.
Step 2 — Build the API service layer
- Create
adapters/<domain>-api.ts. - Use the project's HTTP client for API calls.
- Export a single namespace object:
export const <domain>Api = { list, create, update, delete }. - Export a typed error class:
export class <Domain>ApiError extends Error { ... }. - Accept
signal?: AbortSignalon every function to support query cancellation. - Keep all internal helpers (error extraction, response normalization) private to the module.
Step 3 — Add lib/query-keys.ts
export const <domain>Keys = {
all: ["<domain>"] as const,
lists: () => [...<domain>Keys.all, "list"] as const,
list: (scopeId: string | null) => [...<domain>Keys.lists(), scopeId] as const,
details: () => [...<domain>Keys.all, "detail"] as const,
detail: (id: string) => [...<domain>Keys.details(), id] as const,
};
- Use hierarchical key structure for granular invalidation.
- Scope keys with any identifier (userId, orgId, etc.) that isolates the cache correctly.
- Use
as conston every key tuple.
Step 4 — Add lib/query-options.ts
import { queryOptions } from "@tanstack/react-query";
import { <domain>Api } from "../adapters/<domain>-api";
import { <domain>Keys } from "./query-keys";
export function <domain>ListOptions(scopeId: string | null) {
return queryOptions({
queryKey: <domain>Keys.list(scopeId),
queryFn: ({ signal }) => <domain>Api.list(scopeId!, signal),
staleTime: 60_000,
enabled: Boolean(scopeId),
});
}
export function <domain>DetailOptions(id: string) {
return queryOptions({
queryKey: <domain>Keys.detail(id),
queryFn: ({ signal }) => <domain>Api.get(id, signal),
enabled: Boolean(id),
});
}
- Co-locate
queryKeyandqueryFnviaqueryOptionsfor type safety and reuse. - Export each option factory for use in hooks, prefetching, and route loaders.
- Always pass
signalfrom the query context through to the API layer.
Step 5 — Write hooks
- Query hooks: Wrap
useQuerywith thequeryOptionsfactories; accept a scope ID + optional{ enabled? }. - Mutation hooks: Use
useMutationwith properonMutate/onError/onSettledcallbacks for optimistic updates. - View-model hooks: Compose multiple hooks for a page/shell component; return a flat object.
- Place tests in
hooks/__tests__/or co-locate asuse-xxx.test.tsx.
Read references/patterns.md for complete mutation and optimistic update patterns.
Step 6 — (Optional) Add context
Create contexts/<domain>-context.tsx when query data or combined state must be shared across a component subtree without prop-drilling.
// Always nullable context — consumer hook throws if used outside provider
export const <Domain>Context = createContext<<Domain>ContextValue | null>(null);
- Export the context, provider component, and re-export consumer hooks from the same file.
- For performance-sensitive trees, split into Core / UI / Operations sub-contexts.
Step 7 — (Optional) Add an XState store
Create stores/<domain>-store.ts for complex async state machines (multi-step flows, polling, event emission).
export const <domain>Store = createStore({
context: { ... } as <Domain>Context,
emits: { ... },
on: {
someEvent: (context, event, enqueue) => {
enqueue.effect(async () => { ... });
return { ...context, isLoading: true };
},
},
});
Step 8 — Wire up index.ts
Organize the barrel with labeled sections and explicit named exports:
// Types
export type { <Domain>Type } from "./types";
// Hooks
export { use<Domain>List, use<Domain>Detail } from "./hooks";
export { useCreate<Domain>, useUpdate<Domain>, useDelete<Domain> } from "./hooks";
// Components
export { <Domain>Component } from "./components";
// Utilities
export { <domain>HelperFn } from "./lib/<domain>-utils";
// Query Keys & Options
export { <domain>Keys } from "./lib/query-keys";
export { <domain>ListOptions, <domain>DetailOptions } from "./lib/query-options";
// API
export { <domain>Api, <Domain>ApiError } from "./adapters/<domain>-api";
Critical Rules
- Use
queryOptionsfor co-location. Co-locatequeryKeyandqueryFnin reusable option factories. Never scatter the same query key across multiple files. - Unidirectional dependency flow.
adapters -> lib -> hooks -> components. Adapters never import from hooks or components. - Scope query keys. Any query depending on an authenticated scope (user, org, tenant) must include that scope ID in its key to prevent stale cross-scope data.
- Typed errors in the API layer. Never throw raw errors from adapters. Use a typed error class so consumers can distinguish error types without inspecting message strings.
- AbortSignal propagation. Pass
signalfrom thequeryFncontext through to every API call for proper query cancellation. - Always invalidate after mutations. Use
queryClient.invalidateQueriesinonSettledto ensure eventual consistency with the server. - Optimistic updates require rollback. When using cache-based optimistic updates, snapshot previous data in
onMutateand restore inonError. - Cancel outgoing queries before optimistic updates. Call
queryClient.cancelQueriesinonMutateto prevent refetches from overwriting optimistic state. - Zod schemas in lib/. Place all Zod schemas in
lib/<domain>-schemas.tsfor runtime validation at API boundaries.
Error Handling
- API layer throws typed error: TanStack Query catches and exposes it via
query.error. - Mutation fails with optimistic update:
onErrorcallback rolls back the cache to the snapshot fromonMutate, thenonSettledinvalidates to refetch fresh data. - Stale cross-scope data: Add the scope ID to the query key and verify that
enabledguards checkBoolean(scopeId). - Query cancellation on unmount: TanStack Query automatically cancels in-flight queries via the
signalwhen a component unmounts — ensuresignalis propagated to the API layer.
Detailed References
references/directory-layout.md— Full directory structure, file naming, and barrel conventionsreferences/patterns.md— Annotated code patterns for the API layer, query options, hooks, mutations, optimistic updates, contexts, and stores
04 同仓库更多 Skills
to-prompt-opus
Use when preparing or rewriting prompts for Claude Opus 4.8, Anthropic API agents, XML-structured prompts, long-context document work, coding agents, research synthesis, frontend/design tasks, or model-specific prompt optimization. Do not use for GPT/OpenAI prompts or raw context packaging without Opus-specific tuning.
to-prompt-gpt
Use when preparing or rewriting prompts for GPT-5.5, OpenAI API agents, Responses workflows, coding agents, research synthesis, support assistants, or model-specific prompt optimization. Do not use for Claude/Opus prompts or raw context packaging without GPT-specific tuning.
plan-refactor-qa
Plans and runs qa-report before executing Compozy refactor tasks. Use when the user provides a refactor or issue slug and wants Codex to inspect the matching .compozy/tasks directory, related PRD/TechSpec/ADR/task artifacts, affected code, and existing tests, then invoke $qa-report with a repository-grounded prompt. Do not use to run tests, execute qa-execution, implement code, or perform post-refactor verification.
multi-tool-branch-review
Orchestrates a multi-tool branch review of the current git branch against a base branch. By default it runs two independent thermo-nuclear maintainability audits, one on Codex GPT-5.5 xhigh and one on Claude Opus xhigh, then consolidates the findings into a single remediation plan via writing-plans. If the user explicitly asks for native reviews, it can add the Claude native review pass, the Codex native review pass, or both. Use when the user wants a deep cross-model review of a branch or PR before merge, or asks to review this branch with multiple tools or models. Encodes known infra failure modes and their fixes (missing Claude ACP adapter, Codex MCP auth hangs, false-positive report files, long jobs orphaned inside subagents). Do not use for reviewing a single uncommitted snippet, for non-git work, for running only one reviewer, or when the user only wants a quick lint or test run.
create-pr-with-template
Create a GitHub Pull Request with gh CLI and prefer repository PR templates automatically. Use this whenever the user asks to open/create a PR, especially when template compliance is needed. If multiple templates exist, ask the user which template to use.
ui-craft
Provides guardrails for user-facing UI work: usability heuristics, accessibility floors, design-system discipline, component states, microcopy, motion, dark mode, responsive behavior, and human-AI UX. Use when designing, generating, reviewing, or refactoring visible product surfaces such as components, pages, dashboards, forms, dialogs, loading/empty/error states, or AI interfaces. Do not use for backend-only work, infrastructure, CLI/TUI design, or pure documentation editing.