claude code辅助编写Python异步代码时的事件循环陷阱

上周我在一个实时数据管道项目里，让 Claude Code 帮我把同步的 Kafka consumer 改成异步高并发版本。它生成的第一版代码看起来完全正确，async def、await、asyncio.gather 全用上了。我把代码放进测试环境，跑了 15 分钟，系统崩溃了，报错是：

RuntimeError: This event loop is already running
我盯着这行报错看了十分钟，回溯调用栈翻了三层，最后发现 Claude Code 在一个已经运行着事件循环的线程里，又调了一次 asyncio.run()。它不是不会写异步，而是根本不知道“现在已经有事件循环在跑了”这件事。

这就是我接下来要拆解的核心问题：Claude Code 在生成 Python 异步代码时，最大的坑不是语法错误，而是它对“运行时上下文”的无知。 它看不到你的事件循环状态、线程模型、阻塞点分布，于是它会系统性地踩进几类事件循环陷阱。这些陷阱不是随机出现的，而是有规律可循的。下面我会把每一种规律拆开来讲，从根因、到复现场景、到判断方法、到工程化应对方案。

一、核心结论先放前面

如果你用 Claude Code 写 Python 异步代码，先记住三件事：

Claude Code 不感知事件循环的存在状态。 它生成的代码，默认假设“这是一个干净的、什么都没有的 Runtime”，而这个假设在真实项目里几乎从不成立。
最危险的错误不是报错，而是静默阻塞。 它会把同步阻塞操作塞进异步函数，不报错，但事件循环被卡死，吞吐量直接断崖。
你没法靠“更会写 prompt”彻底解决这个问题。 因为 Claude Code 缺少对程序运行时上下文的可见性，你得从架构上给它建立“安全边界”。
这三条不是我在复述官方文档，是我在过去 8 个月里，用 Claude Code 写了两个异步项目、review 了它生成的至少 400 个异步函数片段之后，总结出来的判断。

二、真实背景：为什么事件循环会成为 AI 辅助编程的“高危地带”

先给不熟悉 Python 异步的人快速铺垫一下。事件循环（Event Loop）是 asyncio 的核心，它是一个在单线程里轮询任务队列的调度器。所有 async def 函数（协程）都要交给事件循环来执行。关键约束有两个：

一个线程里，同一时间只能有一个事件循环在跑。

事件循环在当前协程交出控制权之前，不能去执行其他协程。

这两个约束，在人类开发者写代码时，是靠“我知道我前面写了什么、我知道我程序跑在什么环境里”来保证的。但 Claude Code 没有这个“知道”。

它处理请求的方式是：你给它一个 prompt，它基于这个 prompt 的语义和你附带的上下文片段，生成一个代码片段。这个过程不包含任何对程序运行时状态的感知。它不知道：

你的主线程是不是已经跑了 asyncio.run(main())

你是不是在 FastAPI / Sanic / aiohttp 里，它们都自带事件循环

你的某些函数是不是在线程池里被 loop.run_in_executor 调用的

你的代码里有没有已经挂起的 task

这导致一个奇怪的后果：Claude Code 生成的异步代码，“单独看”几乎总是正确的；“跑起来”却经常崩溃。 这不是它能力不行，是它的设计边界摆在那里。




三、陷阱一：事件循环重复创建，Claude Code 的“单细胞”思维

1. 现象：你已经有一个事件循环了，Claude Code 又帮你建了一个

最常见的触发场景是这样的。你有一个 FastAPI 应用，FastAPI 自己维护着一个事件循环。现在你想加一个异步任务，把数据从 Redis 批量取出来写入 PostgreSQL。你把需求告诉 Claude Code，它生成了这样一个函数：

async def sync_redis_to_postgres():
async with redis.Redis() as r:

data = await r.lrange("queue", 0, -1)

处理 data...

async with asyncpg.create_pool(...) as pool:

async with pool.acquire() as conn:

await conn.executemany(sql, records)

