Agent 开发 on Code Plato

CLAUDE.md 编写简明指南

Sun, 13 Sep 2026 00:00:00 +0000

这个指南同样也适用于 AGENTS.md

CLAUDE.md 有什么用

首先我们要知道 CLAUDE.md 有什么用。因为模型就像一个新生儿。你每一次跟它对话，它都不知道你是谁，它是谁，你们前面说了什么。它都是通过你传给它的上下文得知这一切的。当然，Claude Code 有一些预设的上下文，所以它知道自己是 Claude Code，一个帮你写代码的工具。所以每一次新的会话开始的时候，它对你的项目是一无所知的。之所以它工作得还不错，是因为 Claude Code 自己的预设上下文教它在遇到一个项目改动前，应该做什么来了解项目的信息。所以你会发现它似乎很了解你的项目，但是又常常会重复造轮子。因为它有一套快速理解项目的方法论，但是还是做不到了解你项目的所有细节。当然你也不会希望它这么做，否则太烧 token 了。这个时候就需要有人用简短的语言向它介绍这个项目的背景、架构等等信息。这样做的好处是：

它就不会去遍历你的项目，可以节省 token
它不会做很明显违背你的项目代码意图的事情，或者重复造轮子这些简短的语言就会被放在 CLAUDE.md 中，或者 AGENTS.md 中。这个指南同时也适用于 AGENTS.md。

编写原则

一份好的 CLAUDE.md 应该像： 新员工的最短上手指南： 想象着你在带一个新员工做一个任务。努力用最短的语言告诉他足够的知识。只要能够达到他上手可以干活，而且不至于把你的代码库搞砸就行。 用词犹如简历一般简洁： 我前一段时间在找工作，曾经向 HR 学习过怎么写简历。然后我就绞尽脑汁地把我长达 4 页的简历压缩成了 2 页。几乎删除了所有冗余的词语。每个句子都精简到无法再减少。你也应该这么写 CLAUDE.md。 高度抽象的知识： 你不需要告诉 Claude Code、Codex CLI 代码缩进是多少格，或者连接数据库参考什么文件的第几行。很多事情交给 hook 去做，代码的名字和行数都是会变的。你要告诉模型的是一些高度抽象的设计理念。一般来说，一份好的 CLAUDE.md 长度应该在 200 行以内。

种类

包括项目根目录下的 CLAUDE.md 在内，其实有 3 种 CLAUDE.md。

~/.claude/CLAUDE.md，作用范围是全局。你的所有项目都会用到它。
./CLAUDE.md，作用范围是项目。
./subdirectory/CLAUDE.md，子文件夹也可以有 CLAUDE.md。

框架

并没有一个严格的、完美的 CLAUDE.md 框架。但是我参考了一些比较好的 CLAUDE.md 和相关文章，总结出了一个比较合理的 CLAUDE.md：

一句话介绍
架构
技术栈
命令
约定
边界
领域文档映射表

一句话介绍

简单介绍这个项目是什么，大概的功能是什么。例子：

这是一个多智能体编排框架，用于协调并行运行的 Claude Code 子智能体，在 FastAPI + React 代码库上自动化执行开发/QA 工作流。

架构

简单介绍项目的架构，比如：

## Architecture
- Controller 保持轻量 —— 业务逻辑放在 `app/Services/` 中
- 数据库访问只能通过 `app/Repositories/`。禁止在 controller 中直接使用 Eloquent。
- `app/Http/Resources/` 中的 API resources 负责规范每一个 JSON 响应的结构。

技术栈

简单介绍项目的技术栈，类似：

## Tech Stack
- FastAPI，Python 3.11
- PostgreSQL 15（SQLAlchemy 2.0 异步）
- Celery + Redis 用于后台任务处理
- Poetry 用于依赖管理

命令

一些项目的常用命令，比如：

## Commands
- 开发服务器：`uvicorn app.main:app --reload`
- 运行测试：`pytest -x -v`
- 数据库迁移：`alembic upgrade head`

约定

