As a frontend developer, I use Claude in my day-to-day work. At some point, that meant a CLAUDE.md appeared at the project root, an AGENTS.md created by someone else sat beside it, a .cursorrules file lingered elsewhere, and I even created a .claude/skills/ directory after following an article I had come across. (By the time I stopped to take stock, I had about five files containing roughly the same information.)

The same kind of confusion surfaced in other areas. I added an MCP called serena, installed something called codegraph after seeing it on GitHub Trending, and every time I discovered another new tool, I found myself asking the same question: “Where exactly does this tool fit, and how does it work?” (I was especially hazy, each time, on details such as who built a given tool and exactly how it saved tokens.)

So rather than recommending tools one by one, I decided to map the tooling landscape itself. I divided it into four broad axes.

• The differences among context files (.md)
• How MCP works, and Serena
• The layers of code intelligence tools, and CodeGraph
• Paying attention to GitHub Trending

Once you understand these four areas, I believe you can look at a new tool and quickly get a sense of what kind of thing it is.

Context Files

AI coding agents have a fundamental limitation: they have no persistent memory. Every session starts from a blank slate. In the next conversation, they cannot remember a convention you agreed on yesterday or a directory structure you explained an hour ago. Context files are the simplest mechanism for addressing this problem. If a project contains a file that is read automatically whenever a session starts, you no longer need to repeat the same explanation every time.

The problem is that each tool created its own file around the same basic idea. Claude Code reads CLAUDE.md, Cursor reads .cursorrules (now deprecated, with .cursor/rules recommended instead), GitHub Copilot reads .github/copilot-instructions.md, and OpenAI Codex reads AGENTS.md. When a team uses several tools, it can end up copying the same information into four different places.

CLAUDE.md

CLAUDE.md is a file that Claude Code reads automatically at the start of a session. According to Anthropic’s official documentation (code.claude.com/docs/en/memory), Claude Code looks for CLAUDE.md at the following three levels.

• User memory (~/.claude/CLAUDE.md): global defaults that apply to every project on the machine
• Project memory (CLAUDE.md at the project root): committed to git and shared across the team
• Local memory (CLAUDE.md in a subdirectory): loaded in addition to the others only when working in that directory

When all three levels exist, Claude reads and concatenates all of them. It does not choose only one according to precedence; instead, more specific instructions are layered on top, much like the CSS cascade. (This is a merge, not an override.) As a result, scattering rules about the same topic across several levels can create conflicts. (Anthropic’s official documentation explicitly states that behavior is not guaranteed when instructions conflict.)

There is one frequently overlooked detail here: Claude reads every CLAUDE.md it encounters while walking from the current working directory up to the repository root. If you work inside packages/ui/ in a monorepo, both the root CLAUDE.md and packages/ui/CLAUDE.md are loaded. (That is powerful, but it also means the context can quietly expand without you noticing.)

AGENTS.md

AGENTS.md is a standard created to address the proliferation of tool-specific files described above. In December 2025, Anthropic, Block, and OpenAI donated it to the Linux Foundation’s Agentic AI Foundation (AAIF) alongside MCP, making it a de facto industry standard. The official site (agents.md) states that more than 60,000 open-source repositories have adopted the file.

The list of supported tools makes the picture even clearer. It includes OpenAI Codex, Google Jules, VS Code, GitHub Copilot, Cursor, JetBrains Junie, Aider, Devin, Zed, Factory, Warp, goose, opencode, Amp, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, Ona, Windsurf, and Augment Code, among many others. GitHub Copilot began supporting AGENTS.md natively in August 2025. One interesting detail is that native AGENTS.md support in Claude Code is still an active feature request. Claude Code continues to treat CLAUDE.md as its primary file.

You might still wonder whether this supposed standard is actually being adopted. The strongest evidence is dogfooding—the organizations behind the standard using it themselves.

• The canary branch of Vercel/Next.js has an AGENTS.md at its root. It is actually a symbolic link to CLAUDE.md, whose contents cover the monorepo structure, one-to-two-second iteration with pnpm --filter=next dev, testing guidance for both Turbopack and Webpack, the pr-status script, and rules for handling environment variables and secrets. The fact that create-next-app now generates both AGENTS.md and CLAUDE.md for new projects reflects the same trend.
• The OpenAI/codex repository maintains its own AGENTS.md.

A conventional strategy is beginning to emerge: use AGENTS.md as the single source of truth, while keeping CLAUDE.md minimal, with a one-line reference to AGENTS.md plus instructions specific to Claude Code. This eliminates duplication, and because Claude Code reads both files, nothing is lost.

SKILL.md

SKILL.md belongs to a different category from the two files above. Whereas CLAUDE.md and AGENTS.md are persistent instructions that are always present in the context, a Skill is an on-demand capability invoked only when needed.

A Skill is organized as a directory. The directory contains one SKILL.md, scripts executed by the Skill, and any additional Markdown documents. Claude loads that directory only when the current task matches the Skill’s description. This is called progressive disclosure, a concept established in the UX field by Jakob Nielsen in 1995: advanced or rarely used functions are deferred to secondary screens so users can focus on one task at a time, reducing cognitive load and errors. In the context of Claude Skills, it refers to the mechanism of bringing a Skill’s body into the context only when needed. The result can be a dramatic reduction in context-window costs.

The frontmatter in SKILL.md includes several distinctive fields.

• description: explains when the Skill is needed and acts as the trigger the model uses to decide whether to invoke it
• allowed-tools: restricts which tools may be used inside the Skill (for example, "Read, Glob, Grep, Bash(python:*)")
• disable-model-invocation: true: prevents the model from invoking the Skill; only the user can trigger it with a slash command. This is used for operations with side effects, such as deployments and commits
• user-invocable: false: hides the Skill from the user’s slash-command menu and allows only Claude to invoke it autonomously, for use as background knowledge

Claude Skills launched simultaneously across Claude.ai, Claude Code, the API, and Agent SDK on October 16, 2025. Then, on December 18, 2025, Anthropic published the Skills specification itself as an open standard (agentskills.io). Simon Willison even called it “Skills are awesome, maybe a bigger deal than MCP,” citing the format’s dramatic simplicity compared with MCP and its use of progressive disclosure to address context-window costs.

Files Used by Other Tools

Cursor’s .cursorrules has been deprecated since version 0.43. The current official recommendation is to use the .cursor/rules/ directory and place multiple .mdc files inside it. Each .mdc file has YAML frontmatter.

• description: information the agent uses to judge whether the rule is relevant
• globs: automatically attaches the rule when a matching file is included in the conversation (auto-attach)
• alwaysApply: when true, includes the rule in every conversation without exception (globs is ignored in this case)

