project-doc-update

name	project-doc-update
description	在需要对项目文档进行修改、添加、删除、整理时触发。该skill包括了项目的文档组织方式、文档的撰写规则。

文档组织

实验性横向技术路线

若一个新的技术路线影响数据、训练、评测中的多个链路，那么需要在 ExperimentalTracks/ 中添加对应文档，文档名为 YYMMDD-技术路线名.md，并在 Overview.md 中添加该技术路线文档的链接。

共享技术

若一项技术被数据、训练、评测中的多个链路使用，该技术放在 Shared/ 中，文档名为 YYMMDD(可选)-技术名.md，并在涉及到的链路对应的文档里被链接。

故事线

项目的主线叙事（背景、相关工作、目标）放在 Storyline/ 中，对应 Introduction.md / RelatedWork.md / Target.md。这几篇由 Overview.md 在顶部链接，修改时保持一致。

调研笔记

调研、背景比较、决策依据类文档放在 ResearchNotes/ 中，按主题分子目录：Data/ Models/ Training/ Eval/ Benchmarks/ RelatedPapers/。新建调研笔记时，把文件放到对应子目录，并在 ResearchNotes/ResearchNotesOverview.md 的索引里加一条指向它的 wiki 链接。

常用目录

• 数据集的描述、特殊处理、过滤规则等若内容较多，在 Data/ 下按需创建子目录（如 Data/Datasets/<dataset name>/），对应目录需要有一个入口文档，并链接其他文档。
• 对于训练、评测等其他目录，同理。

灵活性

• 由于科研过程的多样性，很难设计一套能应对所有情况的文档组织形式。因此，这里不对可能涉及到的所有情况做详尽列举和要求，文档的组织应当满足以下几个总体规则：

1. 技术路线分类 (a) 跨多个链路的实验性技术，应当放在 ExperimentalTracks/ 中。 (b) 只涉及到单个链路的实验性技术，可以在对应的链路中创建对应的文档或子目录。

2. 文档与子目录的选择 选择创建"单个文档"还是"包含多个文档的子目录"，主要取决于内容的篇幅。

3. 入口文档与链接规则 (a) 如果创建子目录，则该子目录必须包含一个入口文档，用于链接子目录内的其余文档。 (b) 无论是创建文档还是子目录，都需要有链接指向新创建的文档或子目录的入口。

4. 实验方案的定期整理 在 AI 科研项目中，后续的实验设计通常取决于之前的实验结果，因此需要定期对新创建的实验方案进行整理。整理原则如下： (a) 确认无用或不再使用的内容：放入 Archived 文件夹内（若不存在可新建），并取消对该文档的所有链接。 (b) 确认有效的内容：考虑将其合并入主线。 (c) 同类型实验：如果有多个同类型的实验，需要创建对应的子目录，并使用 Records 子目录来记录这一系列的实验。

格式

• 日期格式为 YYMMDD，如 260203。
• 文件名和目录名不含空格，使用 CamelCase 或连字符（例如 DataOverview.md、260203-track-name.md）。

文档撰写

撰写规则

• 文档需要简洁清晰，不要撰写冗余内容。比如对于一次评测，不用把每个评测产物结果文件的路径都放入文档，只需要关注评测的关键设定、结果数据、结论。
• 对于表格：
  • 若表格为长条状，优先在横向铺开，而不是占用很多纵向空间。比如，如果对于一个或多个评测有很多个评测项，那么每一列表示一个评测项。这样表格的行数会比较少。
  • 表格中的数据直接写入，而不是用 backtick 符号包裹。
• 对于脚本文件：
  • 如果是供用户手动运行的脚本文件，需要写绝对路径，方便用户复制。
• 注意：已有的文档不一定完全遵循上面的规则，所以不需要保持和已有文档一样的格式，而是按照上面约定的规则进行撰写。

文档整理

• 实验性横向技术路线并入主线：如果一项 ExperimentalTracks/ 下的技术路线被并入主线，将该文档移动至 Shared/ 目录下，文件名不用修改。需要在 Overview.md 中更新相关内容。
• 实验性横向技术路线被放弃：移动至 ExperimentalTracks/abandoned/，在文档头部追加放弃原因（一句话）、放弃日期、关键结论/数据链接，并取消来自其它文档的链接。
• 数据处理、训练实现和训练记录、评测实现和评测记录相关文档归档：Data/ Training/ Eval/ 目录下各有 Records/ 目录，记录对应的实现改动和运行，每个文件对应那一次的更改与运行，并被对应的 DataOverview.md / TrainingOverview.md / EvalOverview.md 所链接；Records/ 下各有 Archived/ 目录，收纳过时的、无用的或已经被整理成结论的记录。在触发整理或者用户显式地让你对某些记录进行整理时，把对应的记录文档移入对应的 Archived/ 目录，并在对应的 Overview 文档中删除对应的链接。
• 调研笔记过时：若某篇调研笔记对应的方案已被放弃或被更新的调研取代，在 ResearchNotesOverview.md 的索引里标注（如 (已过时) 或 (被 [[ ]] 取代)），必要时移入 ResearchNotes/ 下的 Archived/ 子目录。