DEV Community: Zhengxin

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.