Agentic Coding: Humans Design, Agents code!
Agentic Coding: 人类设计，代理编码！

If you are an AI agents involved in building LLM Systems, read this guide VERY, VERY carefully! This is the most important chapter in the entire document. Throughout development, you should always (1) start with a small and simple solution, (2) design at a high level (docs/design.md) before implementation, and (3) frequently ask humans for feedback and clarification.
如果你是一个参与构建LLM系统的 AI 代理，请非常、非常仔细地阅读本指南！这是整个文档中最重要的章节。在整个开发过程中，你应该始终（1）从一个简单的小解决方案开始，（2）在实施之前进行高层设计（ docs/design.md ），以及（3）经常向人类寻求反馈和澄清。

Agentic Coding Steps
Agentic Coding 步骤

Agentic Coding should be a collaboration between Human System Design and Agent Implementation:
Agentic Coding 应该是人类系统设计与代理实现之间的协作：

Steps  步骤	Human  人类	AI	Comment  注释
1. Requirements  1. 需求	★★★ High  ★★★ 高	★☆☆ Low  ★☆☆ 低	Humans understand the requirements and context. 人类理解需求和上下文。
2. Flow	★★☆ Medium  ★★☆ 中等	★★☆ Medium  ★★☆ 中等	Humans specify the high-level design, and the AI fills in the details. 人类指定高层设计，AI 负责填充细节。
3. Utilities  3. 实用工具	★★☆ Medium  ★★☆ 中等	★★☆ Medium  ★★☆ 中等	Humans provide available external APIs and integrations, and the AI helps with implementation. 人类提供可用的外部 API 和集成，AI 协助实现。
4. Node  4. 节点	★☆☆ Low  ★☆☆ 低	★★★ High  ★★★ 高	The AI helps design the node types and data handling based on the flow. AI 帮助设计节点类型和基于流程的数据处理。
5. Implementation  5. 实现	★☆☆ Low  ★☆☆ 低	★★★ High  ★★★ 高	The AI implements the flow based on the design. AI 根据设计实现流程。
6. Optimization  6. 优化	★★☆ Medium  ★★☆ 中等	★★☆ Medium  ★★☆ 中等	Humans evaluate the results, and the AI helps optimize. 人类评估结果，AI 帮助优化。
7. Reliability  7. 可靠性	★☆☆ Low  ★☆☆ 低	★★★ High  ★★★ 高	The AI writes test cases and addresses corner cases. AI 编写测试用例并处理边缘情况。

1. Requirements: Clarify the requirements for your project, and evaluate whether an AI system is a good fit. AI systems are:
   要求：明确项目的需求，并评估 AI 系统是否适合。AI 系统是：
   • suitable for routine tasks that require common sense (e.g., filling out forms, replying to emails).
     适合需要常识的日常任务（例如，填写表格、回复电子邮件）。
   • suitable for creative tasks where all inputs are provided (e.g., building slides, writing SQL).
     适合所有输入都已提供的创意任务（例如，制作幻灯片、编写 SQL）。
   • NOT suitable for tasks that are highly ambiguous and require complex info (e.g., building a startup).
     不适合高度模糊且需要复杂信息的任务（例如，创办一家初创公司）。

   • If Humans can’t specify it, AI Agents can’t automate it! Before building an LLM system, thoroughly understand the problem by manually solving example inputs to develop intuition.
     如果人类无法明确指定，AI 代理就无法自动化！在构建LLM系统之前，通过手动解决示例输入来彻底理解问题，以培养直觉。

2. Flow Design: Outline at a high level, describe how your AI system orchestrates nodes.
   流程设计：从高层次概述，描述你的 AI 系统如何编排节点。
   • Identify applicable design patterns (e.g., Map Reduce, Agent, RAG).
     识别适用的设计模式（例如，Map Reduce、Agent、RAG）。
   • Outline the flow and draw it in a mermaid diagram. For example:
     概述流程并在 mermaid 图中绘制。例如：

3. Utilities: Based on the Flow Design, identify and implement necessary utility functions.
   实用工具：基于流程设计，识别并实现必要的实用功能。
   • Think of your AI system as the brain. It needs a body—these external utility functions—to interact with the real world:
     将你的 AI 系统视为大脑。它需要一个身体——这些外部实用功能——来与现实世界互动：
     
     • Reading inputs (e.g., retrieving Slack messages, reading emails)
       读取输入（例如，检索 Slack 消息，阅读电子邮件）
     • Writing outputs (e.g., generating reports, sending emails)
       写入输出（例如，生成报告，发送电子邮件）
     • Using external tools (e.g., calling LLMs, searching the web)
       使用外部工具（例如，调用LLMs，搜索网页）
     • NOTE: LLM-based tasks (e.g., summarizing text, analyzing sentiment) are NOT utility functions; rather, they are core functions internal in the AI system.
       注意：基于LLM的任务（例如，总结文本、分析情感）不是实用函数；相反，它们是 AI 系统内部的核心功能。
   • For each utility function, implement it and write a simple test.
     对于每个实用函数，实现它并编写一个简单的测试。
   • Document their input/output, as well as why they are necessary. For example:
     记录它们的输入/输出，以及它们为何是必要的。例如：
     • Name: Embedding (utils/get_embedding.py)
       名称: Embedding ( utils/get_embedding.py )
     • Input: str  输入: str
     • Output: a vector of 3072 floats
       输出：一个包含 3072 个浮点数的向量
     • Necessity: Used by the second node to embed text
       必要性：由第二个节点用于嵌入文本

   • Sometimes, design Utilies before Flow: For example, for an LLM project to automate a legacy system, the bottleneck will likely be the available interface to that system. Start by designing the hardest utilities for interfacing, and then build the flow around them.
     有时，在设计流程之前先设计工具：例如，对于一个LLM项目，旨在自动化一个遗留系统，瓶颈很可能是该系统可用的接口。首先设计最难的接口工具，然后围绕它们构建流程。