GitHub Copilot has evolved in a similar direction. Repository-wide instructions live in .github/copilot-instructions.md; instructions that require path-specific scope go in .github/instructions/*.instructions.md, with globs specified through the frontmatter key applyTo:. (Copilot code review has officially supported path-scoped instructions since September 2025.)

Tools beyond Cursor and Copilot are converging on similar patterns. The following table summarizes them.

Aider’s CONVENTIONS.md is particularly interesting. Because the official documentation says this entire file is included in the context with every request, it explicitly instructs users to “keep it under 200 lines.” (In effect, Aider recognized this limitation early and tells users about it directly.)

MEMORY.md

Separate from the files above, another pattern is appearing with increasing frequency: MEMORY.md. It is not an official standard, but an organically developed community convention for recording decisions and mistakes over time.

## 2026-04-10
Pages Router에서 App Router로 이전. 신규 라우트는 App Router 컨벤션 사용.
 
## 2026-04-22
Prisma 쿼리 결과에 optional chaining 쓰지 말 것 — null은 if-check로 명시적 처리.
(이전에 옵셔널 체이닝으로 null을 흘려보내 프로덕션 이슈 발생.)

If CLAUDE.md or AGENTS.md records the rules as they stand today, MEMORY.md records the history of why those rules were created. (The two are complementary, not interchangeable.)

How Agents Read These Files

So far, we have cataloged the files that exist. But one surprisingly common question remains unanswered: where, exactly, do agents load these files, and how? Understanding this mechanism makes it easier to see why the ETH Zurich results discussed later—showing that context-file instructions are not followed reliably—emerged.

First, one essential fact: CLAUDE.md is injected as a user message, not as part of the system prompt. Anthropic’s official documentation states the following.

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance.

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance.

In other words, it is contextual guidance rather than an enforced rule. The official guidance recommends using a separate mechanism, such as a PreToolUse hook, when you need to enforce a specific behavior.

The load order progresses from broad → specific. More precisely, it is managed policy (organization-level settings) → the user’s global file (~/.claude/CLAUDE.md) → the project file (./CLAUDE.md) → the local file (./CLAUDE.local.md). Within the same directory, CLAUDE.md comes before CLAUDE.local.md. By taking advantage of the fact that the nearest instructions are read last, you can make more specific rules exert a stronger influence, thanks to the LLM’s recency bias.

The @import syntax is especially interesting. If you put @path/to/file anywhere in the body of CLAUDE.md, that file is expanded in place and loaded with it. The maximum recursion depth is 4 hops, and relative paths are resolved from the file containing the import statement. That is why the official recommendation is to bridge to @AGENTS.md. If you leave CLAUDE.md almost empty and put only @AGENTS.md in it, Claude Code will naturally read AGENTS.md as well. (Given that Claude Code does not yet support AGENTS.md natively, this is the cleanest workaround.)

The token implications also deserve attention. CLAUDE.md has no explicit token limit, so the entire file is loaded if it exists. The official recommendation, however, is to keep each file under 200 lines. Beyond 200 lines, it is said to “consume more context and may reduce adherence.” Interestingly, in Claude 4.x, merely enabling tool use automatically adds 346 tokens via a special system prompt (with tool_choice: auto). Context leaks away in ways that are easy to miss.

Cursor takes a different approach. Rules in .cursor/rules/*.mdc operate in four modes.

• Always Apply: included in every chat without exception; ignores globs/description
• Apply Intelligently (Agent Requested): the agent reads description, determines relevance, and pulls in the rule
• Apply to Specific Files (Auto Attached): activated when a file matching the glob pattern enters the context
• Apply Manually: explicitly invoked by the user with @rule-name

Other tools differ again. OpenAI Codex walks from the git repository root toward cwd, collects every AGENTS.md, and injects them immediately before the user prompt. GitHub Copilot inserts .github/copilot-instructions.md at a middle priority within the context window: “after edit context and explicit references, but before loosely related open files.” Because the load timing, precedence, and merge rules vary by tool even for the same AGENTS.md file, there is no guarantee that three tools will interpret it in exactly the same way.

That leaves a more fundamental question: why does a model follow only some instructions that are present in its context? Simply saying “because the instructions are long” is not enough. The phenomenon is rooted in structural limitations of LLMs.

Hallucination and Context Forgetting

If you have ever seen an AI agent confuse the conversational context or forget something that was clearly stated earlier, that is a form of hallucination. People usually think of hallucination first as “making up facts that do not exist,” but the academic literature divides it into three categories. A 2023 survey by Yue Zhang and colleagues (“Siren’s Song in the AI Ocean”) classifies them as input-conflicting (generating something inconsistent with what the user explicitly provided), context-conflicting (contradicting something the model previously generated), and fact-conflicting (disagreeing with world knowledge). Ignoring instructions in a context file belongs to the first category, not the third. The model processes the input while treating part of its information as though it were not there.

The deeper problem is that hallucination cannot be eliminated in principle. A research team at the National University of Singapore proved this mathematically using learning theory. No LLM can learn every computable function; therefore, as long as it is used as a general-purpose problem solver, it must hallucinate at some point.

Position effects matter as well. Stanford researchers demonstrated experimentally that models reference relevant information most effectively when it appears at the beginning or end of the context window, while performance drops sharply when that information is buried in the middle. This maps directly onto context files. CLAUDE.md is inserted somewhere in the middle by the load order, and as a conversation grows longer, its instructions are pushed further into the “middle” of the context. This also connects to the other side of the recency bias mentioned earlier: within the primacy-recency effect, the middle is the weakest region.

Taken together, these phenomena form a coherent picture. A context file is merely additional text inserted outside the system prompt before the LLM’s first user turn. It is not a mechanism that forces the model’s decisions; it is simply another block of tokens dropped into the context window. The longer the file and the longer the conversation, the farther its instructions drift toward the “middle,” and the less reliably they are referenced. The ETH Zurich results quantitatively confirm this structural limitation.

The ETH Zurich Study

Many people may have thought, “Then I should put as much as possible into these files.” A recent study directly challenges that intuition: the ETH Zurich research referenced throughout the preceding section.

The paper, “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”, was published by an ETH Zurich research team in February 2026. The researchers evaluated four agents—Claude Code (Sonnet-4.5), Codex (GPT-5.2 / GPT-5.1 mini), and Qwen Code—on a benchmark of 138 real-world Python software-engineering tasks (AGENTBENCH) and on SWE-bench Lite. The results were unexpected.

• LLM-generated context files actually reduced task success rates by about 0.5% on SWE-bench Lite and 2% on AGENTBENCH
• Even human-authored files produced only a modest average improvement of about 4%
• Adding a context file increased inference costs by more than 20% per instance
• Context files had an even smaller effect on the stronger model (GPT-5.2), because more capable models already have sufficient parametric knowledge and additional context can become noise

There was one exception: specifying a nonstandard tool. When the Python package manager uv was named in the context, for example, the agent’s use of uv rose from 0.01 times per instance to 1.6 times—an increase of roughly 160×.

Aider’s “200-line recommendation”—keep the file short because it enters the context every time—is practical guidance, while the ETH Zurich study quantitatively demonstrates that long context files reduce performance statistically. I see the following practical implications in the research.

• A huge, automatically generated context file can do more harm than good. If you cram coding standards, architecture, and workflows into a 300-line CLAUDE.md, the agent will follow some of them and ignore the rest. That inconsistency can produce worse results than having no context at all.
• What absolutely belongs in the file is information that cannot be inferred. This includes nonstandard tools, project-specific conventions, and past failure cases. The model already knows general coding best practices.
• Use AGENTS.md as the single source, keep CLAUDE.md limited to brief tool-specific instructions, and move detailed workflows into Skills.

MCP (Model Context Protocol)

If .md files solve the question of “what should we tell the agent?”, MCP (Model Context Protocol) solves the question of “what should we enable the agent to do?”

Put more concretely, an AI agent needs to be able to call the Slack API to send a message to Slack. It needs to call the GitHub API to create a GitHub issue. It needs to handle a database connection to query Postgres. MCP unifies integrations with all these external systems under a single standard protocol. (The point is that any client can connect to any server through the same interface.)

MCP is an open standard first released by Anthropic on November 25, 2024. Then, on December 9, 2025, Anthropic, Block, and OpenAI jointly donated the MCP specification to the Linux Foundation’s Agentic AI Foundation (AAIF) as founding members. Google, Microsoft, AWS, Cloudflare, and Bloomberg joined as platinum members. (By the time of the December 2025 donation, the SDK had already surpassed 97 million monthly downloads, with more than 10,000 active public MCP servers.)

MCP is a stateful session protocol built on JSON-RPC. JSON-RPC is a stateless, lightweight RPC (Remote Procedure Call) protocol that uses JSON as its wire format. It is transport-independent and can run over HTTP, TCP, or standard input/output. It also supports notifications (calls without responses) and batch calls.

Inside the Protocol

Every interaction between an MCP client and server is expressed through one of six primitives. The protocol began with three server-side primitives; three client-side primitives were added in the 2025-06-18 specification, bringing the standard total to six.

Server-side primitives

• Tool (model-controlled): an action the model autonomously decides whether to invoke. Such actions may have side effects
• Resource (application-controlled): read-only data identified by a URI. The host application decides which resources to expose
• Prompt (user-controlled): a reusable template explicitly triggered by the user, for example through a slash command

Client-side primitives

• Sampling: a mechanism that allows the server to request a completion from the client’s LLM, making the client-server architecture bidirectional
• Roots: workspace boundary information through which the client tells the server, “This is the extent of the area you may work in”
• Elicitation: a feature that allows the server to request additional user input in a structured form while executing a tool

The distinction among these six primitives matters because authority over invocation and provision belongs to different actors. A Tool runs at the model’s discretion, so an incorrect invocation carries risk. A Resource is curated by the application and is therefore relatively safe. A Prompt is explicitly triggered by the user and offers the greatest control. Sampling, Roots, and Elicitation refine the permission model through client-side control.

There are exactly two transport mechanisms. This is intentional: it prevents the ecosystem from fragmenting into dozens of competing protocols. The first is stdio, which runs an MCP server as a local subprocess and communicates through standard input and output. It is well suited to locally operating tools such as filesystem and git integrations. The second is Streamable HTTP, which layers SSE streaming over HTTP POST to create near-bidirectional communication. It is suited to scenarios that occur across a network boundary, such as remote servers, OAuth authentication, multi-client connections, and cloud deployments.

Here, SSE (Server-Sent Events) is a W3C standard that lets a server push one-way data to a client over an HTTP connection. Its media type is text/event-stream, and JavaScript accesses it through the EventSource API. Unlike WebSocket, it is unidirectional, but because it operates over HTTP, it works well with proxies and firewalls. Streamable HTTP effectively uses SSE to approximate bidirectional communication. It was introduced in the March 26, 2025 specification (version 2025-03-26), replacing the previous HTTP+SSE transport.

How an LLM Invokes an MCP Tool

Now that we have covered the primitives and transports, let us trace how an LLM actually discovers and invokes an MCP tool. (Where .md files raised the question of “where are they injected?”, the question here is “how does MCP enter the LLM’s field of view?”)

When an MCP session begins, the following handshake takes place.

• Client → server: initialize request (sends the supported protocol version and client capabilities)
• Server → client: initialize response (server capabilities plus an optional instructions field)
• Client → server: notifications/initialized notification
• Client → server: tools/list request → receives the list of available tools
• (Later) The LLM decides to invoke a tool → the client sends tools/call → receives the result

One detail is frequently overlooked: the initialize response’s instructions field. If the server sends text in this field, that content is effectively added to the LLM’s system prompt. In other words, the specification provides a formal slot through which an MCP server can inject guidance directly into the LLM about how its tools should be used. (The existence of this slot is one reason the Tool Poisoning Attack discussed earlier is dangerous.)

How, then, does the tool definition itself enter the LLM’s field of view? An MCP tool definition takes the following JSON Schema form.

{
  "name": "get_weather",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  }
}

The client transforms the list returned by tools/list into the tools parameter of the Anthropic Messages API or the tools parameter of OpenAI function calling, then includes it in the LLM API request. With Anthropic, supplying the tool parameter automatically adds a special system prompt that teaches the model how to invoke tools. (That is the source of the additional 346 tokens mentioned earlier.)

When the LLM decides that it should invoke a tool, its response contains a tool_use block ({"type": "tool_use", "name": ..., "input": ...}), and the response ends with a stop_reason of tool_use. The client receives this, sends tools/call to the actual MCP server, receives the result, places it in a tool_result block in the next user message, and sends it back to the LLM. This loop continues until stop_reason changes from tool_use to another value, such as end_turn or max_tokens. What we commonly describe as “the agent working” is essentially a sequence of these call-result-call loops.

So how does MCP differ from ordinary function calling? The distinction can be condensed into four points.

• Dynamic discovery: the tool list is retrieved at runtime through tools/list rather than known at build time. notifications/tools/list_changed also allows it to change during a session
• Stateful session: lifecycle phases are defined (initialize → operation → shutdown), enabling a clean shutdown
• Primitives beyond Tool: Prompt, Resource, Sampling, Roots, and Elicitation are exposed through capability negotiation
• Bidirectionality: the specification allows a server to invoke the client’s LLM in reverse through sampling

(This is why MCP is sometimes described as “a generalized standard for function calling for agents.”)

Serena

Serena (oraios/serena) is one of the most frequently discussed MCP servers in the context of coding agents. As of May 2026, it has about 24.7k stars and has risen in roughly a year from a niche tool to a de facto standard code MCP.

Serena’s core idea can be summarized in one sentence: show the agent symbols, not text.

To unpack that idea, suppose you need to find every use of a calculateTotal function. A conventional text-based tool such as grep or Read works like this.

It greps the entire codebase for calculateTotal. It then gathers the line number of every match and reads a fixed range of lines from each file to build context. It also captures accidental matches in variable names, string literals, and comments.

LSP-based Serena makes a single call to find_referencing_symbols("calculateTotal") and returns only exact symbol references, without noise from variable-name or comment matches.

LSP (Language Server Protocol) is an open, JSON-RPC-based protocol that standardizes communication between code editors/IDEs and “language intelligence tools” such as code completion, go to definition, find references, and refactoring. Microsoft, Red Hat, and Codenvy jointly standardized it in 2016. Its central idea is simple: instead of reimplementing a language analyzer for every editor, run one server per language and let every editor query that server. (The TypeScript server, Rust analyzer, and Python’s pyright are all LSP servers.)

Serena’s core tools include find_symbol, find_referencing_symbols, and get_symbols_overview. You can choose between two backends: the default is an LSP-compatible language server, which is free and open source; the other is a paid plugin that uses code analysis from a JetBrains IDE and offers a free trial.

The real reason Serena was adopted so quickly is token savings. A text grep-and-file-read loop consumes many tokens, while one precise LSP call consumes very few. The larger the codebase, the greater the difference.

So, Is MCP Safe?

One point needs to be made clearly: MCP does not automate authorization. The user remains responsible for deciding which servers an agent can trust, what side effects each tool may have, and whether a tool will continue to behave the same way over time.

It is useful to understand two representative attacks.

• Tool Poisoning Attack (TPA): an attack named and demonstrated in a PoC by Invariant Labs in April 2025. If malicious instructions are hidden inside an MCP server’s tool description, the model may mistake them for user instructions and follow them. The text is invisible to the user but visible to the model.

• Rug Pull (Silent Redefinition): a concept Simon Willison discussed in an analysis published on April 9, 2025. A tool begins as legitimate. The user reviews it, approves it, and integrates it into a workflow. Weeks later, the tool definition quietly changes to include malicious instructions. Because the user is not asked to approve it again, the behavior changes without warning.

A security incident occurred on April 15, 2026. OX Security disclosed systemic RCE vulnerabilities affecting every major MCP SDK—Python, TypeScript, Java, and Rust. More than 150 million downloads, roughly 7,000 public servers, and an estimated 200,000 vulnerable deployments were potentially affected. More than 14 CVEs were assigned, and Cursor, VS Code, Windsurf, Claude Code, and Gemini-CLI were all affected.

How has the ecosystem responded? Anthropic did not change the protocol architecture itself. Instead, it updated SECURITY.md to state explicitly that downstream developers are responsible for input sanitization when using stdio adapters. At the specification level, the 2025-06-18 revision mandated OAuth 2.1 plus RFC 8707 Resource Indicators to block token-reuse attacks, and the 2025-11-25 revision introduced incremental scope consent, through which users approve only the minimum permissions needed, one step at a time. Even so, more than 30 MCP-related CVEs were issued in January and February 2026 alone, and statistics showed that command injection accounted for 43% of them. Security remains very much a work in progress.

Code Intelligence Tools

If .md files answer “what should we tell the agent?” and MCP answers “what should we enable it to do?”, code intelligence tools answer the question of “how can we find relevant code quickly?”

In a large codebase, most of an AI agent’s cost comes not from changing code but from finding where the relevant code lives. If every task begins with a repeated grep → read → filter → grep cycle, tokens, time, and tool calls are wasted. Code intelligence tools represent a variety of attempts to reduce this search cost.

The landscape becomes clearer when divided into four tiers.

Context Packing

The simplest solution begins with the idea: “Put everything into one context window.” It builds no graph and performs no indexing. It simply serializes the entire repository into a block of text and hands the whole thing to the model.

The representative tool is Repomix. It packages an entire repository into a structure optimized for Claude’s XML parsing. With a CLI, web interface, extension, and MCP server, it has the most complete ecosystem in the category.

GitIngest is known for its zero-friction usability. Change the single word github.com to gitingest.com in a GitHub URL, and the entire repository is transformed into one text page. (For example, github.com/facebook/react → gitingest.com/facebook/react.) Changing one word in the browser’s address bar is all it takes, with no installation required. It is optimized for quick, one-off exploration.

code2prompt, created by Mufeed VH, is a Rust-based CLI whose strength lies in customization through a template system.

An interesting variant is rtk (rtk-ai/rtk, about 55k stars). Whereas the tools above “pack the entire repository at once,” rtk compresses the output of CLI commands in real time. It is a single binary written in Rust that automatically registers itself with the shell hooks of 13 tools, including Claude Code, Cursor, Copilot, Gemini CLI, and Codex. When an agent invokes git status, the hook rewrites it internally as rtk git status. (The fact that users do not need to change their workflows is its key differentiator.) It applies smart filtering, grouping, truncation, and deduplication heuristics to more than 100 commands, reducing output tokens by 60–90%. One sentence from the official site neatly summarizes this category: “70% of your bill is noise the LLM doesn't need.” While the earlier tools reduce the volume of context going in, rtk reduces the volume of context returned by tool calls.

The limitation of this tier is clear, however: large repositories hit token limits. And because code is delivered only as a “block of text,” there is no structural understanding of relationships among symbols.

tree-sitter Repository Maps

The next tier uses tree-sitter to analyze code structure without running a separate index server.

An AST (Abstract Syntax Tree) is a data structure that represents source-code structure as a tree. It is the output of a compiler’s parsing stage: superficial details such as whitespace, semicolons, and parentheses are removed, while meaningful elements such as variables, operators, function calls, and control flow remain as nodes. Every precise form of analysis in code intelligence ultimately operates on an AST.

tree-sitter is an open-source parser generator and incremental parsing library. It has been adopted by GitHub’s code navigation, Neovim, Zed, and Helix. Its key differentiator is that it reparses only the edited region. When you change a single line in an editor, it patches only the changed tree instead of parsing the entire file again. This makes it responsive and well suited to rapid code exploration by AI agents.

Aider, discussed earlier, is a representative example of this approach. It uses tree-sitter to extract symbol definitions such as functions, classes, and methods from source files; constructs a graph with files as nodes and inter-file dependencies as edges; applies a PageRank-family ranking algorithm—which measures a page’s importance by the number and quality of links pointing to it—and extracts only the most important definitions and signatures within a token budget. (By default, --map-tokens=1024 creates a 1k-token repository map.)

AFT (cortexkit/aft) develops this approach with greater precision. In the words of AFT’s official README: “Reading a 500-line file costs about 375 tokens. But when an agent needs only one function most of the time, passing the symbol name to aft_zoom returns only that function and a little context. This costs about 40 tokens.” Line-number-based editing breaks as soon as code above the target moves, whereas AFT’s symbol-mode editing is stable because it addresses functions by name.

Another tool worth noting in the same tier is ast-grep (ast-grep/ast-grep, about 13.9k stars). It is a tree-sitter-based structural search and rewriting CLI. Its decisive difference from ordinary grep is that it matches CST (Concrete Syntax Tree) patterns rather than text. A search for the pattern console.log($A), for example, finds every call with the same semantic structure, regardless of how the text is formatted. A separate ast-grep-mcp server also lets AI agents use structural search instead of text grep.

Knowledge Graph

The third tier goes a step further. It parses the entire codebase in advance, builds a knowledge graph, stores it on disk, and lets the agent query that stored graph. The most talked-about example is a tool called CodeGraph.

Its architecture is surprisingly simple. Code is parsed with tree-sitter; the extracted symbols, edges, and file information are stored in SQLite FTS5 full-text search; and the resulting knowledge graph is exposed to AI agents through MCP. One important detail is that all extraction is performed deterministically through AST parsing, not through LLM summarization. In other words, there is no room for hallucination to enter the process.

FTS5 (SQLite Full-Text Search 5), mentioned above, is a full-text search extension provided as a SQLite virtual table. It has been included in the SQLite amalgamation since SQLite 3.9.0 (2015-10-14). You create a table with CREATE VIRTUAL TABLE ... USING fts5(...) and query it with the MATCH operator. Its decisive advantage is that you can operate a full-text index in a single SQLite file without running a separate search engine such as Elasticsearch. This is one reason CodeGraph can advertise “100% local operation.”

The deterministic parsing just mentioned refers to parsing algorithms that allow only one choice at each stage, without backtracking. LL(1) and LR parsers are representative examples and run in linear time. In the context of CodeGraph, it means that “the symbol relationships extracted from the AST are mathematically precise rather than based on an LLM’s interpretation.” An LLM-generated code summary can hallucinate, while direct AST parsing yields mathematically precise symbol relationships; this principle is central to the approach.

The benchmarks are impressive as well. In a comparison of headless Claude Opus 4.7 runs with and without the CodeGraph MCP enabled, the averages reported in the official README show costs falling by 35%, token usage by 57%, runtime by 46%, and tool calls by 71%. The gains increase with codebase size: on a large repository such as Tokio, the measurements showed an 82% reduction in cost, an 86% reduction in tokens, a 71% improvement in speed, and a 92% reduction in tool calls. (Without CodeGraph, an agent fans out widely across grep/find/Read; with CodeGraph, a single index query replaces all of that.)

The approach also has deep academic roots. GraphCoder (ASE 2024) created a Code Context Graph combining control flow with data/control dependence. CodexGraph (NAACL 2025) enabled an LLM agent to write and execute graph-database queries directly. Prometheus combined a tree-sitter-based knowledge graph with unified memory and applied it to multilingual issue resolution. Academia and industry are clearly converging on this pattern.

One interesting variant deserves mention here. Cursor’s indexing takes a different path: semantic search based on vector embeddings rather than an AST graph. Locally, it splits files into chunks at function and class boundaries, synchronizes them with the server through Merkle tree hashes, and stores only the embeddings in a vector database called Turbopuffer. (Its central privacy claim is that the original source code is not stored in the cloud.) At query time, it embeds the question, runs a nearest-neighbor search, then locally reads the file paths and line ranges returned by the search and sends that content to the LLM. Because it seeks “semantically related code” rather than “exact symbols,” it has lower precision but performs well with natural-language queries. CodeGraph and Cursor indexing solve the same problem—search cost—from different assumptions.

LSP

The final tier depends directly on a language server. tree-sitter knows “that a symbol exists”; LSP knows “what that symbol is.”

Consider a concrete example. A TypeScript LSP knows that UserService implements the IUserService interface, which generic type parameters it accepts, which overloads it has, and what its return type is. tree-sitter cannot go that far.

Serena, discussed in the MCP section, belongs precisely to this tier. Because Aider does not use LSP and performs its own file analysis, its recognition is limited to the function and class level. By contrast, an LSP integration such as the one in OpenCode provides deeper type awareness, though it is limited by its dependence on a good LSP server for each language.

GitHub Trending

Finally, GitHub Trending is where I first discovered many of the tools discussed above. It offers an at-a-glance view of who is building what and which projects are suddenly gaining traction.

At github.com/trending, you can browse three time ranges: today, this week, and this month. You can also filter by language and category. (I usually look at weekly results for TypeScript and Python, occasionally expanding to all languages.)

One interesting pattern I noticed while tracking Trending over the past few weeks is that this quarter’s leading repositories form clear clusters. Understanding those clusters makes it easier to place individual tools in context.

So, What Does This Mean?

The thought that occurred to me most often while writing this article was that the number of tools is growing extraordinarily fast. Even as I wrote, new MCP servers appeared on GitHub Trending, the status of AGENTS.md support changed, and new security CVEs were issued. Half-finished paragraphs quickly becoming outdated is a familiar fate of technical writing, but the pace of the AI agent ecosystem is unusually steep.

That is why my goal here was not to recommend a particular tool, but to develop an eye for the relationships among tools. Once you understand why CLAUDE.md is injected as a user message, exactly how MCP differs from function calling, and why tree-sitter and LSP occupy different tiers, a new tool becomes much easier to read: “This belongs to that tier, and it solves this problem in this way.”

What remains, ultimately, is one intuition from the ETH Zurich study: the model already knows a great deal. Stuffing a context file with everything you can think of does not make the agent follow it more faithfully. It is better to keep only what the model is unlikely to know—project-specific conventions, nonstandard tools, and past mistakes—and remove the rest. Installing more tools and using tools well are different problems.

Rather than immediately adding ten MCP servers or expanding CLAUDE.md to hundreds of lines, I encourage readers to spend some time investigating how the tools they already use actually work. I believe that understanding provides a stable foundation, no matter which direction the ecosystem takes next.

References

AI tools such as Claude, ChatGPT, Cursor, Gemini, and Copilot have become deeply embedded in our daily work. Development has accelerated exponentially, but if I am honest, the quality of the services we build does not seem to have kept pace. We are increasingly confronted with as many new bugs as new features, and I often hear people say, "I have no idea why this ended up this way."

As development speeds up, we spend less time examining every line of code in detail. That makes it even more important, in my view, to have the fundamental skills needed to guide AI in the right direction. To preserve the quality of the result, we need to recognize problems in AI-generated code and steer it back toward the outcome we want. Those fundamentals may include domain-driven development, abstraction, TDD (Test-Driven Development), effective use of libraries, and building performance advantages.

Yet whenever I ask frontend colleagues—and colleagues in other IT roles—"What is the hardest part of frontend development?" the answer I hear most often is remarkably consistent: "Managing state flow."

This article explores why managing state flow is so difficult and what kind of judgment and intuition we need to cultivate to handle it well.

What Is State?

Before getting into the main discussion, let us begin with the most fundamental question: what exactly do we mean by "state"?

While studying frontend development, I often read articles by hoseung.me. There, state is described as "any data that can affect the UI." A like count, the contents of a shopping cart, whether a modal is open, an input value, information about the signed-in user, the currently selected tab, search results, and whether something is loading—all of these are state.

The official React documentation defines it more formally. The page is titled "State: A Component's Memory", which can be understood as "the mechanism by which a component retains data between renders and tells React to trigger a re-render when that data is updated." In other words, it is data that persists over time, changes in response to events, and causes the UI to be redrawn when it changes. One more important point: state is isolated to each component instance. Even if the same component appears ten times on a page, each instance has its own independent state. This fact connects directly to the later discussion of where state should live.

Both definitions point to the same idea: state is "a value that changes over time and affects rendering." A constant that never changes is not state. Primitive design tokens fixed at build time are not state, but a dark mode setting that the user can toggle is. (Strictly speaking, the values themselves resolve according to the dark or light theme state. The "theme selection" is the state, while the tokens are more accurately understood as a mirror reflecting that state.)

There is one important caveat: not all state lives in components. Some state lives in cookies; some in localStorage, sessionStorage, or IndexedDB; and some in the URL. When server-resident data is brought to the client and cached, that cache also becomes a form of state. Even browser-managed values such as scroll position and the history stack sometimes need to be treated as state because they determine how our application behaves.

Why Is It So Difficult?

At first, handling state sounds simple enough. Create the state you need, pass it where it is needed, and correctly handle updates and resets. What could be so difficult about that?

Keep that question in mind and open a page from the service you are currently working on.

How many components does that page contain? Even a simple page may consist of dozens of components, while a complex one may contain hundreds arranged in a tree. Each component may hold its own state, share state with a sibling, or receive state from a parent. State can also carry across pages. Some state must survive a refresh, while other state should disappear when the tab closes.

This is the real reason state is difficult to manage: we cannot see at a glance where countless pieces of state are declared, how they are updated, or when they cease to exist. As the number of components with similar roles grows, both naming state and tracing the code that changes it become increasingly difficult.

An invisible web begins to form. A click in component A invalidates B's data; invalidating B closes C's UI; and closing C discards the form input. If that chain is not explicit anywhere in the code, we have to reconstruct the web in our heads whenever we debug a bug.

How, then, should we untangle this web? I believe the first step is recognizing that "state comes in different kinds."

Not All State Is the Same

Kent C. Dodds divides state into Server Cache (information that exists on the server and is held by the client for fast access) and UI State (information that exists only in the UI to control interface behavior). We often make mistakes when we lump the two together.

The official TanStack Query documentation defines TanStack Query as a server-state library that manages asynchronous work between the server and the client, while tools such as Redux, MobX, and Zustand are client-state libraries. (They can store asynchronous data, but doing so is inefficient.)

The central point is clear: Server State and Client State are different problems. Server State is asynchronous, can be changed by other users, and becomes stale over time. Client State is synchronous, under our control, and disappears on refresh. (More precisely, when the page unloads, the JavaScript runtime restarts, and the component tree and its state in heap memory are reclaimed together. When the component mounts again, it starts over from the initial value of useState.) If we try to handle both with the same tool, we must implement patterns such as cache invalidation, background refetching, and optimistic updates ourselves.

I take this one step further and divide frontend state into seven categories. To be clear, these seven categories do not separate neatly along a single axis. They mix storage location, source, lifecycle, and role, so a single piece of state may belong to several categories at once. Rather than treating this as a perfect taxonomy, think of the categories as questions to ask when deciding how state should be managed.

• Local State — State used only within one component or a narrow subtree
• Global State — State that must be shared across the application
• Server State — State whose source of truth is the server and whose client-side copy is a cache
• Form State — Temporary state that exists while the user is entering data
• URL State — Shareable state that lives in the address bar and survives refreshes
• External State — State outside React, such as cookies, localStorage, sessionStorage, and IndexedDB
• State Guard — Logic that blocks, allows, or validates access and actions based on combinations of state, rather than state itself

Beyond these categories, there is workflow state that may need to be modeled as a state machine and real-time collaborative state built on WebSocket or CRDTs.

Let us examine why each category calls for different tools and what kind of judgment we should apply to it.

Local State

This is the simplest kind of state. It is used only within a single component, and the outside world neither needs nor is entitled to know about it. Examples include whether a modal is open, whether a toggle button is on or off, hover state, and a search term currently being entered.

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

This much is probably familiar. The genuinely difficult question with Local State is deciding "where should this state live?"

In Kent C. Dodds's article on State Colocation, he explains that people are accustomed to "lifting up" state, but when the code changes, they rarely move that state back to where it belongs by "colocating" it.

Lifting state is the natural thing to do when sibling components need to share it. Because both siblings need to see the same data, we move the state to their common parent and pass it down through props.

The problem arises when those siblings no longer need the state. We are much less likely to move it back down into a child. As a result, parent components accumulate state that has little to do with them, and every parent re-render causes the entire child tree to re-render as well.

The first principle for Local State, then, is this: to make the code faster and simpler, keep state as close as possible to the code that uses it. If state is used by only one child of a component, there is no reason for the parent to own it. Move it into that child. The parent becomes lighter as a result.

Global State

Global State must be accessible from anywhere in the application. Authentication information, theme, language, and notifications such as toasts are common candidates.

The difference between Local State and Global State is not simply where they live. They make different contracts about how they may be referenced. Local State promises that "this has meaning only inside this component," while Global State publishes a codebase-wide promise that "this value can be referenced by this name from anywhere in the application." The cost of that promise is the essence of Global State.

Creating a piece of Global State is, in effect, adding another implicit dependency across the entire application.

Server State

We put data returned by an API into Client State and manage loading and error states ourselves with booleans—until we finally ask, "Why am I writing the same boilerplate every time?"

Tanner Linsley, the lead maintainer of TanStack, puts it this way: "Client State is synchronous and predictable. Server State is asynchronous, shared across multiple components, and requires careful handling of caching, background refetching, and error states." Server State is therefore fundamentally a different species from Client State. It should not be handled with the same tool.

What makes Server State difficult is not the tooling but the nature of the data itself.

The data the client displays belongs to the server. What the client holds is merely a snapshot from a particular moment in time. As time passes, this data becomes stale. It is also asynchronous, can fail, and moves through states such as pending, error, and success.

The most important fact is that responses are not guaranteed to arrive in the order requests were sent. Imagine typing "react" quickly into a search box. Requests for r → re → rea → reac → react are sent in that order, but if the response for "react" arrives first and the response for "rea" arrives afterward, the UI will display the results for "rea". Preventing this requires accounting for concurrency hazards (race conditions) that would otherwise force us to implement AbortController logic or request ID tracking by hand every time.

Form State

Forms are a peculiar kind of state. Their values change intensely while the user is typing, but usually disappear once the form is submitted. They are not shared elsewhere, and in most cases there is nowhere else they need to be stored.

The problem is that this intense rate of change can be expensive. If every keystroke causes a React re-render, input lag can become noticeable in a large form. And a form does more than simply hold values. Validation, dirty checks, submission status, error messages, and multistep flows all bring several kinds of state to life within a single form at once.

A multistep form such as a three-step checkout flow is often expected to preserve progress even if the page is refreshed midway through. If its values live only in useState, a refresh wipes them all out. It is more natural to store them in sessionStorage (temporary, tab-scoped storage) or the URL (for shareable steps). In other words, depending on its lifecycle requirements, Form State combines with External State or URL State.

URL State

Imagine a search page where users can filter by category, sort order, and page number. If we keep these values in useState, three problems arise at once.

• Refreshing the page resets every filter
• Sharing the URL with a friend shows them the unfiltered page
• Pressing the Back button does not restore the previous filters

A natural solution is to put the state in the URL. The URL is effectively a free persistent store with built-in support for refreshes, sharing, and navigation history.

/products?category=shoes&sort=price-desc&page=2

That single URL contains the complete state: "page 2 of the shoes category, sorted by price in descending order." There is no need to keep a separate copy in useState.

When is the URL the right place for state? A URL is a public interface. Passwords, authentication tokens, and temporary notes that users would not want others to see must not go into it. Nor should values that change too frequently—such as a search term updated on every keystroke—be written directly to the URL, because they will fill the history stack with noise. In those cases, apply the change after a debounce or avoid polluting history by using push only when appropriate and choosing replace for updates that should not add an entry.

Values in a URL are always strings. Numbers, booleans, arrays, and objects must be serialized and deserialized. URLs must also follow the rules of percent encoding, which gives characters such as &, =, Korean text, and spaces special handling. Implementing all of this by hand every time quickly becomes a breeding ground for bugs.

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

Libraries such as nuqs solve both problems through the concept of a parser. Parsers such as parseAsInteger, parseAsBoolean, and parseAsJson handle serialization, deserialization, and types together. The library supports most common environments, including both the App Router and Pages Router in Next.js, React Router v6/v7, TanStack Router, and Remix.

Does that mean we can put unlimited amounts of state into a URL? Separate from serialization and typing concerns, one final constraint remains. RFC 7230 does not set an exact limit, but recommends that servers support at least 8,000 octets (an octet is the term used in networking and data communications to refer unambiguously to a group of eight bits, or one byte). Browser limits also vary. Modern browsers generally permit anything from 8 KB to tens of thousands of characters, but search engines, social media Open Graph and sharing pipelines, and some gateways may truncate URLs at around 2 KB. So do not treat the URL as boundless storage. Keep only the essential, shareable filters there, and leave the rest to sessionStorage or server-side storage.

External State

React knows only about state within its own world. Our applications, however, constantly communicate with the world outside React. State that lives there can persist and change independently of React's lifecycle. Here, External State includes Cookie, localStorage, sessionStorage, and IndexedDB.

How should we choose among these storage mechanisms? I usually evaluate them along four dimensions: lifetime, capacity, synchronicity, and security.

For authentication tokens, the OWASP recommendation is to prefer HttpOnly + Secure cookies. Because JavaScript can access localStorage, an XSS compromise can expose the token directly. Some security guides recommend a hybrid pattern: keep the access token in memory and the refresh token in an HttpOnly cookie. Use localStorage for persistent, non-sensitive data that changes infrequently, and sessionStorage for data that should disappear with the tab. IndexedDB is commonly used for offline caches, large datasets, and files.

Cookies and Web Storage (local/session) store strings only. Storing an object therefore requires JSON.stringify/JSON.parse. JSON, however, has limitations.

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

Date becomes a string during a JSON round trip, while Map, Set, and undefined can lose data. With the default behavior, BigInt makes JSON.stringify throw a TypeError, so serialization fails entirely. Whenever you put an object into external storage, remain conscious of which types may be lost, transformed, or cause serialization to fail, and introduce a serialization adapter when necessary.

The real difficulty of External State is that React does not detect its changes automatically. Writing a value to localStorage does not cause a React component to re-render. There are generally three patterns for solving this.

• Wrap it in a custom hook (useLocalStorage) that synchronizes External State with React state. This is lightweight, but a hand-rolled implementation must handle edge cases such as multiple tabs, SSR, and tearing.
• Use the useSyncExternalStore hook introduced in React 18 to "synchronize with state outside React." This ensures that tearing does not occur during concurrent rendering. It is the standard tool for connecting React to localStorage, browser APIs, and external stores.
• Use the first-class external storage integrations provided by state libraries, such as Zustand's persist middleware or Jotai's atomWithStorage.

Here is one more important principle: the moment we bring External State into React, synchronization becomes our responsibility. What happens when another tab updates it? What if the server changes a cookie? What if a user edits localStorage directly through the browser's developer tools? These scenarios often become some of the richest sources of bugs.

State Guard

The final category is somewhat different. It is not state itself, but logic that uses a combination of state to block, allow, or validate a particular flow.

The most common example is an Auth Guard.

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

Here, the isAuthenticated state controls the routing flow. That is guard logic. There are many kinds of guards: Auth Guards (authenticated or not), permission guards (specific roles or permissions), flow guards (entry-point branching), and validation guards (enabling a step), among others.

Guard logic tends to accumulate in one place. It is common for a single component to contain every condition: "if the user is not signed in, go to the login page; if they lack permission, show a 403; if the cart is empty, go to the product page; if the user is suspended, show the suspension notice." As a guard grows, it becomes harder to debug which condition blocked the flow and where.

A good guard checks only one thing. Combine guards through Composition.

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

Each guard makes only one decision, while the tree structure handles composition. Adding a new guard does not require changing any existing guard.

When designing guards, what happens next—where the user is sent and how the flow continues—deserves even more thought than the act of blocking access itself. A guard that blocks without a fallback ends in a blank screen or an infinite spinner.

One of the most common bugs occurs when protected content briefly flashes before the guard's asynchronous check finishes. Validating an authentication token and fetching permissions are usually asynchronous. During that interval, isAuthenticated may temporarily be undefined or false. Unless the loading state is handled explicitly, protected content may be exposed during that gap, or the user may be redirected to the login page incorrectly.

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

Two models are commonly used when implementing permission guards.

• RBAC(Role-Based Access Control) : Grants permissions by role—for example, "an admin can view all user information." It is simple and fast, but the number of roles can explode as permissions become more granular
• ABAC(Attribute-Based Access Control) : Determines permissions from combinations of attributes—for example, "the user is the author of the post, belongs to the same team, or is an admin." It is highly expressive but more difficult to implement and debug

Patterns such as the TanStack Router RBAC guide, which places guards in beforeLoad at the router level, are recommended. The key is that permission checks should be expressed as data—a list of roles and permissions—rather than scattered throughout the code. That way, changing an authorization policy remains a data change.

Conclusion

Let us sum up. State Management is difficult not because the libraries are difficult, but because we often forget that state comes in different kinds and overlook the fact that each kind requires different tools and a different way of thinking.

Keep Local State as close as possible; question whether Global State truly needs to be global; treat Server State as a cache; separate forms from the domain; use the URL more actively; understand the responsibility that comes with external storage; and compose small, focused guards. These are the fundamentals of working with the seven categories.

The judgment that ties them together can ultimately be reduced to four questions.

• Where is the Single Source of Truth for this data?
• Is this a value that can be derived, or does it truly need to be stored?
• Are any combinations of this state impossible?
• Does this state really belong in this location?

I believe the surest way to develop sound judgment and intuition is to ask these questions whenever we build a new screen, review a PR, or receive code generated by AI.

As I said at the beginning, AI will remain beside us for a long time. We will spend less and less time inspecting every line. Yet that will only make the ability to answer small questions such as "Where should this state live?" more valuable. Asking AI to "add another useState here" is easy. Knowing what new strand that single line adds to the web of our application depends entirely on the judgment of the person reading the code.

There is no single right answer. But there is a clear difference between "creating state without understanding what state is" and "creating state with deliberate awareness of its category and location." Before readers write their next line of useState, I hope they will pause for a moment and ask, "Which category of state is this?"

References

Throughout my career as a developer, I have encountered the word "domain" quite often. Yet when someone asks, "What exactly is a domain?" it is not easy to give a clear answer. (Honestly, when I first started programming, I thought domain meant the "www" kind.)

Looking up information about domains naturally leads to concepts such as domain models, domain objects, and domain object models. I have always found it unfortunate that there are not many articles that clearly explain how these concepts differ, or what they mean on the frontend rather than the backend. In this article, I will start with a definition of each concept and use examples to explore how domain logic can be appropriately separated and abstracted on the frontend.

Lately, I have been very interested in the tax domain. With the comprehensive income tax filing season coming up in May, I will use taxes for the examples in this article.

Domain

Let us begin with the most fundamental question. What is a domain?

In his book Domain-Driven Design: Tackling Complexity in the Heart of Software (2003), Eric Evans defines a domain as follows.

A sphere of knowledge, influence, or activity.

"A sphere of knowledge, influence, or activity."

Put simply, the domain is the problem space that we intend to solve through programming. If we are building a tax filing service, "tax filing" is the domain; if we are building an insurance claims platform, "insurance claims" is the domain. A domain is not code. It is a real-world problem space that exists before the software does.

What does this mean for frontend developers? Ultimately, the UI we build is a window that lets users see and manipulate the domain. When developing tax-refund services such as Toss Income or 3o3, whose primary domain is tax, we are expressing domain concepts such as income types, expense rates, income deductions, tax credits, and refund amounts through the UI. Frontend developers therefore need a deep understanding of the domain they work with. In other words, knowing "what problem this service solves" is just as important as being good at rendering UI components.

But even a single domain called "tax" contains countless subdomains when examined closely. This is true even of the comprehensive income tax calculation pipeline I only understand at a high level.

Each stage of this pipeline is a subdomain with its own rules and data. Within the broad domain of "tax," the detailed domains of Income, Deduction, Tax, and Filing are intertwined. How these should be divided in code is the central question of domain modeling.

Domain Model

Then what is a domain model? How is a domain different from a "domain model"?

Martin Fowler and Eric Evans define a domain model as follows.

An object model of the domain that incorporates both behavior and data. — Martin Fowler

An object model of the domain that incorporates both behavior and data.

A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain. — Eric Evans

A system of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain.

The key is "selective abstraction." A domain model does not contain everything in the real world. Just as a film director does not capture every scene in reality but selects only the scenes needed for the story, a domain model selects and structures only the aspects needed to solve the problem.

There is one important point here. A domain model does not necessarily have to be code. It might be a diagram on a whiteboard, or a shared mental model in the minds of team members. Ultimately, the term domain model itself can refer to a concept independent of software.

This is where frontend developers are particularly prone to confusion. They see the structure of an API response and think, "So this is the domain model." But that is a data model, not a domain model.

The distinction between a data model and a domain model is as follows.

A data model defines "the shape in which data is exchanged," while a domain model defines "what that data means to the business and what rules it follows." If we fail to distinguish the two, components become directly dependent on the API response structure, and the entire frontend is thrown into disarray whenever the backend schema changes.

Domain Object

If a domain model is a system of concepts, a domain object is a concrete implementation of one of those concepts in code.

In an article by Jason Swett, who runs Code with Jason, he defines a domain object as follows.

Any object in my object model that also exists as a concept in my domain model, I would call a domain object.

Any object in my object model that also exist as a concept in my domain model I would call a domain object.

In other words, if the domain model contains a concept called "comprehensive income" and the code contains a type called Income, that Income is a domain object. But not every object in code is a domain object. Things such as HttpClient, LocalStorageAdapter, and useDebounce are technical tools, not domain concepts.

Entity and Value Object

Evans classifies domain objects into three categories: Entity, Value Object, and Service. (Martin Fowler calls this the "Evans Classification.") A Service is a separate concept that represents "a domain operation that does not naturally belong to a particular object." Because the focus of this article is how data is identified, we will concentrate on Entities and Value Objects.

An Entity is an object with a unique identity that persists across time and different representations. A tax filing (TaxFiling), taxpayer (Taxpayer), or income record (IncomeRecord) is identified by a unique ID; even if its properties change, it remains the same Entity as long as its ID is the same. Even when the deductions on a filing are edited, it is still the same filing unless the filing ID changes.

A Value Object is an object whose meaning comes solely from the combination of its properties, and two Value Objects are considered equal when all their property values are equal. Money, a tax rate (TaxRate), and a tax bracket (TaxBracket) are objects whose values themselves carry the meaning. A "6% tax rate" is simply a "6% tax rate" wherever it is used.

Why does this distinction matter on the frontend? Let us look at the code below.

interface TaxFiling {
  id: string;
  taxpayerName: string;
  taxYear: number;
  status: FilingStatus;
}
 
const isSameFiling = (a: TaxFiling, b: TaxFiling) => a.id === b.id;
 
interface Money {
  amount: number;
  currency: "KRW" | "USD";
}
 
const isSameMoney = (a: Money, b: Money) =>
  a.amount === b.amount && a.currency === b.currency;

TaxFiling is an Entity because it uses its id as the basis of identity. (Merely having an id field does not make something an Entity; the key is that "the id determines whether two objects are the same or different.") Money has no id and is identified only by the combination of amount and currency; it is considered the same value when all properties are equal.

Entities use ID-based comparison; Value Objects use property-based comparison. Making this distinction explicit naturally clarifies the state-management logic for determining whether data is the same or different. When updating an item in a list, for example, an Entity can be found and replaced by ID, while a Value Object can be replaced immutably.

Domain Object Model

We now understand the "domain model" and the "domain object," but what is a domain object model?

Surprisingly, I could not find a commonly agreed-upon definition. A substantial body of literature treats "domain model," "domain object model," "conceptual model," and "analysis object model" as effectively synonymous—different names for the conceptual model created during object-oriented analysis.

Another perspective, however, sees it as a more distinct layer. A representative explanation is that the object model is the point where a domain model is translated into actual code.

Under this second view, an object model is the structure of every object in the system's code. This includes technical tools such as HttpClient and useDebounce. Within it, the subset of objects that represent domain concepts, together with the relationships among them, is the domain object model. This also aligns with the object-oriented modeling tradition, which has defined an "object model" as the static structure of a system—its classes, properties, operations, and relationships.

I find this perspective more practical for frontend developers because the code we actually write always mixes domain objects with technical objects.

Ultimately, domain → domain model → domain object model → domain object is a progression from the abstract to the concrete. The domain is the broadest, and the domain object is the most concrete. Thus, the area we actually wrestle with when writing frontend code is how to structure the domain object model—the types that express domain concepts and the relationships among them.

Where Should Domain Logic Live on the Frontend?

That covers the definitions. Now let us turn to practice. Where should domain logic live on the frontend?

Khalil Stemmler, who has a deep interest in software design, initially argued that "business logic does not belong on the frontend." He later revised his position, saying, "Almost everything we do architecturally on the backend can and should also be done on the frontend."

I agree with this position. Of course, the frontend must not become the Single Source of Truth for business logic. That is the backend's role. But the frontend clearly has domain logic of its own.

Consider a case where "the estimated refund must update in real time based on the information the user enters." If this calculation logic exists only on the backend, an API call must be made every time the user changes a single digit in their income. The UI pauses for a network round trip, and a fast typist can trigger a flood of unnecessary requests. Even with debounce, a delay of a few hundred milliseconds is enough to undermine the experience of a "real-time preview." Ultimately, calculations that require immediate feedback have to be performed directly on the frontend, which means some logic can only be performed there.

When Domain Logic Is Mixed into a Component

Consider a comprehensive income tax preview screen. It shows the estimated tax in real time as the user enters income information. The code below is a common example in which domain logic and UI logic are intertwined.

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

Can you see the problem? Business rules established by tax law—"KRW 1.5 million in personal deductions per person," "eight progressive tax brackets," and "3.3% withholding"—are embedded directly in a React component. Tax law changes every year. When such rules are scattered across components, each revision sends us hunting for every place that needs to change. And if the QA team maintains E2E scenarios, the testing cost will be substantial as well.

Eventually it becomes difficult to distinguish view logic from business logic, and the code turns into a tangle of conditionals and custom hooks.

Let Us Separate the Domain Logic

Let us borrow the central principle from Alex Bespoyasov's Clean Architecture approach: separate domain logic into pure functions that do not depend on a framework.

The domain is the core that distinguishes one application from another. You can think of the domain as something that will not change if we move from React to Angular.

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

Let us refactor the tax calculation example above.

First, we define the domain types and rules, keeping related information together.

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

Then we separate the domain logic into pure functions.

The logic for income calculation, deductions, tax base, tax, and refunds discussed above is extracted into a computeFullTax function. Each stage is then broken down into smaller pure functions. If the result type is inferred with ReturnType<typeof computeFullTax>, there is no need to declare a separate interface.

The component then does nothing but "use" the domain logic.

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

What has changed?

• The table of eight progressive tax brackets (TAX_BRACKETS) is gathered in one place, so when tax law changes, only domain/tax.ts needs to be updated.
• The calculation pipeline is cohesive within a single computeFullTax function, making the entire flow visible at a glance. (It is grouped into one function to keep the example simple, but in a real project it would be appropriate to divide it further by purpose, such as income calculation, deduction calculation, and tax calculation.)
• The component focuses only on "how to present it." A change in tax rates does not require modifying the component.
• Even if we migrate from React to another framework, domain/tax.ts does not change.

Once domain logic is separated, testing becomes surprisingly simple. This is especially important in the tax domain, where calculation accuracy directly affects the user's money.

Pure functions containing tax calculation logic need neither React Testing Library nor render nor screen.getByText. Supply an input and check the output—that is all. Cases such as "a 6% rate up to KRW 14 million," "zero tax when the tax base is zero," and "the refund on KRW 30 million of freelance income" can each be expressed as a one-line it. Domain unit tests naturally establish boundaries for component separation, while the test code also serves as documentation.

Anemic Domain Model

In the previous section, we separated calculation logic. But domain logic also includes state-transition rules and authorization decisions. Questions such as "Can this filing be edited right now?", "Can it be submitted?", and "Can the claim method be changed?" fall into these categories. Separating these rules presents an easy trap: the Anemic Domain Model, a term coined by Martin Fowler.

An Anemic Domain Model is a state in which types are well defined in the domain language, but the rules that operate on them have been scattered outside the domain. Consider the tax filing domain. The type is tidy.

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

But the rules for decisions and transitions concerning this type are buried elsewhere.

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

The same domain rule exists in three different forms across utils, a component, and a hook. If a requirement comes in saying, "The eligibility conditions for claims are changing," we must hunt down every place that needs updating, while any one we miss will make an incorrect decision somewhere on the site. Fowler criticized such code as "little more than procedural code wearing the skin of an object-oriented model."

The solution is the same one we applied to calculation logic in the previous section: put the rules next to the type.

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

Now every filing-related rule is managed in a single place: domain/filing.ts. Any component can call canAmend(filing), and when a rule changes, only this one file needs to be updated. The key is to treat the type and the rules that operate on it as one unit. A partial separation that puts only the type in the domain folder while moving its rules to utils may look clean, but it is still anemic.

The Translation Layer Between API Responses and the Domain Model

There is one more factor to consider in practice: the backend API response structure and the frontend domain model do not always match. This is even more true for a tax service integrated with government systems. Data from Korea's National Tax Service Hometax system is full of abbreviations and coded values, so it is unlikely to arrive in the same shape as the frontend domain model.

What we need here is a transformation layer (Mapper). Rather than passing the API response type all the way into components, we first refine it into a domain type. A single pure function is enough.

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

This converts abbreviated fields such as 총수입금액 and 경비율, as well as code-based classifications in the API response, to suit the frontend domain in one place. Values such as the income-type code that need to be expanded into an enum can be handled with a small lookup table inside the mapper. Even if the field names in the Hometax API change, only the mapper needs to be updated.

Utility Functions and Domain Logic

When separating domain logic, one question inevitably arises: "Isn't this just a utility function?"

Consider the following two functions.

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency is pure presentation logic that converts a number to a string. Adding the unit "won" and thousands separators is not a business rule; it concerns how a value is shown to the user. By contrast, calculateTax contains a business rule grounded in tax law: applying eight progressive tax brackets. It is a domain rule that must apply in exactly the same way even if there is no UI.

Here is the criterion I use in practice.

If this logic disappears, does the business break, or only the screen?

If the business breaks, it is domain logic. If only the screen breaks, it is presentation logic. This one question can identify most boundaries.

Reality, however, is not this tidy. The hardest cases are those that look like domain logic but are actually presentation logic.

Consider the code below. It was classified as domain logic because it takes the domain concept FilingStatus as an argument. But is it really domain logic?

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

Although getStatusBadgeColor and getStatusDisplayText use the domain concept FilingStatus, what they do is screen presentation. Changing a badge color does not break the business at all. Putting such functions in domain/filing.ts makes the domain module increasingly bloated and mixes genuine domain logic with presentation logic.

Separating the Domain Model and ViewModel

There is a practical way to solve this problem: separate the ViewModel into its own file within the same domain folder. Rather than .ui.ts, using the name .viewModel.ts connects naturally to the ViewModel concept in the MVVM pattern. The name immediately communicates its role as "a layer that transforms domain data for the screen."

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

Move the getStatusBadgeColor and getStatusDisplayText functions we saw earlier directly into filing.viewModel.ts. Transformations that expand filing types into Korean labels, such as getFilingTypeLabel(type: FilingType): string, are gathered there as well. filing.ts is responsible only for business rules, while filing.viewModel.ts is responsible only for screen presentation.

The key is the direction of dependency. filing.viewModel.ts imports filing.ts, but filing.ts never imports filing.viewModel.ts. The domain knows nothing about presentation; presentation knows about the domain. This can be seen as a miniature version of Robert C. Martin's Dependency Rule.

I placed the files in the same folder because I believe files that change together should live in the same directory. If the FilingStatus type gains a new value (such as 'rejected'), both filing.ts and filing.viewModel.ts must be updated. Since they are in the same folder, the scope of the change is visible at a glance.

Boundaries and Cohesion

Just as important as separating domain logic is deciding where to draw the boundaries. Here are several boundary decisions I often encounter in practice.

The data handled by a frontend comes from roughly four sources.

• Server data: received in an API response
• Derived data: calculated from server data
• UI state: used to control the screen and reflect user interactions
• User input: values currently being entered in a form

Combining all four in one type pollutes the domain model.

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

This type puts domain concepts, UI state, and temporary data in one basket. Every change to activeStep effectively updates the Filing domain. (Changing a form step is not a business event.)

The improvement is to divide the types along their boundaries. The domain model contains only business concepts such as id, status, and determinedTax; UI state (FilingFormViewState) contains only screen controls such as isExpanded and activeStep; and form state (DeductionEditForm) contains only temporary data being entered.

This gives each type a single reason to change. A domain type changes only when tax law changes, UI state only when the screen design changes, and form state only when the input UX changes.

Keep Things That Change Together Together

Eric Evans's DDD includes the concept of an Aggregate: "a cluster of related objects treated as a single unit." We do not need to apply this concept wholesale on the frontend, but its central principle—keep data and rules that change together together—is worth borrowing.

In a tax service, for example, Income and ExpenseRate always change together. When the income type changes, the applicable expense rate changes, and the comprehensive income calculation is affected as well. These should therefore be kept together in one file, domain/tax.ts.

By contrast, TaxFiling can change independently of tax calculation. A change to the filing's state-transition rules does not affect tax-rate calculation logic. It is therefore appropriate to separate it into domain/filing.ts.

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

Class vs. Functional Style

At this point, a fundamental question may come to mind. Every example so far has used a combination of interface and pure functions. Would cohesion be more natural if we represented the domain with a class?

That is a fair point. A class-based representation of the domain binds data and behavior into a single object, making cohesion immediately visible in the code structure.

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

With a class-based approach, behavior belongs to the data. The subject is also explicit at the call site. filing.canAmend() is as intuitive as reading natural language: the subject (filing) and verb (canAmend) are clearly bound together. It is like writing jihoon.eat('감자탕') and immediately reading, "Jihoon eats gamjatang."

By contrast, the functional style looks like this.

canAmend(filing);
eat("jihoon", "감자탕");

In the functional style, the data exists outside the function. The first call takes filing as an argument and performs an action, while eat takes jihoon and 감자탕 as its arguments.

As a result, the bond between subject and verb is looser. To know that the canAmend function concerns TaxFiling, we have to open the file or inspect its type signature. If functions such as canAmend(filing), canEdit(filing), and calculateTax(taxableBase) are mixed in the same file, it may be difficult to see at a glance which domain each function belongs to.

So Should We Use Classes?

Honestly, the answer is "it depends." In my experience, however, there are practical reasons classes are not a silver bullet in a React + TypeScript environment.

1. Friction with React State Management

React state management fits most naturally with plain objects. useState and useReducer can technically hold any value, and Redux DevTools does not itself remove a class instance's prototype. If Redux/Zustand persistence middleware stores and restores state as JSON, however, a class instance loses its methods and prototype in the JSON.stringify → JSON.parse cycle and becomes a plain object. The props boundary from a React Server Component to a Client Component has a different constraint: it accepts only supported serializable values, so an arbitrary class instance cannot be passed through it in the first place.

Consider the code below.

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

Updating React state alone does not stop filing from being an instance of TaxFilingModel. If Redux/Zustand persistence saves and restores it as JSON, however, the restored value may be a plain object without methods, so an innocent call to filing.canAmend() can produce a runtime error. Passing it from a React Server Component to a Client Component fails earlier because a class instance is not a supported serializable prop value.

2. The Difficulty of Guaranteeing Immutability

React detects state changes based on referential equality. If a method on a class instance mutates internal state with something like this.items.push(...), the reference stays the same and React does not trigger a rerender. In the end, addDeduction(item) has to return a new instance every time—something like return new DeductionList([...this.items, item]). That undermines the class advantage of "encapsulated state mutation" and leaves code that is not very different from functional updates.

Strategies for Achieving Cohesion in a Functional Style

Then how can we improve the loose cohesion of code such as eat('jihoon', '감자탕') in a functional style? Here are three approaches I have found effective.

1. Create Cohesion with a Module Namespace

This is the most straightforward approach. Make the file (module) itself correspond to a domain, and use a namespace when importing it. We can use the domain/filing.ts defined earlier as-is.

import * as FilingModel from "../domain/filing";
 
FilingModel.canEdit(filing);
FilingModel.canAmend(filing);
FilingModel.canSubmit(filing);

FilingModel.canAmend(filing) is not quite as compact as filing.canAmend(), but the code makes it immediately clear that this function belongs to the Filing domain. It also eliminates the risk of functions from several domains being mixed together.

2. Always Make the Domain Subject the First Argument

Another convention expresses cohesion in a functional style: always make the first argument the "subject of the behavior." Consistent signatures such as canAmend(filing) and calculateTotalIncome(income) allow canAmend(filing) to read as "ask canAmend about filing." This also resonates with the Unix pipeline mindset (data |> transform). In fact, Go's method receiver follows precisely this pattern, and Rust's impl blocks accept self as the first argument from the same underlying idea.

3. Bundle Behavior with a Domain Object Factory

This pattern is useful when we miss the cohesion of a class. A factory function returns a domain object and its behavior together.

export function createFilingModel(data: TaxFiling) {
  return {
    ...data,
    canEdit: () => data.status === "draft",
    canSubmit: () => data.status === "draft" && data.determinedTax >= 0,
    canAmend: () =>
      data.status === "completed" && data.filingType !== "amendment",
  } as const;
}
 
const filing = createFilingModel(rawFiling);
filing.canAmend();
filing.canEdit();

This pattern combines the expressiveness of a class (filing.canAmend()) with the practicality of composing behavior through an object literal. Because the returned object has function properties, it is not itself JSON-serializable data. It also creates new function objects each time, but at the scale of data handled on the frontend, this is rarely a performance problem.

How Far Should We Separate Things?

Clean Architecture describes an ideal structure with three or four layers and defined Ports/Adapters. Applying this structure to every project in the real world, however, can become over-engineering.

Here are the practical guidelines I use.

• Separate domain types from API response types. Whether using an interface or a type, define the domain concepts used by the frontend in separate files.
• Move logic containing business rules out of components. It does not have to live in a domain/ folder. What matters is making it a pure function that does not depend on React.
• Transform API responses into the domain model in one place. Whether that is a mapper function or a Zod schema, create a structure where changing that one place prevents the change from propagating.

As a project grows more complex, the following may also be worth considering.

• Divide folders by Bounded Context. The Toss Frontend Chapter also emphasizes the principle, "Place files that change together in the same directory." Dividing folders by domain naturally reveals domain boundaries through import paths.
• Introduce a Use Case layer. When combinations of domain logic become complex, an Application layer is needed to wrap a scenario such as "retrieve income information → apply expense rate → calculate deductions → calculate tax → finalize refund" into a single function.

src/
├── domains/
│   ├── tax/
│   │   ├── tax.ts                  # 세액 계산 도메인 (세율, 공제, 계산 파이프라인)
│   │   ├── tax.viewModel.ts        # 세액 표현 (금액 포맷, 구간 라벨)
│   │   ├── tax.test.ts             # 세액 계산 테스트
│   │   └── incomeMapper.ts         # 홈택스 API ↔ 도메인 변환
│   ├── filing/
│   │   ├── filing.ts               # 신고 상태 도메인 (상태 전이, 권한)
│   │   ├── filing.viewModel.ts     # 신고 표현 (상태 배지, 라벨)
│   │   ├── filing.test.ts
│   │   └── filingMapper.ts
│   └── deduction/
│       ├── deduction.ts            # 공제 항목 도메인 (자격 조건, 한도)
│       └── deduction.viewModel.ts
├── hooks/                           # React 의존 로직
├── components/                      # UI 컴포넌트
└── api/                             # API 호출

Even within the single domain of tax, tax calculation (tax), filing management (filing), and deductions (deduction) are separated into independent subdomains. A change in tax rates does not affect filing state-transition logic, and adding a deduction does not alter the filing-submission flow. This is a practical application of Bounded Context.

Conclusion

To summarize, a domain is the problem space we are trying to solve; a domain model is a conceptual system that selectively abstracts that problem; a domain object model is the implementation of that conceptual system in code; and a domain object is an individual object within that implementation.

Putting these concepts into practice on the frontend is not merely a matter of splitting folders. It means deliberately reasoning about several layers of boundaries. "Is this a business rule or presentation logic?" "Is this data domain state or UI state?" "Is this function sufficiently cohesive?" Simply making a habit of asking these questions will naturally improve the structure of the code.

Of course, not every project needs every layer of Clean Architecture. Splitting a simple CRUD app into four layers and applying the factory pattern to every domain would be a case where the cure is worse than the disease. Between the elegant cohesion of classes and the practical flexibility of functions, the right answer is determined by the project's complexity and the team's context.

There is no single right answer. But there is a clear difference between "writing code without knowing what the domain is" and "recognizing the domain, reasoning about boundaries, and separating things deliberately." I hope readers will take a moment to ask themselves, "What is the domain here, and where should this code live?" in their own projects.

References

I have always been interested in code review and refactoring, so I decided to take on Toss's Frontend Fundamentals mock exam, which presented the challenge in an intriguing format. The task was to refactor a provided meeting room reservation app. It also came with tests, giving me a safety net for verifying that the refactoring had not broken any functionality.

In the end, I spent two days on the refactoring. Here are my reflections on the process.

My First Encounter with the Code

The first thing I did after opening the code was read the test specifications. Tests are the most honest documentation of what an application is supposed to do. I skimmed through App.easy.spec.tsx and App.hard.spec.tsx to understand the application's overall requirements.

I then turned to the implementation itself, where two monolithic components immediately stood out.

• ReservationStatusPage was a component of roughly 400 lines, with date selection, timeline visualization, reservation detail tooltips, the user's reservation list, and cancellation functionality all packed into a single file.
• RoomBookingPage was a component of roughly 300 lines, with filters, the room list, reservation creation logic, and URL parameter synchronization all tangled together.

As I read through the code, rather than immediately deciding that it “needed improvement,” I first focused on classifying the characteristics of the code. I distinguished between code that contained domain knowledge, code that behaved like a utility, and code that belonged purely to the UI layer.

// 도메인 정보: 장비 라벨, 타임 슬롯 등 비즈니스 상수
const EQUIPMENT_LABELS: Record<string, string> = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
};
 
// 유틸리티: 날짜 포맷, 시간 변환
function formatDate(date: Date): string { ... }
function timeToMinutes(time: string): number { ... }
 
// 서버 상태: 인라인 useQuery, useMutation 호출
const { data: rooms = [] } = useQuery(['rooms'], getRooms);
const { data: reservations = [] } = useQuery(['reservations', date], () => getReservations(date));
 
// UI + 비즈니스 로직 혼재: 필터링, 정렬, 충돌 감지가 JSX 사이에 산재

Once I had classified the code this way, it became much easier to see where to begin. I added brief comments to each area of the code to note possible directions for improvement. (It felt a little like migrating the jQuery-based project I encountered when I first joined my current company.)

So where should I start?

Developing a Refactoring Strategy

I planned to carry out the refactoring in the following order.

1. Handle server code: separate queries and mutations
2. Separate domain logic: create Equipment, Room, and Reservation models
3. Define types: organize the type system around the domain models
4. Extract utility functions: date formatting, timeline calculations, and so on
5. Separate the UI layer: divide components into coherent units by concern
6. Abstract and separate concerns: handle errors/loading and manage query keys

I chose this order so I could work from the outside of the dependency structure inward. The idea was to organize the infrastructure—the server code and utilities—first, establish the domain models next, and refine the UI last. If I split the UI components first, I might end up moving still-unorganized domain logic and query code back and forth across multiple components.

With the strategy in place, it was time to execute it one step at a time.

Organizing the Server Code and Utilities First

Extracting the Date Formatting Utility

The first thing I tackled was the formatDate function because the same function had been defined inline on both pages.

// utils/formatYYYYMMDD.ts
export function formatYYYYMMDD(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const date = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${date}`;
}

It was a small change, but it was an important first commit in the refactoring. Starting with the most independent part with the fewest side effects and confirming that the tests still passed served as a kind of warm-up.

Extracting the React Query Hooks

Next, I moved the useQuery and useMutation calls that had been written directly inside the components into separate files. I used the queryOptions pattern to turn the query configuration into reusable units.

During this process, I also explicitly defined the API response types in remotes.ts. Values that had previously flowed through the code as any now had clear types such as GetRoomsResponse and GetReservationsResponse.

With the infrastructure layer organized, it was time to turn to the domain models.

Separating the Domain Models

The most important turning point in the refactoring was moving the domain models into a dedicated models/ directory.

In the original code, business constants such as EQUIPMENT_LABELS and TIME_SLOTS were declared at the top of component files. Types for Room and Reservation existed only in the server handler (_tosslib/server/types.ts), while the client code used values that were effectively treated as any.

// models/equipment.ts
export const EQUIPMENT_LABELS = {
  tv: 'TV', whiteboard: '화이트보드', video: '화상장비', speaker: '스피커',
} as const;
 
export type Equipment = keyof typeof EQUIPMENT_LABELS;
export const ALL_EQUIPMENT = Object.keys(EQUIPMENT_LABELS) as Equipment[];

// models/reservation.ts
export interface Room {
  id: string;
  name: string;
  floor: number;
  capacity: number;
  equipment: Equipment[];
}
 
export interface Reservation {
  id: string;
  roomId: string;
  date: string;
  start: string;
  end: string;
  attendees: number;
  equipment: Equipment[];
}

Why is separating domain models important? When business logic is coupled to UI components, changing that logic requires inspecting the component's rendering logic as well. When it exists independently in a models/ directory, changes to business rules can be made separately from the UI. Perfect separation is difficult in practice, of course, but the key is at least to create a structure where people can predict that “this logic will be here.”

Once the domain models were separated, how much lighter could the UI become?

Breaking Apart the Components

ReservationStatusPage

This commit produced the most dramatic change and took the most time. I split the 385-line monolithic component as follows.

ReservationStatusPage/
├── index.tsx                    # 페이지 레벨
└── components/
    ├── DateSelector.tsx         # 날짜 선택 UI
    ├── ReservationTimeline.tsx  # 타임라인
    └── MyReservation.tsx        # 내 예약 목록 + 취소

My criterion for separating the code was “Does this code have independent meaning?” Timeline visualization is an independent concern: it takes reservation data for a date and renders a grid. The user's reservation list is another independent concern: it retrieves and cancels the user's reservations. There was no reason for them to live in the same file.

After the split, index.tsx served only as an orchestrator. It managed state, displayed messages, and composed the child components, while delegating the actual data fetching and rendering details to those components.

RoomBookingPage

I applied the same principle to the booking page.

RoomBookingPage/
├── index.tsx                    # 페이지 레벨
├── components/
│   ├── BookingFilter.tsx        # 날짜, 시간, 인원, 장비, 층 UI
│   └── AvailableRoomList.tsx    # 예약 가능 방 목록
└── hooks/
    └── useBookingParams.ts      # URL searchParams 기반 상태 관리

One interesting decision emerged during this process. At first, I introduced react-hook-form and zod to validate the form. In the end, however, I removed them and replaced them with a custom useBookingParams hook. I will explain that decision in more detail later.

At this point, a natural question arises: how far should abstraction go?

Finding the Right Level of Abstraction

This was the part I wrestled with most during the mock exam.

How Far Should Nested Conditionals Be Unraveled?

The logic that determines whether a room is available combines several conditions: whether its capacity is sufficient, whether it has the required equipment, whether it is on the preferred floor, and whether its schedule overlaps with another reservation. In the original code, all of these conditions were written inline inside a single filter callback.

When I extracted this logic into models/roomFilter.ts, I separated each condition into a named function.

const isEnoughCapacity = (room: Room, attendees: number) => room.capacity >= attendees;
const hasRequiredEquipment = (room: Room, equipment: Equipment[]) =>
  equipment.every(eq => room.equipment.includes(eq));
const isOnPreferredFloor = (room: Room, floor: number | null) =>
  floor === null || room.floor === floor;
const hasNoTimeConflict = (room: Room, reservations: Reservation[], date: string, start: string, end: string) =>
  !reservations.some(reservation => reservation.roomId === room.id && reservation.date === date && reservation.start < end && reservation.end > start);
 
export function filterAvailableRooms(rooms: Room[], reservations: Reservation[], params: Params): Room[] {
  return rooms
    .filter(room =>
      isEnoughCapacity(room, params.attendees) &&
      hasRequiredEquipment(room, params.equipment) &&
      isOnPreferredFloor(room, params.floor) &&
      hasNoTimeConflict(room, reservations, params.date, params.startTime, params.endTime)
    )
    .sort((a, b) => {
      if (a.floor !== b.floor) return a.floor - b.floor;
      return a.name.localeCompare(b.name);
    });
}

The key here was that I extracted a condition into a function only when there was a clear name for the abstraction. Names such as isEnoughCapacity and hasRequiredEquipment let readers predict what the functions do without seeing their implementations. If the name had to be vague, like processRoomConditions, the abstraction could instead impose additional cognitive load on the reader.

This is not to say that my approach is the one correct answer. My criterion was simply “Can I predict the behavior from the function name alone?” If so, I abstracted it. If not, I thought leaving it inline might actually make the code easier to read.

searchParams vs. Form State

I also spent considerable time deciding where the booking filter state should live. In the original code, each filter value was managed with useState and synchronized with the URL searchParams through useEffect.

// 원본: useState + useEffect 동기화 방식
const [date, setDate] = useState(searchParams.get('date') || formatDate(new Date()));
const [startTime, setStartTime] = useState(searchParams.get('startTime') || '');
 
// ... 6개의 개별 상태
useEffect(() => {
  const params: Record<string, string> = {};
  if (date) params.date = date;
 
  // ... 모든 상태를 searchParams에 동기화
  setSearchParams(params, { replace: true });
}, [date, startTime, endTime, ...]);

I initially tried managing it as a form with react-hook-form and zod. Ultimately, however, I removed them and replaced them with a useBookingParams hook that uses searchParams as the Single Source of Truth.

// useBookingParams: searchParams가 곧 상태
export function useBookingParams() {
  const [searchParams, setSearchParams] = useSearchParams();
 
  const params = useMemo<BookingParams>(() => ({
    date: searchParams.get('date') || formatYYYYMMDD(new Date()),
    startTime: searchParams.get('startTime') || '',
    // ...
  }), [searchParams]);
 
  const updateParam = useCallback(<K extends keyof BookingParams>(key: K, value: BookingParams[K]) => {
    setSearchParams(prev => {
      // 기존 파라미터 병합 후 업데이트
      return result;
    }, { replace: true });
  }, [setSearchParams]);
 
  return { params, updateParam };
}

The core rationale for this decision was that “it does not make sense for these states to evolve separately.” If useState and searchParams each hold their own state, they can fall out of sync depending on when synchronization occurs. If searchParams alone holds the state, however, the URL becomes the application state and the synchronization problem disappears entirely. As a bonus, sharing the URL reproduces the same filter state for another user.

I found similar considerations in other participants' retrospectives. “We standardized on URL searchParams as the Single Source of Truth,” and “We chose to consolidate the individual filter props into a single filter object.” The expressions differed, but the underlying recognition was the same: “Scattered state needs to be grouped into a single concept.”

Resilience

Suspense and ErrorBoundary

I added error and loading handling after the component structure had been finalized. The order matters because you can only decide where to place a boundary after the component tree has been established.

Using the react-error-boundary library, I wrapped each independent data-fetching unit in an ErrorBoundary and Suspense. If the timeline fails, the user's reservation list should still render normally, and vice versa.

{/* 각 영역이 독립적으로 에러/로딩을 처리 */}
<ErrorBoundary FallbackComponent={ErrorFallback} resetKeys={[date]}>
  <Suspense fallback={<Loading message="예약 현황을 불러오는 중..." />}>
    <ReservationTimeline date={date} />
  </Suspense>