Claude Code 可能会这么写入口

if __name__ == "__main__":

asyncio.run(sync_redis_to_postgres())

这段代码，放在一个独立的脚本文件里跑，一点毛病没有。但如果你把它挂在 FastAPI 的 startup 事件里，或者被某个已经跑在事件循环里的 handler 调用，问题就来了：asyncio.run() 会创建一个新的事件循环，而当前线程里已经有一个在运行了。 Python 3.10 以后，这个行为直接抛 RuntimeError。

2. 核心原因：Claude Code 的“无上下文”假设

Claude Code 生成 asyncio.run() 的时候，它的逻辑链路是这样的：

• prompt 里有“写一段代码，完成 X 任务”
• 它知道 X 任务需要异步执行
• 它生成了一段需要事件循环来驱动的协程代码
• 它“贴心”地帮你补了一个入口，asyncio.run()

这个“贴心”本身没问题。问题是它没法判断：你这段代码最终会放在什么环境里跑？ 是不是已经有事件循环了？是不是应该用 await 而不是 asyncio.run()？这些判断需要的上下文，不在 prompt 里，在 runtime 里。

我用 Claude Code 做项目的时候，观察过一个规律：当一个文件里的异步函数超过 15 个，且这些函数分布在至少 3 个不同的模块里时，Claude Code 大概率会在某个地方错误地插入 asyncio.run() 或 loop.run_until_complete()。

3. 怎么判断是不是这个问题？

排查步骤很简单：

1. 找到报错信息里的调用栈，看 asyncio.run() 出现在哪一行
2. 往上回溯调用链，看这个 asyncio.run() 是不是被一个已经在事件循环里的函数调用了
3. 如果是，你就中了这个陷阱

一个快速判断的 shell 指令：在 Python 3.10 及以上，如果你的报错是 RuntimeError: asyncio.run() cannot be called from a running event loop，那毫无疑问。

4. 工程化应对：一个“事件循环感知”的安全入口

我不能让 Claude Code 自动感知事件循环，但我可以给它写一个安全的入口，让它的代码不管在什么环境下都能安全运行。这个入口的核心逻辑是：

import asyncio
import threading

def safe_run_async(coro, loop=None):

"""

安全地运行一个协程：如果当前线程已有事件循环，就复用；否则创建新的。

这个函数应该作为所有 Claude Code 生成代码的“安全封装”。

"""

try:

running_loop = asyncio.get_running_loop()

except RuntimeError:

running_loop = None

if running_loop is not None:

当前线程已有事件循环在运行，不能再调 asyncio.run()

必须把协程作为一个 task 提交

if loop is None:

loop = running_loop

return loop.create_task(coro)

else:

当前线程没有事件循环，可以安全地创建一个

if loop is None:

return asyncio.run(coro)

else:

return loop.run_until_complete(coro)

关键点：这个函数并不解决所有问题，它解决的是“让 Claude Code 生成的代码不至于因为重复创建事件循环而直接崩溃”。 把这段代码放进你的项目 utils 里，然后告诉 Claude Code：“所有需要运行协程的地方，用 safe_run_async 而不是 asyncio.run()。”

我测试过几轮，在 5 个不同规模项目的 prompt 里嵌入这个约束之后，事件循环重复创建的错误率下降了大约 80%。

四、陷阱二：同步阻塞操作被偷偷塞进 async def，最隐蔽的循环杀手

1. 这个陷阱为什么比报错更危险？

前面说的 asyncio.run() 重复创建事件循环，至少会报错。你马上知道有问题。

但同步阻塞操作被塞进 async def，不报错。事件循环照样跑，程序不崩溃，CPU 使用率也不高，只是你发现吞吐量差了 5 倍、10 倍、甚至更多。

我第一次遇到这个问题是在做一个文件读取密集型任务。Claude Code 帮我写了一段代码，从 S3 批量下载文件、解析 JSON 然后入库。代码长这样：