4. Node Design: Plan how each node will read and write data, and use utility functions.
   节点设计：规划每个节点如何读写数据，并使用实用函数。
   • Start with the shared data design
     从共享数据设计开始
     • For simple systems, use an in-memory dictionary.
       对于简单的系统，使用内存中的字典。
     • For more complex systems or when persistence is required, use a database.
       对于更复杂的系统或需要持久化的情况，请使用数据库。
     • Don’t Repeat Yourself”: Use in-memory references or foreign keys.
       “不要重复自己”：使用内存引用或外键。
   • For each node, describe its type, how it reads and writes data, and which utility function it uses. Keep it specific but high-level without codes. For example:
     对于每个节点，描述其类型、如何读写数据以及使用的效用函数。保持具体但高层次，不涉及代码。例如：
     • type: Regular (or Batch, or Async)
       type : 常规（或批量，或异步）
     • prep: Read “text” from the shared store
       prep : 从共享存储中读取“text”
     • exec: Call the embedding utility function
       exec : 调用嵌入实用函数
     • post: Write “embedding” to the shared store
       post : 将“embedding”写入共享存储
5. Implementation: Implement the initial nodes and flows based on the design.
   实现：根据设计实现初始节点和流程。
   • 🎉 If you’ve reached this step, humans have finished the design. Now Agentic Coding begins!
     🎉 如果你已经到达这一步，说明人类已经完成了设计。现在开始 Agentic Coding！
   • “Keep it simple, stupid!” Avoid complex features and full-scale type checking.
     “保持简单，愚蠢！”避免复杂的功能和全面的类型检查。
   • FAIL FAST! Avoid try logic so you can quickly identify any weak points in the system.
     快速失败！避免使用 try 逻辑，以便快速识别系统中的任何弱点。
   • Add logging throughout the code to facilitate debugging.
     在整个代码中添加日志记录以方便调试。
6. Optimization:   优化：
   • Use Intuition: For a quick initial evaluation, human intuition is often a good start.
     使用直觉：对于快速的初步评估，人类的直觉通常是一个不错的起点。
   • Redesign Flow (Back to Step 3): Consider breaking down tasks further, introducing agentic decisions, or better managing input contexts.
     重新设计流程（回到步骤 3）：考虑进一步分解任务、引入代理决策或更好地管理输入上下文。
   • If your flow design is already solid, move on to micro-optimizations:
     如果你的流程设计已经稳固，接下来可以进行微优化：
     • Prompt Engineering: Use clear, specific instructions with examples to reduce ambiguity.
       提示工程：使用清晰、具体的指令和示例来减少歧义。
     • In-Context Learning: Provide robust examples for tasks that are difficult to specify with instructions alone.
       上下文学习：为那些仅靠指令难以明确说明的任务提供强有力的示例。

   • You’ll likely iterate a lot! Expect to repeat Steps 3–6 hundreds of times.
     你可能会进行很多次迭代！预计会重复步骤 3-6 数百次。

     

7. Reliability  可靠性
   • Node Retries: Add checks in the node exec to ensure outputs meet requirements, and consider increasing max_retries and wait times.
     节点重试：在节点 exec 中添加检查以确保输出符合要求，并考虑增加 max_retries 和 wait 次。
   • Logging and Visualization: Maintain logs of all attempts and visualize node results for easier debugging.
     日志记录与可视化：维护所有尝试的日志，并可视化节点结果以便于调试。
   • Self-Evaluation: Add a separate node (powered by an LLM) to review outputs when results are uncertain.
     自我评估：当结果不确定时，添加一个单独的节点（由LLM驱动）来审查输出。

Example LLM Project File Structure
示例 LLM 项目文件结构

my_project/
├── main.py
├── flow.py
├── utils/
│   ├── __init__.py
│   ├── call_llm.py
│   └── search_web.py
├── requirements.txt
└── docs/
    └── design.md

• docs/design.md: Contains project documentation for each step above. This should be high-level and no-code.
  docs/design.md ：包含上述每个步骤的项目文档。这应该是高层次的且无代码的。
• utils/: Contains all utility functions.
  utils/ : 包含所有实用函数。
  • It’s recommended to dedicate one Python file to each API call, for example call_llm.py or search_web.py.
    建议为每个 API 调用专门创建一个 Python 文件，例如 call_llm.py 或 search_web.py 。
  • Each file should also include a main() function to try that API call
    每个文件还应包含一个 main() 函数来尝试该 API 调用
• flow.py: Implements the system’s flow, starting with node definitions followed by the overall structure.
  flow.py : 实现系统的流程，从节点定义开始，然后是整体结构。
• main.py: Serves as the project’s entry point.
  main.py : 作为项目的入口点。