</ErrorBoundary>
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Suspense fallback={<Loading message="내 예약을 불러오는 중..." />}>
    <MyReservation onCancel={handleCancel} />
  </Suspense>
</ErrorBoundary>

Centralizing Query Keys

As I extracted the query hooks during the refactoring, query keys became scattered across multiple files. This made it difficult to determine which key to use for invalidation in a mutation's onSuccess callback.

I introduced @lukemorales/query-key-factory to manage the query keys centrally.

// queries/queryKeys.ts
export const roomKeys = createQueryKeys('rooms', {
  list: { queryKey: null, queryFn: () => remotes.getRooms() },
});
 
export const reservationKeys = createQueryKeys('reservations', {
  list: (date: string) => ({ queryKey: [date], queryFn: () => remotes.getReservations(date) }),
  my: { queryKey: null, queryFn: () => remotes.getMyReservations() },
});

This makes it possible to use them in the form useSuspenseQueries({ queries: [roomKeys.list, reservationKeys.list(date)] }), ensuring that a query key and its fetching function always travel together. I also extracted route paths into PATHS constants to eliminate hard-coded strings.

What Was the Exam Designed to Assess?

After completing the refactoring, I took a step back and reflected. What was this mock exam trying to evaluate?

While reading other participants' retrospectives, I noticed an interesting common thread. Nearly every post included the sentence “Code is not read; it is predicted.” Our brains do not interpret code one line at a time. We read by making predictions based on patterns accumulated through experience, and cognitive load rises sharply when those predictions are violated.