async def process_s3_file(s3_client, bucket, key):
response = s3_client.get_object(Bucket=bucket, Key=key)

data = json.loads(response['Body'].read())

return await save_to_db(data)

这里的问题是：s3_client.get_object() 是 boto3 的同步方法。它会在发起 HTTP 请求、等待响应、读取数据的过程中，阻塞当前线程。因为是同步 I/O，它不会交出事件循环的控制权。整个事件循环就被这一个文件的下载给卡住了。

而 Claude Code 把它放进 async def 里的理由非常自然，它看到 await save_to_db(data) 是异步的，就认为整个函数应该定义为异步。但它没有能力区分哪些底层调用是同步阻塞的、哪些是真正的异步非阻塞。

2. 根因：Claude Code 的“库调用模式匹配”是模糊的

这一点很关键。Claude Code 判断一个函数是否该标 async，主要基于这些线索：

• 函数内部有 await 表达式 → 标 async
• 函数名里包含 async 关键词 → 标 async
• prompt 里写了“异步”、“高并发”、“事件循环” → 函数更可能标 async

但是 s3_client.get_object() 这种库调用，它既没有 await，也不包含明显的关键词。Claude Code 默认把它当作“普通调用”，然后就出现了一个 async def 内部藏着一个同步阻塞 I/O 的杂种函数。

这类错误在真实项目里比事件循环重复创建更难发现，因为：

• 它不报错
• 在测试数据量小的时候，阻塞时间短，你感知不到
• 只有并发上来以后，事件循环被多次阻塞，吞吐量才会断崖式下跌

3. 侦查手段：如何系统性地找出这些“蛀虫”

我后来逐步形成了一套检测流程，专门用来审查 Claude Code 生成的异步代码：

第一步：扫描所有 async def 函数的 AST（抽象语法树）。 把函数内所有的函数调用节点提取出来。

第二步：检查这些调用是否属于已知的同步阻塞库。 黑名单类库包括：

• time.sleep
• requests.get/post/put/delete（应该用 aiohttp 或 httpx 的异步客户端）
• boto3 的上层 API（应该用 aioboto3）
• psycopg2（应该用 asyncpg）
• redis-py 的同步客户端（应该用 redis.asyncio 或 aioredis）

第三步：标记出所有“在 async def 内但没有 await 的调用”。 这些调用不一定是阻塞的，但必须逐一审查。

我写了一个简单的检测脚本，放在项目 CI 里，专门针对 Claude Code 生成的文件做扫描。运行下来的结果：每 100 个它生成的 async def 里，大约有 12-15 个混入了潜在的同步阻塞调用。

4. Claude Code 的“补丁”：自动生成 run_in_executor 包装

有一个细节值得特别讲。Claude Code 有时候也能“认识到”它的代码里出现了同步阻塞，然后它会建议你用 loop.run_in_executor 来把同步调用扔到线程池里执行：

async def process_s3_file(s3_client, bucket, key):
loop = asyncio.get_running_loop()

response = await loop.run_in_executor(

None,

lambda: s3_client.get_object(Bucket=bucket, Key=key)

)

data = json.loads(response)

return await save_to_db(data)

这是一个改进，但带来了两个新问题：

问题一：lambda 包 s3_client.get_object 可能引发变量捕获问题。 如果 s3_client 不是线程安全的（事实上 boto3 的某些连接对象确实不是），就会在线程池里报错。

问题二：Claude Code 不知道 run_in_executor 里的线程池应该多大。 它默认用 None，对应 Python 默认的线程池（Python 3.8 之后默认是 32 个线程）。如果你的并发远大于 32，线程池就成了新瓶颈。

对于这两个问题，我的做法是：

• 不让 Claude Code 替我管理线程池。 我自己在项目初始化时显式创建 ThreadPoolExecutor，并把它作为参数传给所有需要它的函数。
• 在项目文档里明确标注：哪些库是线程安全的，哪些不是。 把这个信息写进 .claude.md，让 Claude Code 在生成 run_in_executor 时引用。

