diff --git a/AGENTS.md b/AGENTS.md
index 1a98b0f15e..1b463e3616 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1065,6 +1065,13 @@ slog.Error("failed to set model rate limit",
 )
 ```
 
+#### API 错误响应规范
+- 后端返回错误时，必须使用结构化 JSON，携带错误码和上下文参数，禁止直接返回拼接好的自然语言错误消息
+- 前端根据错误码和参数组装国际化错误提示（i18n），后端不负责拼接用户可见的文案
+- 错误响应格式：`{ "code": <错误码>, "message": "<开发者可读的英文错误描述>", "details": { <上下文参数> } }`
+- `message` 字段为英文错误描述，供开发人员调试使用，前端不直接展示给用户
+- `details` 携带前端渲染所需的动态参数（如 `{ "channel_id": 42, "model": "gpt-4" }`），前端根据错误码匹配 i18n key 并用 `details` 填充模板变量
+
 ### 5. 测试规范
 
 #### Mock 函数签名同步
@@ -1166,6 +1173,21 @@ antigravityRateLimitThreshold
 - [ ] 日志是否包含足够的上下文信息？
 - [ ] 是否考虑了并发安全？
 
+### 11. 代码结构化与解耦
+
+- **禁止跨作用域传递布尔开关**：不要为了在函数末尾使用某个中间状态，将局部变量提到外层作用域。让计算结果结构体自带上下文（如 `cost.BillingMode`），下游直接读取
+- **重复逻辑必须提取公共方法**：两个函数 90%+ 相同时，差异通过参数控制，而非复制粘贴后微调
+- **兼容旧版本用结果分支，不用布尔开关**：新增功能需兼容旧行为时，通过结果对象的字段（如 `resolved.Mode`）自然分支，而非散落各处的 `if hasNewFeature` 检查
+- **变量作用域最小化**：变量只在使用它的最小代码块内声明，不提前声明
+
+### 12. 前端显示规范
+
+- **浮点精度**：价格单位换算使用 `toPrecision(10)` 避免 IEEE 754 误差；倍率显示使用自适应精度，确保小数值（如 0.001）不会被截断为 0.00
+- **条件渲染基于业务语义**：前端显示分支基于业务字段（如 `billing_mode`），而非数据存在性（如 `image_count > 0`）
+- **数值格式化统一**：同类数值（如倍率）在所有页面（管理端、用户端、CSV 导出）使用相同的格式化函数
+<div v-else>Token 明细</div>
+```
+
 ---
 
 ## CI 检查与发布门禁
diff --git a/CLAUDE.md b/CLAUDE.md
index 1a98b0f15e..1b463e3616 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1065,6 +1065,13 @@ slog.Error("failed to set model rate limit",
 )
 ```
 
+#### API 错误响应规范
+- 后端返回错误时，必须使用结构化 JSON，携带错误码和上下文参数，禁止直接返回拼接好的自然语言错误消息
+- 前端根据错误码和参数组装国际化错误提示（i18n），后端不负责拼接用户可见的文案
+- 错误响应格式：`{ "code": <错误码>, "message": "<开发者可读的英文错误描述>", "details": { <上下文参数> } }`
+- `message` 字段为英文错误描述，供开发人员调试使用，前端不直接展示给用户
+- `details` 携带前端渲染所需的动态参数（如 `{ "channel_id": 42, "model": "gpt-4" }`），前端根据错误码匹配 i18n key 并用 `details` 填充模板变量
+
 ### 5. 测试规范
 
 #### Mock 函数签名同步
@@ -1166,6 +1173,21 @@ antigravityRateLimitThreshold
 - [ ] 日志是否包含足够的上下文信息？
 - [ ] 是否考虑了并发安全？
 
+### 11. 代码结构化与解耦
+
+- **禁止跨作用域传递布尔开关**：不要为了在函数末尾使用某个中间状态，将局部变量提到外层作用域。让计算结果结构体自带上下文（如 `cost.BillingMode`），下游直接读取
+- **重复逻辑必须提取公共方法**：两个函数 90%+ 相同时，差异通过参数控制，而非复制粘贴后微调
+- **兼容旧版本用结果分支，不用布尔开关**：新增功能需兼容旧行为时，通过结果对象的字段（如 `resolved.Mode`）自然分支，而非散落各处的 `if hasNewFeature` 检查
+- **变量作用域最小化**：变量只在使用它的最小代码块内声明，不提前声明
+
+### 12. 前端显示规范
+
+- **浮点精度**：价格单位换算使用 `toPrecision(10)` 避免 IEEE 754 误差；倍率显示使用自适应精度，确保小数值（如 0.001）不会被截断为 0.00
+- **条件渲染基于业务语义**：前端显示分支基于业务字段（如 `billing_mode`），而非数据存在性（如 `image_count > 0`）
+- **数值格式化统一**：同类数值（如倍率）在所有页面（管理端、用户端、CSV 导出）使用相同的格式化函数
+<div v-else>Token 明细</div>
+```
+
 ---
 
 ## CI 检查与发布门禁