最近在写项目相关的技术沉淀文档，因为有cursor的存在，写技术文档的方式跟之前相比有了一些新的方式和方法，特此记录分享。
在编写技术沉淀文档之前，我们的主要目的有两个：一是帮助团队的新成员更快地熟悉现有的逻辑，二是使当前团队成员同步了解实现细节和注意事项。提高团队的信息透明度，不仅能够减少代码迭代过程中出现错误的概率，还能增强整体协作的效率。
在AI时代，这些文档还可以被集成到IDE中的大型语言模型（LLM）中，提升仓库的上下文理解能力，从而在代码提示、AI审查（AI Review）和代码优化方面取得更好的效果。当然，这也有赖于我们选择的工具，比如目前广泛使用的Cursor和它集成的Sonnet模型，正是因为这些工具的强大性能使得这一切成为可能。
然而，实现上述目标的前提是高质量的技术文档。只有内容精准、图文并茂且简明扼要的文档，才能真正有效地传达方案和思路。因此，我对AI辅助文档撰写方向进行了初步的探索，希望这些尝试能为大家带来一些启发和帮助，最近一直在用cursor，便以此为例来说明。
Cursor的预配置
- 对当前项目生成代码向量索引，从而可以
@CodeBase提问问题。 - 建议使用
.cursorrules和cursorignore来提升模型的回答表现，具体例子可以网上搜一下。 - 如果已有针对这个项目的文档，可以加到
Docs中，也会作为问题的上下文提升模型的回答表现。
撰写文档的工具
其实我本人对这部分没做过多研究，因为现在市面上有很多AI结合的文本编写工具，我没试用过太多，如果这类文档用得好的话，是可以避免让大模型优化的步骤的，但是我实际体验，随时的补全和提示会导致自己的行文思路被打断，思考连贯性受影响。
所以我习惯直接在支持MardDown格式的编辑器里面写一版，整个过程一气呵成，而后再做润色和错别字修正的问题，这样整个文章分块的思维脉络是完整的。所以在使用AI工具来辅助写作时，一定要记住要写的内容和思路一定是掌握在作者手里，不要被AI牵着鼻子走。
较清晰的业务逻辑
- 首先这部分逻辑撰写人是熟悉的，那建议直接上手写一版，第一版要争取把逻辑描述清楚，行文啰嗦一点也无所谓。
- 借助openai或者一些别的模型，优化自己的内容表述，提示词类似：优化如下的技术文档表述，使之简明扼要，等等。
- 转入
cursor，开启对话模式，然后打开技术文档涉及到的仓库，@CodeBase后进行提问业务逻辑涉及的片段，做一个代码的解读/逻辑介绍。 - 结合第三步的结果，丰富整体的表述，代码引用相关可完全参考
cursor的输出。 经过以上四步成文后可以再看下条理性，如果有必要可以在用LLM优化一轮，用任何模型都可以，不过清晰的业务逻辑的条理性不会很复杂，一般这里的结果已经很OK了。
复杂的业务逻辑
先说明下复杂的定义，暂且认为代码复杂或者需求复杂，只有有一个，就认为是复杂的内容，因为复杂，所以在表述时要更注重条理清晰和表述的正确性，针对这类文档，建议按照如下步骤进行：
- 进入
Cursor，在对话模式开启@CodeBase后提问业务逻辑涉及的内容，但是主要提示词为：请为我提供一套介绍这段逻辑的大纲/我想说明白这段逻辑，有哪几个方面是值得展开的呢。 - 结合第一步的内容反馈和自己对这段业务逻辑的理解，输出一份逻辑清晰的描述大纲，注意这段大纲的核心是梳理条理，可能人占的主导更多一些，要尽可能考虑受众想要从文档里面获取的信息。
- 针对提纲里面的每一块内容，结合自己的理解 +
cursor的输出(正常提问即可)，以把问题说明白为目标，行文完成当前提纲小节的第一个版本，并依次完成初稿。 - 把初稿喂给
cursor，注意关联下主要的依赖文件和CodeBase(可选)，让cursor看描述有无错误或者可改进的地方，不过这部分提议不一定全部接受，需要结合自己的详略安排来修正。 - 完成第一次修正稿后，可以直接扔给
chatGPT等，改一下文法和描述的语句，可以只选择部分感觉比较啰嗦或者重复的地方，因为已经基本完成行文，只做部分修正即可，主逻辑不要让GPT来动。 经过以上步骤，一篇较为靠谱的文档已经完成，不过上述步骤可能略微繁琐，可以结合自己的实践选择部分步骤，主要目的还是把事情写明白，当然有文采就更好了。
重视反馈
无论成文过程是怎样，评价一个文档优劣的关键在受众手上，再引人入胜的文档也不能言而无物，所以看文章的人的回馈是更重要的一部分，针对读者的部分建议，也可以扔给AI咨询下修改方向和内容。 不过我实际体会下来，及时反馈的文章修改可能还是作者自己来更靠谱，因为读者针对某个细节的回复往往有一个只有作者和读者知道的上下文，这部分可能很难传递给大模型，所以更建议作者自行修改，不过行文的通顺性还是可以通过模型加以修正。