五、陷阱三：Claude Code 的“上下文遗忘症”，跨文件的异步签名不一致

1. 典型场景：重构一半，签名变了，调用方没变

这是最难排查的一类错误，因为报错信息通常不直接指向根因。

举个例子。我有一个项目，结构如下：

services/
├── fetcher.py      # 数据抓取

├── processor.py    # 数据处理

└── storage.py      # 数据存储

最初，fetcher.py 里有一个函数是同步的：

# fetcher.py
def fetch_user_data(user_id):

return requests.get(f"{API_URL}/users/{user_id}").json()

后来我让 Claude Code 优化性能。它正确地识别出网络 I/O 是瓶颈，于是把 fetch_user_data 改成了异步：

# fetcher.py (v2)
async def fetch_user_data(user_id):

async with httpx.AsyncClient() as client:

resp = await client.get(f"{API_URL}/users/{user_id}")

return resp.json()

问题在于，processor.py 里还有一堆调用 fetch_user_data 的代码，它们没有跟着改：

# processor.py (未修改)
def process_user(user_id):

user_data = fetch_user_data(user_id)  # 现在返回的是一个 coroutine 对象，不是 dict

return transform(user_data)

由于 Python 的动态类型，fetch_user_data(user_id) 的返回值变成了一个 coroutine 对象，但 process_user 不会报错，直到后面的 transform(user_data) 试图把一个协程对象当字典来用时才会崩。

而 Claude Code 并不知道 processor.py 里存在这些调用。 因为它一次只能看到你给它的一部分代码。你让它改 fetcher.py，它就只改 fetcher.py。调用方不受影响，是人的问题，但人来排查这种跨文件的不一致，成本极高。

2. 这类错误为什么在异步代码里特别严重？

同步代码里也有类似问题（改了返回值类型，调用方没改），但异步代码有两个特性让问题严重得多：

• 协程对象不会立即执行，错误被延迟了。 你把一个协程对象当普通值传递，不调用 await，它不会报错，只是一直不被执行。等到后面某个环节突然发现类型不匹配，回溯调用链的成本极高。
• 异步项目的依赖图更分散。 因为 await 的存在，调用关系经常跨模块、跨函数，人工追踪很费劲。

我有一个实际的踩坑记录：修改了一个底层异步函数后，报错信息出在第 7 层调用栈上，根因在第 2 层。排查花了将近 40 分钟，而问题只是“少了一个 await”。

3. 工程化方案：用类型注解 + CI 静态检查做防线

针对 Claude Code 的这个特性，我在项目里强制加了两道防线：

第一道：要求所有 async def 必须有完整的类型注解，包括返回值。

让 Claude Code 在生成代码时就遵循这个规则。在 .claude.md 里写：

所有 async 函数必须带有返回类型注解，例如：
async def fetch_data(url: str) -> dict:

类型注解本身不会阻止错误，但它让后面的静态检查工具（mypy、pyright）能工作了。

第二道：CI 管线里跑 mypy --strict，拦截协程对象被错误传递的情况。

mypy 能检测出这类问题：

# mypy 会报：Incompatible types in assignment (expression has type "Coroutine[Any, Any, dict]", variable has type "dict")
user_data: dict = fetch_user_data(user_id)  # 缺少 await

我在项目里设置：CI 管线里的 mypy 检查不过，不允许合并代码。这个规则配上 Mandatory 的类型注解，能挡住大约 70% 的异步签名不一致问题。

六、陷阱四：Claude Code 的 asyncio.gather 缺失，高并发沦为“串行排队”

1. 现象：代码看着是异步，执行起来却是串行

这是我见过最伤感情的一个坑。你让 Claude Code 写一段批量请求的代码，它的输出是这样的：

async def fetch_all_users(user_ids):
results = []

for uid in user_ids:

user_data = await fetch_user(uid)

results.append(user_data)

return results

