From c925d17e8f70ed615ab17739a3effedc002fa4b8 Mon Sep 17 00:00:00 2001
From: CoralGarden52 <97677340+CoralGarden52@users.noreply.github.com>
Date: Sun, 8 Mar 2026 06:03:52 +0800
Subject: [PATCH] chore: add TypedDict related prompt to api/AGENTS.md 
 (#33116)

---
 api/AGENTS.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/api/AGENTS.md b/api/AGENTS.md
index 13adb42276..d43d2528b8 100644
--- a/api/AGENTS.md
+++ b/api/AGENTS.md
@@ -62,6 +62,22 @@ This is the default standard for backend code in this repo. Follow it for new co
 
 - Code should usually include type annotations that match the repo’s current Python version (avoid untyped public APIs and “mystery” values).
 - Prefer modern typing forms (e.g. `list[str]`, `dict[str, int]`) and avoid `Any` unless there’s a strong reason.
+- For dictionary-like data with known keys and value types, prefer `TypedDict` over `dict[...]` or `Mapping[...]`.
+- For optional keys in typed payloads, use `NotRequired[...]` (or `total=False` when most fields are optional).
+- Keep `dict[...]` / `Mapping[...]` for truly dynamic key spaces where the key set is unknown.
+
+```python
+from datetime import datetime
+from typing import NotRequired, TypedDict
+
+
+class UserProfile(TypedDict):
+    user_id: str
+    email: str
+    created_at: datetime
+    nickname: NotRequired[str]
+```
+
 - For classes, declare member variables at the top of the class body (before `__init__`) so the class shape is obvious at a glance:
 
 ```python