build_a_product_agent CLAUDE.md

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.13+。Web 层用 FastAPI（async def 路由），Agent 编排用 LangGraph（StateGraph/astream_events/checkpointer），工具层用 LangChain（@tool），数据校验用 Pydantic v2，Redis 一律用 redis.asyncio，LLM 客户端用 AsyncOpenAI。关键 SDK 版本要求：FastAPI ≥ 0.136、LangGraph ≥ 1.2、LangChain ≥ 1.3、Pydantic ≥ 2.13。
6. 收尾：章末通常有 常见踩坑清单（表格：坑/现象/原因/解法）和 本章小结（表格：要点/核心原则/一句话记住）。新文章建议沿用。
7. 全章示例代码假设统一的项目骨架：core/（config、llm、cache、database、agent、logger、middleware 单例封装）+ routes/ + services/ + models/ + tools/ + main.py。各章代码示例互相引用这个结构（如 from core.llm import call_llm_with_retry），写新文章时保持该骨架一致，不要引入与已有章节冲突的目录约定。