这段代码没有语法错误。async def、await ， 一个不少。但它完全不是并发的。

因为 await 是在循环体内逐个执行的。它等于先等 fetch_user(uid_1) 完成，再开始 fetch_user(uid_2)，再等它完成…… n 个并发请求退化成了一个串行队列。

正确的写法应该是：

async def fetch_all_users(user_ids):
tasks = [fetch_user(uid) for uid in user_ids]

return await asyncio.gather(*tasks)

或者用 asyncio.TaskGroup（Python 3.11+）：

async def fetch_all_users(user_ids):
async with asyncio.TaskGroup() as tg:

tasks = [tg.create_task(fetch_user(uid)) for uid in user_ids]

return [t.result() for t in tasks]

2. 为什么 Claude Code 会犯这个错误？

这个错误的根因比“不知道有事件循环”更深层。它涉及到 Claude Code 对“异步”这个词的理解偏差。

Claude Code 的“异步”概念主要来自语法层面，它知道 async 和 await 是配对的。但它对于“并发调度”这件事没有体感。因为并发调度靠的是事件循环的机制（创建 Task、把 Task 提交给事件循环、让事件循环在多个 Task 之间切换），这些机制在代码里是通过 asyncio.gather、asyncio.wait、TaskGroup 等调度 API 来体现的，而这些 API 的调用，不在 async/await 的语法范围内。

换句话说，Claude Code 理解了“怎么定义协程”，但没完全理解“怎么调度协程”。

我的统计：在我 review 过的 Claude Code 生成的批量异步请求代码中，它自动使用 asyncio.gather 或 TaskGroup 的比例大约只有 40%。剩余 60% 都是串行 for + await 的模式。

3. 怎么修正？把“并发调度”写进 prompt 规范

在我的项目里，对于任何涉及“批量”、“多个”、“遍历请求”的异步任务，我会在 prompt 里明确指定：

当需要并发执行多个异步任务时，使用 asyncio.gather 或 asyncio.TaskGroup，不要在 for 循环里逐个 await。

这句话写进了 .claude.md 里。实施之后，Claude Code 生成的批量请求代码中，正确使用并发调度的比例从 40% 提升到大约 85%。

七、陷阱五：那些被 Claude Code 悄悄藏起来的 Future 和 Task 泄漏

1. Task 泄漏是什么？

Python 的 asyncio 里，Task 是协程的“执行句柄”。当你 create_task 之后，这个 Task 就会在事件循环里跑。如果它跑完了，没问题。但如果它没跑完，或者被忘记了，就会一直挂在事件循环上。

Claude Code 生成的代码里，最容易出现 Task 泄漏的场景是“创建了 Task 但没有收集结果，也没有取消”。

async def main_loop():
while True:

asyncio.create_task(handle_event(event))  # Task 被创建了，但没有被 await 或 cancel

await asyncio.sleep(1)

这个代码每次循环都会创建一个新的 handle_event Task。如果 handle_event 的耗时大于 1 秒，Task 就会越积越多，直到内存爆掉。

2. 这个问题不是 Python 特有的，但 Claude Code 让它更易发

任何异步编程模型都有类似的“并发泄漏”问题。但 Claude Code 生成的代码里，这个问题更常见，原因是：

• 它在生成代码时，更关注“功能是否正确”，而不是“资源是否被正确回收”。
• 它倾向于用 create_task 来“异步化”调用，但不会自动补上对应的 await、cancel、或 TaskGroup 管理。
• 在长函数里，它可能在前面创建了一个 Task，但后面的异常处理没有 cancel 它。

我在一个 websocket 项目中遇到过这种情况，Claude Code 生成的连接管理代码，在连接断开时没有取消对应的心跳 Task，导致 Task 数量线性增长。跑了大概 2 小时后，内存从 150MB 涨到了 1.2GB。

3. 强制规则：Task 必须可追踪、可取消

我给 Claude Code 加了这么一条规则：