无法被 linter 包含的抽象约定，类似：

## Conventions
- 布尔类型的变量/属性以 `is`、`has` 或 `should` 开头
- 所有日期时间统一以 UTC 格式存储和传递
- 事件名称遵循 `domain.action` 的命名格式

边界

文件修改的边界：

## Boundaries
- `legacy/` — 老版支付系统，只做紧急 bug 修复，不引入新模式或重构
- `src/generated/` — Prisma/GraphQL 自动生成
- `vendor/`, `third_party/` — 第三方代码，通过升级依赖版本解决问题，不直接修改

领域文档映射表

领域名词和文档的对应关系：

## Domain Doc Map
| 提及 | 阅读 |
|---|---|
| billing, stripe, payment, subscription, invoice | docs/billing.md |
| auth, login, session, oauth, jwt | docs/auth.md |
| migration, schema, drizzle, kysely | docs/db-migrations.md |
| feature flag, rollout, kill switch | docs/feature-flags.md |

我们把这几个例子拼起来，看一个好的 CLAUDE.md 应该像这样：

这是一个多智能体编排框架，用于协调并行运行的 Claude Code 子智能体，在 FastAPI + React 代码库上自动化执行开发/QA 工作流。

## Architecture
- Controller 保持轻量 —— 业务逻辑放在 `app/Services/` 中
- 数据库访问只能通过 `app/Repositories/`。禁止在 controller 中直接使用 Eloquent。
- `app/Http/Resources/` 中的 API resources 负责规范每一个 JSON 响应的结构。
 
## Tech Stack
- FastAPI，Python 3.11
- PostgreSQL 15（SQLAlchemy 2.0 异步）
- Celery + Redis 用于后台任务处理
- Poetry 用于依赖管理

## Commands
- 开发服务器：`uvicorn app.main:app --reload`
- 运行测试：`pytest -x -v`
- 数据库迁移：`alembic upgrade head`

## Conventions
- 布尔类型的变量/属性以 `is`、`has` 或 `should` 开头
- 所有日期时间统一以 UTC 格式存储和传递
- 事件名称遵循 `domain.action` 的命名格式

## Boundaries
- `legacy/` — 老版支付系统，只做紧急 bug 修复，不引入新模式或重构
- `src/generated/` — Prisma/GraphQL 自动生成
- `vendor/`, `third_party/` — 第三方代码，通过升级依赖版本解决问题，不直接修改

## Domain Doc Map
| 提及 | 阅读 |
|---|---|
| billing, stripe, payment, subscription, invoice | docs/billing.md |
| auth, login, session, oauth, jwt | docs/auth.md |
| migration, schema, drizzle, kysely | docs/db-migrations.md |
| feature flag, rollout, kill switch | docs/feature-flags.md |

要不要写 Never

你可能在别的指导上看到一个段落叫 Never，用来记录曾经犯过的错。听起来很好。但是我不太建议增加这个部分。因为 Never 的特点是 只有添加的动机，没有删除的动机。导致这个部分越来越长，甚至 Claude Code 自己都会去加，而且没有人会去删除它。时间久了就会变成一个历史事故墓地。我建议的做法是：当问题出现了，把出问题的模式反过来，写成一种正向的规则。比如“不要在 webhook/stripe.ts 里做同步数据库写入”，改成“只在 repository/ 内做数据库操作”。

修剪

就算你按照以上的框架编写了 CLAUDE.md，对于一个大项目，或者维护周期较长的项目，或者这个项目已经有了 CLAUDE.md，你还是会发现这个文件的长度无法控制在 200 行以内。那么就要进入修剪步骤。修剪就是把东西从 CLAUDE.md 中移除出去。具体的移动方法和路径有以下几种：

自定义子智能体：.claude/agents
规则文件夹：.claude/rules
子目录 CLAUDE.md：./subdirectory/CLAUDE.md
固定工作流：.claude/skills/
其他文档：docs/ 你会发现我给它们编了号。这是因为文档的抽取是有优先级的。顺序是从具体到抽象，从精准到泛化。