From this perspective, the mock exam was assessing not merely coding ability, but the collaborative skill of “making code as predictable as possible for your colleagues.” (Perhaps the ability to read the minds of exam authors and coworkers is the true mark of a software engineer.)

Looking through other participants' retrospectives, I related to comments such as “Understanding code written by someone else is not easy,” and “Designing the interface first is important, but that approach can falter when you face a vast existing codebase.” I had a similar experience. When existing code already works, there is a temptation to rationalize its structure: “It already works, so why bother?” But the point of the mock exam was to move past that temptation and judge the code by “how quickly someone other than me can understand it, and whether I can assess and solve the problem using my own judgment.”

What I Learned from Refactoring

The order of refactoring shapes the outcome. Working from the outside—the infrastructure—inward to the UI was a safe path that kept the process from becoming tangled midway through. Once the utilities and domain models were organized, splitting the components made each component's dependencies clear.

The criterion for abstraction is the name. If the name of an extracted function or variable can explain its behavior, it is worth abstracting. If the name must remain vague, leaving the code inline may be the better choice.

Where state lives is architecture. State that needs to move together should live in the same place. Using searchParams alone as the source of truth is structurally healthier than synchronizing useState with searchParams.

Closing Thoughts

After finishing the task, I discussed it with two colleagues. Things I had not noticed while examining the code alone began to emerge as I worked through my thoughts in conversation. The moment someone asked “Why did you do it that way?” about a structural choice I had taken for granted, gaps in my reasoning that I had not recognized became visible.

