From “what is an agent”
to “I can build one”

Prerequisite: install one AI coding tool

Install Claude Code or the Codex CLI on your own machine. Spend a day or two on ordinary tasks. The point is not the theory. The point is the felt sense: you tell the computer what to do, and it does it. Every later lecture assumes that intuition.

Three concepts you need before Stage 1

You do not need implementations. You need jobs-to-be-done. Five minutes each.

1. API (programs calling programs)

Restaurant metaphor: you (the client) read a menu and order (send a request); the kitchen (the server) cooks and sends a plate back (the response). You do not need to know how the kitchen cooks. You need to know how to order.

In an agent: the harness sends “what the user said + which tools exist + prior turns” to the model over an API. The model returns “what I said + which tool I want” over the same API.

2. Terminal — talking to the machine in text

A GUI is pointing. A terminal is typing. Many developer tools live only in a terminal because typing is faster than clicking and because a typed session can be scripted.

3. Git — a time machine for code

Three operations suffice: git commit (take a snapshot), git log (look at the album), git diff (compare two snapshots—which lines changed).

Then enter Stage 1

Recommended order

Step 1: Claude Code — how it works (deep dive), chapters 1–7 (2–3 hours)

English: claude-code-deep-dive.md. Chinese original: Claude-Code-工作原理科普-深入版.md.

Why this first: it is the flagship document. Using one concrete agent (Claude Code), it walks startup → input split → context assembly → the agent loop → the tool system. Learn one skeleton before you look at thirteen variants. If you start on the comparative tables, you will drown in differences and lose which pieces are shared.

Watch chapter 6 (the agent loop). If you read only one chapter in the station, read that one. It is the loop: model speaks → software acts → results are fed back → until the model stops requesting tools.

Step 2: Claude Code learning station v1 (../learn/claude-v1/, public path /learn/claude-v1/) (1–2 hours)

Step 1 is prose. Step 2 is interactive. Three labs, three mechanisms:

• LAB 01 Prompt-journey simulator: how a user request is assembled into the messages sent to the model
• LAB 02 Agent-loop visualizer: model → tool → model
• LAB 03 Permission gate: which operations are blocked, which are allowed

Skip the labs and the loop stays on paper.

Step 3: Build an AI coding assistant from scratch, chapters 1–8 (1 hour)

English: tutorials/build-coding-assistant.md.

Steps 1–2 are “look at a finished system.” This step is “look at how one is assembled.” You need not write code yet (that is Stage 3). You do need the parts list and how the parts couple.

Step 4: return to the deep dive, chapters 8–14 (1–2 hours)

Skeleton, then flesh: 40+ tools, 60+ slash commands, plugins / skills / MCP, effort tiers and model switching, compaction, sub-agents.

Concept graph

flowchart TD
    U["User input"] --> R["Input split: command or dialogue?"]
    R --> A["Context assembly: system prompt + project notes + history"]
    A --> L["Agent loop ★ core"]
    L --> M["Model API"]
    M --> L
    L --> T["Tool system: read/write files / run commands / search"]
    T --> P["Permission gate: is this operation safe?"]
    P --> L
    L --> O["Output: task done, or the user must decide"]

Common mistakes

❌ “An agent is ChatGPT with a terminal skin.” No. ChatGPT only speaks. An agent acts (edits files, runs commands, fetches the web). That requires a tool system, a permission system, and error handling.

❌ “The agent loop is just while True.” It is, at the type-system level. The gap between “it runs” and “it runs well” is about a hundred edge cases (the user interrupts; a tool fails; the context overflows; the model loops). Chapter 6 is the difference.

❌ “Permissions are a y/n modal.” That is the naïve reading. A real gate includes: rule deposition (last time’s allow becomes next time’s default), command AST parsing (string match is not enough), provenance (a sub-agent’s result is not the user’s confirmation), and mode switches (Plan mode does not even register write tools).

Acceptance

After Stage 1 you should be able to:

• [ ] Draw the agent-loop flowchart (it need not be pretty; the logic must be right)
• [ ] Name two essential differences between an agent and a chatbot
• [ ] Explain what happens between “the model asked to read_file('/foo')” and “the file contents are fed back”
• [ ] Name at least three permission lineages and their core idea
• [ ] Explain “what an agent is” to a non-engineer

Recommended order

Step 1: Comparative review, chapters 1–2 (1 hour)

English: analyses/comparative-review.md. Chinese: 项目分析/横向对比与总结评价.md.

Lay the thirteen projects on one table—overview plus ten dimensions. Read the table in landscape. Each column is a physical of one project.

While reading:

• Chapter 2: each dimension (architecture shape, loop, tools, permissions, compaction, memory, sub-agents, extension, model auth, cache) has a table (“what”) plus a short “what they were thinking” (“why”)
• The architecture-shape figure matters: monolith / server / message bus. Later lectures assume you can see that split

Step 2: pick three projects whose architectures disagree the most (about 1 hour each)

A useful triple (three different product positions):

1. CodeWhale: Rust single binary + safety by construction + an “issue notebook” culture. “Put safety in the compiler.”
2. nanobot: small Python core + explicit state machine + MessageBus + Dream (nightly reflection). “Keep the core small; grow capability at the edge.”
3. goose: everything is an MCP extension + engine-as-server + ACP. “The agent is local infrastructure.”

Do this on paper: three circles, labeled CodeWhale / nanobot / goose. Every time a lecture shows how that project solves a problem, write it in the circle. Examples:

• Permissions: CodeWhale → structural safety (Plan does not register write tools); nanobot → sandbox lineage (bwrap); goose → GooseMode four modes
• Shape: CodeWhale → dual-binary message pipe; nanobot → MessageBus dual queue; goose → engine-as-server

Step 3: Catalog of agent engineering patterns, full text (1–2 hours)

English: agent-engineering-patterns.md.

Steps 1–2 ask “what did this repo do.” This lecture asks “what is the cross-project pattern”—the same engineering problem, different answers.

You need not read in order. If cache is the pain, open chapter 1. Each chapter is the same shape: why the problem is hard, how each project solves it, what you should do.

Step 4: Architecture gallery (../架构图库.html) (30–45 minutes)

After a lot of prose, diagrams spatialize the abstractions. Each figure states two things first: what question it answers and what load-bearing claim it is making. Click to fullscreen.

Common mistakes

❌ “More tools are better.” hermes ships 74 tools; goose ships 0 built-in tools. Count is not capability. The scarce resource is the marginal cost of one more core tool (its schema is sent on every request).

❌ “Locking one model vendor is technically conservative.” Claude Code locks Anthropic because the product wants you to use Claude, not because a multi-provider architecture is impossible. The dividend of a lock is depth you cannot buy in a least-common-denominator multi-provider stack (cache billing headers that match the body, signed thinking, ToolSearch).

❌ “Open source is always freer than closed source.” Incomplete. Open source pays an adapter tax and a least-common-denominator tax. Closed source pays with first-party depth. Pick from what you actually optimize for.

Acceptance

• [ ] Name three permission lineages (prompt-the-user / structural safety / OS sandbox) and the jobs they fit
• [ ] Explain why hermes-agent’s “persist to disk before you act” is a hard rule
• [ ] Recite the five prompt-cache moves (statics first / volatiles out / stable tools / compact carefully / make cache hits visible in telemetry)
• [ ] Facing a new agent repo, ask “what is the product position?” before judging a technical choice

Four build tracks — pick the one that fits

English tutorials live under tutorials/. Additional tracks in the Chinese station (Easel, CodePilot, Cline, Kanban, OpenAI4S, DeepSeek Harness) have English siblings in the same folder as they are translated.

How to use the tutorials

1. Do not skip steps. They are ordered as “hit a wall → add a part.” Skip “give it a brain” and jump to “give it brakes,” and you will not know where the brakes attach.
2. Match each step against the acceptance assertions. The appendix of each track says “after step N you should observe XXX.” That is your CI.
3. When stuck, return to the matching Stage 2 analysis. The tutorial’s “why this way” is usually expanded there, with path:line.

Mental preparation

• Version 1 will fail or fail poorly. That is expected. The “how it blows up” lists exist for that.
• The same feature (a permission gate) can be v1 blacklist + modal (half an hour), v2 deposited rules (half a day), v3 provenance downgrade (days). Do not try to make v1 perfect.
• The largest trap is not “the tech is too hard.” It is over-design—two weeks of clever compaction before you have evidence a user needs it. Ship the simplest loop that runs, then iterate on pain you have actually felt.

Acceptance

• [ ] Your agent completes an end-to-end task (not a demo; a real task)
• [ ] Dangerous operations are blocked (you do not discover an rm -rf after the fact)
• [ ] You can explain three decisions in your code—“why this, not that”

Recommended order

Step 1: MiMo Code chapter 20 (layer-by-layer diff) + LAB 05 attribution bench (2–3 hours)

The most pedagogically useful analysis in the station. Not “what MiMo added,” but on top of opencode, what Xiaomi changed, why, and which capabilities were already upstream. Fifteen capabilities, each tagged 🟢 first-party / 🟡 inherited-and-extended / 🔵 already upstream, with real byte counts on both sides. Steal the method; use it on the next fork you meet.

Step 2: Open Design lab station (2–3 hours)

The most counter-intuitive sample: zero lines of an agent loop, driving 25 CLIs. Three labs: adapter dissection (“data instead of code”), layered prompt assembler (cache bands), anti-AI-taste linter (aesthetic quality as a program).

Step 3: MiroFish lab station (2–3 hours)

The only non-coding agent in the series—crowd simulation. The point is not to copy the code. The point is to widen “what an agent is for.” LAB 01 contains a real silent data-corruption defect: Chinese type names all collapse to Unknown inside _to_pascal_case, with no error. That bug was found by running the bench, not by reading the file. That is the gap between “it runs” and “I read the code.”

Step 4: OpenAI Codex lab station (2–3 hours)

LAB 01 (approval × sandbox truth table—two orthogonal walls), LAB 02 (AGENTS.md byte budget—a 32 KiB chain shared across the tree starves deep directories), LAB 03 (run_turn stop protocol—why compaction must continue).

Step 5: Architecture-diagram guide + two review errata (1 hour)

Draw a figure that answers a question. Every box and edge exists to support one load-bearing claim. Directory trees are not architecture.

Acceptance

• [ ] Between any two fork / upstream trees, write ten or more differentiated findings (not “this has it, that doesn’t”—“what changed, why, and what it costs”)
• [ ] Draw an architecture figure for any project you have read (not a directory tree: a figure that answers one question, e.g. “how does the permission gate stop one shell command”)
• [ ] In a discussion of permission lineage / architecture shape / model strategy, use a framework: “in your setting, pick X because Y, and the cost is Z”