自定义子智能体

把所有关于子智能体的指导文档都抽取到 .claude/agents 下，比如：你可以定义一个专门用来跑集成测试的 agent。文件名叫 integration-tester.md。内容：

---
name: integration-tester
description: Runs integration tests
tools: Bash
model: sonnet
---

You run and diagnose integration tests. You should follow these steps.....

规则文件夹

具体的规则文件可以放在 .claude/rules 中。分为带路径和不带路径两种。不带路径的优先级等同于 CLAUDE.md，比如：

# Security Rules

- All user input is validated at the API boundary
- Secrets and API keys are read from environment variables only
- SQL queries always use parameterized statements

带路径的会在满足指定路径的条件下才被加载，比如：

---
paths:
 - "tests/**/*.py"
 - "**/*.spec.ts"
---

# Unit Testing Rules

- One assertion concept per test
- Test names describe behavior, not implementation
....

规则文件和领域文档映射表： 你可能会有疑问：“规则文件和领域文档映射表会不会重复定义了相同的东西？”是的，确实会出现这个问题。比如，你可能会定义 billings/ 路径下的文件应该遵循 billings 相关的文档，然后在领域文档映射表中也有一行 | billings | docs/billings.md |，这样确实是重复了。解决的办法就是把文档分为规则和背景。规则文件强制性高，放到 .claude/rules 中。背景文件相对较弱，放到 docs/ 中。

子目录 CLAUDE.md

针对某些子目录的规则可以移动到这些目录下，常见的场景有 sql/、domains/、adapters/ 文件夹。在这些目录下的 CLAUDE.md 不必遵循特定的框架。但是还是要保持简短。

固定工作流

如果有一些固定的、需要按顺序做的操作，就尽量做成项目级的 skill，然后放到 .claude/skills/ 下。

其他文档

其他的文档放到 docs/ 目录下。这个目录下放一些比较泛化的文档。比如更具体的 architecture.md，或者把 ADR（Architecture Decision Record）文档放到 docs/adr/ 文件夹下，比如 docs/adr/0001-migrate-to-drizzle.md。

如何开始

如果你还没有一份 CLAUDE.md 或者 AGENTS.md，那么按照以下步骤开始做：

运行 /init 生成一份初稿
开始根据以上方法来修改初稿

未来也要记得定时运行 /doctor 来优化 CLAUDE.md。

参考文献

关于作者

我是代码Plato。

我相信，人类的创造力才是 AI Coding 的真实之树，而代码与模型不过是投射在洞穴墙上的影子。

微博：@代码Plato 主页：https://weibo.com/u/1041257881

我们什么时候不需要MCP

Mon, 07 Sep 2026 00:00:00 +0000

问题

经常看到招聘 JD 上写着 MCP，似乎每个人都要会 MCP 才能做 agent 开发
又有人说 MCP 太重了，没什么人用 MCP
我们又会看到很多教程说，使用 MCP 统一接口很好用

我们平时看到的教程都是介绍 MCP 是什么，为什么要用 MCP。说了很多，其实大家还是不能直观地理解 MCP 的取舍。我今天就反过来说说什么时候不需要 MCP，来帮助大家更直观地感受 MCP。

MCP是什么

MCP（Model Context Protocol，模型上下文协议） 是 Anthropic 发起的一个开放协议，用来让 AI 应用（比如 Claude Code、Claude Desktop、OpenClaw 这些 agent）用统一的方式去发现和调用外部工具、读取外部资源

这是字面上的概念。实际上你可以把 MCP 看作是暴露给 agent 的一种资源。在 MCP 出现之前，如果你想让一个 AI 应用连上 Google Drive、GitHub、Slack 这些服务，每个 AI 应用都得为每一个外部服务单独写一套集成代码。 MCP 相当于给这个连接关系定义了一个"标准插座"。

不用MCP用什么

如果不用 MCP，我们还有很多别的东西可以选择。最重要的是两种： function calling： 2023 年 OpenAI 推出了 function calling 的能力。其实很简单，就是你先把一段函数签名传给 LLM。

