Back to Details

ds-explain

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ds-explain

ds-explain

Give one plain account of what a thing is, how it runs, and why it has its current shape, so the reader can change it with confidence.
用一段通俗的说明讲清某个事物是什么、如何运行，以及为什么会是当前这个形态，让读者能够有把握地修改它。

Steps

步骤

  1. Work out what the reader needs. Read the conversation: are they about to change it, review it, debug it, or are they new? Pick the three or four things they should walk away knowing. Skip what they already know.
  2. Size the job. A single function needs one pass. A subsystem across many files can use two to four parallel read-only subagents, each on one angle, then one pass to combine them.
  3. How it works. Read the actual code. Trace the main runtime path from entry point to effect. Note who owns each piece of state and where the boundaries are. Cite files and lines.
  4. Why it is that way. Check commit history, blame, PR descriptions, linked issues and comments near the code. Separate what the record says from what you infer, and label inferences clearly. If no record exists, say so.
  5. Write the explanation. Start with a plain definition in general terms, then tie it to this codebase. Walk through what happens when someone actually uses it. Then the reasons, then the edge cases. Use a small diagram or table when it helps.
  6. Offer to go deeper on one named part.
  1. 判断读者需要什么。阅读对话：他们准备修改它、审查它、调试它，还是第一次接触？选出读者读完后应掌握的三到四件事。跳过他们已经知道的内容。
  2. 确定工作范围。单个函数只需处理一轮。涉及多个文件的子系统，可以使用两到四个并行只读子 Agent，让每个 Agent 从一个角度分析，然后再用一轮处理来合并结果。
  3. 分析它如何工作。阅读实际代码。从入口点到最终效果追踪主要运行时路径。记录每一部分状态由谁负责，以及边界在哪里。引用具体文件和行号。
  4. 分析为什么是这样。查看提交历史、blame、PR 描述、关联 issue，以及代码附近的评论。将有记录依据的内容与推断区分开，并明确标注推断。如果没有任何记录，就直接说明。
  5. 撰写说明。先用一般性语言给出通俗定义，再结合当前代码库进行解释。逐步说明用户实际使用它时会发生什么。然后解释设计原因，最后说明边界情况。必要时使用小型图示或表格。
  6. 提出可以进一步深入讲解一个指定部分。

Stop when

停止条件

  • The reader's question is answered with cited code and sourced reasons.
  • Or you have spent three rounds of searching for the reason with no record. Say the reason is unknown.
  • 读者的问题已通过带引用的代码和有来源的理由得到回答。
  • 或者已经用了三轮时间查找原因，却仍找不到任何记录。此时说明原因未知。

Rules

规则

  • Do not edit code.
  • Every claim about behavior points at a file and line.
  • Never present a guess about intent as fact.
  • Explain ideas, do not list functions.
  • 不修改代码。
  • 关于行为的每项论断都要指向具体文件和行号。
  • 绝不把对意图的猜测当作事实。
  • 解释设计思路，不要罗列函数。