diff --git a/docs/design/v2.8-direction-notes.md b/docs/design/v2.8-direction-notes.md
index a5e7ddf..765a097 100644
--- a/docs/design/v2.8-direction-notes.md
+++ b/docs/design/v2.8-direction-notes.md
@@ -109,6 +109,7 @@ Mail 是机械投递，不需要智能。当前 46 处 if/_mail 散落在三个
 - 遇到什么问题、怎么解决的  
 - 给下一个 Agent 的建议和注意事项
 POST /api/projects/{pid}/tasks/{id}/comments  {"comment_type": "handoff"}
+⚠️ handoff 不超过 500 字，只写决策/权衡/坑/建议，不写实现细节
 ```
 
 **不告诉它具体步骤，只告诉它目标、工具、约束。Agent 自己决定怎么干。**