{
 "name": "get_weather",
 "description": "查询某个城市当前的天气",
 "input_schema": {
 ...
 "properties": {"city": {"type": "string"}},
 }
}

LLM 知道有一个 tool 之后，如果 LLM 在执行过程中觉得需要调用这个外部工具，那么执行结果的 content 内会多出一个 tool_use 对象，并且 stop_reason 也会写 tool_use。就像：

{
 "content": [
 {
 "type": "tool_use",
 "name": "get_weather",
 "input": {"city": "new york"}
 }
 ],
 "stop_reason": "tool_use"
}

然后你就自己写代码去实现这个函数调用。

if response.stop_reason == "tool_use":
 tool_use = response.content[-1]
 // ... 调用查天气的函数

当然实际工作中没这么土，你可以用 LangChain 之类的框架。

CLI： 其实也是一种 function call，只不过你就只暴露一种 tool，而且直接告诉 LLM 这就是个 bash，你想执行什么命令就自己写命令。好处就是你不需要告诉 LLM bash 能干啥，要怎么用。因为 LLM 在阅读了大量资料后，它本来就知道怎么写 bash 命令。

但是使用 CLI 有一定风险，权限控制不好做。

模型视角感受

首先你必须知道一件事情：模型根本不知道你调用的是 MCP 还是 function calling。比如，当你注册查询天气这个工具的时候，如果使用 MCP 注册，那么模型看到的 tools 是这样的：

{
 "name": "get_weather",
 "description": "Get the current weather for a specified city",
 "input_schema": {
 "type": "object",
 "properties": {
 "city": {"type": "string"}
 }
 }
}

如果你用 function calling，模型看到的 tools 是这样的：

{
 "name": "get_weather",
 "description": "Get the current weather for a specified city",
 "input_schema": {
 "type": "object",
 "properties": {
 "city": {"type": "string"}
 }
 }
}

我们现在来玩一个游戏，你能看出这两个 JSON 的区别吗？答案是它们没有区别。所以不需要纠结用 MCP 跟 function calling 会对模型造成什么影响。对模型来说，根本就没有区别。

MCP的缺点

那么 MCP 既然这么好，为什么不都用 MCP 呢？因为 MCP 有缺点：

上下文开销大： 一旦连接上一个 MCP server，这个 server 暴露的所有工具的完整 schema（名字、参数、描述）都会被提前塞进模型的上下文窗口，不管这次对话用不用得上。

消耗服务器资源： MCP Server 是一个持续存在、需要一直跑着的东西。你启动的 MCP Server 多了，服务器的 CPU、内存都会被消耗。

运维负担： MCP server 既然是一个独立进程，你需要自己负责它崩溃后重启、多个 server 间的启动顺序，以及内部状态的持续维护。

MCP的优点

MCP 听起来很糟糕啊。那为什么那么多公司还是继续使用 MCP 呢？因为它虽然有很多缺点，但是它最大的优点就是统一了项目资源的集成接口。统一接口这件事情本身就有 2 个好处：

调用代码简洁： 这东西不做软件的人感觉不出它的好处。做软件的人听到统一接口都知道它好。你原来几千行的屎山代码，可能突然就变成十几行了。接口一多，bug 就埋藏得多、埋藏得深，维护起来就没完没了。

接入第三方资源简单： 所有第三方资源都做成了 MCP，这下接入资源不用再花费很多精力去做定制化了。这件事情其实也没什么技术含量，就跟统一货币、度量衡一样。关键是得有人去做这件事情。

结论

如果你的需求是以下其中一种：

你想用第三方做的工具
你在用你们团队多平台公用的工具
你想做多角色权限区分

那么你可以考虑使用 MCP，否则的话，使用其他轻量化方法，比如 function calling 就够了。

关于作者

我是代码Plato。

我相信，人类的创造力才是 AI Coding 的真实之树，而代码与模型不过是投射在洞穴墙上的影子。

微博：@代码Plato 主页：https://weibo.com/u/1041257881