From zero to one: build an AI coding assistant the way you would build a car

1.1 One sentence for the essence

It = a large language model ([[LLM]]) + a ring of software that lets the model “use its hands.”

The model itself does only one thing: read some text, write some text. It cannot open files, cannot run commands, cannot remember yesterday’s conversation. Every one of those “superpowers” is given to it by the outer ring of software. That ring is the main body we are going to build.

1.2 Split it into five layers (this is the product anatomy)

Borrowing Claude Code’s classic structure, any agent of this kind can be split into five layers (this is the map the book keeps citing; call it the [[five-layer architecture]]):

🎯 First lesson of reverse engineering: building a product like this is, in essence, implementing these five layers one by one, then assembling them. The “step by step” of chapter 7 walks exactly this road.

1.3 Claude Code versus Claude Desktop (do not mix them up)

• [[Claude Code]]: a coding assistant that runs in the terminal, built around “edit code.”
• [[Claude Desktop]]: a desktop chat app, built around “talk to Claude + connect your local tools through [[MCP]].”

The product this book builds is closer in form to Claude Code. When we talk about “how to develop in the AI-agent era,” we will use Claude Desktop as your development copilot—the tireless junior engineer sitting next to you.

3.1 “Programming” ≠ “software engineering”

• Programming: writing code that runs. Like “being able to cook one dish.”
• [[Software engineering]]: letting a group of people, over a long time, keep shipping software that other people can read, can maintain, and that does not break easily. Like “running a restaurant that can franchise for ten years.”

A solo person writing a small script does not need much engineering. To build a product like Claude Code that thousands of people use and that has to live for years, you must talk engineering. Engineering’s core contradiction is:

People forget, people leave, requirements change, code gets messier. Engineering is a whole discipline for fighting that entropy.

3.2 Two mainstream process paradigms

① [[Waterfall]]: like putting up a building—design everything first, then construct, step by step downstream, no turning back. - Strength: fits scenes where requirements are extremely clear and will not change much. - Cost: if you finish and discover the design was wrong, tearing it down is enormous.

② [[Agile]]: like building with Lego—first assemble a little car you can play with, give it to users, listen, then add parts. - Core move: cut the big goal into cycles of about two weeks ([[sprint]]); every cycle ships a “usable little bit.” - Accompanying rituals: daily standup, [[backlog]], [[kanban]], retrospective. - Almost every internet product today, including AI products, uses agile.

🧭 Advice for you: as a solo developer, use “minimal agile”—you do not need meetings, but you keep agile’s soul: always ship a runnable minimum version first ([[MVP]]), then add.

4.1 Product manager ([[PM]])

• Mission: figure out “what to build, for whom, and why it is worth building.”
• Requirements: understand users, make trade-offs, turn a fuzzy idea into a clear [[PRD]].
• Artifacts: PRD, feature-priority list, [[user stories]].
• Who they most easily fight with: engineers, over “is this feature actually hard, is it worth doing”; designers, over “pretty versus fast.”

4.2 [[UX/UI designer]]

• Mission: make the product usable and good-looking.
• Requirements: understand how people operate, draw [[wireframes]], define interaction and visual rules.
• Artifacts: wireframes, high-fidelity mocks, [[design system]].
• For a terminal product like Claude Code, “design” shows up as: how commands are named, how errors speak human, the rhythm of streaming typewriter text, color and layout.

4.3 [[Frontend engineer]]

• Mission: turn mocks into an interface the user can click and see.
• Requirements: interface technology (on the web, [[HTML]] / [[CSS]] / [[JavaScript]] and frameworks such as [[React]]; in the terminal, [[TUI]] technology).
• Artifacts: interface-layer code (layer ① of the five).

4.4 [[Backend engineer]]

• Mission: build the engine the user never sees, which holds everything up.
• Requirements: servers, [[databases]], [[API]] design, concurrency, security.
• Artifacts: most of the brain, loop, hands-and-feet, and memory layers (layers ②③④⑤ of the five).
• This is the most central, heaviest role for this class of product.

4.5 [[AI engineer]]