It is true that AI is dramatically reducing the time required to write and review code. Even so, experiences like this are precisely why I believe code reviews and daily meetings remain important. AI can verify the consistency of code, but pointing out “Here is the perspective you missed” ultimately falls to colleagues who share the same context. Discovering what I could not see, then using that discovery to make the product more stable—is that not the essence of collaboration?

There is no single correct answer when writing code as part of solving a problem. Other participants who took the same mock exam followed different paths, each with their own rationale. What matters is being able to explain “why the code was written this way.” I encourage readers to look at their own code through the eyes of someone seeing it for the first time. That perspective may be the most powerful standard for determining code quality.

One of the articles that made the strongest impression on me as a junior was Hwidong Bae’s “Frontend Engineer Career Roadmap: Three Specialization Tracks for Juniors”. It organizes frontend engineering careers into three tracks—web specialization (Software Engineer), product specialization (Product Engineer), and operations specialization (Full-Stack Engineer)—and goes on to identify “five foundational capabilities of exceptional engineers” and “three keys to becoming a senior.” At the time, the biggest question was which capabilities to build for each track. Yet less than two years after I read it, the question itself has changed completely.

When I talk with fellow engineers these days, their concerns feel noticeably different from those I had been hearing over the past several years.

• “Our company adopted AI, and if we give it a design mockup, it builds almost everything. It’s convenient, but...”
• “The hiring market is brutally cold.”
• “I’m afraid to merge AI-generated code as is, but reviewing every line defeats the efficiency gains. I’m not sure what to do.”

I went through—and am still going through—a similar period. Just a year or two ago, I thought of AI as merely a useful assistant. Now, it is hard to imagine developing without it at all (I am also asking Claude to help with research as I write this). Think of this article as a sequel to Hwidong Bae’s piece: my attempt to describe how the landscape has changed since then and, from my own perspective, what additional capabilities frontend engineers need to develop within it.

Once again, I have tried to find and verify as many sources as possible. But because this field changes so quickly, some parts may already be outdated by the time this article is published. If you have a rebuttal or something worth discussing, please leave a comment anytime.

“Doesn’t AI Do Everything Now?”

There is one question we need to address first. Is the statement “AI does everything now” actually true? How much of it is reality, and where does the fantasy begin?

In February 2025, Andrej Karpathy, an OpenAI co-founder and former director of AI at Tesla, posted the following on Twitter.

There is a new kind of coding I call “vibe coding,” where you fully surrender to the vibes, embrace exponential growth, and even forget that the code itself exists.

There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes, embrace exponentials, and forget that the code even exists.

In short, vibe coding is “a way of coding where you hand the keyboard to AI and simply describe what you want in natural language.” There are no architecture documents, no boilerplate, and no hunting for semicolons. The code simply runs on vibes. In less than a year, the term became standard vocabulary in English-speaking developer communities.

Yet exactly one year later, in February 2026, the same Karpathy took a step back. He proposed replacing the term vibe coding with “agentic engineering.” The distinction is clear.

• Vibe coding: Describing what you want and accepting the result
• Agentic engineering: Designing the system, specifying constraints, and using AI to accelerate an implementation you have already reasoned through in your head

A year ago, the baseline assumption was, “Just tell it what to do and it will build everything.” Now, “the ability to design what to ask AI to do and how to ask it” has itself become an engineering capability. This shift is not merely one person’s tweet. Around the same time, Google engineer Addy Osmani published Beyond Vibe Coding: From Coder to AI-Era Developer, stating plainly: “AI is an assistant, not an autonomously trustworthy coder. You are the senior developer, and the LLM exists to accelerate your judgment.”

The Tools Are Racing Ahead

The tools are also evolving rapidly in step with this shift. As of May 2026, the most frequently discussed coding tools include Cursor, Claude Code, GitHub Copilot, Windsurf, v0 by Vercel, Bolt.new, and Devin.

The evolution of v0 is especially symbolic. Vercel uses the phrase “the 90% problem”, meaning that 90% of real-world development takes place within existing codebases and infrastructure. At first, v0 only needed to excel at greenfield prototypes. Now it can import a GitHub repository directly, work within it, enforce a design system, and automatically pull in deployment environment variables. In effect, toolmakers are directly answering senior engineers who ask, “Isn’t AI only good at making toy demos?”

Big Tech codebases illustrate this change most clearly.

Google’s Sundar Pichai announced during the Q3 2024 earnings call that “more than 25% of new code is generated by AI and then reviewed and accepted by engineers”, and said in April 2025 that the figure had risen above 30%. Microsoft’s Satya Nadella revealed at LlamaCon in April 2025 that “as much as 30% of our code is written by AI”. Meta’s internal target has risen as high as “by the first half of 2026, 65% of engineers will generate more than 75% of their commits with AI.”

The trend is no different in Korea. Toss built an AI-powered documentation system to improve developer experience so developers no longer have to search for documentation, and went a step further by exploring topics such as “What Happened When We Removed Designers in the AI Era”. Every Tuesday, Karrot shares team experiments through AI Show & Tell, and has begun using the recruiting slogan “Beyond Engineer, Become a Builder.” Woowa Brothers has published articles such as “In an Era When AI Writes Code, Do You Still Want to Become a Developer?”, arguing that “the essence of being a developer lies not in code, but in the ability to define and solve problems.”

But the Numbers Tell a Slightly Different Story

At this point, it is easy to conclude, “So now you can just tell AI what to do and everything works.” But the actual data tells a somewhat different story.

First, consider the figures from the 2025 Stack Overflow Developer Survey, a comprehensive analysis of the state of software development.

• 84% of developers said they use or plan to use AI tools, up from 76% in 2024.
• Among professional developers, 51% use AI tools every day.
• Yet positive sentiment toward AI tools actually declined. After exceeding 70% in both 2023 and 2024, it fell to 60% in 2025.
• Senior developers with more than ten years of experience have the lowest trust in AI output.

In short: “Everyone uses it, but the longer they do, the less they trust it.”

A 2025 experiment conducted by the nonprofit research institute METR revealed the gap between perception and reality even more dramatically. It was a controlled experiment in which 16 experienced open-source developers—averaging five years of experience and 1,500 commits—completed 246 tasks and were randomly assigned whether to use AI. The results were as follows.

• Before starting, the developers predicted that AI would make them 24% faster.
• Immediately after finishing, they still estimated that they had been about 20% faster.
• Actual measurements, however, showed that they were 19% slower.

The researchers’ explanation is revealing. The acceptance rate for AI-generated code was below 44%; rejected code still required time to review and test; and even accepted code demanded substantial review and revision. This gap—the illusion of feeling faster despite actually slowing down—is one reason senior developers are becoming increasingly skeptical of AI.

Nor is the quality of AI-generated code itself especially polished. Consider Veracode’s experiment in which more than 100 AI models were asked to write code.

• 45% of AI-generated code contained OWASP Top 10 security vulnerabilities.
• The failure rate for XSS (cross-site scripting) protection was 86%.
• The failure rate for log injection protection was 88%.
• Another study reported that the vulnerability density of AI code was 2.7 times higher than that of human-written code.

The 86% failure rate for XSS, in particular, deserves serious attention from frontend engineers. It shows exactly what it means to merge an AI-generated form input unchanged. (Developers with frontend security-audit experience feel uneasy and concerned even when they write dangerouslySetInnerHTML themselves; it feels even more frightening when AI quietly slips it in.)

The quality signals are similar elsewhere. GitClear analyzed 211 million lines of code changes made between 2020 and 2024 and found the following.

• Code churn—the share of code reverted within two weeks of being written: 5.5% in 2020 → 7.9% in 2024
• Share of changes devoted to refactoring: 25% in 2021 → below 10% in 2024
• Copy-and-paste (clone) rate: 8.3% in 2021 → 12.3% in 2024 (and an astonishing fourfold increase in 2025)

The interpretation is not difficult. Our ability to produce code quickly has increased, while our ability to produce code worth refining has declined. Apiiro’s data from Fortune 50 companies is even more striking. AI-assisted developers produce three to four times as many commits as their peers, but also ten times as many security findings. Privilege-escalation paths rose by 322%, while architectural design flaws surged by 153%.

What AI Has Replaced—and What It Has Not

The tools are racing ahead, yet the numbers are nuanced. So what exactly has AI replaced, and what has it not yet replaced? We need a clear distinction to understand where to invest our time.

What AI has replaced is a large share of developers’ manual typing. We spend less time writing boilerplate and repetitive code; given a design mockup, a screen that follows the conventions can appear within minutes; and the time spent searching for syntax and APIs, as well as the learning curve, has fallen sharply. In short, AI has flattened the speed of production.

But it has not yet replaced the domain of “judgment.” (More precisely, it has “not yet met our expectations.” People differ in their ability to use AI, but this discussion is based on the average user experience.)

The first sticking point is translating requirements into specifications. Turning ambiguous business requirements into precise edge cases and state machines still requires deeper human involvement. The same is true of understanding system-wide impact. Questions such as how a component affects the bundle, whether a dependency can be tree-shaken, or how a data-fetching pattern affects the Core Web Vitals metric INP (Interaction to Next Paint) may receive plausible answers from AI, but a human still needs to examine them before we can feel confident.

We also cannot omit security and risk assessment, as illustrated by the 45% OWASP vulnerability rate above. The same applies to maintaining the design system and consistency—checking whether a new component aligns with the existing system’s tokens, accessibility rules, and interaction patterns—and to understanding customer and market context, such as why a feature is needed and where it belongs in the user flow.

Finally, borrowing a phrase from yceffort’s article, managing cognitive debt—the “gap between a system’s complexity and the degree to which the team understands that system”—has actually become a faster-growing concern since AI adoption. Closing that gap remains a human responsibility.

Developers are not disappearing; the form of developers’ work is changing. The bottleneck has shifted from “the speed of building” to “the speed of deciding.”

In the same vein, Toss’s “Will AI Replace Developers?” offers a weightier diagnosis. Its central point is this: AI is not replacing the entire workforce; it is removing the apprenticeship ladder. Ten or twenty years from now, when today’s senior engineers retire, there may be too few people in the next generation capable of designing complex systems. This is not merely a question of “what will our company do about hiring next year?” It is a delayed-action bomb for the entire industry. (I think it is an exceptionally well-written article for a time when so many of us are wrestling with these questions.)

The “first version that works” produced by AI is 70%. The remaining 30%—getting it to “a version safe to serve to real users”—belongs to humans. And the ability to fill that 30% does not appear overnight. This is the essence of the apprenticeship-ladder problem. If the time spent “getting your hands dirty” writing boilerplate and simple components disappears, so do the people who will eventually be able to fill that 30%.

Hwidong Bae’s original article named writing good code, maximizing present value (balancing fast delivery with long-term maintainability), making data-driven decisions, helping colleagues make effective decisions, and learning continuously as the “five foundational capabilities of exceptional engineers.” All five remain relevant in the AI era, but the last is in the most precarious position. Learning itself has not disappeared; its subject has changed. Where we once learned “how do I use this tool?”, we now need to spend time learning “how does this entire system work?” More troubling still is the problem Evan Moon identifies: “the moment AI takes over code writing, the brain’s cognitive load drops dramatically.” Reduced cognitive load sounds appealing, but it is dangerous because that load was the very material from which learning emerged. The more comfortable it gets, the less you grow.

This naturally raises a question. Do the three tracks in Hwidong Bae’s article—web specialization, product specialization, and operations specialization—no longer matter?

I see it differently. The tracks themselves remain valid. It is more accurate to say that each has evolved by one stage for the AI era. Let us examine how the landscape has changed for each one.

From Producer to “Verifier”

In Hwidong Bae’s original article, the web specialization track was grouped under the title Software Engineer. Its core capabilities were “a deep understanding and practical command of the internet, web browsers, and HTML/CSS/JS,” familiarity with the trade-offs of web ecosystem tools, troubleshooting experience, and sensitivity to emerging technologies. The suggested senior paths were engineer at a web tooling company, frontend educator, or tech lead in a complex product organization. In short, these were “people who dig deeply into how browsers and HTML/CSS/JS work,” and until a year or two ago, their greatest advantage was that “they could write correct code more accurately than anyone else.”

How has their value changed in the AI era? In terms of coding speed alone, AI has caught up. Yet the ability to accurately evaluate AI-generated code has become something they almost uniquely possess.

• Non-developer using AI: It implemented my requirements, and it works correctly.
• Developer using AI: It works, but this dependency could cause certain problems, and improving this pattern in this way would better fit our conventions. Let’s examine the related areas again.

The Veracode study discussed earlier found failure rates of 86% for XSS and 88% for log injection. Experts like us are the people capable of finding and fixing those failures. They naturally evolve into senior quality-assurance roles for AI output.

There is another development: an entirely new topic has entered the expert domain—Generative UI and AI interface design. Examples include chat UIs that render LLM responses as they stream, abort controls that let users stop generation midway, progressive rendering of Markdown and code blocks, UX that displays tool-call results inline, and assistant integrations using the Vercel AI SDK or MCP (Model Context Protocol). Demand is exploding for people who “understand precisely how the web works while also understanding the behavioral characteristics of LLMs and knowing how to apply them.”

The Natural Evolution into a Product Engineer

The product specialization track has benefited the most. People who understand markets and customers well and communicate frequently with external stakeholders gained a far more powerful tool the moment AI entered the picture. Another hallmark of this track was that its suggested senior paths included expansion into other roles, such as growth engineer or consultant, or a transition to PM, PO, or CPO.

An interesting change is that the track’s name has begun to establish itself as a global standard. The original article already called it “Product Engineer,” but when I first read it, the term still felt somewhat unfamiliar. A year later, it has become established enough that Vercel renamed every “Fullstack Engineer” role in its job descriptions to “Product Engineer”.

Lee Robinson identifies three core qualities of a Product Engineer.

• Iteration-mindedness: Moving quickly through the deploy → feedback → adjustment cycle.
• Customer centricity: Improving the product by speaking directly with customers.
• Pragmatism: “Every technology choice is merely a means to an end.” Tools that do not advance the product goal are discarded without hesitation.

There is one trap here: it is dangerous when product-focused engineers are perceived merely as “people who build quickly.” With the arrival of AI, that danger has grown. “Shipping features fast” is now something people in virtually any role can do with AI tools. A Product Engineer’s differentiator is “the ability to define the customer’s problem accurately and validate it quickly with the smallest possible solution,” not “having fast hands.”

Within this trend, Design Engineer has begun to rise into a formal role. Vercel is hiring design engineers as a formal career track with compensation above $200K, and Linear and Stripe are moving in similar directions. The role eliminates the handoff between frontend and design itself. Because AI can draw quickly, the combined ability to decide “what to draw” and determine “whether the result fits a consistent design system” has become even scarcer.

AI Orchestrator

The operations specialization track is changing most dramatically. Hwidong Bae’s original article classified this track as Full-Stack Engineer, defining it as “someone deeply interested in project structure, integration, testing, and deployment; someone who can handle simple APIs and infrastructure directly, fill gaps in the organization, and improve processes.” Over the past year or two, the role of operating AI agents themselves has been added on top, rapidly expanding the track’s scope.

In a review of 2026 trends, “Orchestrating Coding Agents” was identified as a central concept. It means going beyond assigning work to one AI and instead designing and operating a system in which multiple AI agents collaborate simultaneously. In the same vein, the “agent-skills” framework was proposed, along with the idea of encoding professional workflows, quality gates, and industry best practices directly into agent behavior.

After reviewing the related material, these are the new keywords I believe engineers in the operations track need to work with.

• MCP (Model Context Protocol): Anthropic’s proposed standard for connecting LLMs with external tools
• AI governance: Managing who can use AI, with what context, and whether secrets can leak
• Agent evaluation: Pipelines that automatically score the output produced by agents
• AI gates: Automated security and quality verification before PR merges, plus labeling for AI-generated code

The original article named roles such as platform team engineer in a large organization, tech lead, agile coach, technical program manager (TPM), and CTO as senior paths for the operations track. Those paths remain valid, but new roles such as “AI development infrastructure lead” and “developer productivity (DevProd) engineer” have now been added.

While the three tracks are each evolving, there are also capabilities that have become more important across all of them. I originally wanted to think in terms of five years from now, but at today’s pace of progress, even a year feels like too large a unit. So I will narrow the horizon to “next year” and identify the capabilities I expect to become more important.

Five Capabilities

The first is the ability to write specifications. In the AI era, the “starting point of coding” is not the keyboard but the specification. The ability to state precisely what AI should do has become more important than the code itself. A specification here does not mean a grand RFC document. It can be tests that express the expected behavior of business logic in code, Storybook stories that define a UI component’s scenarios and visual contract, or type definitions that specify the contract for data flow. Ultimately, the work is about establishing in advance the criteria that will automatically verify AI-generated output. If AI coding proceeds without those criteria, problems accumulate.

The second is verification and judgment. AI confidently produces code that looks plausible but is wrong. That is why I believe “the ability to review AI-generated code quickly and accurately” is itself a core capability. It means determining whether security headers, input sanitization, or CSRF tokens are missing; whether accessibility—ARIA, keyboard navigation, and focus traps—remains intact; and whether there are performance issues involving rendering cost, memory, or bundle size. Throwing AI slop into a PR without review is a dereliction of an engineer’s duty. A human still clicks the merge button, and that responsibility cannot be shifted onto AI. Senior developers may have the lowest trust in AI in the Stack Overflow survey precisely because they have the eye to catch these details.