所有 asyncio.create_task 创建的 Task，必须被收集到一个集合里，并在适当的清理阶段被取消或 await。

对应的安全代码模板是：

active_tasks: set[asyncio.Task] = set()
async def safe_create_task(coro) -> asyncio.Task:

task = asyncio.create_task(coro)

active_tasks.add(task)

task.add_done_callback(active_tasks.discard)

return task

async def cleanup():

for task in list(active_tasks):

task.cancel()

await asyncio.gather(*active_tasks, return_exceptions=True)

我把这个模板放进项目公用模块，然后告诉 Claude Code：“创建 Task 时用 safe_create_task，别用裸的 create_task。”这样即使用它忘记 cancel，至少 Task 集合是可追踪的。

八、如何系统性地降低 Claude Code 异步代码的风险，一个工程化框架

前面五个陷阱讲完了。这里我把应对方案整合成一个系统化的工程框架。这个框架不是“让 Claude Code 写出完美代码”的方案，而是 “让 Claude Code 的异步代码不至于炸掉你的生产环境” 的方案。

第一步：建立项目级的异步安全约束文件（.claude.md）

在项目根目录放一个 .claude.md，写清楚以下内容：

1. 事件循环管理规则： 不要在任何地方调用 asyncio.run() 或 loop.run_until_complete()。所有协程通过 safe_run_async 执行。
2. 阻塞调用黑名单： time.sleep、requests.xxx、boto3 上层 API、psycopg2 等必须替换为异步版本或通过 run_in_executor 包装。
3. 并发调度规则： 批量异步任务必须用 asyncio.gather 或 TaskGroup，禁止在 for 循环内逐个 await。
4. Task 管理规则： 所有 create_task 必须使用 safe_create_task 封装，Task 集合在退出前统一清理。
5. 类型注解规则： 所有 async def 必须有完整的参数和返回值类型注解。

第二步：建立异步代码审查的“人工 checkpoint”

Claude Code 生成的异步代码，我会在合入主分支前对以下 5 个点逐一检查：

• [ ] 有没有裸的 asyncio.run()？
• [ ] async def 内有没有 time.sleep、requests.xxx 等同步阻塞调用？
• [ ] 批量并发请求是否用了 gather / TaskGroup？
• [ ] create_task 有没有对应的生命周期管理？
• [ ] 跨文件的函数签名是否一致？（用 mypy 辅助检查）

这个 checklist 我给团队里每个用 Claude Code 的人都发了一份。实施后，异步相关 bug 的线上逃逸率降低了大约 60%。

第三步：用 CI 自动化异步代码质量检查

在 CI 里集成以下检查：

1. mypy –strict：拦截类型不匹配（包括缺少 await 导致的类型错误）。
2. 自定义 AST 扫描脚本：扫描所有 async def 函数，检查是否包含来自同步阻塞库黑名单的调用。
3. ruff 或 pylint 的异步规则：检测“在 async def 中调用 time.sleep”等典型错误。
4. 压力测试：在 staging 环境中用并发压测来验证吞吐量是否达到异步应有的水平。

九、不同场景下的取舍：没法做到 100% 安全时的决策逻辑

现实情况是，即使上了前面所有手段，Claude Code 的异步代码还是会有残留风险。工程上要做的是在不同场景下做正确的取舍。

场景 A：内部工具、数据脚本、一次性任务

风险容忍度可以高一些。 这类代码不直接面向用户，崩溃了重启就行。

决策： 不必追求完全的异步安全性。允许 Claude Code 使用更“野生”的写法，但在入口处加一个统一的事件循环安全检查（比如前文的 safe_run_async），避免频繁报错打断工作流。

场景 B：API 服务、web 后端、面向用户的功能

风险必须很低。 异步问题会导致请求超时、响应变慢、甚至服务不稳定。

决策： 严格实施前面讲的三阶段防线。CI 检查不过不允许合并。用并发压测作为门禁。

场景 C：数据处理管道、流处理、实时系统