• Mission: use the [[LLM]] well—write [[prompts]], design [[context]] assembly, tune [[streaming]], control cost ([[prompt cache]]).
• Requirements: know the model’s temperament, evaluate quality, save [[tokens]].
• In an AI product this role overlaps heavily with backend; it is the most important new role of the era.

4.6 [[QA]]

• Mission: find every fault before the user does.
• Requirements: design test cases, write [[automated tests]], watch [[edge cases]].
• Artifacts: test cases, bug reports, quality red lines.

4.7 [[DevOps]]

• Mission: make the product release, update, and stay up.
• Requirements: [[CI]] / [[CD]], [[packaging and distribution]], [[observability]].
• Artifacts: release pipeline, installers, monitoring dashboards.

4.8 [[Architect / tech lead]]

• Mission: set the technical direction, hold the quality floor, decide technical disputes.
• Requirements: experience, long view, [[code review]].

🗺️ A “role → five layers” map:

Role	Layers they mainly own
PM / design	Decide what ① the interface looks like, and what the whole thing does
Frontend	① Interface
Backend / AI engineer	②③④⑤ Brain / loop / hands and feet / memory
QA	Quality of all five layers
DevOps	Make the assembled five layers shippable and runnable
Architect	How the five layers are cut, and how they are joined

5.1 Three classic conflicts

Conflict one: PM wants more features ⨯ engineers say it will not finish. - Resolution: [[prioritization]] (for example MoSCoW: must / should / could / won’t this time). Turn “both, and” into “what first.” A product’s essence is trade-off, not piling on materials.

Conflict two: fast ⨯ good ([[technical debt]]). - Rotten code written to make a deadline is like a credit card—[[technical debt]]. Short-term pleasure, long-term interest (harder and harder to change). - Resolution: say out loud “here we deliberately borrow, and we repay next iteration,” and put it in the backlog. Do not pretend you did not borrow.

Conflict three: I think it should be this ⨯ you think it should be that (a fight over a technical plan). - Resolution: write a [[design document]], put both plans’ costs and benefits on the table, and let the [[architect]] or the team decide from evidence (performance numbers, maintenance cost, risk), not from volume. This is the same “choice dilemma” thinking that keeps appearing in this project’s analyses.

5.2 Three pieces of “infrastructure” without which collaboration collapses

No matter how many people, you must have these three (a solo developer too):

1. [[Git]]: the “time machine + collaboration table” for all code. Who changed what, when, and how to roll back when it breaks—all of it. → See the glossary.
2. [[Code review]]: before code merges onto the main line, another pair of eyes (or an AI) looks first. As a solo developer, [[Claude Desktop]] can be that pair of eyes.
3. [[Documentation]]: leave a manual for future-you and for other people. README, design docs, code comments.

6.1 How a traditional software company does it

立项 → PM 写 PRD → 设计出稿 → 架构评审 → 拆任务给前端/后端/AI 工程师
→ 各自开发（用 Git 分支协作）→ 提交 Code Review → QA 测试
→ DevOps 走 CI/CD 发布 → 监控运营 → 收集反馈 → 下一个迭代

• Character: fine division of labor, heavy process, quality with multiple insurances, high communication cost, relatively slow.
• Strength: can build large, build stable, maintain for a long time.
• Cost: a small change may have to walk a long process.

6.2 How a solo indie developer does it

• You alone are full stack (frontend + backend + AI + test + ops) + half a PM + half a designer.
• Core strategy: extreme trade-off + leverage.
• Do not invent wheels: if there is an existing [[open-source]] library or an existing model [[API]], never write your own.
• Only build an [[MVP]]: first get the shortest path “ask the model → edit one file” running, then add features.
• Treat “future you” as a collaborator: write a clear README and comments, because in three months you will have forgotten too.
• Strength: extremely fast, zero communication cost, complete freedom.
• Cost: easy to leave large holes in the layers you are weak at (security, testing); one person’s energy is finite.

6.3 How the AI-agent era does it (Claude Desktop as copilot)

This is the new paradigm this book most wants you to understand: you are no longer fighting alone; you are directing a crew of AIs.

