DEV Community: Zhengxin

Claude Code Tools Deep Dive (4): Grep + Glob

Zhengxin — Tue, 04 Aug 2026 14:26:28 +0000

This is the fourth article in my series on Claude Code tools. The first three covered the “interaction primitive trio”: AskUserQuestion, EnterPlanMode, and ExitPlanMode. Together, those tools solve one problem: how the AI and the user align with each other.

Starting with this article, we enter the world of execution primitives—how Claude turns an agreed-upon plan into actual code changes. But before it can read, edit, or write anything, it first needs to know where to look. That makes the first execution primitives worth examining the search duo: Glob finds by path; Grep finds by content.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

Grep + Glob

When Claude enters a new project, it does not know the file paths. Questions such as “Where is the authentication code?”, “Which files use useState?”, and “Which files changed recently?” are impossible to answer reliably without search tools. Claude would otherwise have to guess from its training data—which is unreliable—or ask the user to list files manually—which is tedious.

Claude Code provides two complementary search tools: Glob searches by path; Grep searches by content. I am covering them together because their roles are tightly coupled, they are frequently used in combination, and treating them separately would create a lot of repetition.

They share one central philosophy: perceive on demand, and send only what Claude truly needs into the context window. They are also the prerequisites for the next three file-operation primitives: Read, Edit, and Write.

What they do

Glob finds files using a path pattern. It accepts a shell glob such as **/*.ts or src/**/api-*.js, then returns matching file paths sorted by modification time in descending order.

Grep finds files or lines by content. It is powered by ripgrep, accepts a regular expression, and can return matching file paths, matching lines, or match counts, depending on the selected output mode.

Together, they solve the core problem of helping Claude locate the files it needs inside a large codebase:

No need to read the entire project—locate relevant files first, then use Read, saving context.
No need to guess where files are—search exposes the truth on disk rather than relying on training-time assumptions.
No need to construct Bash commands—dedicated tools avoid shell escaping, path dependencies, and permission issues.
Controllable output—Grep in particular offers three output modes so Claude can request only the level of detail it needs.

A concrete example

Scenario: The user says, “Help me understand how the auth code is organized. I want to refactor it.”

Claude has no idea where the auth code lives. It could be under src/auth/, server/middleware/, or lib/security/, or scattered inside files such as pages/api/login.ts.

The bad alternative: Read alone

Without search tools, Claude would have only a few poor options:

Guess from training-time patterns—“Auth middleware in a Node.js project is probably at src/middleware/auth.js.” It tries to read the file and discovers that it does not exist.
Ask the user to list files—“Can you tell me the paths of all auth-related files?” The user has to do tedious manual work.
Read the entire src/ directory—a medium-sized project may contain 200 files and hundreds of thousands of tokens, overwhelming the context window.

The core problem is simple: without search, Claude cannot see the shape of the codebase. It must rely on indirect information or brute-force reading.

How Grep + Glob solve it

Step 1: Use Glob to sketch the file landscape

Claude calls Glob with:

pattern: **/*{auth,login,session,jwt}* (matching paths or filenames containing those keywords)

It returns:

src/auth/middleware.ts    (2h ago)
src/auth/routes.ts        (2h ago)
src/lib/session-store.ts  (3d ago)
src/pages/api/login.ts    (1w ago)
tests/auth.test.ts        (2h ago)

The results are ordered by modification time, so recently modified files appear first. Those files are often where the active work is happening.

Step 2: Use Grep to investigate specific calls

Claude now wants to know where jwt.verify is used:

pattern: jwt\.verify
output_mode: content (return matching lines, file paths, and line numbers)
-C: 2 (include two lines of context before and after each match)
type: ts

It returns:

src/auth/middleware.ts:8:      const decoded = jwt.verify(token, process.env.JWT_SECRET);
src/auth/middleware.ts:9:      req.user = decoded;
--
src/services/api-client.ts:42:  return jwt.verify(token, PUBLIC_KEY);
--

Every result is a precise coordinate that Claude can immediately pass to Read or Edit.

Step 3: Combine modes according to the question

If Claude only wants to know how many files use jwt.verify, rather than the exact locations, it can use:

pattern: jwt\.verify
output_mode: count

The result might be 4 files. This call uses only a few dozen tokens because it does not pull every matching line into the context window.

If it only wants to know which files contain the call, without seeing the lines themselves, it can use:

pattern: jwt\.verify
output_mode: files_with_matches

The result is simply a list of file paths.

Key insight: Grep’s three output modes—content, files_with_matches, and count—let Claude choose the right precision on demand. It can fetch matching lines for deep investigation, paths for narrowing the scope, or a count for estimating impact.

When they are triggered

Use Glob when:

Searching by filename or path—“all .tsx files,” “everything under src/api/,” or “where are the tests?”
Looking for recently modified files—Glob sorts results by modification time in descending order.
Narrowing the scope before Grep—first identify relevant files, then search their contents.

Use Grep when:

Searching files or lines by content—“where is useEffect used?” or “where is UserBadge defined?”
Investigating API usage—“every place that calls db.query.”
Tracing an error message—when a user supplies an error, search the codebase for the place that may throw it.

Use both when:

Locating a module in a large codebase—first Glob for **/*auth*, then Grep for a specific call.
Restricting by language or file type—if you only need to search .ts files, Grep’s type: "ts" can do that directly without a preceding Glob call.

Do not use them when:

You already know the exact path—use Read directly instead of taking a detour through Grep or Glob.
You merely need to list a directory—use ls; Glob matches patterns rather than browsing directories.
You need fuzzy semantic search—for a request such as “find all code that performs authentication,” Grep can only perform literal or regex matching. It does not understand semantics; an Agent should investigate instead.

Technical design

Grep and Glob are sibling tools. Their responsibilities are distinct, but their design philosophies are shared. Let us examine each through the four layers, then compare their symmetry.

Glob

1. Naming

Glob

The name comes directly from the convention used by shells and Python’s glob library. “Glob” is the standard term for finding files with path patterns. The fields pattern and path are immediately intuitive to anyone familiar with a shell.

Calling it FindByPath or SearchFiles would actually weaken its central promise: the input uses glob syntax, not regular expressions. The name itself signals the syntax.

2. Tool-level description

Glob’s description is extremely short—only five bullet points—centered on two concerns: usage constraints and delegation at the boundary.

The pattern uses glob syntax, not regex

Supports glob patterns like **/*.js or src/**/*.ts

It provides two examples and no regex examples. This is demonstration instead of prohibition. Rather than saying “do not use regex,” it shows Claude canonical glob shapes such as **/*.js, preventing it from passing something like .*\.ts as the pattern.

Results are sorted by modification time

Returns matching file paths sorted by modification time

This declares a total ordering for the output. It gives Claude a useful intuition: the first file returned by Glob is the most recently modified. For questions such as “where is the project’s active work?” or “which module was just refactored?”, inspecting the first few results may be enough.

The explicit purpose is filename search

Use this tool when you need to find files by name patterns

Grep also has a glob field, but that field is a filter, not a search operation. Glob treats the filename as the primary search target.

Open-ended searches are delegated to Agent

When you are doing an open-ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead

This is the most interesting part: the tool explicitly acknowledges its own boundary. If a task needs repeated cycles of Glob and Grep—for example, “find which module a recent change broke”—the description tells Claude to switch to Agent rather than forcing the task into a single Glob call.

3. Field-level descriptions

pattern—a shell glob expression such as **/*.js or src/**/*.{ts,tsx}, not a regular expression.
path—an optional search directory; defaults to the current working directory.

The field set is minimal. The modification-time ordering is a subtle but valuable design choice. When developers want to know which area is currently active, their instinct is often to run ls -lt. Glob effectively provides the same signal by default: cold code sinks, hot code rises.

4. Schema validation

The schema is minimal. Only pattern is required; path is optional, and there are no additional numeric constraints.

Almost all of Glob’s behavioral signals live in its name and tool description. The schema adds little restriction because glob syntax is already narrow enough.

Grep

1. Naming

Grep

This name also borrows an industry convention. In the Unix world, “grep” universally means “match by content.” Under the hood, however, the tool uses ripgrep (rg) rather than traditional grep. The familiar name reduces cognitive load while the implementation uses a faster engine.

2. Tool-level description

Grep’s description is one level more detailed than Glob’s: seven bullet points plus a declaration, centered on four concerns—locking in correct usage, explaining syntax, exposing filter dimensions, and delegating at the boundary.

ALWAYS + NEVER: locking usage from both directions

ALWAYS use Grep for search tasks. NEVER invoke grep or rg as a Bash command. The Grep tool has been optimized for correct permissions and access.

This is the strongest sentence in the entire description. “ALWAYS” and “NEVER” constrain behavior from both directions: it says what to use, forbids the tempting shortcut, and explains why with “optimized for correct permissions and access.” It prevents Claude—already comfortable with the shell—from instinctively running rg through Bash, where output is unstructured and permission handling may differ.

The pattern uses ripgrep regex syntax

Supports full regex syntax (e.g., log.*Error, function\s+\w+)

This is the direct opposite of Glob. Grep’s pattern is a regular expression. Two realistic examples—searching for logged errors and function declarations—immediately communicate the syntax.

Two filtering dimensions: glob vs. type