风险必须极低。 这类系统的异步问题会造成数据丢失或不一致。

决策： 除了三阶段防线外，额外加上：

• 生产环境的 slow task 监控：记录事件循环中耗时超过一定阈值（比如 100ms）的 Task，用它来发现未被检出的同步阻塞调用。
• 显式的背压机制：不让 Claude Code 自由决定并发量，而是由开发者明确设置并发上限（如 asyncio.Semaphore）。

十、一些你可能会问的具体问题

Q1: Python 版本对这些陷阱有影响吗？

有，而且不小。

• Python 3.10 及以后，asyncio.run() 对“在已有事件循环中重复调用”的限制变得更严格，直接抛 RuntimeError。asyncio.run() inside a running event loop 不再默默创建新的 loop，而是报错。这让“事件循环重复创建”这个问题至少变得可见了。
• Python 3.11 引入的 TaskGroup 让 Task 管理更结构化，显著减少了 Task 泄漏的可能性。如果项目跑在 3.11+，我会建议把 asyncio.gather 尽量替换成 TaskGroup，前者允许部分 task 失败后继续跑，后者默认任何一个 task 失败都会取消其他 task，更安全。
• 3.12 的 asyncio 引入了一些性能优化，但陷阱类型没有根本性变化。

我的建议：如果你的项目用 Claude Code 大量写异步代码，尽量跑在 Python 3.11 以上，至少 3.10。早期版本里很多错误是静默的，更难排查。

Q2: 用 nest-asyncio 是不是解决问题了？

不要。 nest-asyncio 是通过 patch asyncio 来允许嵌套事件循环。它“解决了”报错，但只是把问题盖住了。嵌套的事件循环会产生几个隐蔽的副作用：

• Task 的运行顺序变得不可预测
• 异常传播路径可能绕过正常的 handler
• 与 uvloop 等第三方事件循环实现不兼容
• 在生产环境下，它是“定时炸弹”级别的存在

Claude Code 有时候会在报错后建议你 install nest-asyncio。这是一个 flag，说明前面有事件循环重复创建的问题没解决。 应该去找根因，而不是打 patch。

Q3: 怎么让 Claude Code 更“懂”异步？

根据我的经验，最有效的 prompt 策略不是教它异步知识，而是给它具体的工程约束。

❌ 无效的 prompt：

“请帮我写一段正确的异步代码”

✅ 有效的 prompt：

“项目的事件循环在主线程中已初始化。所有新函数应该是 async def，使用 httpx.AsyncClient 而不是 requests。批量请求用 asyncio.gather。不要调用 asyncio.run()。”

后者给了它具体的边界，限制它的“自由发挥空间”。而 Claude Code 在边界清晰的条件下，生成的代码质量会明显更高。

十一、结语：Claude Code 是一个很好的“协程打字员”，但不能替你守事件循环的边界

写到最后，我把自己过去几个月跟 Claude Code 异步代码的博弈总结成一句话：

Claude Code 能写出语法完美的异步代码，但它不知道你的程序现在“跑在什么状态里”。 事件循环问题的根源就在这里。

你不需要因为它有这些陷阱就不用它。我的团队还在大量用它写异步代码，生产效率提升是实打实的。但我们现在会做三件额外的事：

1. 在项目里建立异步安全约束文件，让 Claude Code 在一个有边界的空间里生成代码。
2. 每次提交前，用 checklist + CI 检查来兜底。
3. 关键路径的异步调度逻辑，自己设计；让 Claude Code 生成的是“填空”部分，而不是架构部分。

这三件事做下来，Claude Code 带来的异步代码风险就从“不可接受”降到了“可控”。

下一步你可以立刻做的：

• 在你的项目根目录建一个 .claude.md，把本文第六节里的五条规则写进去。
• 下一次 Claude Code 给你生成异步代码时，按第七节的 checklist 逐条过一遍。
• 把 safe_run_async 放进你的 utils，以后所有 Claude Code 生成的入口都用它。