# Research Project

> Set up, take over, reorganize, and maintain a research project directory so the work stays iterable across months and across agent sessions. Ships four scripts — explore_project.py (read-only survey of an unfamiliar messy project: what it is, what's active, what's stale, versioned duplicates, and the questions to ask the user), migrate.py (applies a user-approved reorganization plan; dry-run by default, moves and archives only, has no delete operation, writes an undo script), init_project.py (canonical layout + PROJECT.md single source of truth, and the dated submission schedule when given a deadline), and project_status.py (audits any directory for unfilled decisions, stale state, deadline vs. writing progress, experiment-log health, and stops hard when the topic scores as already-solved). Use whenever a user starts a project, hands you an existing research folder that wasn't built to this structure, asks to tidy or restructure a project, asks where things stand or what to do next, resumes after a break, men

- Skill: `hughyau/research-project` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add hughyau/research-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hughyau/research-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: HughYau (https://skillmd.com/u/hughyau)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hughyau/research-project

---


# 研究项目的建立、接管与维护

一个 research project 跨越几个月、几十次实验循环、多次 agent 会话。
**Agent 没有跨会话记忆，人也会忘。**没有单一事实源时，每次接手都要重新考古：
当初为什么选这个题？这个实验为什么失败的？下一步本来打算做什么？

这个 skill 建立并维护那个事实源。核心约定只有一条：

> **`PROJECT.md` 是唯一入口。接手任何项目，先读它；做完任何一轮工作，回写它。**

## 三条不可越过的红线

接管别人的项目时，你面对的是一个**你不了解、但对用户很重要**的工作区。

1. **不删除任何东西。** 这个 skill 的工具里根本没有删除操作。
   判断没用的东西移进 `archive/`，附上理由，随时可以移回来。
   你对"这个文件没用"的判断有可能是错的，而代价不对称。
2. **没得到明确同意前不移动任何文件。** 先探查、先汇报、先问。
   用户可能正在跑依赖当前路径的脚本。
3. **保证可回滚。** 动手前先让工作区进入 git 干净状态；
   迁移工具默认 dry-run，执行后生成撤销脚本。

## 工具

```bash
SK=<这个 skill 的目录>

# 新建项目
python3 $SK/scripts/init_project.py <path> --name "<一句话主题>" \
        [--deadline 2026-11-14] [--venue "CVPR 2027"] [--force]

# 探查一个陌生项目（只读，不改动任何文件）
python3 $SK/scripts/explore_project.py <path> [--json] [--stale-days 60]

# 执行用户已确认的整理方案（默认 dry-run，--apply 才动手；只移动和归档，无删除）
python3 $SK/scripts/migrate.py <path> --plan plan.json [--apply]

# 审计（初始化与否都能跑）
python3 $SK/scripts/project_status.py <path> [--json]
```

`init_project.py` 是幂等的——已存在的文件默认跳过并列出来。
`--force` 会重置模板，但**不会直接覆盖**：原件先移进 `archive/<日期>/` 并记进
`archive/MANIFEST.md`，再写新模板。

**投稿排期归这个 skill 管。** 用户给出截稿日期时，直接生成带真实日期的时间表，
不要在对话里复述节奏：`--deadline` 会按方法论的四周节奏写出
`docs/writing/schedule.md`（每行具体日期 + 勾选框），之后 `project_status.py`
持续对照倒计时与章节进度。写作本身怎么做是 `paper-writing` 的事。

## project_status.py 检查什么

它不只是列文件，它执行方法论里的判据：

| 它检查什么 | 为什么这条值得自动检查 |
|---|---|
| 选题落在四种情况的哪一种 | 情况 1/2 = 已有 well-established solution。这时候继续往下做是纯浪费，越早停损越好，所以报 **阻塞** 而不是警告 |
| PROJECT.md 多久没更新 | >14 天意味着接手者会拿到过期状态，比没有状态更危险 |
| 距截稿天数 vs 章节进度 | 方法论要求截稿前一个月启动写作。倒计时进入 30 天而章节全空 → 阻塞 |
| 实验日志里有多少条没写"本质技术原因" | 这些循环没拿到梯度，下一次改动是随机的。这是**项目速度的头号杀手**，比实验做得慢更致命 |
| 最近一条实验记录距今多久 | >7 天说明循环频率掉了，要找原因 |
| §6 下一步是否为空 | 没有明确下一个动作的项目会静默停摆 |

## 走哪条流程

| 情况 | 流程 |
|---|---|
| 全新项目 | **流程 A**（下面，一条命令 + 填 §1 §2） |
| 已有的乱项目，用户要整理 | **流程 B**：五阶段多轮对话，全文见 [references/takeover.md](references/takeover.md) |
| 项目已是这套结构 | **Agent 交接协议**（下面） |
| 用户想干别的活、项目恰好很乱 | 先把活干了，收尾时提一句可以整理，**不要中途自作主张搬文件** |

最后一行是刻意的：整理是一件需要用户投入注意力的事，
挑他没准备好的时候做只会添乱。

### 流程 A：新建项目

```bash
python3 $SK/scripts/init_project.py ~/work/sparse4d \
        --name "稀疏视角下的动态场景重建" --deadline 2026-11-14 --venue "CVPR 2027"
```

然后**先只填 PROJECT.md 的 §1 和 §2**，配合 `research-ideation`。

§2 的"四种情况判定"是闸门：判定为情况 1 或 2 就停下来换 failure case，
不要开始写代码。这一步花半天，能省掉半年。判定完跑一次 `project_status.py`
确认没有阻塞项，再进 §3。

### 流程 B：接管一个已有的乱项目

用户丢过来的是一个跑了几个月、**不是按这套结构建立的**文件夹。
**这是多轮对话，不是一条命令**——五个阶段，每个阶段结束都停下来等用户：

```
1 探查（只读，一个文件都不动）  → explore_project.py
2 汇报画像，问要不要整理        → 先证明你看懂了，再提整理；给 A/B/C 三档
3 拟迁移方案，逐条对齐（多轮）  → migrate.py dry-run，用户几乎一定会改几条
4 执行，然后补骨架              → migrate.py --apply，再 init_project.py 补空缺
5 考古式回填 PROJECT.md         → 找不到的留空，留空比编造好
```

**开始阶段 1 之前先读 [references/takeover.md](references/takeover.md)**：
每个阶段的话术、迁移方案的 `to` 语义、`--apply` 的安全保证、`archive/` 的约定都在那里。
有两处顺序陷阱不看会踩：**先迁移再建骨架**（反了的话用户真实的 `notes.md`
就迁不进 `docs/topic.md`），以及动手前先让 git 进入干净状态。

## 文件格式

目录结构、`PROJECT.md` 六节各自何时回写、实验日志一条记录的合格标准
（含一个不合格→合格的改写实例）：[references/files.md](references/files.md)。

需要建目录、回写 PROJECT.md、或判断一条实验记录合不合格时读它。
其中一条判据值得先知道：**实验日志的目的不是记录做了什么，是记录拿到了什么梯度**——
只写到"表面原因"就停的记录不合格，`project_status.py` 会报警。

## Agent 交接协议

**项目已经是这套结构时：**

1. `project_status.py <path>` —— 30 秒拿到全局状态和阻塞项
2. 读 `PROJECT.md` —— 完整上下文
3. 只在需要时按 §6 的下一步深入对应的 `docs/` 或 `experiments/`
4. 干完活**回写 §4/§5/§6 和"最后更新"日期**，再结束会话

不要在没读 PROJECT.md 的情况下就开始改代码或写论文——
你会重复项目已经排除过的路径，这正是实验日志存在的意义。

**项目不是这套结构时：**走流程 B，从 `explore_project.py` 开始，
先看懂、再汇报、再问、再动。

## 与其他 skill 的关系

这个 skill 管**状态与结构**，具体每一步怎么做在别处：

| PROJECT.md 的节 | 卡住时读哪个 skill |
|---|---|
| §2 选题状态 | `research-ideation` |
| §3 技术方案 | `research-ideation` |
| §4 实验状态 | `research-experiment` |
| §5 论文状态 | `paper-writing` → `paper-revision` → `paper-self-review` |
| `docs/literature/` | `research-ideation/references/literature-tree.md`；检索用 `literature-review`，读论文用 `pdf-explore` |
| `paper/figures/` | `figure-style` → `figure-composer` → `paper-narrative` |

整体流程图见 `research-methodology`。