# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目本质（README 概览之外）

这是一个**纯文档项目**——没有源码、没有依赖、没有构建/测试/静态检查命令，无需安装任何东西。内容是一份面向开发者的中文技术手册，主题是"如何从零构建生产级 AI Agent 后端"。所有内容在 `docs/` 下，全部为简体中文 Markdown。

因此，本项目中的"开发任务"几乎都是**写/改 Markdown 文章**，而非写代码。代码块只是文章内容的一部分（示例代码）。

- 作者：Andy Yanqi Wang (ADW-19)，上海
- 许可：MIT
- 提交信息使用中文（如 `增加AI Infra章节`）
- 英文版：根目录和 `docs/01-首页/` 下有 `README-en.md` 落地页；正文英文版暂未发布（TBD）。新增正文无需同步英文。

## 目录与编号规范

`docs/` 下共 4 个一级目录，按"第 N 章"连续编号展开（一章一个二级目录）：

```
docs/
├── 01-首页/                         # 落地页 README（中英各一份）
├── 02-生产级开发-通用知识/           # 第1~4章
│   ├── 第1章：技术选型/              # 技术栈 / 中间件 / 协议与架构模式 / 运维架构
│   ├── 第2章：开发基本要求/          # 开发习惯（.env、Redis、async、日志、异常处理、类型注解）
│   ├── 第3章：模块开发/              # 对话接口 / 记忆 / 工具 / 工作流 / RAG
│   └── 第4章：Agent通路/             # 单Agent / Multi-Agent(A2A)
├── 03-生产级测试-系统测试/           # 第5章：系统测试
└── 04-生产级AI Infra-基座与运维/     # 第6章：AI Infra基础知识
```

命名规则：
- 一级目录：`NN-中文主题名`（01-首页、02-生产级开发-通用知识…）
- 章目录：`第N章：主题名`
- 文章文件：`NN-标题.md`，章内序号从 01 开始
- **章内 H1 编号在每个章目录内重置**：每个章目录下的文章各自用 `# 第一章/第二章/…`，与全局章号无关（例如"第3章：模块开发"内的文件标题是 `# 第一章：对话接口`、`# 第二章：长期记忆与短期记忆`）。不要想当然地把 H1 的"第N章"当作全局章号。
- 文件系统目录名（含冒号 `：`、空格、括号）是真实路径，编写/引用时原样保留，不要改写。

## 文章写作规范（新增/修改文章时必须遵循）

每一篇独立成文，遵循统一模板与叙事线 `工业界标准 → 为什么课堂不教 → 你应该怎么写`：

1. **开头**：H1 `# 第N章：主题名`，紧接一行 `> **核心论点**：…` 引言块（用一两句话概括本章最核心的判断）。
2. **正文**：小节标题 `## 1.1 小节标题`、`## 1.2`…（章内小节号从 1.1 递增）。
3. **叙事结构**：每个主题按 `问题场景（学生/课堂典型错误代码）→ 本质原因 → 正确做法（带完整可运行代码）→ 对比表格 → 一句话总结` 展开。先给错误示范再给正确做法是强约定。
4. **表达手段**：大量使用对比表格（错误做法 vs 正确做法、维度对比）、ASCII 示意图（时序/架构图）、错误代码 vs 正确代码并置。每条关键结论通常以 `**一句话…：**` 加粗短句收束。
5. **示例代码**：均为 Python 3.11+。Web 层用 FastAPI（async def 路由），Agent 编排用 LangGraph（`StateGraph`/`astream_events`/checkpointer），工具层用 LangChain（`@tool`），数据校验用 Pydantic v2，Redis 一律用 `redis.asyncio`，LLM 客户端用 `AsyncOpenAI`。关键 SDK 版本要求：FastAPI ≥ 0.115、LangGraph ≥ 0.3、LangChain ≥ 1.0、Pydantic v2。
6. **收尾**：章末通常有 `常见踩坑清单`（表格：坑/现象/原因/解法）和 `本章小结`（表格：要点/核心原则/一句话记住）。新文章建议沿用。
7. **全章示例代码假设统一的项目骨架**：`core/`（config、llm、cache、database、agent、logger、middleware 单例封装）+ `routes/` + `services/` + `models/` + `tools/` + `main.py`。各章代码示例互相引用这个结构（如 `from core.llm import call_llm_with_retry`），写新文章时保持该骨架一致，不要引入与已有章节冲突的目录约定。

## 常用操作

- **预览/审阅一篇或多篇文章**：直接 `Read` 对应 `.md` 文件。
- **新增一章**：在 `docs/` 下建 `NN-主题` 目录，内含 `第N章：主题名/` 子目录，文章按上述规范编写，并在根 `README.md`（及 `README-en.md`）的目录结构与内容概览表中同步登记。
- **无构建、无测试、无 lint**：唯一需要关注的工程操作是 git（提交信息用中文）。