The third is system understanding and architectural thinking. AI handles one file at a time well and has strong awareness of flows and relationships. AI fixes symptoms quickly, but highly capable developers find root causes. One way to build this capability is through deliberate practices such as Architecture Retrospectives. As the rate of code change accelerates, cognitive debt will accumulate quickly unless the team deliberately raises its understanding of the system as well.

The fourth is AI orchestration. The ability to work with AI is separating into its own skill set. This is no longer simply about writing good prompts. It now encompasses the ability to break work into small tickets, choose which model to use for a given task, design agent evaluation and verification pipelines, and define recovery strategies—including rollback—when an agent fails. Steve Yegge describes this progression as six waves (traditional → completions → chat → coding agents → agent clusters → agent fleets).

The fifth is Context Engineering. Promoted since mid-2025 by Karpathy and Shopify CEO Tobi Lütke, it can be summarized as “the ability to design what context to show AI, in what form, and how much of it.” In practice, it takes forms such as maintaining CLAUDE.md / rules files that place project conventions, architectural principles, and prohibitions within AI’s reach; deliberately reducing context by selecting only relevant modules instead of loading every file; explicitly separating phases—planning → implementation → verification—into different sessions to prevent context contamination; and supplying external context through MCP, connecting design systems, API schemas, monitoring data, and other resources through standard interfaces. Anthropic’s official documentation calls this “the new prompt engineering” and states plainly that a single prompt can never contain a system’s architectural knowledge, patterns, and tribal wisdom. Put differently, “designing an environment where AI consistently receives good context” has become far more important than “writing one good prompt.”

If you have read this far, a natural question follows: how, specifically, should we study? I use roughly four approaches.

How to Learn

The “continuous learning” item from the original article remains valid, but we need to allocate our learning time differently.

There are areas where we once spent a great deal of time but can now spend less. By contrast, there are complex areas that we may have avoided because they were difficult or time-consuming. The latter include writing test specifications, using performance measurement tools (Lighthouse, WebPageTest, Chrome DevTools Performance), accessibility (WCAG), and security—especially the OWASP Top 10. There are also entirely new areas to learn, including the Vercel AI SDK, LangChain.js, MCP, streaming UI patterns, and agent evaluation pipelines. It is important to recognize which capabilities you need and allocate your time accordingly.

AI-generated code tends to grow large. It can produce hundreds of lines in a minute. Unless we deliberately manage PR size and merge cadence, code review itself breaks down. Within companies, average PR size rose 18%, incidents per PR rose 24%, and the change failure rate rose 30% after AI adoption. Viewed alongside the data discussed earlier, this shows why it is important to subdivide work: writing a large change and merging it all at once makes it difficult to understand the flow and preserve intent.

There is a practice directly related to the reduced cognitive-load problem identified in Evan Moon’s article: it is worth setting aside one or two hours a day to write code without AI. Drawing an architecture by hand or reading through code in an unfamiliar area one line at a time are examples. (I also write code without AI during the drowsy period after lunch each day. It is time I use to keep from drifting too far from old, familiar habits.)

This is not merely about “avoiding forgetting the old way.” Your own depth does not grow during the time AI does the work for you. Capabilities such as verification, judgment, and system understanding are functions of the time you spend confronting problems directly.

So, Where Does That Leave Us?

I have written at length, but the image of a frontend engineer who survives the AI era is not actually so different from the conclusion of the original article. It identified three qualities of a good senior engineer.

• They strive to stay grounded in the fundamentals. (Continuously maintaining and strengthening the five foundational capabilities.)
• Even without being the designated leader, they exert natural influence through exemplary behavior.
• They do not settle for completing the task in front of them; they examine the broader context and create greater impact.

Applied to the AI era, that becomes the following.

• Stay grounded in the fundamentals beyond AI-generated code: the web, systems, and the domain.
• Set the direction yourself, not AI. Even when you are not the designated owner, decide “where we should go.”
• Use AI not merely as a personal productivity tool, but to remove bottlenecks in the team and the system.

Looking at the writing of Andrej Karpathy, an authority on OpenAI, the core of the “agentic engineering” he now emphasizes is ultimately the same: design the system, specify the constraints, and use AI to accelerate an implementation you have already reasoned through in your head. The tools may change, but the directional controls remain in human hands.

The original article’s closing message was likewise that the person who becomes a senior is someone who “does not settle for completing the assigned work well, but examines the surrounding context and creates greater impact.” In the AI era, only the definition of that “impact” has changed. One person merges a screen AI built in an hour because “it works.” Another spends thirty more minutes examining how reasonable it is in terms of accessibility, security, performance, and system consistency. A year later, it is the latter who will be recognized as a senior. The people who survive will be those who stand on the 30% side of the boundary between 70% (functionality) and 30% (application and effective use).

I hope the frontend engineers reading this leave with their own answer to the question, “What should I study next?” No one knows the definitive answer, but I am quite confident that the more AI writes our code, the more the people who can see “what lies beyond the code” will survive. I will close with the hope that, a year from now, I can write again about how this landscape has changed.

(If this article feels painfully obvious or outdated a year from now, perhaps that will mean we responded well enough.)

References

As a frontend developer, I have wrestled countless times with questions like, “How much of this logic should I separate?” and “At what level should I break up this component?” At first, I thought abstraction simply meant extracting what different pieces had in common: turning repeated code into a function, or identifying the commonalities among similar components and combining them into one. But after watching code built this way turn into a monster that became harder to touch over time on several occasions, I began to rethink what abstraction really is.

In this article, I want to organize the thoughts I have developed about the essence of abstraction and how we can use it in frontend development to create good code.

Abstract and Abstraction

Before getting into the main discussion, I want to clarify exactly what the words “abstract” and “abstraction” mean in programming. They may look similar, but they are quite different in nature.

Abstract is a state and a property. When we say, “This is abstract,” we mean that concrete details have been omitted, leaving only the essential concept. Classes or methods marked with the abstract keyword in Java or TypeScript carry precisely this meaning. They are incomplete blueprints that define only the essential form, before the concrete implementation has been filled in.

Abstraction is a process and an act. It is the process of simplifying something complex by retaining only its essential characteristics and removing unnecessary details. Crucially, abstraction is not about “roughly lumping things together”; it is the act of defining roles precisely at each level.

In everyday language, “abstract” often carries the nuance of “vague.” In programming, however, abstraction is the exact opposite. Its purpose is not to make things vague, but to create a new level of meaning that can be absolutely precise. The essence of abstraction is preserving information relevant to a given context and forgetting what is irrelevant.

Ultimately, the distinction between abstract and abstraction can be understood like this: the abstract is “a state in which only the essence remains,” while abstraction is “the process of leaving only the essence.” What we do when designing code is precisely this process of abstraction: retaining only the essential interface from a complex implementation and hiding the rest.

Then why do we need abstraction in programming?

Why Do We Need Abstraction?

The fundamental reason abstraction is necessary in programming is surprisingly simple: to build more complex things. When we try to build something more complex, there are too many complex elements to remember and manage all at once. So we group those elements and turn them into simplified, abstract concepts.

Consider React, which frontend developers use every day. Rendering a single component internally involves complex processes such as creating the Virtual DOM, reconciliation, and manipulating the actual DOM. Yet we can write JSX without worrying about any of that, because React abstracts those complex processes away for us.

Look at the code below. When using the UserProfile component, we can build and work with the UI perfectly well without knowing about the complex processes happening internally, such as VDOM creation and diffing.

<UserProfile name="jihoon" />

Configuring Webpack directly used to be part of a frontend developer’s daily life, but frameworks such as Next.js and Vite have since abstracted away bundler configuration. As a result, we can develop applications without knowing the bundler’s inner workings and use that time to focus on higher-level problems such as business logic and user experience. (This is why I believe the concept of abstraction is extremely important to the role of a frontend developer.)

This, ultimately, is the core value of abstraction: hiding complexity so that it appears simple and allowing each of us to focus only on our own domain. Thanks to it, we can build increasingly large and complex software without having to understand everything ourselves.

If abstraction is so beneficial, then is more abstraction always better? Let us consider what purpose abstraction should serve.

Reducing Context

Many developers understand abstraction as “extracting the common parts.” That is not wrong, but it is only one technique for performing abstraction; it does not explain abstraction’s essence.

To me, the essence of abstraction is “reducing the context a reader needs to know to an appropriate level.”

Let us look at a simple example.

interface Order {
  id: string;
  status: "pending" | "completed";
  amount: number;
}
 
let total = 0;
 
const orders: Order[] = [
  { id: "a", status: "pending", amount: 10000 },
  { id: "b", status: "completed", amount: 5000 },
  { id: "c", status: "completed", amount: 8000 },
];
 
for (let i = 0; i < orders.length; i++) {
  if (orders[i].status === "completed") {
    total += orders[i].amount;
  }
}

A developer reading this code has to understand the loop’s initialization, condition, and increment; follow element access by index; inspect the conditional branch; and keep track of how the external accumulator is updated. What the code is actually trying to do can be expressed in one sentence—“calculate the total of the completed orders”—yet understanding that sentence requires holding four different contexts in mind at once.

const total = orders
  .filter((order) => order.status === "completed")
  .reduce((sum, order) => sum + order.amount, 0);

Thanks to the abstractions filter and reduce, the developer only needs to follow two intentions: “select only completed orders” and “accumulate their amounts.” The context of index management and the declaration and updating of an accumulator disappears from the surface of the code.

We can take this one step further.

const total = sumCompletedOrders(orders);

Now the reader does not even need to know that the calculation is performed by traversing an array. All that remains is the business intent: “calculate the total amount of completed orders.” The code lets us focus not on how the calculation is performed, but on what is being calculated.

From this perspective, we can see that the React code we write every day is itself a composition of countless abstractions.

import { css } from "@emotion/css";
import { format } from "date-fns";
 
const TodayHeader = () => {
  const now = new Date(); // Date 객체 생성이라는 복잡한 과정을 추상화
  const formatted = format(now, "yyyy-MM-dd"); // 날짜 포맷팅 로직을 추상화
 
  return (
    <h1
      className={css`
        font-size: 1.8rem;
      `}
    >
      {/* CSS-in-JS 처리 과정을 추상화 */}
      Today is {formatted}
    </h1> // React.createElement를 추상화
  );
};
 
// 그리고 위 모든 것을 다시 추상화
<TodayHeader />;

What if all the internal code of emotion, date-fns, and react were expanded directly inside this component file? It would be difficult to know where to begin reading or distinguish the business logic from the library code. Because abstraction hides the context of each domain at an appropriate level, we can focus solely on the essential purpose: “show today’s date.”

Then how should we approach abstraction when designing actual code?

What It Means for a Level of Abstraction to Be High or Low

Any discussion of abstraction must include the concept of the Level of Abstraction. What exactly does it mean for code’s level of abstraction to be “high” or “low”?

Code at a low level of abstraction is close to the concrete procedures performed by the computer: parsing strings directly, iterating through arrays by index, manipulating bytes. It openly exposes how it works.

// 추상화 수준이 낮은 코드
const response = await fetch('/api/users');
const users = await response.json();
const filteredUsers = users.filter(user => user.status === 'active');
 
filteredUsers.forEach(user => {
  const element = document.getElementById(`user-${user.id}`);
  if (element) element.style.display = 'block';
});

Code at a high level of abstraction is expressed in the language of the business domain or problem space. Examples include processPayment(order), sendNotification(user, message), and validateUserInput(formData). High-level code reveals what it does while hiding how it does it.

In Clean Code, Robert C. Martin summarized this idea as the principle of “One Level of Abstraction per Function.” When high-level and low-level code are mixed within one function, the reader must decide at every line, “Is this core logic, or is it an implementation detail?”

The problem becomes clear in actual code.

// 추상화 수준이 뒤섞인 함수
async function registerUser(name: string, email: string, password: string) {
  // ✅ 높은 수준: 비즈니스 규칙 검증
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  // ❌ 낮은 수준: 비밀번호 해싱 직접 구현
  const encoder = new TextEncoder();
  const data = encoder.encode(password);
  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
  const hashedPassword = Array.from(new Uint8Array(hashBuffer))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
 
  // ✅ 높은 수준: 사용자 저장
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  // ❌ 낮은 수준: 이메일 전송 직접 구현
  const verifyToken = crypto.randomBytes(32).toString("hex");
  await db.execute(
    "INSERT INTO email_tokens (user_id, token, expires_at) VALUES (?, ?, ?)",
    [user.id, verifyToken, new Date(Date.now() + 86_400_000)]
  );
  await transporter.sendMail({
    from: "noreply@example.com",
    to: user.email,
    subject: "Welcome! Please verify your email",
    html: `<a href="/verify?token=${verifyToken}">Verify your account</a>`,
  });
 
  // ✅ 높은 수준: 환영 이메일 발송
  await sendWelcomeEmail(user);
}

The reader of this function begins by following the high-level, business-rule context of the “user registration flow,” only to be abruptly dragged down into the low-level contexts of hash buffer manipulation, SQL queries, and email template strings. Then the code jumps back up to the high-level sendWelcomeEmail. When the level of abstraction keeps rising and falling like this, the reader’s mind has to rise and fall with it.

If we rewrite the same function so that its level of abstraction is consistent, it looks like this.

// 추상화 수준이 일관된 함수
async function registerUser(name: string, email: string, password: string) {
  validateUserInput({ name, email, password });
  await ensureEmailNotDuplicated(email);
 
  const hashedPassword = await hashPassword(password);
  const user = await userRepository.save({ name, email, password: hashedPassword });
 
  await sendVerificationEmail(user);
  await sendWelcomeEmail(user);
}

Every statement speaks at the same level of abstraction. How email delivery is implemented and which algorithm password hashing uses are the responsibilities of their respective lower-level functions. The reader of this function only needs to focus on a single context: the overall user registration flow.

Martin also called this “The Stepdown Rule.” When code is read from top to bottom, it should resemble a newspaper article: the big picture appears at the top, and the details emerge as the reader moves downward.

Kent Beck presented the same principle as the Composed Method pattern in Smalltalk Best Practice Patterns. A method should consist only of operations at the same level of abstraction, and each step should be expressed as a one-line method call.

All of this ultimately leads to one conclusion: a function should speak at only one level of abstraction. Following this principle alone makes a noticeable difference in readability.

Then which direction should abstraction take? Should we begin with the concrete or with the abstract?

Think in Terms of Assembling Parts, Not Extracting Commonalities

OOP commonly offers the guideline, “Extract the commonalities among concrete things to define something abstract.” The approach itself is not wrong, but I believe adhering to it too rigidly risks producing a design trapped by the current requirements.

Consider an example. Suppose the requirements call for buttons A, B, and C. All three are blue and rounded; the only difference is their label text. A design based solely on extracting their commonalities might look like this.

const BlueRoundButton = ({ label }: { label: string }) => {
  return <button className="blue round">{label}</button>;
};

This perfectly satisfies the current requirements. But a few days later, the product manager says:

“Please make it possible to change the color of button B.”

At that point, even the name BlueRoundButton becomes awkward. We could add a color prop, but the design was vulnerable to change from the outset because it began with the concrete commonality of “a blue rounded button.” (And this is a mild example. In reality, countless requests arrive about the button’s shape, size, and everything else.)

After this happens repeatedly, one thing becomes clear: when we extract commonalities from concrete requirements, even the resulting abstraction tends to reflect only the requirements that exist right now.

That is why I prefer the opposite direction. Instead of extracting abstractions from concrete things, I prefer to think of abstract parts first and assemble them into concrete things.

Imagine building a toast notification component. The initial requirement is simple: “When saving is complete, display a short message at the bottom.” An approach based on extracting commonalities would look like this.

// 현재 요구사항의 공통 특성에서 출발한 설계
type ToastProps = {
  message: string;
  hasAction?: boolean;
  actionLabel?: string;
  onAction?: () => void;
};
 
const Toast = ({ message, hasAction, actionLabel, onAction }: ToastProps) => (
  <div className="toast">
    <span>{message}</span>
    {hasAction && <button onClick={onAction}>{actionLabel}</button>}
  </div>
);

The current requirement is handled perfectly. But a few days later, the product manager says, “Add an icon on the left depending on whether it is a success or a warning.” hasIcon and iconName are added. Soon another request arrives: “We also need a toast with an upload progress bar.” Another progress prop is added. After repeating this a few times, Toast ends up with more than ten props and hidden rules about which combinations are valid and which are not that developers must memorize. (And those rules are usually not documented even in comments.)

The design was vulnerable to change because it began with a concrete, present-day image of “what a toast should look like.”

The story changes when we approach it as an assembly of parts.

// 부품을 조립하는 설계
const Toast = ({ children }: PropsWithChildren) => (
  <div className="toast">{children}</div>
);
 
Toast.Icon = ({ name }: { name: "check" | "warn" | "info" }) => {
  /* ... */
};
 
Toast.Message = ({ children }: PropsWithChildren) => <span>{children}</span>;
 
Toast.Action = ({
  children,
  onClick,
}: PropsWithChildren<{ onClick: () => void }>) => (
  <button onClick={onClick}>{children}</button>
);
 
Toast.Progress = ({ value }: { value: number }) => {
  /* ... */
};
 
// 필요한 부품만 골라 조립한다
<Toast>
  <Toast.Message>저장되었습니다</Toast.Message>
</Toast>;
 
<Toast>
  <Toast.Icon name="check" />
  <Toast.Message>업로드 완료</Toast.Message>
  <Toast.Action onClick={undo}>실행 취소</Toast.Action>
</Toast>;
 
<Toast>
  <Toast.Progress value={0.4} />
  <Toast.Message>파일 전송 중...</Toast.Message>
</Toast>;

The stable essence—“a toast is a shallow container that holds something”—is now separated from the changeable concrete detail of “what it contains.” We can add as many new parts as we like, or arrange existing parts in new combinations, without touching Toast itself. The validity rules for prop combinations also disappear. We simply put in what we want to put in.

Of course, an experienced developer might say, “Couldn’t we just design it with IoC (Inversion of Control) from the beginning?” That is true. But such judgment is possible because countless past mistakes have cultivated an intuition for which parts are likely to change.

When that intuition is not yet well developed, beginning with the question, “What parts make up this feature, and how should those parts be assembled?” makes it much easier to create a design that is open to change.

At this point, a natural question arises: by what criteria should we divide the parts, and how should we present them externally?

Three Principles for Good Abstraction

Think Carefully About Expression

The most important virtue of an abstracted module is that its behavior should be inferable without opening its source code. Kent Beck called this the “Intention-Revealing Name” pattern and argued that if an abstraction cannot be given a concise name, the abstraction itself should be reconsidered.

Broadly speaking, we have two tools for achieving this: names and types.

// 도대체 뭘 하는 건지 알 수 없는 함수
function calculate(price: number, rate: number): number;
 
// 이름과 타입만으로 동작을 유추할 수 있는 함수
function calculateDiscountedPrice(originalPrice: number, discountRate: number): number;

From the name alone, calculateDiscountedPrice tells us that it takes an original price and a discount rate and calculates the discounted price, while the type information supports this by showing that it accepts number values and returns a number. We do not need to know which calculation logic is applied internally.

By contrast, calculate(price: number, rate: number): number gives us no information about what is being calculated, so we cannot anticipate the result. We can only use it after opening the source code, which forfeits the benefit of abstraction.

It is worth noting that naming itself reflects the level of abstraction. Function names in programming generally take the form verb + noun, and the verb we choose reveals the level of abstraction at which the function operates.

A verb alone does not determine the level of abstraction. The noun that accompanies it—the domain context—determines the final level.

Certain verbs often appear at a low level of abstraction: parse, encode, decode, serialize, read, write, push, pop, convert, and transform. These words imply physical transformations of data or direct manipulation of data structures.

At the middle level, verbs such as get, save, load, and validate appear. They describe technical operations while revealing their intent to some degree.

At a high level of abstraction, verbs such as register, refund, confirm, cancel, and submit are used. These words belong to the language of the business domain. They reveal nothing about the technical procedures happening internally and express only a user action or business process.

// 낮은 수준: 기술적 동작이 드러남
function parseJSON(text: string): object;
function encodeBase64(data: Uint8Array): string;
 
// 중간 수준: 의도가 드러나되 기술적 맥락이 남아있음
function getUserById(id: string): Promise<User>;
function validateEmail(email: string): boolean;
 
// 높은 수준: 비즈니스 의도만 드러남
function registerUser(form: RegistrationForm): Promise<User>;
function refundPayment(orderId: OrderId, amount: Money): Promise<Refund>;

In Clean Code, Robert C. Martin wrote that “a long descriptive name is better than a short enigmatic name.” He also proposed the principle “pick one word per concept.” If fetch, retrieve, and get are mixed for operations in the same context, the reader is left wondering, “Do these three do different things?”

