Research Session Flow

research-session-flow

一个 [Claude Code](https://claude.ai/code) skill，用于科研项目的初始化、文档维护、session 交接与日终收束。

---

科研项目的文档问题，往往不是从一开始就乱的。

跑到第三次实验迭代的时候，发现 results.md、paper-plan 和邮件附件里各有一个 accuracy，三个数字没有一个一样。改到 V7 版本，已经不记得 V3 和 V4 到底改了什么、哪次跑出来的结果还算数。session 结束前忘了写交接，第二天重新打开项目，光是回忆"上次做到哪"就花了半小时。工作区还堆着二十个未提交文件，git log 已经一周没动。

这些不是粗心，是科研项目没有文档结构的必然结果。

`research-session-flow` 是一个面向 Claude Code 的科研项目管理 skill。设计上有三条硬规则：

• 单一来源：results.md 是实验数字的唯一权威，paper-plan.md 是论文叙事的唯一权威，方法描述、版本日志各归其位
• handoff append-only：每次 /research handoff 新建一份文件，不回改历史；历史 handoff 的"下一步"全部完成后自动 resolve 归档
• handoff 轻，log 重：handoff 纯文本快速收束不碰 git；log 做日终完整收束，包含分组 commit

---

支持的子命令

子命令	说明
init	初始化。幂等覆盖三种场景：空目录冷启动（git + README + CLAUDE.md + gitignore + docs 全套）/ 旧结构迁移 / 版本升级
handoff	每次新建一份 session 交接；"下一步"全完成的历史 handoff 自动搬到 resolved/
log	日终收尾：写当天开发日志 + 按语义类别分组 commit 未提交改动
update	更新过期文档
status	文档健康检查（默认子命令）
aris	归档 ARIS 产出为中文版，并生成合并完整版
dashboard	HTML 交互看板管理（list / new / render / status）

触发关键词

• handoff：说"写交接"、"交接文档"、"session 结束"、"记录一下进度"时自动触发
• log：说"写日志"、"记日志"、"开发日志"时自动触发
• aris：说"aris"、"归档aris"、"整理aris"时自动触发

标准文档结构

项目根/
├── docs/
│   ├── README.md
│   ├── project/
│   │   ├── overview.md        # 项目 dashboard
│   │   └── paper-plan.md      # 论文规划（唯一）
│   ├── data/
│   ├── methods/
│   ├── evaluation/
│   │   └── results.md         # 实验数字唯一来源
│   ├── dashboards/            # HTML 交互看板（含 render/ 生成器）
│   ├── handoffs/
│   │   ├── resolved/          # 已完成的交接文档
│   │   └── YYYY-MM-DD-HHMM-slug.md
│   ├── journal/               # 每日开发日志
│   └── aris/
├── archive/
│   └── docs/                  # 文档归档入口（用户手动管理）
│       ├── deprecated/
│       └── scratch/
├── scratch/                   # 一次性 HTML 便签（gitignored）
│   └── README.md
├── CLAUDE.md                  # Claude Code 入口
└── AGENTS.md                  # Codex 入口（内容：@ CLAUDE.md）

安装

git clone https://github.c