# Project Doc Update

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

- Skill: `haowenhou/project-doc-update-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add haowenhou/project-doc-update-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haowenhou/project-doc-update-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HaowenHou (https://skillmd.com/u/haowenhou)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/haowenhou/project-doc-update-2

---


# 文档组织

## 实验性横向技术路线
若一个新的技术路线影响数据、训练、评测中的多个链路，那么需要在 `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/` 子目录。