The same principle applies directly to naming React components and hooks.

<Button />           
<SearchInput />      
<SubmitOrderButton />

The specificity of a component’s name varies with its level of abstraction. Button is a general-purpose UI primitive at a lower level, whereas SubmitOrderButton clearly expresses business intent at a higher level.

const handleSubmit = async(data: FormData) => { 
  await registerUser(data);
};
 
<Form onSubmit={handleSubmit} />           

on* is the name of the prop a component exposes externally. It lets the component’s consumer declare which event to respond to. handle* is the name of the implementation function actually passed to that prop.

const user = useAuth();                  
const [items, setItems] = useCartItems();
const { isOpen, toggle } = useModal();   

Custom hooks use the use prefix to follow React’s rules and make the state or behavior they provide available to components.

Jeff Atwood, who runs Coding Horror, once pointed out the problem with the Manager suffix. A name like UrlManager tells us nothing about whether it pools, validates, or creates URLs. Names that reveal a specific role—such as UrlBuilder, UrlValidator, or UrlPool—are far better. An ambiguous name can be a sign that the module’s responsibility itself is ambiguous.

Ultimately, a good name is one that immediately tells the reader the level of abstraction at which the code operates.

Deliberately Design the Degree of Input Freedom

One question arises frequently when designing an abstracted module: “How much functionality should we expose?” This decision has a major impact on the experience of developers who use the module.

// 기능이 닫힌 컴포넌트
const Button = ({ children }: {children?: React.ReactNode}) => {
  return <button>{children}</button>;
};
 
// 기능이 완전히 열린 컴포넌트
const Button = (props: ComponentProps<"button">) => {
  return <button {...props} />;
};

The first button can accept only children. It cannot be given onClick, type, or disabled. In return, its users have nothing to deliberate over.

The second button can accept every attribute of the button element. It offers a high degree of freedom, but its users must decide which of dozens of props they should use. I describe this situation as “the component forcing developers to deliberate.”

There is no single correct answer. The appropriate level depends on the module’s purpose and its users. For a design system’s base button, restricting Props may be better for maintaining consistency. For a general-purpose utility component, keeping the interface flexible may be preferable.

// 지나치게 닫힌 인터페이스 — 다양한 상황에 대응 불가
<Button onClick={handleSubmit}>제출</Button>
// onClick 외의 이벤트, className, disabled 등을 전달할 방법이 없다
 
// 지나치게 열린 인터페이스 — 의도가 사라짐
<Button {...anyProps} />
// 무엇을 전달해야 하는지 사용자가 직접 파악해야 한다

The breadth of an abstraction should be determined by who its users are. A low-level interface is appropriate for users who need to understand and finely control the internal implementation. On the other hand, giving an overly open interface to users who should not need to know the details only adds confusion. Conversely, restricting inputs too heavily for users who must handle varied situations can make the module unusable in the first place.

Keep the Unit of Abstraction Appropriate

The unit of abstraction—how much to group into a single module—is another important consideration.

One common frontend antipattern is the over-extraction of Custom Hooks.

// 이 훅은 단 하나의 컴포넌트에서만 사용된다
const useUserProfileData = () => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    fetchUser()
      .then(setUser)
      .finally(() => setLoading(false));
  }, []);
 
  return { user, loading };
};

If logic used by only one component is separated into a hook unnecessarily, the reader has to move back and forth between two files to understand the context. Instead of reducing context, the abstraction has increased it.

The reverse is also a problem: putting too much into a single hook.

// 관련 없는 관심사가 하나의 훅에 뒤섞여 있다
const useEverything = () => {
  const auth = useAuth();
  const theme = useTheme();
  const analytics = useAnalytics();
  const toast = useToast();
 
  return { auth, theme, analytics, toast };
};

This kind of “God Hook” is difficult to test, and changing one thing can affect unrelated parts.

The criterion for choosing the right unit of abstraction is “Does this separation actually reduce the context required by the reader?” If separating the code instead scatters the context and makes it harder to understand, the time for that abstraction has not yet come.

Beware of Premature Abstraction

After reading this far, one question may remain: “So when should we abstract?” My view is this: our default premise should be not to abstract prematurely.

Unless there is a clear signal for abstraction, leaving code as it is gives us a better worst-case outcome than creating the wrong abstraction and later having to unravel it. The process by which a bad abstraction emerges tends to look like this.

1. A similar pattern appears in code A and code B.
2. We think, “The DRY principle says I should extract this into a shared function!” and abstract it.
3. A similar pattern appears in code C, so we use the same function but add one parameter to accommodate slightly different behavior.
4. As code D and E begin using it as well, conditionals and parameters continue to accumulate.
5. The function is now used everywhere, yet everyone is afraid to touch it.

// 처음에는 단순했던 함수가...
const formatUserName = (user: User) => `${user.firstName} ${user.lastName}`;
 
// 요구사항이 추가될 때마다 매개변수가 늘어나고...
const formatUserName = (
  user: User,
  includeMiddleName?: boolean,
  format?: "full" | "short" | "initials",
  locale?: string,
  honorific?: boolean,
) => {
  if (format === "initials") {
    /* ... */
  }
  if (includeMiddleName && user.middleName) {
    /* ... */
  }
  if (honorific && locale === "ko") {
    /* ... */
  }
  // ...끝없는 분기
};

If we find ourselves in this situation, the solution is clear. Inline the abstracted code back into each call site, remove the unnecessary code from each one, and then, from that clean state, abstract again only if a genuine commonality becomes visible. “The fastest way forward is to go back.”

Then when should we abstract? In my experience, the signals for abstraction look roughly like these.

• Consistency is breaking down. The same logic is inline in one component and separated into its own function in another. The same calculation is scattered throughout the codebase.
• The internal structure is being exposed externally without need. The caller is forced to manage implementation details it has no reason to know.
• A module keeps exposing its own procedure. It fails to hide its internal steps, forcing consumers to follow those steps themselves.

The problem is that while detecting these signals is generally straightforward, in practice, it is easy to ignore them and focus on satisfying more “important” requirements. Under deadline pressure or absorbed in implementing a feature, we tell ourselves, “It works for now; I’ll clean it up later,” and later rarely comes.

Another crucial point is to maintain consistent criteria for abstraction. If the same kind of logic is inline in one part of the codebase, extracted into a function in another, and separated into a custom hook somewhere else, a new reader will wonder, “Is there an intentional reason for these differences?” Whether a team chooses to abstract or not, its criteria must be consistent.

Joel Spolsky’s “Law of Leaky Abstractions,” proposed in 2002, is also worth remembering in this context. The law says that abstractions attempt to hide complex implementations, but the details of those implementations eventually leak out. In other words, even when an abstraction is designed so that its users should not need to know the internal implementation, situations arise in which they must understand it to use the abstraction correctly.

TCP abstracts an unreliable network so that it appears to be a reliable connection, but when a cable is disconnected, the abstraction breaks. React abstracts UI updates declaratively, but optimizing rerenders ultimately requires understanding its internal behavior. Because no abstraction is perfect, we must ask when creating one: “Can users respond when this abstraction breaks?”

Ultimately, “Abstractions save us time working; they do not save us time learning.”

Abstraction Is Something We Internalize

I once discussed abstraction with a colleague, and something from that conversation stayed with me: detecting the signals for abstraction and separating code at the right time and at the right level are ultimately matters of intuition.

The principles discussed earlier—keeping levels of abstraction consistent, choosing good names, and designing the degree of input freedom—are certainly important. But trying to recall each principle and consciously weigh “Should I separate this or not?” at the very moment we write code can instead disrupt our flow. Just as consciously thinking about the angle of your elbow while throwing a jab during a match can make you miss the timing, abstraction while coding should emerge from natural intuition rather than conscious judgment.

There are moments while writing code when a feeling of resistance begins to surface: “This logic does not seem like it belongs here,” or “This component seems to know too much.” That feeling is the signal for abstraction, and internalization means being able to detect and respond to it naturally.

This intuition, however, is not built overnight. Only after studying countless patterns, reading a wide variety of code, and making plenty of mistakes yourself does the feeling that “this seems like something I should separate” begin to arise naturally. When a colleague later asks, “Why did you separate this?” and you can naturally answer, “I separated it because of X,” then the principle has become internalized.

I think the same is true in any field. Trying to become good by memorizing rules can make judgment harder. Ultimately, we need to hold on to the broad direction while letting the details fill themselves in naturally. And that naturalness comes from the variety of patterns and experiences we have accumulated over time.

Closing Thoughts

Abstraction in programming is the act of hiding complexity so that it appears simple and allowing readers of the code to focus only on the context they need.

To revisit what is worth remembering in order to create good abstractions:

• As a default premise, do not abstract prematurely; separate code only when a clear signal appears.
• Let each function speak at one level of abstraction only.
• Express behavior fully through names and types so that the code can be used without opening its source.
• Deliberately design the degree of input freedom to suit the module’s purpose and users.
• Rather than piling more onto a bad abstraction, have the courage to unravel it and start again.
• And internalize a variety of patterns until all of this comes naturally without conscious effort.

Of course, what I have presented in this article is not the one correct answer. The appropriate level of abstraction inevitably varies with the business situation, the composition of the team, and the nature of the project. But if one thing remains constant, it is that the ultimate purpose of abstraction is to create code that people can understand easily.

I hope readers will ask this question of their own codebases: “Is this abstraction actually reducing context?” I believe that question alone can shift, at least slightly, the way we look at code.

References

This article drew substantial inspiration from several official documents and earlier articles. Below are the sources of passages quoted directly, along with writings that helped shape the framework for my thinking.

While using TanStack Query in production, I have completely overhauled how I manage queryKeys several times. At first, I simply wrote arrays like ['user', userId] inline inside components. Then I started making typos because I had to repeat the same keys in multiple places whenever I invalidated queries, so I moved them into a constant object such as QUERY_KEYS. After reading TkDodo's article, I switched to the query key factory pattern. Much later, I adopted the @lukemorales/query-key-factory library. Then v5 arrived, and I overhauled everything once more using queryOptions.

I started wondering why so many patterns had emerged around a tiny array that was merely a cache identifier. Why does a single queryKey bear the marks of so much evolution? And what exact problem was each stage trying to solve?

In this article, I will trace TanStack Query's official documentation, TkDodo's blog series, and even the internal implementation of queryOptions introduced in v5 to explain how queryKey works and why it evolved into its current form.

Before queryKey

Before we get into the main discussion, let's establish some context. Today, we take libraries like TanStack Query and SWR for granted, but how did we handle asynchronous data before they existed?

The most common approach was probably to combine useState, useEffect, fetch, and axios.

function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
 
  useEffect(() => {
    let cancelled = false;
    setLoading(true);
 
    fetch(`/api/users/${userId}`)
      .then((res) => res.json())
      .then((data) => {
        if (!cancelled) setUser(data);
      })
      .catch((err) => {
        if (!cancelled) setError(err);
      })
      .finally(() => {
        if (!cancelled) setLoading(false);
      });
 
    return () => {
      cancelled = true;
    };
  }, [userId]);
 
  // ...
}

The problem with this code is obvious. If just two components on the page display the same userId, the same request is sent twice. That happens because there is no cache. If the user navigates to another page and returns, the data is fetched from scratch yet again. There is no way to tell whether the data was fetched one second ago or one hour ago, so even approximating behavior such as "show cached data while refreshing in the background" is difficult. (You could build your own cache system to implement this, but I think it would be quite difficult to maintain.)

Redux combined with redux-thunk (or redux-saga) emerged as a way to solve this. By moving data-fetching logic into a thunk and storing the result in the store, other components could reuse the same data. But every request required defining action types, writing a reducer, and manually managing loading, success, and failure states. The amount of boilerplate needed to fetch a single piece of data was enormous. (I started working professionally during this era and found myself wondering, "Why do I need to create several files just to fetch one piece of data?")

The essence of this progression is ultimately this: "To avoid repeating a request, we need to be able to identify which request it is." The identifier for that "which request" is exactly what a queryKey is.

SWR and React Query (now TanStack Query) tackled this problem head-on. "An asynchronous request must have an identifier, and requests with the same identifier share a cache." That single, simple principle eliminated all the boilerplate above.

The essence of queryKey

So what exactly is a queryKey? TanStack Query's official documentation defines it this way.

At its core, TanStack Query manages query caching based on query keys. A query key must be an array at the top level... As long as the query key is serializable and unique to the query's data, you can use it.

At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level... As long as the query key is serializable, and unique to the query's data, you can use it.

There are two key requirements. It must be serializable, and it must be unique to the data. The same key must represent the same data, and different data must have different keys. This simple rule determines how the entire cache system behaves.

There is one more important point: a queryKey also acts as a dependency array. Just as an effect runs again when its dependencies change in React's useEffect, TanStack Query automatically fetches new data when the queryKey changes.

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

The queryKeys for a userId of 'A' and one of 'B' are different. A different key means a cache miss, and a cache miss triggers a fetch. It is automatic. Thanks to this simplicity, we do not need to write logic that says, "The userId changed, so fetch again."

This raises a question: how does TanStack Query determine whether two queryKeys are "the same key"? A simple === comparison would find different object references and cause a cache miss every time.

Inside QueryCache

According to TkDodo's Inside React Query, QueryCache is ultimately just an in-memory data structure. More precisely, in the v5 official implementation, that data structure is not a plain object but a Map<string, Query>. It is declared inside the class as #queries = new Map<string, Query>(), and every write and read goes through #queries.set(query.queryHash, query) and #queries.get(queryHash). The key is the serialized form of the queryKey (queryHash), and the value is an instance of the Query class.

Older versions did use a plain object, but by v5 the implementation had settled on the native Map. (Map has no risk of key collisions or prototype pollution, preserves insertion order, and offers average O(1) string-key lookup, making it an almost textbook choice for a cache data structure.)

What happens each time useQuery is called is straightforward. The queryKey is converted into a hash, and that hash is used to look it up in the Map. If an entry exists, TanStack Query retrieves the cached Query instance. Otherwise, it creates a new one and calls set.

This naturally leads to another question: why serialize the queryKey into a string at all? Why not use the array itself as the key, as in Map<QueryKey, Query>?

The answer lies in JavaScript's equality model. A native Map compares keys using reference equality. Even when their contents are identical, objects at different locations in memory are treated as different keys.

const m = new Map();
m.set(['user', 1], 'alice');
m.get(['user', 1]); // undefined — 새로 만든 배열은 다른 참조다

But in a React component, useQuery({ queryKey: ['user', userId] }) creates a new array instance on every render. The queryKey arrays from the first and second renders are separate objects in memory even if their contents match. If the cache depended on reference equality, a component displaying the same data would tragically miss the cache on every render.

The solution to the problem caused by reference equality is simple: convert reference equality into structural equality. Create a deterministic string using only the contents of the queryKey, then use that string as the Map key. This restores the semantics we want: "equal contents mean the same key." JSON.stringify is simply the most straightforward tool for that conversion. (It is also why TanStack Query, after experimenting with several serialization strategies during the v3 era, ultimately settled on a stable variation of JSON.stringify.)

The key here is the function that produces the hash: hashKey. Its official implementation in packages/query-core/src/utils.ts looks exactly like this.

export function hashKey(queryKey: QueryKey | MutationKey): string {
  return JSON.stringify(queryKey, (_, val) =>
    isPlainObject(val)
      ? Object.keys(val)
          .sort()
          .reduce((result, key) => {
            result[key] = val[key]
            return result
          }, {} as any)
      : val,
  )
}

It does use JSON.stringify, but instead of stringifying directly, it supplies a replacer callback that sorts the keys of plain objects alphabetically before serialization.

This sorting is fundamental because string serialization carries an additional, stronger requirement: semantically equivalent inputs must always produce the same string. Ordinary JSON.stringify, however, preserves key order. { a: 1, b: 2 } and { b: 2, a: 1 } are semantically equivalent objects, but they serialize into different strings and therefore occupy different cache slots. That would bring back duplicate requests for the same data.

The technique that consistently prevents this is a canonical form. It forces semantically equivalent inputs to map to exactly one representation. This is precisely why the hashKey replacer sorts the keys of plain objects. By producing the same output regardless of input order, it creates a one-to-one relationship between the serialized result and the meaning of the object. In mathematical terms, it selects the sorted form as the representative element of the equivalence class formed by objects whose keys appear in different orders.

The fact that arrays are not sorted is the other side of the same principle. An array is a data structure in which order itself carries meaning, so sorting it would destroy information. Object key order is incidental; array element order is intentional. hashKey treats the two accordingly. This is why the official guide recommends arranging a queryKey from "generic → specific." As long as array order carries meaning, the author must define that meaning directly.

There is one more detail worth highlighting: key sorting applies only to plain objects. In the same file, isPlainObject does not merely check typeof === 'object'; it goes as far as checking Object.getPrototypeOf(o) === Object.prototype to distinguish plain object literals from class instances. As a result, a literal such as { foo: 1 } is sorted, while an instance created with class User { ... } passes through unsorted. (This is where a subtle trap arises: if you put a class instance directly into a queryKey, its interaction with JSON.stringify, which outputs only enumerable properties, may produce a hash different from what you intended.)

This behavior has two important consequences.

1. Object key order does not matter.

useQuery({ queryKey: ['todos', { status: 'done', page: 1 }], queryFn });
useQuery({ queryKey: ['todos', { page: 1, status: 'done' }], queryFn });
// 두 쿼리는 같은 캐시 슬롯을 공유한다

That is because the keys are sorted before serialization. Without this behavior, you would have to remember the key order every time you used an object literal.

2. Array element order matters.

useQuery({ queryKey: ['todos', status, page], queryFn });
useQuery({ queryKey: ['todos', page, status], queryFn });
// 두 쿼리는 다른 캐시이다

That is because an array is a data structure where order itself carries meaning. JSON.stringify also preserves array order.

It is also useful to know that undefined values disappear during serialization. { a: 1, b: undefined } and { a: 1 } produce the same hash. (I once made the mistake of thinking, "I explicitly included undefined, so this must be a different cache!")

Another constraint is that a queryKey cannot contain circular references or functions, because JSON.stringify cannot handle them. Objects such as Date, Map/Set, and BigInt are likewise not recommended under the default behavior. A queryKey should be a serializable, plain data structure.

Interestingly, this constraint is not absolute. TanStack Query provides an escape hatch through the queryKeyHashFn option, allowing you to replace the hash function itself. Internally, hashQueryKeyByOptions(queryKey, options) branches: if queryKeyHashFn exists in the options, it calls that; otherwise, it calls the default hashKey.

useQuery({
  queryKey: [{ id: userId, fetchedAt: new Date() }],
  queryFn,
  // Date를 ISO 문자열로 바꿔서 해싱
  queryKeyHashFn: (key) =>
    JSON.stringify(key, (_, v) => (v instanceof Date ? v.toISOString() : v)),
});

However, this option must be specified separately for each query, and it does not apply to imperative APIs invoked without knowledge of those options, such as queryClient.setQueryData (Issue #1343). In production, it is therefore much safer to avoid the escape hatch and convert values into a serializable form when constructing the queryKey. (I once placed a Date directly in a key and spent a long time wondering, "Why isn't the cache updating even though it represents the same instant?" The answer turned out to be, "That Date represents the same instant, but it is a different object instance, so it produces a different hash every time.")

Rules for writing queryKeys

Once you understand the internals above, the rules for writing queryKeys follow naturally. The official recommendations can be summarized as follows.

Rule 1. A queryKey must be an array.

Passing a string still works because it is converted to an array internally. For consistency, however, it is better to use an array from the start.

// 비권장
useQuery({ queryKey: 'todos', queryFn });
 
// 권장
useQuery({ queryKey: ['todos'], queryFn });

Rule 2. Include every variable that the queryFn depends on in the queryKey.

// 잘못된 예: userId가 쿼리키에 없다
useQuery({
  queryKey: ['user'],
  queryFn: () => fetchUser(userId),
});
 
// 올바른 예
useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

The mental model is exactly the same as the dependency array in useEffect. Every variable used inside the function must be part of the key (= dependency). Violating this rule creates bugs that are difficult to trace, such as continuing to display the previous user's data after switching to another user.

Rule 3. Arrange the key from the most generic element to the most specific.

// 좋다
['todos', 'list', { filter: 'done' }]
['todos', 'detail', todoId]
 
// 안 좋다 (순서가 뒤집혀 있음)
[{ filter: 'done' }, 'list', 'todos']

This order matters because of invalidation. By default, TanStack Query's invalidateQueries uses prefix matching.

// 모든 todos 관련 쿼리 무효화
queryClient.invalidateQueries({ queryKey: ['todos'] });
// → ['todos', 'list', ...], ['todos', 'detail', ...] 모두 매치된다
 
// list 쿼리만 무효화
queryClient.invalidateQueries({ queryKey: ['todos', 'list'] });
// → ['todos', 'list', ...]만 매치된다

When keys are designed as a tree, a single line can express anything from "fetch all data in this domain again" to "fetch only this exact item again." (It may not seem like much at first, but after designing a key hierarchy poorly and seeing invalidation affect an unintended scope, its value becomes painfully clear.)

The evolution of queryKey management

So far, we have covered how queryKey works and how to use it. Now we can move on to the central question: how has queryKey management changed over time?

I will walk through the stages I have used in production, in chronological order.

1. Inline arrays

This is the simplest form: combine fixed strings with prop values inside the component.

function UserProfile({ userId }: { userId: string }) {
  const { data } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });
  // ...
}
 
