Learn Claude Code TypeScript — Design skill for Claude Code

learn-claude-code-typescript

中文 ｜ [English]

面向前端工程师的 Agent harness 学习项目：把 [Learn Claude Code](https://github.com/shareai-lab/learn-claude-code) 的 20 个递进课程，改写成 TypeScript + Algebraic Effects 版本。

这个仓库不是 Claude Code 的产品复刻，也不是一个完整 Coding Agent 框架。它更像一套可运行的学习笔记：用 TypeScript 代码把 Agent loop、工具调用、权限、hooks、todo、subagent、skill、compact、memory、task、team、MCP 等机制逐章拆开，再用代数效应视角解释它们共同的工程结构。

如果你还不了解代数效应，可以先把它理解成一句话：

Agent 逻辑只声明“我要做什么”，运行时 handler 再决定“怎么做”。

更完整的入门解释见 [docs/zh/algebraic-effects-primer.md](docs/zh/algebraic-effects-primer.md)。

为什么做这个项目

我做这个项目的动机很简单：很多前端工程师已经开始使用 Claude Code、Cursor、Codex 一类工具，但真正理解它们背后的 harness 工程并不容易。

原版 Learn Claude Code 用 Python 展示了这些机制。我希望把它翻译成前端工程师更熟悉的 TypeScript，同时进一步用第一性原理和代数效应重述：

Agent = 模型的 agency + harness
Harness = loop + tools + permissions + context + memory + state + protocols

模型负责产生意图，harness 负责解释意图、执行副作用、注入观察结果、维护边界和状态。工程师真正能设计的部分，主要就是 harness。

AI 协作说明

这个项目是我和 AI 协作完成的学习型工程。

我负责提出问题、设定方向、判断抽象是否成立、校验课程结构和表达方式；AI 负责大量代码转换、章节草稿、重构建议和文档生成。这个过程本身也是项目想传达的一部分：我们不只是“使用 AI 写代码”，还可以用 AI 帮自己理解 AI coding agent 背后的工程原理。

所以这个仓库既是一份 TypeScript 教程，也是一份 AI 协作学习的样本。

核心视角：代数效应

原版 Python 课程里的核心循环大致是：

while True:
    response = client.messages.create(...)
    if response.stop_reason != "tool_use":
        return
    for block in response.content:
        output = TOOL_HANDLERS[block.name](**block.input)
        results.append(output)
    messages.append(results)

用代数效应看，这个循环可以拆成三个部分：

机制	代数效应表达	含义
Tool use	yield* perform(effect)	Agent 声明“我要做什么”
Tool handler	handlers[effect.type]	运行时决定“怎么做”
Agent loop	runAgent()	把副作用结果送回 Agent

在本项目里，Agent 逻辑通常写成 Generator：

function* agentLoop(perform: PerformFn) {
  const output = yield* perform({
    type: "BashExec",
    input: { command: "ls" },
  });

  return output;
}

这段代码不直接执行 shell。它只是声明一个意图。真正执行、拦截、审批、mock、记录日志或替换成隔离环境，都由 handler