Filter files with glob parameter (e.g., *.js, **/*.tsx) or type parameter (e.g., js, py, rust)

Claude gets two parallel options: use glob for a precise path pattern or type for a language shortcut from ripgrep’s built-in type table. One type: rust is far more concise than spelling out a collection of extensions.

The default output mode is files_with_matches

Output modes: content shows matching lines, files_with_matches shows only file paths (default), count shows match counts

Notice that “default” is attached to files_with_matches, not content. Why? Because content consumes the most context. Making it the default could flood the context window. A path list lets Claude decide whether a deeper read is necessary. This is a default designed around the token budget.

Open-ended search is delegated to Agent

Use Agent tool for open-ended searches requiring multiple rounds

This mirrors Glob. Both tools declare their own boundary: if the task requires repeated iterations, use Agent.

ripgrep is not grep; literals may need escaping

Pattern syntax: Uses ripgrep (not grep)—literal braces need escaping (use interface\{\} to find interface{} in Go code)

This is a concrete example of a real failure mode. In a regular expression, braces express repetition ranges—a{2,3} means two or three occurrences—so searching for Go’s interface{} syntax requires escaping the braces. One realistic example replaces a long syntax lecture.

Multiline mode is off by default and must be enabled explicitly

Multiline matching: By default patterns match within single lines only. For cross-line patterns like struct \{[\s\S]*?field, use multiline: true

This prevents Claude from writing a cross-line expression, receiving no matches, and not understanding why. It also illustrates a recurring design pattern: expensive behavior stays off by default and requires an explicit switch.

3. Field-level descriptions

Grep has far more fields than Glob:

pattern—a regular expression using ripgrep syntax.
path—an optional directory in which to search.
glob—an optional file glob, such as *.ts.
type—an optional language filter such as ts, py, or rust.
output_mode—content, files_with_matches (default), or count.
head_limit—limits the number of output entries.
-i—case-insensitive matching.
-n—shows line numbers; enabled by default in content mode.
-A, -B, and -C—lines of context after, before, or around a match; only relevant in content mode.
multiline—allows patterns to match across lines.
Format flags such as -c, -l, -L, -o, and -Z—pass output handling through to native grep behavior.

Several design choices stand out.

Three output modes

This is Grep’s most elegant feature. A single search can return three levels of precision:

content—all matching lines, when you need to inspect or fix exact locations.
files_with_matches—file paths only, when you are scoping a refactor.
count—counts only, when you are estimating impact.

These map to three common intents: “I need to fix it,” “I need to refactor it,” and “I need to assess it.” Grep lets Claude choose precision according to intent instead of always retrieving the maximum amount of data.

head_limit as a safety net

A search for console.log might return 1,000 lines. Without a limit, that could overwhelm the context window. head_limit: 50 returns only the first 50 entries—enough to work with without flooding the model.

One subtle detail: Grep orders by file-path lexicographic order, whereas Glob orders by modification time. Neither is a relevance ranking; the limit simply truncates that ordering.

type vs. glob for narrowing scope

type uses ripgrep’s language recognition based on extensions and file types, covering common languages such as Python, Rust, and TypeScript. glob is pure path matching and can express special layouts such as **/legacy/**/*.js. type is more concise; glob is more flexible.

Native format flags as an escape hatch

When the normalized tool output is not enough, Claude can fall back to native ripgrep capabilities. The designers recognize that no wrapper can cover every use case, so they leave an escape hatch.

4. Schema validation

Grep’s schema also has almost no hard constraints such as numeric ranges or string-length limits. Most constraints are enums or types:

Field	Type	Constraint
`output_mode`	string	`content`, `files_with_matches`, or `count`; defaults to `files_with_matches`
`-i`, `-n`, `multiline`	boolean	default to `false`
`-A`, `-B`, `-C`	integer	only apply when `output_mode` is `content`
`head_limit`	integer	no default; unlimited when omitted

Defaults are central to Grep’s design. The output mode defaults to files_with_matches, multiline mode is off, and the flags are off unless requested. Every default leans toward less output and simpler behavior, making the tool context-efficient even when Claude accepts all defaults.

Why dedicated Grep and Glob tools instead of Bash + rg?

Bash is a catch-all: in theory, it can do everything. But invoking rg directly creates several problems:

Shell escaping—characters such as $, !, and ( inside regular expressions may be interpreted by the shell.
Path dependencies—is rg installed, and which version is available?
Output parsing—Bash returns a large text blob that Claude must parse itself.
No output-mode abstraction—Claude has to remember and combine raw rg flags.

Dedicated tools solve these problems with typed parameters, normalized output, no shell quoting traps, and a single structured call. That is the technical foundation behind the instruction: “ALWAYS use Grep… NEVER invoke grep or rg as a Bash command.”

Division of responsibility among neighboring tools

Here is where Grep + Glob sit within Claude Code’s execution primitives. Later articles will fill in the rest of the map:

Dimension	Interaction trio	Grep + Glob	Read	Edit	Write
Role	Collaborative alignment	Locate coordinates	Perceive content	Precise execution	Full execution
Frequency	Key moments	High-frequency	High-frequency	High-frequency	Medium-frequency
Input	Structured / empty	Pattern; path need not be known	Known path	Known path + `old_string`	Known path + full content
Output	User decision	Paths / matching lines / counts	Complete file content	Modified diff	New or overwritten file
Conservative bias	“When uncertain, plan”	“Search on demand before reading everything”	“When uncertain, read”	“When uncertain, read first”	“Prefer Edit when possible”

A complete investigation chain:

User: Help me refactor the auth-related code
    ↓
Glob (**/*{auth,login,session}*)                 ← This article
    → Relevant file paths, ordered by mtime
    ↓
Grep (pattern: "jwt\.verify", output_mode: files_with_matches)  ← This article
    → Files that actually use the API
    ↓
Read (each relevant file)                       ← Next article
    → Full contents establish a perception commitment
    ↓
Edit / Write                                    ← Later articles
    → Precise or full changes based on that perception

The trust chain of execution primitives:

Glob / Grep—location: Which files are relevant to this task?
Read—perception: What do those files look like right now?
Edit / Write—execution: How should they be changed, precisely or in full, based on that perception?

Every step is enforced at runtime, accepts typed parameters, and produces normalized output. A vague user request gradually converges into a precise file change, and the entire process remains predictable, reviewable, and composable.

Summary

The elegance of Grep + Glob is not merely that they let an AI search. It lies in how their signals are highly symmetrical yet deliberately different:

Glob relies on its industry-standard name for the core semantics, uses a minimal field set, and imposes almost no schema constraints. Its entire complexity is contained in one job: finding paths with glob syntax.
Grep has a much richer set of fields and flags, yet almost no numeric hard constraints. Instead, its defaults converge on the most context-efficient behavior.

Their most compelling symmetry is that both tools explicitly acknowledge their limits in their descriptions. When a task requires repeated rounds of globbing and grepping, they tell Claude to switch to Agent. The tools know what they are good at—and what they are not. That restraint is a sign of a mature tool ecosystem.

This reflects a core philosophy of Claude Code: do not give the AI one universal shell and ask it to improvise; turn each step into a primitive that is sufficient, safe, and composable.

The next article will examine Read: once Claude has the coordinates, how does it accurately perceive the current state of a file and establish the “perception commitment” that makes Edit and Write trustworthy?

Claude Code Tools Deep Dive #3 — ExitPlanMode: The Small Signal That Closes the Loop

Zhengxin — Mon, 03 Aug 2026 11:58:42 +0000

This is the third post in my Claude Code Tools Deep Dive series. The first two unpacked AskUserQuestion and EnterPlanMode—the first two stages of the decision pipeline: clarify, then expand. This post covers the final stage: submit the plan for user approval.

Before reading this post, it may help to read the series prelude on how Claude Code's tool mechanism works. This article follows the same four-layer framework introduced there.

ExitPlanMode

On the surface, ExitPlanMode may be the least conspicuous of Claude Code's three interaction tools. It has none of AskUserQuestion's option cards and none of EnterPlanMode's dramatic mode switch. It does exactly one thing: trigger an approve-or-reject confirmation.

But that restraint—doing almost nothing—is precisely what closes the three-tool workflow.

What It Does

ExitPlanMode is Claude Code's built-in “leave planning mode and request approval” tool. Its responsibility fits in one sentence: after Claude has written a complete plan in plan mode, it calls this tool so the user can review the entire plan and decide whether to approve execution, request revisions, or reject the direction.

It solves the core problem of obtaining explicit user approval when the AI moves from planning back to implementation:

Make the proposal visible — the UI displays the complete plan file instead of letting it disappear inside a chat message.
Require an explicit decision — the user must approve or reject; Claude cannot continue by default or jump the gun.
Switch back to implementation in one action — after approval, Claude automatically returns to the default mode where Edit and Write are available.
Preserve a feedback channel — the user can reject the current version and ask for changes instead of choosing between “accept everything” and “throw everything away.”

A Concrete Example

Scenario: continuing the authentication refactor from the EnterPlanMode post. The user asked Claude to replace JWT with session cookies. Claude entered plan mode, explored the codebase, clarified that only the web flow should change and that Redis should hold session state, then wrote the plan file. It is now ready to implement.

One question remains: how does Claude tell the user that the plan is complete and implementation can begin?

The Anti-Pattern: Life Without ExitPlanMode

Claude could only say something like this in chat:

“I've finished the plan. It looks roughly like this... [several hundred words] ... May I start?”

That creates several problems:

The plan gets buried in the conversation — hundreds of words mix with exploration logs and clarification messages, making the proposal difficult to review.
There is no explicit approval action — “OK,” “sure,” “go ahead,” and “👍” may all mean approval, but their semantics are not identical.
Claude must interpret approval language — a reply such as “Looks good, but can we add a device_id field to the sessions table?” is half approval and half revision request. Should Claude implement or revise the plan?
The mode transition has no boundary — Claude can gradually slide from planning into implementation and start writing code before the user realizes the transition occurred.
Rejection is expensive — if the proposal is wrong, the user must type an explanation instead of using a first-class “reject and explain” channel.

The deepest problem appears if Claude tries to solve this with AskUserQuestion by asking, “Is the plan OK?” As the previous post explained, the user cannot see the full plan before ExitPlanMode presents it. Asking for approval before showing the document is asking the user to vote in a vacuum.

How ExitPlanMode Fixes It

After finishing the plan file, Claude calls ExitPlanMode. The call takes no meaningful arguments—more on that below. The UI then handles three steps.

Step 1: Display the Complete Plan

The interface reads the file at the path maintained by plan mode and renders it as a separate, structured, scrollable proposal. The user sees a formal plan—scope, affected files, migration steps, risks, and rollback—not a paragraph floating through chat.

Step 2: Provide Explicit Response Paths

✅ Approve — return Claude to default mode and execute the plan.
✏️ Request changes — give feedback and keep Claude in plan mode so it can revise the proposal.
❌ Reject — stop and change direction.

Step 3: Make the Transition Atomic

The moment the user approves, the runtime performs several actions together:

Edit, Write, and NotebookEdit become available again.
CWD-dependent caches are refreshed.
Claude receives an explicit “user approved” signal and begins implementation.

There is no semantic ambiguity, no gradual slide, and no opportunity for Claude to jump the gun.

Side-by-Side Comparison

Anti-pattern pain	ExitPlanMode's solution
The plan gets buried in chat	The UI independently renders the complete plan file
No explicit approval action	The user must choose approve, revise, or reject
Claude must interpret agreement	The result is a structured state, not ambiguous natural language
The mode transition has no boundary	Approval atomically changes the tool allowlist
Rejection is expensive	Revision is a first-class path rather than an improvised reply

When to Fire It

The tool description gives a very strict rule: use ExitPlanMode only when Claude is in plan mode, has finished writing the plan file, and is ready for user approval.

The One Valid Situation

Claude is in plan mode and the plan file is complete.

Situations That Do Not Qualify

Pure research — a task such as “search for and understand the Vim mode implementation” does not need ExitPlanMode because no implementation plan is being submitted.
An unfinished plan — do not submit a partial proposal for approval. Finish it first.
A general-purpose permission question — do not use this tool as a fancy “May I continue?” prompt. If a real implementation fork needs clarification, use AskUserQuestion to ask about that fork rather than asking a meta-question.

A useful dividing line is: only a citable plan deserves ExitPlanMode. If the proposal is not yet a readable, reviewable, refutable document, keep exploring in plan mode instead of rushing to exit.

Technical Design

1. Naming

ExitPlanMode

The name is perfectly dual to EnterPlanMode. The Enter/Exit pair signals a stateful operation with a beginning and an end, following familiar pairs such as opening/closing a file descriptor or acquiring/releasing a lock. The semantics need almost no explanation.

Names such as SubmitPlan or RequestApproval would shift attention toward submitting data or requesting permission. They would weaken the tool's core meaning as a signal that ends a mode.

2. Tool-Level Description

ExitPlanMode's description focuses on three things: when to use it, why the plan content is not an argument, and why AskUserQuestion must not be used for the same meta-question.

Strict Applicability Boundary

Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.

Three conditions are stacked together: Claude is in plan mode, the plan file is complete, and the proposal is ready for approval. If any one is false, the tool should not be called.

Transparent Parameter Mechanism

This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote

The instruction tells Claude not to copy the plan into the tool call. The UI reads the file directly. This saves tokens and, more importantly, guarantees that the plan the UI displays is the same plan stored in the file.

Approval as an Implied Signal

This tool simply signals that you're done planning and ready for the user to review and approve

The key word is signals. The tool itself does not render the document or decide whether it was approved. It only emits an event. The runtime handles rendering, user input, and the state transition.

The tool call is therefore the lightest possible signal emitter—a distinctly Unix-like design.

Boundary with Research Tasks

IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.

This mirrors the boundary described for EnterPlanMode: plan mode exists for planning implementation, not for understanding an existing codebase as an end in itself. A pure investigation belongs in a research workflow rather than an implementation-approval workflow.

The Forbidden Meta-Question

Important: Do NOT use AskUserQuestion to ask “Is this plan okay?” or “Should I proceed?” - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.

This is especially elegant. It does not merely say “use ExitPlanMode instead of AskUserQuestion.” It identifies the two actions as semantically equivalent and declares that ExitPlanMode is the correct representation of that intent.

The earlier posts noted this anti-pattern. Here, the tool description bans it at the source.

Clarification Before Approval

One official example says:

Initial task: “Add a new feature to handle user authentication” - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.

This establishes the ordering between AskUserQuestion and ExitPlanMode while planning: clarify concrete forks first, then request approval for the complete proposal. Do not clarify and approve at the same time. Let the process converge linearly.

3. Field-Level Descriptions

Effectively none.

There is an allowedPrompts field, but it is marked deprecated: “Deprecated: no longer used.” In practice, the tool accepts no useful input.

That historical trace is interesting. Judging by the field name, an earlier version may have allowed Claude to declare a set of operation types that would become automatically permitted after approval—for example, run tests or install dependencies. Its deprecation suggests that the design moved toward a more conservative separation: approving the plan and granting additional permissions are different decisions.

In other words, it hints at an evolution from “approval implies authorization” toward “approval is approval; authorization is authorization.”

4. Schema Validation Rules

Effectively none.

Like EnterPlanMode, the input schema has no active constraints. Calling the tool is itself the intent to submit the plan; there is no data Claude needs to pass.

The empty schema leaves four responsibilities to the runtime:

Make the tool available only in plan mode.
Read and render the plan using the file path stored in the plan-mode state.
Block until the user explicitly responds; there is no automatic continuation.
On approval, atomically restore the tool allowlist, refresh caches, and send Claude the approval signal.

None of that requires an argument. This echoes EnterPlanMode's empty-schema design: permissions and state belong to the runtime; Claude only emits a signal.

Division of Responsibility with Neighboring Tools

ExitPlanMode is the final stage of the decision pipeline:

User: “Refactor auth and replace JWT with sessions.”
    ↓
Claude: Several forks need clarification.
    ↓
AskUserQuestion: clarify web-only scope and Redis session storage
    ↓
Claude: Let me develop a plan first.
    ↓
EnterPlanMode: user approves entry
    ├─ Explore with Grep / Read / Glob
    ├─ Clarify sub-decisions with AskUserQuestion as needed
    └─ Write the plan file
    ↓
ExitPlanMode: user sees the complete plan
    ├─ Approve → return to default mode and execute
    ├─ Request changes → revise in plan mode, then call ExitPlanMode again
    └─ Reject → stop or change direction

Each of the three tools has exactly one job. Together, they create a complete collaborative alignment loop:

AskUserQuestion — clarify: “A or B?” A single-point decision.
EnterPlanMode — expand: explore read-only and turn the approach into a document.
ExitPlanMode — commit: let the user approve, revise, or reject the entire proposal.

Takeaway

ExitPlanMode's elegance is not simply that it “lets the user approve the plan.” It comes from how closely its signals mirror EnterPlanMode: dual naming, behavior concentrated in the tool description, and effectively empty field and schema layers.

If AskUserQuestion lets the user choose, and EnterPlanMode opens a protected planning state, then ExitPlanMode is the humblest part of the system: it does nothing but emit a signal. Yet that signal gives the workflow an endpoint and gives collaboration a ceremonial moment of commitment.

The three-tool pipeline is now complete:

Claude Code decomposes AI–human collaboration into three composable, orchestratable, predictable interaction primitives: clarify, expand, commit. Each primitive is deliberately restrained—it does one small thing—but together they can express a complete collaborative workflow.

The next post will move from collaborative alignment to code exploration with Grep + Glob, examining how information-retrieval tools encode what to search, how to search, and how much to return.

Claude Code Tools Deep Dive #2 — EnterPlanMode: Why an Empty Schema Is a Design Choice

Zhengxin — Sun, 02 Aug 2026 14:49:25 +0000

This is the second post in my Claude Code Tools Deep Dive series. The previous post unpacked AskUserQuestion, a structured tool that lets users choose from concrete options. This time, we're looking at its sibling: EnterPlanMode.

Before reading this post, it may help to read the series prelude on how Claude Code's tool mechanism works. This article follows the same four-layer framework introduced there.

EnterPlanMode

Like AskUserQuestion, EnterPlanMode is a tool you may encounter almost every day. But its design is much heavier. It does not merely ask a question; it switches Claude into an entirely different mode of operation.

What It Does

EnterPlanMode is Claude Code's built-in entry point into planning mode. Its job is simple but forceful: move Claude from the default "think while writing" workflow into a planning workflow built around read-only exploration and solution design. Claude returns to implementation only after the user explicitly approves the plan.

The core problem it solves is alignment between the AI and the user:

Prevent work from drifting in the wrong direction — Claude aligns on the approach before modifying a single file.
Enforce read-only exploration — once plan mode is active, Edit, Write, and NotebookEdit are disabled. Claude cannot quietly make changes while it explores.
Create an explicit decision boundary — the user can approve, reject, or request changes to a complete proposal instead of discovering a wrong direction only after seeing the pull request.
Produce a traceable planning artifact — plan mode creates a written plan that can be referenced and revised, rather than a paragraph that disappears into the chat history.

A Concrete Example

Scenario: the user tells Claude, "Refactor this authentication module and replace JWT with session cookies."

The request sounds clear, but it actually spans login routes, token-generation middleware, frontend storage, session-expiration policy, database schema decisions, and backward compatibility for existing API consumers. It is a multi-file, multi-decision, dependency-heavy change.

The Anti-Pattern: Working Without EnterPlanMode

Without a planning boundary, Claude has to infer an approach from the available context and start editing immediately:

Open auth/middleware.ts and switch it to reading a session cookie.
Open auth/routes.ts, remove JWT issuance, and replace it with req.session.
Open frontend/api.ts and remove the Authorization header logic.
Open models/user.ts and add a sessionId field.
Halfway through the refactor, discover that three other services authenticate against the same API with JWTs.

The user sees the diff and says: "I only wanted sessions for the web app. The backend services still need JWT. Why did you replace authentication for the entire API?"

Several things went wrong:

The directional error surfaced five steps too late — four files have already changed, so rollback is painful.
The decision boundary was unclear — "replace all authentication or only the web flow?" was a critical fork, but Claude guessed without asking.
The user never saw the whole picture — they received a pile of diffs and had to reverse-engineer the intended design.
Important side effects were never surfaced — should the system create a sessions table? Should session state live in memory, Redis, or the database? Claude may have considered these questions, but never turned them into an explicit proposal.
Rollback is expensive — every edit consumes tokens and attention; discarding the implementation wastes both.

The core pain: "think while writing" lets Claude generate diffs before the approach is stable, while the user cannot see the full design until the end.

How EnterPlanMode Fixes It

Claude first declares that it wants to enter plan mode and asks for the user's approval. That transition is itself an interactive confirmation. If the user declines, Claude remains in the default mode.

Step 1: Enter Read-Only Exploration

Claude's toolset becomes narrower:

✅ Available: Read, Glob, Grep, Agent, AskUserQuestion, and ExitPlanMode
❌ Disabled: Edit, Write, and NotebookEdit

Claude physically cannot modify project files. Every exploration action is read-only.

Step 2: Understand the Current System

Use Grep to find every JWT reference and discover the three internal services.
Use Read to inspect the current validation logic in auth/middleware.ts.
Use Glob to locate authentication-related tests.
Use Agent to assign a general-purpose subagent to investigate whether the project already has a session-store convention.

Step 3: Clarify Critical Forks with AskUserQuestion

For example:

Replace JWT only for the web app, or everywhere?
Store sessions in memory, Redis, or the database?

This is exactly the clarification pattern discussed in the previous post. AskUserQuestion and EnterPlanMode are natural partners.

Step 4: Write the Plan

Claude writes the complete proposal to a plan file: scope, affected files, migration steps, risks, and rollback strategy. This is a revisable, referenceable artifact—not a transient chat message.

Step 5: Request Approval with ExitPlanMode

The user sees the complete plan and chooses what happens next:

✅ Approve → Claude returns to implementation mode and executes the plan.
✏️ Request changes → Claude revises the plan using the feedback.
❌ Reject → Claude changes direction.

Not a single project file is modified before approval. The user's tokens, time, and attention are not spent implementing the wrong approach.

Side-by-Side Comparison

Anti-pattern pain	EnterPlanMode's solution
Directional error discovered five steps too late	No project files can be changed before ExitPlanMode approval
Unclear decision boundaries	AskUserQuestion clarifies critical forks inside plan mode
User cannot see the big picture	The plan file presents a complete proposal instead of scattered diffs
Important side effects are not surfaced	The enforced explore → design → present sequence gives Claude time to reason through them
High rollback cost	Exploration is read-only, so rejecting a plan requires no code rollback

When to Use It

The tool's official description contains an interesting rule: non-trivial implementation tasks should default to planning. This is a deliberately conservative bias.

Seven Situations That Call for Plan Mode

Implementing a new feature — even small features hide decisions: where should the code live, what should the button do, and how should errors be handled?
Multiple reasonable approaches — "add caching" may mean Redis, memory, or files; "real-time updates" may mean WebSockets, SSE, or polling. The choice itself is design work.
Changing existing behavior — "update the login flow" is ambiguous. Define the change before touching the code.
Making architectural decisions — patterns, dependencies, and data-flow direction should be agreed upon.
Changes spanning more than two or three files — the impact is large enough that a diff no longer communicates the whole design.
Unclear requirements — "make the app faster" requires profiling and a discussion of optimization priorities first.
Implementation shaped by user preferences — if you need AskUserQuestion to clarify the approach, you probably need EnterPlanMode to develop it.

Four Situations That Do Not

A one-line fix — correcting a typo or an obvious off-by-one error.
Adding one clearly specified function — implement it directly; there is no need for ceremony.
The user already supplied precise, detailed instructions — the user has already done the planning, so repeating it adds friction.
Pure research or exploration — use the Agent tool with an explore agent when no implementation will follow.

One phrase in the original description is especially revealing: "err on the side of planning." When uncertain, plan first. The default itself exposes the designers' preference: bias toward alignment over speed.

Technical Design

1. Naming

EnterPlanMode

AskUserQuestion carries signals across all four design layers. EnterPlanMode distributes them very differently: the name performs work that a schema might otherwise do.

Enter is a verb that implies moving into a state—not fetching data or performing a one-off action.
PlanMode names that state and forms a natural pair with ExitPlanMode.

Consider a counterfactual design: SetMode(mode: "plan"). The model might interpret that as setting a property and switch modes casually. The current name encodes a ceremonial state transition: entering is explicit, and exiting is explicit. Its semantics are much stronger than a parameterized SetMode.

That is why the schema can be empty. The name has already locked down the meaning, so the schema does not need to rescue it.

2. Tool-Level Description

EnterPlanMode's description revolves around four questions: when to use it, when not to use it, how it divides work with neighboring tools, and what happens at runtime.

A Conservative Opening Bias

Prefer using EnterPlanMode for implementation tasks unless they're simple.

One sentence reshapes Claude's behavior. When uncertain, plan instead of immediately acting. The tool starts by moving the default setting toward caution.

Quantified Thresholds for Seven Use Cases

The "When to Use This Tool" section lists seven numbered cases, each with concrete signals. A representative example is:

Multi-File Changes: The task will likely touch more than 2-3 files

This supplies a quantified threshold instead of asking Claude to trust a subjective feeling. Intuition becomes an operational rule, reducing inconsistency around whether plan mode is warranted.

The Boundary with AskUserQuestion

If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead

This turns a fuzzy boundary into a direct rule: AskUserQuestion handles isolated clarification, while approach-level forks call for plan mode. It prevents the anti-pattern of repeatedly asking disconnected questions and trying to assemble the answers into a plan afterward.

The Boundary with Agent

Pure research/exploration tasks (use the Agent tool with explore agent instead)

This defines another boundary: do not use EnterPlanMode for research that will not lead to implementation. Plan mode exists for planning before implementation. If implementation is not the goal, entering it is wasted motion; delegate the investigation to an explore agent instead.

User Approval Is Mandatory

This tool REQUIRES user approval - they must consent to entering plan mode

The AI cannot unilaterally change the workflow. The user guards the transition. This also explains why the tool accepts no arguments: the call itself is a request, not the execution of a parameterized operation.

The Default Under Uncertainty

If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work

This is the description's statement of values: a round of alignment is cheaper than an incorrect implementation and rollback. The same philosophy appeared in AskUserQuestion. Claude Code's tool ecosystem consistently favors alignment.

Planning as Collaboration Etiquette

Users appreciate being consulted before significant changes are made to their codebase

This sentence trains Claude's social intuition. Planning is not merely an efficiency mechanism; it respects the user's ownership of the codebase. The framing encourages Claude to treat consultation as good collaboration rather than an interruption.

3. Field-Level Descriptions

None.

EnterPlanMode has no input fields. Its schema is the empty object {}, so this layer does not exist. Every behavioral signal moves up into the tool-level description.

4. Schema Validation Rules

None.

The input_schema is empty: no fields, no types, and no constraints. Calling the tool is itself the intention to change state; there is no data to pass.

That absence is a design signal in its own right: permission is enforced at the tool and runtime layers, not the parameter layer. Claude does not need to request individual permissions or specify a target mode. After Claude calls EnterPlanMode, the runtime automatically:

Requires user approval, just as AskUserQuestion requires user interaction.
Narrows the tool allowlist by disabling Edit, Write, and NotebookEdit.
Refreshes CWD-dependent caches, including system-prompt sections, memory files, and the plans directory, so plan mode starts with clean context.
Keeps the state active until Claude explicitly calls ExitPlanMode.

Unlike AskUserQuestion, which ends after the answer arrives, plan mode is a persistent state.

Division of Responsibility with Neighboring Tools

AskUserQuestion — clarify one decision: "A or B?"
EnterPlanMode — develop the complete proposal; AskUserQuestion remains available while planning.
ExitPlanMode — submit the proposal for user approval.

Together, the three tools form a complete decision pipeline:

Encounter an unclear fork
    ↓
AskUserQuestion: clarify A vs. B
    ↓
EnterPlanMode: enter planning mode
    ├─ Explore with Grep / Read / Glob / Agent
    ├─ Clarify sub-decisions with AskUserQuestion as needed
    └─ Write the plan file
    ↓
ExitPlanMode: submit the plan
    ├─ User approves → return to default mode and implement
    ├─ User requests changes → revise in plan mode
    └─ User rejects → stop or change direction

As discussed in the AskUserQuestion post, Claude should not use AskUserQuestion inside plan mode for the meta-question, "Is this plan OK?" The reason is temporal: the user cannot see the plan until ExitPlanMode presents it for approval. Asking whether an invisible plan is acceptable is meaningless.

Takeaway

EnterPlanMode's elegance is not simply that it "makes the AI think before acting." It comes from an extremely uneven distribution of design signals:

The name carries the core semantics through the Enter/Exit pairing.
The tool-level description carries a dense set of behavioral constraints: seven use cases, a conservative default, neighboring-tool boundaries, and collaboration etiquette.
The field-description and schema-validation layers are empty.

That reveals a deeper principle: an empty schema is itself a design choice. When a tool's meaning is "transition into a state," parameterizing it can weaken the meaning. SetMode invites casual switching. A zero-argument EnterPlanMode is a deliberate, ceremonial request.

The next post will examine ExitPlanMode, the final stage of this three-tool decision pipeline, and unpack how "submit a plan for approval" is designed.

Claude Code Tools Deep Dive #0 — How the Tool Mechanism Actually Works

Zhengxin — Sat, 01 Aug 2026 17:58:41 +0000

Each post in this series will dissect one specific Claude Code tool. But first, we need a shared foundation: What is a tool, and how does Claude use one? Every later deep dive builds on this mechanism.

Why Tools Exist

An LLM, by itself, can only generate text. That creates two fundamental limitations:

It cannot act on the outside world. Generating the sentence “I deleted the file” does not actually delete anything.
Its output is not inherently reliable. A model may return malformed structures, omit fields, or hallucinate content, making the result unsafe for downstream programs to consume.

Tools fill both gaps:

Actions — a tool declares an executable function. When the model calls it, the harness performs the real operation: reading a file, sending a request, switching modes, and so on.
Structure — a JSON Schema defines the input. The model must produce arguments that conform to that schema; invalid input can be rejected before execution.

From this perspective, a tool does not simply “make the LLM more powerful.” It creates a trusted channel between the LLM and the outside world.

What a Tool Definition Looks Like

In the Anthropic API, a tool definition is a JSON object. Here is a simplified version of AskUserQuestion:

{
  "name": "AskUserQuestion",
  "description": "Use this tool only when you are blocked on a decision that is genuinely the user's to make: one you cannot resolve from the request, the code, or sensible defaults. ...",
  "input_schema": {
    "type": "object",
    "properties": {
      "questions": {
        "type": "array",
        "description": "Questions to ask the user (1-4 questions)",
        "minItems": 1,
        "maxItems": 4,
        "items": {
          "type": "object",
          "properties": {
            "question": {
              "type": "string",
              "description": "The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: \"Which library should we use for date formatting?\""
            },
            "header": {
              "type": "string",
              "maxLength": 12,
              "description": "Very short label displayed as a chip/tag (max 12 chars). Examples: \"Auth method\", \"Library\", \"Approach\"."
            },
            "multiSelect": {
              "type": "boolean",
              "default": false,
              "description": "Set to true to allow the user to select multiple options ..."
            },
            "options": {
              "type": "array",
              "minItems": 2,
              "maxItems": 4,
              "items": { "...": "..." }
            }
          },
          "required": ["question", "header", "options"]
        }
      }
    },
    "required": ["questions"]
  }
}

There are three top-level fields:

name — the tool's unique identifier and a naming signal the model can interpret
description — natural-language guidance explaining what the tool does, when to use it, and when not to use it
input_schema — a JSON Schema defining the argument structure, field-level descriptions, and validation rules

That is the entire tool definition. There is no hidden configuration inside the definition itself. Every design intention must be encoded in these three fields.

The Four Layers of a Tool Definition

Later posts will analyze each tool through four layers. These layers are simply an expanded view of the three top-level fields:

Layer	Location	Purpose
1. Naming	`name` and field names inside the schema	Communicates meaning through names
2. Tool-level description	`description`	Helps the model decide, “Is this the tool I should use?”
3. Field-level descriptions	Each field's `description` inside `input_schema`	Tells the model what belongs in each field
4. Schema validation	`type`, `minItems`, `maxLength`, `enum`, and so on	Hard-blocks invalid input

The signal density decreases while coverage increases:

Naming — understood from a single word and reinforced every time the model encounters the field
Tool description — available whenever the model considers using the tool; defines the broad behavioral boundary
Field description — becomes most relevant while the model is filling that field; provides a precise hint
Schema validation — becomes visible when the model gets something wrong; acts as a hard guardrail

Together, these four layers form the complete prompting surface of a tool definition.

How Claude “Reads” Tool Definitions

The important point is that the available tool definitions are sent with the model request, rather than appearing only after a tool has been selected.

The flow looks roughly like this:

The harness collects all available tool definitions.
On each request to Claude, it includes the tool list in the API's tools parameter.
Claude receives the system instructions, the available tool definitions, and the conversation history as part of the request context.

This has two direct consequences:

Every word in a description costs tokens. If your tool definitions total 20 KB, that payload must be processed across requests, and the cost compounds over a long conversation.
A tool description can reference neighboring tools. Because the model sees the available definitions together, AskUserQuestion can say, for example, “Do not use this to ask whether the plan is OK; that is ExitPlanMode's responsibility.”

That is why a good tool description must be both short and precise. Short saves tokens; precise ensures that every sentence defines a responsibility, boundary, or collaboration contract.

How Claude Calls a Tool

A tool call is a message round trip.

Step 1: The Model Emits a `tool_use` Block

When Claude decides to use a tool, it does not execute the tool directly. Instead, it emits a special block in its response:

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "AskUserQuestion",
  "input": {
    "questions": [
      {
        "question": "Which authentication method should we use?",
        "header": "Auth method",
        "options": [
          {
            "label": "JWT (Recommended)",
            "description": "Stateless and easy to scale horizontally"
          },
          {
            "label": "Session cookie",
            "description": "Uses a server-side session store"
          },
          {
            "label": "OAuth",
            "description": "Connects to a third-party identity provider"
          }
        ]
      }
    ]
  }
}

Step 2: The Harness Intercepts and Executes It

The harness intercepts the model's output, finds the implementation associated with name, and passes it the input. That implementation might be a local function, an external service, or a UI interaction.

Step 3: The Harness Returns a `tool_result`

After execution, the harness sends the result back to the model:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "content": "The user selected: JWT (Recommended)"
}

This block is included in the next message sent to Claude. Claude then continues: it may call another tool based on the result, or it may respond to the user in plain text.

Throughout the process, the model is the decision-maker. It decides when to call a tool, which tool to call, what arguments to pass, and how to use the result. The harness is responsible for execution and for carrying messages between the model and the tool implementation.

Two Tool-Result Modes

Success

A successful tool_result carries content:

{
  "type": "tool_result",
  "tool_use_id": "...",
  "content": "..."
}

The content may be plain text or structured content blocks, such as multiple text segments and images.

Failure

A failed result adds is_error: true:

{
  "type": "tool_result",
  "tool_use_id": "...",
  "content": "Error: file not found",
  "is_error": true
}

This is a loud failure: the error is not silently swallowed. The model can see the failure and decide what to do next—retry, choose a different approach, or ask the user.

This is also why strict schema validation matters. A harness can reject invalid input explicitly instead of allowing the model to continue with an empty or semantically ambiguous result.

Tool Results Consume Context Too

Every tool_result returned to the model becomes part of the conversation context. That means result size must be controlled:

A grep result containing 100,000 lines can exhaust the context window almost instantly.
Good tools summarize, truncate, or paginate their output before returning it.
A read tool might default to a fixed number of lines; a search tool might expose a result limit.

This explains why many of Claude Code's read-oriented tools return deliberately compact results. It is not a lack of capability; it is intentional context-budget management.

Tools Are Structured Prompt Engineering

Compare two approaches.

Free-form prompt version:

You can call a function named AskUserQuestion to ask the user a question. After the user chooses, you will receive the answer.

Tool version:

name = AskUserQuestion
description = detailed behavioral constraints
input_schema = exact field types, validation rules, and examples

The difference is not whether the function can be implemented. The difference is whether it can behave reliably:

Dimension	Free-form prompt	Tool
Structure	The model improvises	JSON Schema provides hard constraints
Failure	Malformed output may fail silently or produce a bad value	Schema validation rejects it explicitly
Boundaries	The model decides based on intuition	The description states when to use and not use it
Composition	The model must remember how several functions relate	Tool descriptions can reference neighboring tools directly
Main-loop visibility	Results are mixed into conversational text	Structured `tool_use` and `tool_result` blocks can be intercepted by the harness

A tool is, fundamentally, structured prompt engineering. It turns the soft requirement “make the model do this reliably” into a specification that is validatable, composable, and maintainable.

What Comes Next

With the mechanism established, every later post in this series will use the same outline to dissect one concrete tool:

Purpose
A concrete example, including a counterexample
Trigger conditions
Technical implementation across four layers
- Naming
- Tool-level description
- Field-level descriptions
- Schema validation rules
Division of responsibility with neighboring tools
Takeaway

This prelude explains the mechanism: what tools are and how Claude uses them. The rest of the series focuses on design: how a specific tool uses all four layers to turn a capability from merely “possible” into something stable, predictable, and composable.

Next: AskUserQuestion—how Claude Code turns “AI asking a question” into a structured interaction primitive.

Claude Code Tools Deep Dive #1 — AskUserQuestion

Zhengxin — Tue, 28 Jul 2026 15:20:18 +0000

I've spent some time reverse-engineering the design of Claude Code and even wrote a stripped-down Java clone — open source at jooj. One thing that keeps striking me: every tool Claude Code ships with is carefully designed. So I'm starting a series to unpack them one by one.

This first post is about AskUserQuestion — one of the most commonly seen tools, and one whose design is easy to underestimate.

What AskUserQuestion Actually Is

AskUserQuestion is Claude Code's built-in structured question tool. Instead of Claude emitting a plain-text question and waiting for the user to type back, this tool renders the question as an interactive selection panel — the user sees a set of predefined options (as cards), not a wall of text.

The core problem it solves is efficient alignment between AI and user:

Lowers user effort — clicking an option is faster than typing a reply
Structured input — Claude gets an unambiguous enum value, no natural-language parsing needed
Converges ambiguity — the preset options force a choice among concrete alternatives instead of a vague "you decide"
Escape hatch — the system always appends an implicit "Other" option so users are never boxed in

A Concrete Example

Before diving into triggers, implementation, and prompt details, let's ground everything with a real scenario. Compare "life without AskUserQuestion" vs "life with it."

Scenario: the user tells Claude "help me add user login to this app."

That request is severely under-specified — no decision on auth method, no decision on where to store the credential. Claude can't just guess (the team might have conventions), and it can't infer from the code either (it's a new feature with no precedent).

The Anti-Pattern: What Happens Without AskUserQuestion

Claude can only throw the question back as a plain-text prompt, something like:

"Which auth method do you want? I'd suggest JWT, but session cookies or OAuth also work. Also, where should we store the credential — httpOnly cookie or localStorage?"

The user immediately hits several problems:

High cognitive load — one paragraph packs in 2 decisions and 5 options; the user has to parse the question before answering
High answer cost — they either type a reply ("JWT + httpOnly") or spend two hours Googling "JWT vs session cookies" before coming back
High parsing cost for Claude — a reply like "let's go with JWT, and the cookie one" forces Claude to figure out which option the user actually picked, with room for misinterpretation
Recommendation drowns in text — Claude says "I'd suggest JWT" but it's blended into the paragraph, easy to miss
No fallback — if the user wants an option Claude didn't list (e.g. magic email links), they have to break out with a separate explanation or accept being funneled into a three-way choice

The core pain: free-text form turns "collaborative alignment" into an expensive natural-language round-trip.

The Fix: How AskUserQuestion Solves It

Claude constructs a single call containing two questions. The user sees two cards like this:

Question 1 — Auth method

Question 2 — Credential storage

Each card has a short chip label at the top ("Auth method" / "Token storage"), followed by 3 / 2 options, plus an automatically appended "Other". Two clicks and Claude receives roughly:

Question 1 → user picked JWT (Recommended)
Question 2 → user picked httpOnly cookie (Recommended)

Decision time compressed from minutes to seconds. That's the point of AskUserQuestion — not "let the AI ask a question," but "make every clarification in the collaboration cheap."

Side-by-Side: Each Pain Point Solved

Anti-pattern pain	AskUserQuestion's fix
High cognitive load	Split into 2 independent cards, one decision at a time
High answer cost	Click instead of type; trade-offs sit right under each option
High parsing cost for Claude	Return value is an explicit label — no NL parsing needed
Recommendation drowns in text	"(Recommended)" suffix + first position — impossible to miss
No fallback	"Other" is auto-appended; a custom answer is always one field away

Every design decision below traces back to exactly one of these pains. Keep this mapping in mind — you'll see each constraint in the tool description addressing a specific row in this table.

When to Fire It

The tool description spells out the boundary: only when you're blocked, and only when the decision is genuinely the user's.

Three "yes, ask" situations:

Can't infer from the request — the requirement itself is vague (e.g. "add login" with no auth method specified)
Can't infer from the code — there's no existing pattern to mimic
No sensible default — the choice involves taste, business rules, or architectural forks that AI shouldn't decide unilaterally

Three "no, don't ask" situations:

The answer is in the code — spend time reading, don't interrupt the user
Only one obviously reasonable path — just do it, explain in the commit message
In plan mode asking "is my plan OK?" — that's ExitPlanMode's job, using Ask here is a duplication

A canonical anti-pattern: avoid meta-questions like "does this plan look good?" or "can I proceed?". ExitPlanMode already exists to request approval — using Ask for the same purpose is pure redundancy.

Schema Design

Reverse-engineering from the tool's input schema, the core structure looks like this:

Claude passes in a list of questions (1 to 4). Each question object has four parts:

question — the full question text, ending with a ?
header — a very short chip label displayed at the top of the card (max 12 chars)
multiSelect — boolean; whether multiple options can be selected (default false)
options — a list of 2 to 4 options

Each option object has three fields:

label — the display text the user sees (1 to 5 words)
description — an explanation of what the option means / the trade-off
preview — optional; when the difference between options needs visual comparison (mockups, code snippets), this content is rendered when the option is focused

A few key design choices:

1–4 questions per call — supports batched decisions (like "auth method + token storage" in one call), but prevents Claude from bombarding the user with 10 questions at once
2–4 options per question — forces Claude to pre-categorize, converging N possibilities into a small set of clickable choices instead of dumping a long list
"Other" is implicit — auto-appended by the UI, Claude doesn't hand-list it. This guarantees "options Claude thought of ≠ complete space" doesn't trap the user
Recommendation mechanism — if Claude has a preference, put it first + append "(Recommended)" to the label. The user spots it at a glance
Return value shape — keyed by question text, mapped to the selected label; a separate annotations field carries user notes for preview-based options

The preview field is a subtle-but-powerful escalation — when options differ visually (two UI mockups, two code styles), embedding the visual in preview lets the UI render it live as the option gets focus. Perfect for "which API shape" or "which layout" questions.

Division of labor with EnterPlanMode / ExitPlanMode:

In plan mode: use AskUserQuestion to clarify "which approach" (before finalizing)
In plan mode: do NOT use AskUserQuestion to ask "is my plan ready?" (use ExitPlanMode)
Outside plan mode: use AskUserQuestion for any technical fork that needs user judgment

The three tools form a complete decision pipeline: Ask clarifies → EnterPlanMode expands → ExitPlanMode commits.

Prompt Breakdown

Every sentence in the tool description encodes a behavior constraint. Let's decompose them.

Constraint 1: Strict applicability boundary (opening sentence)

Use this tool only when you are blocked on a decision that is genuinely the user's to make: one you cannot resolve from the request, the code, or sensible defaults.

This trains Claude to not interrupt — when uncertain, the first move should be to check the code and try sensible defaults, not throw a question at the user.

Constraint 2: Making the "Other" escape hatch transparent

Users will always be able to select "Other" to provide custom text input

Instead of hiding "Other" from Claude and letting it invent a custom option, the tool description states outright: "Other is auto-added; you don't list it." This prevents Claude from wasting one of its 2–4 option slots on a hand-rolled "custom" entry.

Constraint 3: multiSelect semantics

Use multiSelect: true to allow multiple answers to be selected for a question

Use cases: pick multiple feature flags / multiple environments / multiple files to modify. Defaulting to false protects users from decision paralysis.

Constraint 4: How to express a recommendation

If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label

Interesting design point: the recommendation isn't a separate field — it's encoded via convention (position + suffix). The benefits:

Keeps the schema simple; no recommended: true boolean field
The UI just renders the label; no special-case handling
Claude's endorsement must be visible in the label — impossible to hide in metadata, the user sees it immediately

Constraint 5: Temporal ordering with plan mode

Plan mode note: To switch into plan mode, use EnterPlanMode (not this tool). Once in plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?", "Should I proceed?", or otherwise reference "the plan" in questions — the user cannot see the plan until you call ExitPlanMode for approval.

This is the most instructive passage — it locks in the temporal ordering of the workflow:

In plan mode: use Ask to clarify approach forks (e.g. "A or B?")
Once clarified: use EnterPlanMode to draft a full plan
Finally: use ExitPlanMode to request approval — do NOT loop back to Ask with "OK to proceed?"

Especially note the last clause — "the user cannot see the plan until you call ExitPlanMode for approval" — this is the real reason you shouldn't ask "is my plan OK?" in plan mode. It's not just redundancy: the user literally has nothing to approve until ExitPlanMode fires.

Three tools, each with a distinct role: Ask (clarify) / EnterPlanMode (expand) / ExitPlanMode (commit). The constraint fundamentally prevents Claude from looping back into Ask to serve as its own approval mechanism.

Constraint 6: The header chip is mandatory (enforced at the schema layer)

Very short label displayed as a chip/tag (max 12 chars). Examples: "Auth method", "Library", "Approach".

A UX constraint — the UI renders each question as a card with a chip at the top. The chip uses header, not the full question text. This forces Claude to condense a long question ("Which authentication method should we use for the login flow?") into a tight chip ("Auth method").

Constraint 7: Questions must end with a question mark

Should be clear, specific, and end with a question mark.

Looks trivial, but it shapes the UI's tone — a question form vs a statement form triggers a completely different psychological response. Indirectly, this forces Claude to phrase the content as a genuine query, not a disguised instruction.

Takeaway

The elegance of AskUserQuestion isn't in the surface feature "let the AI ask users questions." It's in how the schema constraints + prompt constraints together lock down when to ask / how to ask / how it's rendered / how it composes with other tools. It takes the general-purpose capability "AI asking questions" and refines it into a predictable, composable, maintainable interaction primitive.

How can I do，let more people read My post?

Zhengxin — Sat, 25 Jul 2026 17:06:23 +0000

From One-Shot LLM to Multi-Turn Agent: How I Rebuilt My Text-to-Diagram Tool

Zhengxin — Sat, 25 Jul 2026 16:57:24 +0000

The problem: one LLM call isn't enough

I built an AI tool that turns natural language into editable diagrams. You describe a flow, an LLM generates Mermaid code, and the result renders in real time.

The v1 was a single LLM call: user input → LLM → diagram. After a few days in production, two failure modes kept showing up:

Syntax errors with no recovery. The generated Mermaid code looks correct, but Mermaid throws a Parse error and the user sees a red stack trace. They leave.
Silent semantic drift. The user asks for "a login flow" — the LLM helpfully adds a "send verification code" actor. It doesn't ask. It doesn't tell you it added anything.

Neither problem can be reliably fixed by "tweaking the prompt." The first needs a second chance; the second needs an audit trail.

So v2 became an agent: multi-turn dialogue, self-correction, and — critically — a memory of what the user said and didn't say. This post is about what that agent actually looks like.

Core insight: this isn't one loop, it's two

What looks like "a multi-turn diagram generator" is actually two loops with different goals:

Outer loop · Understand the request
User speaks → extract facts → detect gaps → ask → refine

Inner loop · Generate and repair
Structured spec → generate code → validate → fix → output

The outer loop asks, "Do I understand the request well enough?" The inner loop asks, "Is the generated code correct?"

Trying to do both in one loop leads to the question "should the agent ask the user about this ambiguity?" — a question with no answer, because outer-loop ambiguity (user hasn't specified) and inner-loop ambiguity (generation went off-script) are fundamentally different.

The agent is a team — divide the work

I model the agent as a law firm handling a case. Each role does exactly one thing:

Role	Does	Does NOT
Clerk	Records facts the user explicitly stated	Never guesses or infers
Auditor	Notes which fields in the record are empty	Doesn't decide whether to ask
Planner	Decides whether/what to ask the user	Doesn't ask directly
Lawyer	Drafts Mermaid, filling reasonable gaps	Leaves assumptions unrecorded
Reviewer	Checks syntax + flags unauthorized additions	Rewrites the user's requirements
Front Desk	Sequences the roles, maintains the case file	Makes no judgment calls

Initially I stuffed all of this into a single mega-prompt. Debugging was hell — I couldn't tell whether the Clerk hallucinated a fact or whether the Lawyer improvised a character. Splitting them out means each role is a pure function: same input → same output, testable in isolation.

The call graph: Front Desk orchestrates everyone

The six roles don't operate in parallel — they're a pipeline, and Front Desk is the sole orchestrator:

User message
    ↓
  Front Desk  (append to conversation history)
    ↓
  Clerk    ──→ extract facts from history, populate the case file
    ↓
  Auditor  ──→ list which fields are still empty
    ↓
  Planner  ──→ decide next action using (missing list + budget + past questions)
    │
    ├─ "Ask one"     ──→ Front Desk renders question ──→ User
    │                                 ↑  (next turn loops back to top)
    │
    └─ "We have enough" ──→ Lawyer  ──→ generate Mermaid code
                                          ↓
                                    Reviewer · syntax check
                                          │
                                          ├─ FAIL ──→ inner repair loop (back to Lawyer)
                                          │
                                          └─ OK   ──→ Reviewer · semantic check
                                                          ↓
                                                    Unauthorized additions?
                                                          │
                                                    ├─ Yes → diagram + follow-up question
                                                    │
                                                    └─ No  → diagram only
                                                              ↓
                                                             User

A few points worth noting:

Front Desk is the only stateful component. Every other role is a pure function. Multi-turn memory lives entirely in the case file that Front Desk maintains.
Planner is the only branching point. The agent's "ask vs draw" decision happens in one function, nowhere else.
The inner repair loop runs between Lawyer and Reviewer without bothering the user. Mermaid syntax self-healing lives here.
Semantic issues don't block output — they're delivered alongside the diagram ("here's your diagram, by the way, I added this thing — want to keep it?"). Users find it easier to judge with the picture in front of them.

The foundation rule: Clerk is conservative, Lawyer can improvise

If you take one thing away from this post, take this.

User says: "Draw a login flow. User enters password, system verifies, returns result."

The Clerk outputs:

{
  actors: ["user", "system"],
  events: [
    { from: "user", to: "system", action: "enter password" },
    { from: "system", to: "user", action: "return result" },
  ],
  sync: "unknown"    // ← user didn't say sync/async. NEVER guess.
}

That sync: "unknown" is the signal that triggers a question — the Auditor flags it, the Planner decides whether to ask.

If the Clerk "helpfully" fills it in ("login is usually sync"), that signal is destroyed. The agent can no longer distinguish "user actually said sync" from "I made it up." Every follow-up decision downstream is corrupted.

The Lawyer operates under a different constraint: it may fill in a "verification service" as a reasonable assumption, but that assumption must be written to the case file's assumptions slot. Later the Reviewer reconciles every element in the diagram: it must trace back to either "the user said this" or "the Lawyer assumed this." Anything that traces to neither is called an unauthorized addition, and it becomes a follow-up question ("I added X. Keep it?").

This one rule solves a class of nasty bugs by itself — including the classic "user said 'no X', LLM keeps re-adding X on regeneration." Because unauthorized additions are detectable, the agent surfaces them proactively instead of leaving the user to catch them.

The Planner: one function, one decision

My favorite architectural decision: every "should we ask the user?" judgment lives in a single pure function — the Planner.

Auditor and Reviewer only identify problems — what's missing, what's wrong.
Planner takes three inputs: candidate question pool, remaining budget, and past questions asked.
Planner outputs one of three: AskOne / ProceedToDraw / AskConfirm.

Each session has a global budget (say, 5 agent-initiated questions). Note the framing: only the agent's proactive questions consume the budget. User-initiated changes — modifying the spec, tweaking the diagram, requesting a redraw — do not consume it. This prevents the kind of UX where users become more reluctant to speak the longer they use the tool.

The practical payoff: want to change ask frequency or budget policy? Edit one function. No other component moves.

A walkthrough — 4 turns of dialogue

Architecture is easier when you see it in motion:

Turn 1  User: "Draw a user registration sequence diagram"
        Clerk    → { actors: ["user"], events: [], sync: unknown }
        Auditor  → missing: actors / events / sync
        Planner (budget=5) → ask actors
        Agent: "Besides the user, which other roles are involved?"
        [budget: 5 → 4]

Turn 2-3  User: frontend / backend / database, plus each step
          Planner asks per turn, budget: 4 → 3 → 2

Turn 4  User: "Just draw it and see"  ← skip clarification, no budget cost
        Lawyer  gen #1 → helpfully adds "send email notification" (never mentioned)
        Reviewer syntax check → FAIL (undeclared email actor)
        Inner repair loop → Lawyer gen #2, drops email → syntax OK
        Reviewer semantic check → 3 response arrows not grounded in the case file
                                → unauthorized additions
        Output: diagram + prompt "I added a full response flow. Keep it?"

Turn 5  User: "No responses. Just draw up to the database write."
        Agent records "response flow" as a negative fact (explicitly rejected)
        Regenerate → no response arrows
        [budget unchanged — this is user reviewing output, not agent asking]

5-unit budget, 3 agent-initiated questions used, 2 in reserve. That's the flexibility of a global budget with clean semantics.

What it takes to add a new diagram type

The system supports 8 diagram types: Sequence · Flowchart · ERD · State · Class · Mindmap · Gantt · Architecture.

Adding a new type means implementing four type-specific pieces:

Clerk — how to extract facts from natural language for this type
Auditor — which fields are required vs optional
Reviewer — what counts as an unauthorized addition
Question templates — how to phrase prompts (a sequence diagram asks about "actors", a class diagram asks about "entities")

Planner / Front Desk / state store don't move — they don't care what type of diagram is being drawn.

Three takeaways worth stealing

Split the two loops. "Understand the request" and "generate the code" are different problems that happen to share state. Fusing them creates the unanswerable "should we ask about this ambiguity?" trap.
Clerk conservative + Lawyer improvises, strictly separated. If your Clerk fills in gaps, you've handed the agent's judgment to the LLM's intuition. Every Lawyer assumption must be written down so the Reviewer can audit it.
All policy lives in one Planner function. Want to change ask cadence, budget policy, or the "when to confirm" heuristic? One file. Zero downstream ripples.

What's next

I'm currently working on:

Auto-classification confidence calibration (when the user doesn't state the diagram type, how often does the LLM guess wrong?)
Extending the "unauthorized addition" rule set for each diagram type
One-click session replay: serialize prompt + spec + generated diagram into a shareable link, so bug reports can replay the entire agent state

If you're building a similar multi-turn LLM agent — whether for diagrams, SQL, API mocks, or something else — these three principles saved me weeks of pain. An agent is not just "call the LLM more times." It's a team designed to self-correct, remember negative feedback, and produce an audit trail for every decision.

Try it: text2everything.vip

Beyond the IDE: Building an AI-Native Development Workflow with Obsidian

Zhengxin — Thu, 23 Jul 2026 10:23:52 +0000

Code is no longer the primary artifact. Context is.

1. AI Has Outgrown the IDE: From an IDE to a "Cognitive Layer"

Using IntelliJ IDEA with AI plugins exposes several limitations:

You ask a question, AI generates a code snippet, and you manually review the result.
Previous conversations with AI are difficult to search.
As conversations grow longer, the AI loses focus due to accumulated context. Start a new session, and its memory resets—you have to teach it the project all over again.
A single feature often spans multiple microservices, meaning the implementation lives across several codebases.
From IDEA's perspective, there's only code. It has no awareness of database schemas, middleware, infrastructure, or architecture documentation.

Traditional IDEs are no longer sufficient for AI-assisted software development.

2. What Is Obsidian? A Local-First Markdown Knowledge Base

Official website: https://obsidian.md/

Obsidian is a local-first knowledge management tool built entirely on plain Markdown files. Its core strengths include:

Local ownership. Every note is simply a .md file stored on your disk. Nothing is locked inside a proprietary cloud service. Everything works offline and remains fully under your control.
Bidirectional links (Wiki-links). [[note-name]] connects notes into a knowledge graph, while backlinks automatically show every page that references the current one.
Graph View. Visualize the relationships between notes to understand the structure of your knowledge base at a glance.
Rich plugin ecosystem. Community plugins extend Obsidian into a task manager, calendar, Dataview database, AI workspace, and much more.
AI-friendly plain text. Since everything is UTF-8 Markdown, AI models can read, write, diff, and edit notes directly—without requiring the specialized plugin bridges typical IDEs need.

Looking back at the pain points of using IDEA with AI, Obsidian addresses every one of them:

IDEA + AI Problem	Obsidian Solution
AI conversations become disposable and difficult to review	Notes are persistent documents. Every AI edit is preserved, traceable, and reviewable.
Conversation history is hard to search	Full-text search, backlinks, and tags turn conversations into searchable knowledge assets.
Context grows too large, while new sessions lose memory	Project context is explicitly stored in notes. Simply have the AI read the notes to restore context.
One feature spans multiple microservices	A single vault can contain documentation for Services A, B, and C, with links connecting them.
IDEA only understands source code	The vault can hold architecture notes, database schemas, Kafka topics, deployment diagrams, and more alongside the code.

In other words, Obsidian is not replacing IDEA as your code editor.

It replaces IDEA as your cognitive layer.

You continue writing code inside IDEA, while everything surrounding the code—design decisions, AI conversations, database schemas, architectural diagrams, and cross-service relationships—lives permanently inside Obsidian.

3. Environment Setup: Obsidian + Claudian

Install Obsidian and enable community plugins.
Install the Claudian plugin from GitHub,https://github.com/YishenTu/claudian

4. The Theory: Karpathy's "Wiki as Codebase"

Source: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
Andrej Karpathy's Wiki as Codebase gist.

He summarizes the idea in a single sentence:

"Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase."

Every note you write is no longer just documentation.

Instead, it becomes part of the codebase maintained by an LLM—except that instead of executable instructions, it stores structured knowledge about your project.

4.1 The Three-Layer Architecture

Karpathy divides the system into three layers, corresponding to three types of files inside your vault.

Layer	Definition	Example
Raw Sources	Immutable source material. Read-only for the LLM.	Meeting notes, PDFs, code diffs, web clippings
The Wiki	Markdown pages generated and maintained by the LLM	Analysis notes, architecture documentation, ADRs
The Schema	Rules that make the LLM a disciplined maintainer	`CLAUDE.md` at the vault root

The important insight is that CLAUDE.md is much more than project instructions.

It acts as the schema governing the knowledge base.

The schema determines whether the LLM behaves like an ordinary chatbot—or like a disciplined maintainer of a living wiki.

4.2 Three Core Operations

Within this wiki, the LLM performs three kinds of work.

Ingest

Consume new raw materials, update multiple wiki pages, and maintain cross-references.

Query

Search the wiki, synthesize answers, and write valuable results back as new knowledge pages.

Lint

Detect inconsistencies, outdated information, orphan pages, and missing links.

Most people already perform the first two.

Linting is the new capability.

Just as source code benefits from linting, so does your knowledge base.

4.3 Why This Is Finally Practical

Organizations have long abandoned internal wikis because the maintenance cost exceeded the benefit.

Keeping links updated, eliminating contradictions, and maintaining structure simply required too much human effort.

LLMs remove that bottleneck.

Humans now focus on:

selecting high-quality source material,
directing the analysis,
asking good questions.

Meanwhile, the LLM performs all the bookkeeping:

updating dozens of pages,
maintaining links,
synchronizing knowledge,
resolving inconsistencies.

The breakthrough isn't that Obsidian became more powerful.

It's that the cost of maintaining a wiki has shifted from humans to LLMs.

5. Workflow: One Vault, One `CLAUDE.md`, Four Everyday Habits

5.1 One Vault per Project

Instead of storing everything in one giant vault, create one vault for each project.

Place a CLAUDE.md file at the root containing:

technology stack
repository structure
commit conventions
common pitfalls
recurring project context

Claudian automatically loads this file whenever a new session starts, eliminating the need to repeatedly explain your project.

5.2 Typical Development Workflow

The traditional workflow looked like this:

Open AI sidebar → Ask a question → Copy code → Close sidebar → Lose context.

The new workflow becomes:

Create a requirement note containing the background, objectives, and constraints.
Have the AI read the relevant context by linking architecture docs, database schemas, and previous requirement notes with [[...]].
Collaboratively analyze the problem through conversation.
Let the AI write important decisions back into the notes.
Return to IDEA and implement the code.
Once implementation is complete, record:

why the design changed,
lessons learned,
commit hash.
1. Future work simply reuses these notes as project context.

The mindset changes fundamentally.

AI output is no longer disposable conversation.

It becomes permanent project documentation.

5.3 High-Frequency Workflows

Some particularly useful habits include:

@-reference notes to inject documents directly into AI conversations, especially for coordinating across services.
Paste code into notes and let AI edit it, preserving the entire discussion history.
Architecture Decision Records (ADRs) with one note per architectural decision, linked together via wiki links.
Daily Notes for debugging and investigation, allowing AI to follow your reasoning process over time.
Graph View to quickly identify densely connected core modules and isolated knowledge gaps.

5.4 Division of Responsibilities

Task	IntelliJ IDEA	Obsidian + Claudian
Coding, debugging, testing	✅
Breakpoint debugging, profiling	✅
Requirements analysis		✅
Architecture design		✅
Database documentation		✅
Long AI conversations		✅
Cross-service context		✅
Team knowledge sharing		✅

In short:

IDEA writes the code.

Obsidian manages the brain.

6. Case Study: A Two-Week Refactoring Project

One local project involved:

Six implementation phases (P1–P6)
Four rounds of architectural refactoring
Fifteen technical decisions (D1–D15)
Thirteen commits
Two weeks of continuous work

Managing this entirely inside an IDE would have been nearly impossible.

Each new AI session would require reconstructing the project's context from scratch.

Obsidian solved this in five ways:

A master planning note guided every conversation and was continuously updated by the AI.
All fifteen architectural decisions were documented, including background, alternatives, final choice, and rationale.
Session continuity became effortless. On day seven, a simple "Read this note and continue" restored the entire project context.
Commit hashes were written back into the notes, turning them into a living changelog.
Lessons learned were ultimately incorporated into CLAUDE.md, allowing future sessions to begin with full project knowledge.

Without this workflow:

Design decisions would be scattered across dozens of conversations.
Every new AI session would waste twenty minutes rebuilding context.
The architectural intent behind each commit would be forgotten within a few months.

The larger and longer a project becomes, the more valuable the Obsidian + Claudian workflow proves to be.

It isn't just a productivity enhancement.

It is the infrastructure that makes long-running, AI-assisted software engineering practical.

7. Practice: Linting Your Obsidian Vault

The most practical habit is to regularly let AI lint your vault.

Treat your knowledge base the same way you treat your source code.

Two simple linting tasks provide enormous value.

7.1 Dead-Link Scan

Prompt:

Scan the entire vault and find every [[wiki-link]] whose target file does not exist. Sort the results by reference count. Output the top 30. Ignore image embeds, code blocks, and Templater variables.

The results generally fall into six categories.

Category	Example	Action
Daily note navigation	`[[2026-05-14]]`	Usually harmless
Template placeholders	`[[<% after_date %>]]`	Ignore
Web clipping artifacts	URLs or usernames converted into wiki links	Batch cleanup
Missing concept pages	Frequently referenced but nonexistent notes	Create the missing note
Typos	Incorrect capitalization or trailing characters	Fix immediately
Missing MOC pages	Referenced index pages that don't exist	Create an index page

The most valuable category is the fourth.

Frequently referenced dead links reveal concepts you've repeatedly intended to document—but never actually did.

They become a concrete to-do list generated by your own knowledge graph.

7.2 Orphan Page Scan

Prompt:

Find every note that is never referenced by another note via wiki links. Exclude daily notes, entry pages, CLAUDE.md, and empty notes. Sort by file size, largest first.

Typical results include:

Large orphan clusters

Entire collections—such as book notes or article series—remain disconnected.

The solution isn't adding one link.

You likely need a Map of Content (MOC) to organize the entire collection.

Orphan entry pages

Pages intended as dashboards or indexes receive no incoming links.

An entrance nobody reaches isn't an entrance at all.

Empty notes

Drafts containing only a title should simply be deleted.

7.3 Why Regular Linting Matters

A single lint run provides four concrete benefits:

A prioritized list of missing core notes
Discovery of structural weaknesses in your knowledge organization
Cleanup of stale data, typos, and clipping artifacts
Validation that important entry pages are actually reachable

A practical cadence is:

once per month, or
after importing a large amount of new material into your vault.

Without periodic linting, most vaults eventually become graveyards of broken links and isolated notes.

With regular linting, every page remains connected, discoverable, and useful.

This is precisely what Karpathy means by treating a wiki like a codebase.

8. Conclusion: IDEA Handles the Code; Obsidian + Claudian Handle the Thinking

IntelliJ IDEA remains an excellent code editor.
Obsidian provides the missing cognitive layer, preserving design intent, AI conversations, architecture, database knowledge, and cross-service context.
Claudian serves as the bridge, allowing AI to directly maintain your knowledge graph rather than acting as a disposable question-and-answer tool.
CLAUDE.md functions as the schema that transforms an LLM from a chatbot into a disciplined knowledge-base maintainer.
Linting is the essential maintenance routine that keeps your vault healthy over the long term.

Together, they form what can truly be called an AI-native development environment.

Instead of simply embedding AI into an IDE sidebar, this workflow reimagines software development around knowledge organization, making AI a first-class participant in long-term, complex engineering projects.