function PostList({ filter }: { filter: PostFilter }) {
  const { data } = useQuery({
    queryKey: ['posts', filter],
    queryFn: () => fetchPosts(filter),
  });
  // ...
}

This is enough when you are just getting started.

The problems begin as the codebase grows. When a mutation that updates user information needs to invalidate a query, you have to search for the answer to "What was the query key for user data again?" every time. Some places end up using ['user', userId], while others use ['users', userId] in the plural. These are entirely different cache slots, so invalidation affects only one of them.

2. A constant object

To prevent typos, gather query keys into constants.

// queryKeys.ts
export const QUERY_KEYS = {
  USER: 'user',
  POSTS: 'posts',
  COMMENTS: 'comments',
} as const;
 
// 사용처
useQuery({
  queryKey: [QUERY_KEYS.USER, userId],
  queryFn: () => fetchUser(userId),
});

The typos disappear, but each call site is still responsible for assembling the key. One person may use [QUERY_KEYS.USER, userId], another [QUERY_KEYS.USER, userId, 'detail'], and someone else ['user', 'detail', userId]. Eventually, you need to memorize a separate convention just to know which form is correct.

3. Query Key Factory

This pattern was formalized in TkDodo's Effective React Query Keys. It defines an object that creates keys for each domain and expresses the hierarchy through functions.

// features/todos/queries.ts
const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
};
 
// 사용
useQuery({ queryKey: todoKeys.detail(1), queryFn: ... });
useQuery({ queryKey: todoKeys.list('done'), queryFn: ... });
 
// 무효화
queryClient.invalidateQueries({ queryKey: todoKeys.all });        // 전체
queryClient.invalidateQueries({ queryKey: todoKeys.lists() });    // 모든 리스트
queryClient.invalidateQueries({ queryKey: todoKeys.detail(1) });  // 특정 항목

This pattern is powerful because the hierarchy is made explicit in the code. todoKeys.all refers to every query related to todos, todoKeys.lists() refers to every list query, and todoKeys.detail(1) refers to one specific item. The precise scope of invalidation can be expressed in a single line of code.

Another benefit is co-location. TkDodo does not recommend gathering keys into a global file. Instead, he recommends placing queries.ts inside the feature directory and keeping keys and hooks together there.

src/
└── features/
    └── todos/
        ├── index.tsx
        └── queries.ts   # 키와 훅을 모두 여기에

This creates a simple mental model: "To change something about todos, I only need to look in the todos directory." It is a faithful application of the principle of keeping things that change together close together.

4. @lukemorales/query-key-factory

Writing the third pattern by hand every time accumulates boilerplate. And when you want to combine keys from multiple domains, the lack of a standardized interface becomes apparent. @lukemorales/query-key-factory is the library form of this pattern.

import { createQueryKeys, mergeQueryKeys } from '@lukemorales/query-key-factory';
 
const users = createQueryKeys('users', {
  detail: (userId: string) => ({
    queryKey: [userId],
    queryFn: () => api.getUser(userId),
  }),
  list: (filters: UserFilters) => ({
    queryKey: [{ filters }],
    queryFn: () => api.getUsers(filters),
  }),
});
 
const todos = createQueryKeys('todos', {
  detail: (id: number) => ({
    queryKey: [id],
    queryFn: () => api.getTodo(id),
  }),
});
 
export const queries = mergeQueryKeys(users, todos);
 
// 사용
useQuery(queries.users.detail('abc'));
useQuery(queries.todos.detail(1));
 
// 무효화
queryClient.invalidateQueries(queries.users._def);            // 모든 user 쿼리
queryClient.invalidateQueries(queries.users.detail('abc'));   // 특정 항목

createQueryKeys automatically adds the prefix, and mergeQueryKeys can combine domains. The conventional _def property provides access to the key for an entire domain. This eliminates the manual work of repeatedly adding as const to narrow types in a hand-written factory.

For a while, this library was effectively the standard. (I was a happy user for quite some time.) Then queryOptions changed the landscape.

5. queryOptions (official in v5)

One of the most important changes in TanStack Query v5 was the introduction of the queryOptions API. During the transition from v4 to v5, every hook's arguments were unified into a single object. The real purpose of this change was to make it possible to extract that object into a reusable unit.

import { queryOptions } from '@tanstack/react-query';
 
export const userDetailOptions = (userId: string) =>
  queryOptions({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 5 * 60 * 1000,
  });
 
// 어디서나 사용 가능
useQuery(userDetailOptions('abc'));
useSuspenseQuery(userDetailOptions('abc'));
queryClient.prefetchQuery(userDetailOptions('abc'));
queryClient.setQueryData(userDetailOptions('abc').queryKey, newUser);

At first glance, you might think, "What is different about this? It looks like an object wrapped in a function." TkDodo acknowledges this in The Query Options API. At runtime, it truly does nothing more than return the object it receives.

The real work happens inside the type system. Let us continue.

DataTag in queryOptions

queryOptions is more than a simple helper because it embeds data type information in the returned queryKey. TanStack Query calls this mechanism DataTag internally.

A simplified implementation looks like this.

declare const dataTagSymbol: unique symbol;
declare const dataTagErrorSymbol: unique symbol;
 
export type DataTag<TType, TValue, TError = unknown> = TType & {
  [dataTagSymbol]: TValue;
  [dataTagErrorSymbol]: TError;
};

This is a branded type built with a unique symbol. It is merely a marker with no runtime effect, but to TypeScript it carries the information that "this array is not just an array; it is an array associated with data of type TValue."

There is a reason for using a unique symbol here. The Zenn article Uncovering the unique symbol Behind DataTag compares this mechanism to "a dedicated parking space for type information." An ordinary string key could collide with a key from another library or from user code, but each unique symbol declaration creates a type unique to itself, so it cannot have the same type as any other declaration. In effect, it becomes an identifier that can never collide.

The difference this one mechanism makes is significant.

const data = queryClient.getQueryData(['user', 'abc']); // unknown
const data = queryClient.getQueryData(userDetailOptions('abc').queryKey); // User | undefined

getQueryData and setQueryData receive only a queryKey. But because that queryKey already carries the data type, the return type is inferred automatically. There is no need to pass a generic explicitly, and if you try to provide setQueryData with a value of the wrong type, the compiler catches it immediately.

There are limitations, of course. Methods such as getQueriesData, which retrieve multiple queries at once, return a heterogeneous array of tuples, so this type inference does not apply. And because the implementation uses a unique symbol, generating .d.ts files in a monorepo can produce a TS4023 error; importing dataTagSymbol explicitly provides a workaround.

The mechanism so far makes one fact clear: the type inference provided by queryOptions depends entirely on declaring the queryKey and queryFn together in one place. To embed the return type of the queryFn in the queryKey, they must be declared together.

This has a major implication for the design direction of query key factories. Earlier patterns emphasized separating queryKey management into its own abstraction. The v5 recommendation takes the opposite direction: bring the queryKey and queryFn back together as a single unit. TkDodo goes so far as to say that separating the queryKey and queryFn was a mistake. After all, the key is a collection of the function's dependencies, and the two are inseparable.

A practical queryOptions composition pattern

The real value of queryOptions emerges when it is combined with a domain-specific factory. The form recommended by the official v5 documentation looks like this.

import { queryOptions } from '@tanstack/react-query';
 
export const todoQueries = {
  all: () => ['todos'] as const,
  lists: () => [...todoQueries.all(), 'list'] as const,
  list: (filters: TodoFilters) =>
    queryOptions({
      queryKey: [...todoQueries.lists(), filters],
      queryFn: () => fetchTodos(filters),
      staleTime: 30 * 1000,
    }),
  details: () => [...todoQueries.all(), 'detail'] as const,
  detail: (id: number) =>
    queryOptions({
      queryKey: [...todoQueries.details(), id],
      queryFn: () => fetchTodo(id),
      staleTime: 5 * 60 * 1000,
    }),
};

Let us unpack the strengths of this pattern one by one.

1. You get hierarchy and type inference at the same time.

todoQueries.all() and todoQueries.lists() return plain arrays, while todoQueries.detail(1) returns an object created through queryOptions with a data tag attached. Use the arrays for invalidation and the options object for query calls.

useQuery(todoQueries.detail(1));                                // 옵션 객체
queryClient.invalidateQueries({ queryKey: todoQueries.all() }); // 배열

2. Components can partially override the options.

The result of queryOptions is ultimately an object, so individual options can be composed at the call site.

const { data: title } = useQuery({
  ...todoQueries.detail(1),
  select: (todo) => todo.title,  // 컴포넌트별로 다른 select 적용
});

What makes this especially powerful is that the return type of select is inferred automatically, narrowing the type of data to string. The component can select only the piece it needs while leaving the domain definition centralized.

3. Custom hooks wrapping useQuery gradually disappear.

A common pattern in v4 was to create a custom hook for each domain.

The problem with that approach was that the moment prefetching became necessary, you had to write the same definition again. Because useTodoDetail is a hook, it cannot be called outside a component, so a router loader or event handler had to repeat queryClient.prefetchQuery({ queryKey: [...], queryFn: ... }).

With queryOptions, that duplication disappears.

The same definition works everywhere. That is why TkDodo recommends, "In v5, define queryOptions instead of creating hooks." Hooks become thin wrappers used only when needed, while the domain definition stands on its own without them.

Mutation Invalidation

The queryKey hierarchy truly shines when invalidating queries after a mutation. According to TanStack Query's Query Invalidation documentation, invalidateQueries uses prefix matching by default.

// 모든 todos 관련 쿼리 (list, detail, lists 모두)
queryClient.invalidateQueries({ queryKey: todoQueries.all() });
 
// 모든 list만 (detail은 건드리지 않음)
queryClient.invalidateQueries({ queryKey: todoQueries.lists() });
 
// 정확히 이 키만 (자식 키 매치 안 함)
queryClient.invalidateQueries({
  queryKey: todoQueries.detail(1).queryKey,
  exact: true,
});
 
// 더 복잡한 조건은 predicate으로
queryClient.invalidateQueries({
  predicate: (query) =>
    query.queryKey[0] === 'todos' &&
    (query.queryKey[2] as any)?.version >= 10,
});

When keys are designed hierarchically, the scope of invalidation matches the meaning of the code. "Refresh all todos" is expressed with all(), "refresh only the lists" with lists(), and "refresh only this item" with detail(id).

If the keys were scattered in a flat structure such as ['todoList'] and ['todoDetail', 1], invalidating the entire todos domain would require two separate calls or a separately managed prefix constant. (And if you forgot to update that constant whenever a new domain key was added, the new key would be omitted from invalidation, causing a bug.)

Reading the queryKey back inside queryFn

There is one final pattern worth examining. A queryFn actually receives an object called QueryFunctionContext, which contains the queryKey used for that invocation.

queryOptions({
  queryKey: ['user', userId, { include: 'profile' }] as const,
  queryFn: ({ queryKey }) => {
    const [, id, options] = queryKey;
    return fetchUser(id, options);
  },
});

Why is this pattern useful? According to TkDodo's Leveraging the Query Function Context, it can force the dependencies of queryKey and queryFn to stay synchronized.

const sortBy = 'name';
 
queryOptions({
  queryKey: ['users'],
  queryFn: () => fetchUsers({ sortBy }),
});

This code is risky because the queryFn depends on an external variable. The cache will not update when sortBy changes because the dependency was omitted from the key. As long as the queryFn pulls variables from an external closure, this mistake can happen at any time.

The solution is simple: make the queryFn independent of external variables. If every dependency is read from the queryKey, a variable omitted from the queryKey cannot be used inside the function in the first place.

queryOptions({
  queryKey: ['users', { sortBy }] as const,
  queryFn: ({ queryKey: [, { sortBy }] }) => fetchUsers({ sortBy }),
});

With this structure, when a new dependency is introduced, there is no way to use it inside the function without adding it to the queryKey. The compiler catches the mistake by saying, in effect, "That key does not exist." Synchronization between the key and the function is delegated to the type system rather than left to convention.

How much should you extract?

After reading this far, you may be wondering, "Should every query be extracted into queryOptions?"

As always, my answer is "it depends."

The important thing to remember is that abstraction is not always beneficial. Extracting a query used only once into a domain factory merely forces readers to jump between two files. The evolution of queryKey management patterns does not mean "always use the most sophisticated tool." It means "you have the option to move up one rung of the ladder when the need arises."

Conclusion

In summary, a queryKey is the fundamental unit TanStack Query uses to identify and cache asynchronous data. That small array serves as a cache-slot identifier, a dependency array, and a definition of invalidation scope. In v5, it even carries data type information. Because so many responsibilities converge in this one place, how queryKeys are written and managed directly affects the cognitive load of the entire codebase.

Each stage was an answer to a real problem someone encountered at the time. So the right approach is not simply, "This is v5, so always use queryOptions." Instead, first ask: "What stage of this problem is my codebase currently facing?" Introducing a domain factory into a project where inline arrays are sufficient can itself be overengineering.

I hope this article encourages you to examine your own project: how queryKeys are distributed throughout the codebase, how invalidation is performed, and whether that structure fits the current size of your team and the complexity of your domain.

References

In practice, I have often felt vaguely uneasy whenever I wrote error-handling code. Some errors are caught with try/catch, some by an ErrorBoundary, and others by TanStack Query's onError. Their respective domains subtly overlap or fail to line up. As a result, errors sometimes leak out, while at other times they propagate farther than intended.

The problem is that we rarely take the time to examine how all these tools work together. We may know that "Error Boundaries only catch render-phase errors," but if asked exactly what that means in practice, what happens internally when reset is called, or at what point TanStack Query rethrows an error when throwOnError is enabled, we may struggle to answer.

Based on React's official guide, the react-error-boundary library, and the official TanStack Query v5 documentation, this article explains where the responsibility of each frontend error-handling tool ends and how the tools fit together.

Errors React Can and Cannot Catch

Let's begin with the most fundamental question: Which errors does React catch?

The official React documentation clearly distinguishes between errors that an Error Boundary can catch and those it cannot.

What an Error Boundary catches

• Errors thrown while a child component is rendering
• Errors thrown inside lifecycle methods
• Errors thrown in constructors

What an Error Boundary does not catch

• Errors inside event handlers
• Errors in asynchronous code such as setTimeout, requestAnimationFrame, and Promises
• Errors during server-side rendering (SSR)
• Errors thrown by the Error Boundary itself

Why does this distinction matter? Most of the errors we deal with every day actually belong to the second category. A button click triggers a mutation and the server returns a 500 response; a fetch inside useEffect fails; validation logic throws while a form is being submitted. React does not catch these errors automatically. We must catch and handle them explicitly.

Frontend error handling therefore splits into two paths: use an Error Boundary for render-phase errors, and use try/catch or library callbacks for everything else. At the point where these paths intersect, asynchronous state-management libraries such as TanStack Query serve as a bridge.

What an Error Boundary Really Is

An Error Boundary is ultimately a class component with two lifecycle methods. According to the official React documentation, a component must implement one of the following methods—usually both—to become an Error Boundary.

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }
 
  // 에러 발생 시 state를 업데이트해 다음 렌더에서 fallback UI를 보여준다
  static getDerivedStateFromError(error) {
    return { hasError: true };
  }
 
  // 에러가 발생한 직후에 호출. 로깅 같은 사이드이펙트는 여기서 처리한다
  componentDidCatch(error, info) {
    logErrorToMyService(error, info.componentStack);
  }
 
  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

getDerivedStateFromError must be a pure function. Its sole role is to return new state without side effects. In contrast, componentDidCatch is the place for side effects. This is where you send the error to Sentry or log the component stack to the console.

There is one important point here: these two methods exist only on class components. There is still no official way to build an Error Boundary as a function component. The official React documentation explicitly says so.

There is currently no way to write an Error Boundary as a function component.

There is currently no way to write an Error Boundary as a function component.

Writing a class component from scratch every time is cumbersome, so developers typically use the react-error-boundary library. (It was created by former React maintainer Brian Vaughn and is effectively treated as the standard.)

Three Types of Fallback in react-error-boundary

The react-error-boundary library's ErrorBoundary component offers three ways to specify fallback UI through props. Let's take a quick look at how each one is used.

fallback

This is the simplest form: pass static JSX directly.

<ErrorBoundary fallback={<div>문제가 발생했습니다.</div>}>
  <Page />
</ErrorBoundary>

Use it when you do not need access to the error object or the reset function. In practice, I have not used it yet because an error message or a retry action is usually necessary.

FallbackComponent

Extract the fallback UI into a separate component and pass its reference.

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>오류가 발생했습니다.</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  );
}
 
<ErrorBoundary FallbackComponent={ErrorFallback}>
  <Page />
</ErrorBoundary>

The error object and the resetErrorBoundary function are automatically injected as props. This approach is clean when the fallback UI may be reused elsewhere.

fallbackRender

Use this when you want to render the fallback inline.

<ErrorBoundary
  fallbackRender={({ error, resetErrorBoundary }) => (
    <div role="alert">
      <p>오류가 발생했습니다: {error.message}</p>
      <button onClick={resetErrorBoundary}>다시 시도</button>
    </div>
  )}
>
  <Page />
</ErrorBoundary>

It does essentially the same thing as FallbackComponent, but lets you handle it inline without creating a separate component. It is useful when you need access to an outer closure, such as parent state or handlers.

There is no single correct choice among the three, but the pattern I use most often in production is to create one shared ErrorFallback component and inject it through FallbackComponent. This keeps the design system and tone consistent. I use fallbackRender inline only when a page needs a different fallback.

What Does reset Actually Do?

When using react-error-boundary, you naturally encounter the resetErrorBoundary function. It is the function called when the user clicks the "Try again" button in the fallback. Let's examine what it actually does.

In short, resetErrorBoundary only tells the ErrorBoundary component to reset its own state and render its children again. It does not automatically touch any external state, such as the TanStack Query cache.

Here is what happens internally, step by step.

1. resetErrorBoundary() is called.
2. The ErrorBoundary's internal hasError state returns to false.
3. Optionally, the onReset callback runs. This is where custom side effects happen.
4. The children render again. If the cause of the error—such as state or cache—remains, the same error is thrown again.

The final step is the key. Reset only means "forget the error and try rendering again"; it does not mean "fix the cause of the error." Calling reset alone can therefore cause the same error to repeat indefinitely.

Two additional tools help solve this problem.

onReset

This acts like a hook that runs immediately before the reset. Use it to clean up the external state that caused the error.

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  onReset={() => {
    queryClient.invalidateQueries({ queryKey: ['user'] });
  }}
>
  <Page />
</ErrorBoundary>

resetKeys

The ErrorBoundary resets automatically when values in this array change. Pass keys for which it makes sense to retry when the value changes, such as URL parameters, a search term, or the selected tab.

<ErrorBoundary
  FallbackComponent={ErrorFallback}
  resetKeys={[userId]}
>
  <UserProfile userId={userId} />
</ErrorBoundary>

When userId changes, the boundary resets automatically and its children render again. If the user navigates to another profile, the previous error naturally disappears.

How Do We Catch Errors from Event Handlers and Asynchronous Code?

As discussed earlier, Error Boundaries do not catch errors from event handlers or asynchronous code. Yet that is where most of the errors we deal with occur. So how should we handle them?

For this problem, react-error-boundary provides the useErrorBoundary hook. The hook returns a function called showBoundary; calling it lets you explicitly send an error to the nearest ErrorBoundary.

import { useErrorBoundary } from 'react-error-boundary';
 
function MyComponent() {
  const { showBoundary } = useErrorBoundary();
 
  const handleClick = async () => {
    try {
      await someAsyncOperation();
    } catch (error) {
      showBoundary(error);
    }
  };
 
  return <button onClick={handleClick}>실행</button>;
}