Reassign the roles of chapter 4:

• The human’s new mission: upgrade from “write every line” to “define the problem, make the key decisions, gate quality, take final responsibility.” You are the director; AI is the cast.
• How you collaborate: like working with a smart junior engineer who needs explicit instructions—
• Give it clear context (this is exactly the value of [[context engineering]] in this project’s analyses);
• Let it produce in small steps, and you accept incrementally;
• Fill in what it is bad at (long-horizon architecture judgment, taste, responsibility) yourself.
• Strength: one person can approach the throughput of a small team.
• Risk: AI will err with confidence ([[hallucination]]); if you cannot read the code it wrote, you cannot gate it. The more you understand the technical principles, the more you can steer AI—that is also why you read all the preceding agent analyses.

🚀 One sentence for the three paradigms: a traditional company relies on process and headcount; a solo developer relies on trade-off and leverage; the AI era relies on your judgment × AI’s productivity.

Stage 0: set up the “workbench” (environment and tools)

Before any code, prepare tools. Analogy: a chef needs a kitchen before cooking.

• [[Terminal]]: a black box where you command the computer by typing. The programmer’s main battlefield.
• [[Editor / IDE]]: where you write code (VS Code, Cursor, and the like).
• [[Git]] + [[GitHub]]: the time machine and the cloud repository for code.
• [[Programming language]] and [[runtime]]: pick a language (this class of project commonly uses [[TypeScript]] / [[Python]] / [[Rust]]). A language needs a “runtime” to run, for example [[Node.js]] or a Python interpreter.
• [[Package manager]]: downloads other people’s libraries for you (npm, pip, and the like).

🤖 AI-era move: ask [[Claude Desktop]] directly: “I am on a Mac, I want to learn to make a Python command-line tool, list what to install, give each install command, and explain.” It becomes your environment-setup guide.

Stage 1: decide what to build (requirements → PRD)

• Write a one-page [[PRD]]:
• Who uses it (target user), what pain it solves, the three most core features, what you explicitly will not do.

• MiniClaude’s MVP requirement can be: “Type one sentence in the terminal; it can read one file in the current directory, rewrite it to my request, and ask me first whether I agree before it writes.”

• Traditional company: PM interviews users, writes a detailed PRD, reviews it.

• Solo: three sentences of requirements to yourself is enough.
• AI era: throw your fuzzy idea at the AI; let it ask you questions and complete the PRD.

Stage 2: draw the plans (architecture)

• Decide how MiniClaude’s five layers land:
• ① Interface: start with the simplest command line that reads one line of input.
• ② Brain: call some [[provider]]’s [[API]].
• ③ Loop: one while [[agent loop]].
• ④ Hands and feet: first implement two [[tools]]—“read file” and “write file.”
• ⑤ Memory: storing the conversation in RAM is enough for now.

• Draw a data-flow diagram: your words → assembled into [[context]] for the model → the model returns “I want to call the write-file tool” → a prompt asks you before execution → execute → feed the result back to the model → the model says “done.”

• Terms: [[API]], [[context]], [[tool use]], [[permission]].

Stage 3: raise the skeleton (tech choice + scaffolding)

• [[Tech choice]]: pick language and libraries from “what the team knows, how good the ecosystem is, what pain you are solving” (chapters 3 and 4 of this project’s analyses are exactly this). Solo advice: pick the language you know best or that AI is best at assisting.
• [[Scaffolding]]: use a tool to generate the project’s initial file structure in one shot, instead of starting from a blank page.

Stage 4: make the heart beat ([[agent loop]] MVP)

This is the product’s “engine,” and the most critical step. Pseudocode (a version anyone can read):

while 对话没结束:
    把"历史对话 + 你的新指令"打包成上下文
    发给大模型，问它：下一步做什么？
    如果模型说"我要调用某个工具":
        （必要时）先弹窗问用户同不同意
        执行工具，拿到结果
        把结果加回对话历史
        继续循环   ← 让模型看到结果后决定下一步
    否则（模型只是回话）:
        把回答显示给用户
        结束这一轮

