diff --git a/CLAUDE.md b/CLAUDE.md
index 6b69e40..06d9b67 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -485,3 +485,27 @@ export async function queryVideos(request: QueryRequest): Promise<QueryResponse>
 \d kol_videos
 -- 应该看到 idx_star_id, idx_star_unique_id, idx_star_nickname
 ```
+
+## 前后端数据结构一致性
+
+**重要**：后端返回的 JSON 字段名必须与前端 TypeScript 类型定义完全匹配。
+- 前端类型定义位置：`frontend/src/types/index.ts`
+- 修改后端响应结构时，务必同步检查前端类型定义
+- 常见错误：`Cannot read properties of undefined` 通常是字段名不匹配
+
+## 外部 API 参数格式
+
+### 云图 API (GetContentMaterialAnalysisInfo)
+- 日期格式：`YYYYMMDD`（不是 `YYYY-MM-DD`）
+- industry_id：数组格式 `["20"]`（不是字符串）
+- Cookie：直接使用 `sessionid=xxx` 格式
+
+### 品牌 API
+- URL 格式：`/v1/yuntu/brands?brand_id=xxx`（查询参数，非路径参数）
+- 认证：`Authorization: Bearer {token}`
+
+## 前端常见问题
+
+- **Next.js 模块错误**：清理缓存 `rm -rf .next node_modules/.cache && pnpm build`
+- **Ant Design Modal 文字无法复制**：添加 `styles={{ body: { userSelect: 'text' } }}`
+- **CORS 400 错误**：检查后端 `CORSMiddleware` 配置的 `allow_origins`