ds-explain

ds-explain

用通俗的语言说明某个事物是什么、如何运行，以及它为何形成如今的样子，让读者可以放心地对其进行修改。

步骤

1. 弄清读者需要什么。阅读对话：他们是要修改、审查、调试，还是刚接触这个事物？选出他们应该了解的三四件事，略去他们已经知道的内容。
2. 确定工作量。单个函数只需通读一遍。若要了解跨多个文件的子系统，可以安排 2 到 4 个并行的只读子 Agent，分别从一个角度着手，然后再通读一遍，整合结果。
3. 说明其工作原理。阅读实际代码。追踪从入口点到产生效果的主要运行路径。注意每部分状态由谁负责，以及边界在哪里。引用文件和行号。
4. 说明其设计缘由。检查提交历史、blame、PR 描述、关联的问题和代码附近的注释。区分记录中的内容与推断，并明确标注推断。如果没有相关记录，就如实说明。
5. 撰写说明。先用通俗的语言概括定义，再联系这个代码库进行说明。按实际使用时的顺序讲述发生的事情，然后说明原因，最后说明边缘情况。适用时使用简短图示或表格。
6. 主动提出可以深入讲解一个明确指出的部分。

停止条件

• 已通过引用代码并提供有来源依据的原因，回答了读者的问题。
• 或者，为查找原因进行了三轮搜索，仍未找到记录。说明原因未知。

规则

• 不要编辑代码。
• 每项关于行为的陈述都要指出对应的文件和行号。
• 切勿把对意图的猜测当作事实。
• 解释概念，不要罗列函数。