This loop is the shared heartbeat of every agent. Every flourish you saw across the six open-source projects is “supporting machinery” around this loop.

• Traditional company: several people separately write model calls, tool execution, and UI rendering, then integrate.
• Solo: first get the loop above running with the least code, even if it is ugly.
• AI era: let AI generate the first version of the loop; you read it line by line and get it working with your own hands—you must understand this step yourself, or you cannot gate anything later.

Stage 5: attach hands and feet ([[tool system]])

• Define a unified “interface” for tools: each tool has a name, description, parameters, execute function.
• Key engineering points (echoing the project analyses):
• Tool descriptions are sent to the model every turn; they are expensive in [[tokens]] → do not have too many tools.
• Stamp tools with safety marks (read-only? will it edit files? will it run commands?) → that decides whether you need approval.

Stage 6: attach the brakes ([[permissions and safety]])

• Dangerous operations (delete files, run commands) must pass a gate before they execute: ask the user, or intercept by rule, or drop them into a [[sandbox]].
• This is the layer beginners most easily skip, and the most important—an agent that can run commands with no brakes is a disaster.

Stage 7: attach memory ([[context]] and [[memory]])

• The conversation gets longer and longer, past the model’s reading limit ([[context window]]) → you need [[compaction]] (summarize old dialogue into an abstract).
• If you want it to “remember you across days” → write important information into a [[memory file]] (for example AGENTS.md / CLAUDE.md in the project).

Stage 8: taste and pick faults ([[testing]])

• [[Unit tests]]: test the smallest part (for example, whether the write-file tool works on its own).
• [[Integration tests]]: test several parts assembled (for example, “the whole agent loop”).
• [[Edge-case]] tests: what if the network dies? what if the model confabulates? what if the user hits cancel? — a mature product’s code is more than half handling these.

Stage 9: open for business ([[packaging and distribution]] and [[release]])

• Turn code into something other people can install and run in one shot ([[installer]], publish to a [[package manager]], or make a website).
• Stand up [[CI]]: every code change automatically runs tests, so you do not break it.

Stage 10: day-to-day operations ([[iteration]] and [[ops]])

• Collect user feedback → put it in the backlog → do it in the next iteration → loop back to stage 1.
• Add [[observability]]: know how many people use it, where it errors, how much it costs.

9.1 Interface layer: from the command line to a visual UI

Your agent already has an agent loop, a tool system, permission management—those are the “brain.” Now you give it a “face.”

Choosing a UI framework, two main roads:

💡 Advice for a zero-background reader: start with a React + TypeScript web UI—it has the most learning material and the best debugging tools. Once you are fluent, consider packaging as a desktop app.

9.2 Streaming display: show it as it is generated

A command-line version can print the model’s output directly. A graphical UI that wants a “typewriter effect” (character by character) must handle streaming render:

• Technical principle: the model API returns [[SSE (Server-Sent Events)]] or a WebSocket stream—not the full text at once, but character by character.
• What the frontend must do: listen to the stream, append each new character to the UI, and keep the scrollbar pinned to the bottom.
• The hard part: if several tools are executing in parallel, the UI must show “several tasks in progress at once,” not wait until the last one finishes and then show everything together.

In real projects this part is usually larger than you expect—opencode’s frontend has hundreds of lines for streaming display alone.

9.3 Syntax highlighting and the Diff view

The core display scene for an AI coding assistant is code. An ordinary text box is not enough. You need:

• [[Syntax highlighting]]: keywords, strings, comments of different languages in different colors. Recommend Prism.js or Shiki (Shiki supports VS Code themes; the result is the best).
• [[Diff view]]: when the AI edited a file, you should see at a glance “what was deleted, what was added” (red vs green). Recommend the diff mode of Monaco Editor (the same editor component as VS Code), or the lighter diff2html.
• Code-block interaction: the user can copy a block in one click, can click “Apply” to write AI-generated code into a real file—these each need their own implementation.

9.4 Animation and transitions

A good client product makes every state change smooth, not a flash. Consider:

