设计 CrewAI 任务时用：通过清晰…

在创建、配置或调试 CrewAI 任务，需要定义描述、期望输出、依赖、输出格式、校验和人工审核时使用。

适用场景

解决思路

1. 把 80% 的精力投入任务设计，20% 投入 agent 设计；优先改进任务，而不是只依赖更强 agent。
2. 每个 Task 同时定义 description 和 expected_output。
3. description 包含 What：核心动作。
4. description 包含 How：具体步骤或方法。
5. description 包含 Context：为什么做、结果会喂给什么。
6. description 包含 Constraints：范围限制、禁止事项。
7. description 包含 Inputs：可用数据或上下文。
8. expected_output 明确 Format：bullet points、paragraphs、JSON、table 等。
9. expected_output 明确 Structure：sections、headings、顺序。
10. expected_output 明确 Length：近似字数或条目数。
11. expected_output 明确 Quality markers：引用、置信度、特定字段。
12. 避免 expected_output 只写 A research report；改成包含 5 个 section，每节有 trend name、2-3 paragraph summary、source citations、impact rating。
13. 避免 expected_output 只写 An analysis of the data；改成 markdown table，列为 metric name、current value、30-day trend、recommended action，至少 10 个 metric。
14. 避免 expected_output 只写 A blog post；改成 1000-1500 word 技术博客，包含 title、introduction、3-4 main sections with code examples、conclusion with next steps。
15. 遵循 Single Purpose Principle：一个 task 只做一个目标。
16. 不要把 research、analyze、write、proofread 合并成 God Task；拆成 research_task、writing_task、editing_task 等独立任务。
17. 为每个 Task 设置 Essential Parameters：description、expected_output、agent；agent 在 hierarchical process 可选，在 sequential process 必填。
18. 用 context 建立任务依赖：Task(..., context=[research_task]) 接收上游输出作为上下文。
19. 在 sequential process 中，task 会自动接收所有前序 task 输出；仅在需要非线性依赖时显式设置 context。
20. 在 hierarchical process 中，用 context 创建显式数据流。
21. 当下游代码需要解析结果时，用 output_pydantic 或 output_json。
22. 定义 Pydantic BaseModel，例如 ResearchReport 包含 trends、confidence、sources，并传给 output_pydantic。
23. 保持 expected_output 始终为字符串描述，不要放 Pydantic 类名；Pydantic 模型放在 output_pydantic，expected_output 文本告诉 agent 要包含哪些字段。
24. 读取结构化输出：result.pydantic 取最后一个 task 的 Pydantic；result.tasks_output 取所有 TaskOutput；all_outputs[0].pydantic 取指定 task 的 Pydantic。
25. 用 output_file 保存输出到文件，例如设置为 output/report.md。
26. 文件输出时用 create_directory=True 自动创建缺失目录，默认已为 True。
27. 文件输出可与结构化输出组合：文件保存原始文本，output_pydantic 保存解析后的模型。
28. 对可并行的任务设置 async_execution=True，使其不阻塞下一个任务。
29. 对依赖 async 结果的下游任务使用 context 等待其结果。
30. 对关键输出设置 human_input=True，让 agent 在完成前展示结果并等待人工反馈或审批。
31. 不要用 human_input=True 或 Flow @human_feedback 模拟普通后续聊天；对话式 Flow 中下一步用户消息应调用 flow.handle_turn(message, session_id=...)。
32. 需要 markdown 输出时设置 markdown=True，让 agent 按 markdown 标题、列表、强调、代码块格式化。
33. 用 callback 在任务完成后记录或保存输出，例如 callback=log_completion，回调接收 output 对象。
34. 用 guardrails 在下游使用前验证任务输出；验证失败时 agent 会重试。
35. 函数式 guardrail 返回 (bool, Any)：成功返回 (True, output)，失败返回 (False, 错误消息)。
36. 用 guardrail_max_retries=3 控制最大重试次数，默认 3。
37. 用字符串 guardrail 让 agent 的 LLM 做主观质量检查，例如 Verify the output contains at least 3 source citations and no speculative claims。
38. 用 guardrails=[...] 串联多个 guardrail；它们顺序执行，每个接收上一个 guardrail 的输出。
39. 混合函数式确定性检查和 LLM 主观检查，例如先 validate_word_count、validate_no_pii，再检查 tone。
40. 推荐用 YAML 配置任务：在 tasks.yaml 写 research_task、analysis_task、report_task 的 description、expected_output、agent、context、output_file。
41. 在 crew.py 中用 @CrewBase、agents_config 指向 config/agents.yaml、tasks_config 指向 config/tasks.yaml 接线。
42. 用 @task 装饰方法返回 Task(config=self.tasks_config[...])；需要显式依赖时传 context=[self.xxx_task()]。
43. 确保 @task 方法名与 YAML key 完全匹配，例如 def research_task 对应 research_task:。
44. 理解 sequential process 默认按顺序运行，每个 task 自动接收所有前序输出；无需写 context，除非要非线性和显式依赖。
45. 实现显式依赖：Task B context=[task_a]、Task C context=[task_a]、Task D context=[task_b, task_c]，形成 diamond dependency pattern。
46. 用 ConditionalTask 和 condition 函数实现条件任务，例如 needs_more_data(output) 返回 len(output.pydantic.items) < 10，只在条件满足时运行 extra_research。
47. 为特定任务配置 task-level tools：Task(..., tools=[SerperDevTool(), ScrapeWebsiteTool()])，覆盖该任务中 agent 的默认工具。
48. 在以下情况使用 task-level tools：任务需要 agent 通常没有的工具；需要限制 agent 在该任务只用特定工具；同一 agent 的不同任务需要不同工具集。
49. 在 YAML 中用 {variable} 占位符实现可复用任务，例如 {topic}、{current_year}、{target_audience}。
50. 调用 crew.kickoff(inputs={...}) 时提供与 YAML 变量匹配的键值来替换变量。
51. 避免变量错误：inputs 缺变量会导致 prompt 出现字面 {variable}；不要用 Jinja2 的 {{ }}，crewAI 用单花括号 { }；inputs 中未使用变量会被静默忽略。
52. 修复 vague description：加入具体步骤、约束和上下文，而不是只写 Research the topic。
53. 修复 vague expected_output：指定格式、section、长度和质量标记，而不是只写 A report。
54. 修复多目标任务：拆分为单一职责任务，避免 agent 每项都做差。
55. 不要把每轮聊天建模成 Crew task；Task 是批处理或工作流单元，不是会话循环；用 conversational Flow，每个用户消息调用 handle_turn()。
56. 对有依赖的任务补 context=[prior_task]，避免 agent 缺少前序信息。
57. 不要让 expected_output 引用 Pydantic 类；保持人类可读字符串，并用 output_pydantic 指定模型。
58. 对数据任务补齐 tools，避免 agent 编造数据而不是获取数据。
59. 对关键输出加 function 或 LLM guardrails，防止坏输出流入下游。
60. expected_output 要具体但可达成；过于严格会让 agent 死循环，可降低 guardrail_max_retries 更快失败。
61. 避免 description 重复 backstory：description 写做什么，backstory 写 agent 是谁；重复浪费 token 并混淆 agent。
62. 运行前验证 description 包含 what、how、context、constraints。
63. 运行前验证 expected_output 指定 format、structure、quality markers。
64. 运行前验证 single purpose：每个 task 只有一个明确目标。
65. 运行前验证 agent 已分配，或任务处于 hierarchical crew。
66. 运行前验证需要依赖时已用 context 设置。
67. 运行前验证需要外部数据的任务已提供 tools。
68. 运行前验证下游代码解析结果时已配置 structured output。
69. 运行前验证关键输出已设置 guardrails。
70. 运行前验证 YAML 变量与 inputs dict 键匹配。
71. 运行前验证 expected_output 可实现，先做一次简单运行再增加复杂度。
72. 如需深入了解结构化输出，查看 references/structured-output.md，了解 output_pydantic、output_json、response_format 在 LLM、Agent、Task、Crew 层级的模式。
73. 相关技能：getting-started 用于项目脚手架、选择抽象、Flow 架构；design-agent 用于 Role-Goal-Backstory、参数调优、工具分配、memory 与 knowledge；ask-docs 用于查询 CrewAI 文档 MCP server。

适用边界 · 注意事项

• 项目不使用 CrewAI 或其他 CrewAI 专有概念时，不适用。
• 不要把普通多轮对话或会话循环建模为 Crew task；Task 是批处理或工作流单元，不是会话循环。
• 不要用 human_input=True 或 Flow @human_feedback 模拟正常后续聊天；对话式 Flow 中下一步用户消息应调用 flow.handle_turn(message, session_id=...)。