• Loading animation: while the model is thinking, the UI needs a spinner / dots / ripple so the user knows “it is working.”
• Message-enter animation: new messages fade or slide in, rather than appearing suddenly.
• Tool-execution state: while reading a file or running a command, show a progress bar or a live-scrolling log.
• Recommended libraries: CSS animation (light), Framer Motion (React animation library, first choice for interactive animation), GSAP (complex timeline animation).

Note: animation is an experience bonus, but performance is the premise—streaming output re-renders every frame; heavy animation makes the UI stutter. Guarantee smoothness first, then add animation.

9.5 State management: the “sync problem” between UI and brain

Your agent backend has a set of state (current session, tools currently executing, user permissions…). The frontend UI must reflect that state in real time. That is “state management.”

• Simple scene: React useState / useContext is enough.
• Medium scene: Zustand (light) or Jotai (atomic state), a fit for session list + current messages + tool state at that depth.
• Complex scene (multi-window, concurrent multi-session, live sync): consider Redux Toolkit, or opencode’s idea—treat the backend as the server, the frontend as a “thin client”; all state is authoritative on the backend; the frontend only displays and sends commands.

9.6 Multi-pane layout and keyboard shortcuts

Professional coding tools have multi-pane layout: file tree on the left, conversation in the middle, code preview on the right. That needs:

• Layout: CSS Grid / Flexbox for the base; react-resizable-panels for drag-to-resize.
• Pane coupling: click a file path in the conversation, and the right-hand code pane jumps to that location.
• [[Keyboard shortcuts]]: Ctrl+K for the command palette, Esc to interrupt a task, Ctrl+Enter to send—each must be registered and handled separately (use hotkeys-js or native keydown).
• Command palette: like VS Code’s Ctrl+Shift+P; the user types a keyword and finds any feature. grok-build’s Ctrl+P command palette is this design.

9.7 Theme system: light / dark mode

Users expect to switch dark/light themes; professional tools also support custom palettes.

• CSS-variable approach: define a set of color variables (--color-bg, --color-text, …); switching themes only changes variable values, not component code. This is the most general approach.
• Tailwind CSS: it has built-in dark: prefix support; pairing it with a class="dark" switch is convenient.
• Caveats: syntax highlighters (Shiki and the like) need their own matching theme; terminal-emulator colors need extra handling.

9.8 Terminal emulator: show real command-line output inside the UI

Your agent will run shell commands. Users want to see colored terminal output (ANSI escape codes rendered) in the UI, not a pile of garbage.

• Recommended library: xterm.js—VS Code’s built-in terminal uses it; it supports 256 colors, cursor movement, live streaming output.
• Integration points: the backend pushes the command’s stdout/stderr to the frontend over a WebSocket stream; xterm.js renders line by line; also handle ANSI color escapes (\033[32m and the like).

9.9 Desktop packaging: from a web page to an installable app

If you want users to “download and install” rather than “open a browser,” you need to package the web page as a desktop app:

For an AI coding assistant that needs to call local files and run commands, Electron or Tauri is required—PWA permissions are not enough. After packaging you still need auto-update (Electron uses electron-updater; Tauri has a built-in updater).

9.10 Recap: extra work for a client

Turning an AI agent into a graphical client is usually 2–4× the work of a “pure terminal” version. Main extras:

① UI 框架搭建（React + 路由 + 状态管理）          约 1–2 周
② 流式展示 + 代码高亮 + Diff 视图                  约 1–2 周
③ 动画与加载状态                                  约 3–5 天
④ 多面板布局 + 快捷键 + 命令面板                    约 1 周
⑤ 主题系统                                       约 2–3 天
⑥ 终端模拟器集成                                  约 3–5 天
⑦ 桌面打包 + 自动更新（如需要）                     约 1–2 周

📌 Advice: do not try to build a client from day one. First get the pure-terminal version (chapter 7’s MiniClaude) running, validate the product direction, then add a UI. The UI can come later; the core loop must be stable first. See goose’s history—its Electron desktop came after the Rust engine was stable; a stable core API is the premise of UI development.