# Reentry

> 人與 AI agent 工作一整天之後要離開、或隔了幾小時到一個週末回來接手時，用這套流程留下與讀取「重建材料」。收工分四個階段——人離開工作畫面憑記憶寫、agent 校驗、人修正、整理任務狀態；回來時照固定順序讀出來。它解的不是記憶問題：在這個時間尺度上恢復成本十幾秒就飽和，回來時發生的幾乎都是重建，真正的病是理解債——在尚未真正理解前就讓任務往下推進，症狀看起來像忘了，實際是當時就沒形成足夠的理解。觸發情境：使用者說「我回來了」「繼續某某專案」「上次做到哪」「我忘記做到哪了」「重新進入狀況」「哪個專案還沒做完」，或說「收工」「今天到這」「先記一下進度」「交接一下」「幫我留個紀錄」；也包含任何檢視完 agent 的產出準備離開、或隔了一段時間要接回某個專案的時刻。使用者不必說出 reentry 這個詞——只要他們在問「我上次在幹嘛」或正要結束一段工作，就用這個 skill。Also triggers on — resume work, pick up where I left off, where was I, wrap up, end of session, handoff notes, context recovery, what did I do last time.

- Skill: `nickolaslin33/reentry` (Agent Skill, multi-file: 28 files)
- Install (CLI): `npx skillmds@latest add nickolaslin33/reentry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nickolaslin33/reentry/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nickolaslin33 (https://skillmd.com/u/nickolaslin33)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nickolaslin33/reentry

---


# 重新進入工作狀態

## 這個 skill 要解決的問題

人與 AI agent 工作了一整天，隔天或幾天後再回來接手時，失去的往往不只是「我忘了做到哪裡」「接下來要做什麼」。

真正需要重建的資訊可以分成四類，而且每一類遺失的方式、恢復的方法都不同：

| | 是什麼 | 能否重建 |
|---|---|---|
| **任務狀態** | agent 改了什麼、跑了什麼 | 可以，從 git diff 重建 |
| **決策脈絡** | 為什麼選擇這個做法、曾排除哪些方案 | 沒有留下紀錄的話，通常很難完整還原 |
| **下一步** | 接下來要做什麼 | 有時記在其他地方，有時只存在人的記憶裡 |
| **理解程度** | 人對目前工作內容實際理解到什麼程度 | 無法只靠程式碼或紀錄直接重建 |

前三項描述的是任務本身的狀態，最後一項描述的是人對任務的理解狀態。

最關鍵的是最後一項。在還沒真正理解前就讓任務往下推進，後續工作會建立在不完整的
理解上，之後補回來的成本愈來愈高。這類尚未補足的理解稱為**理解債**。

所以交接紀錄要完整到隔一段時間之後，只靠它就能重新理解當時的工作狀況，不能只當
提示用。每條規則的研究依據見 `references/evidence.md`。

## 環境

以下 `$SKILL_DIR` 指本 skill 的安裝目錄，依你的環境代入實際路徑。腳本一律用 `python3` 呼叫，不依賴執行位元、PATH 或任何特定 agent 的機制。只用 Python 3 標準函式庫。

資料放在 `$REENTRY_ROOT`（預設 `~/reentry`），按專案拆資料夾：

```
~/reentry/
├── orders-api/
│   ├── handoff.md      # 工作接續紀錄，每次重新建立
│   ├── artifacts.md    # 任務狀態，腳本與 agent 合寫，每次重新建立
│   ├── debt.md         # 理解債（以為自己懂但沒懂），保留尚未理解的項目
│   ├── open-questions.md  # 待確認（知道自己不知道），保留尚未查清的問題
│   └── decisions/      # 決策紀錄，逐筆保留
└── billing-service/
```

**只有已登記的專案才納入管理**。沒有對應資料夾的專案視為未登記，刪除資料夾等於取消登記。**不要自動建立或恢復資料夾。**

格式規範在 `references/file-formats.md`，寫任何一個檔案之前先讀它。

## 先判斷目前處於哪個階段

- 使用者隔了一段時間回來，準備繼續先前的工作 → **回來階段**，參考下方「回來時」
- 使用者準備結束這次工作，或剛檢視完 agent 的一批產出 → **收工階段**，參考下方「收工時」

---

## 回來時

這個階段不需要重新分析或整理內容，只要執行腳本，並將結果原樣提供給使用者。

如果使用者尚未指定專案，先執行索引腳本，列出可接續的專案供他選擇：

```bash
python3 "$SKILL_DIR"/scripts/reentry_index.py
```

指定專案之後：

```bash
python3 "$SKILL_DIR"/scripts/reentry_read.py <專案名>
```

**腳本輸出的內容必須完整保留，不要改寫、摘要或重新排版。**

使用者自己的用詞是他最好的回憶線索，換句話說等於把線索抽掉；而每次輸出長得一樣，
他才建立得起「打開就知道哪裡看什麼」的習慣。

輸出順序固定如下：

```
警告（若有）→ 上次叫它做什麼、做到哪裡 → 上次的決定（若有）→ 欠債 → 待確認（若有）→ 下一步
```

**下一步壓在最後是刻意的**——避免還沒掌握前因後果就直接繼續往下做。

「上次的決定」只在上次收工真的寫了 `decisions/` 才顯示。永遠留一個空欄位會退化成
每次略過的噪音。

腳本最後會顯示一句：「先用自己的話說一次下一步，再開始動手」。

這句只是提醒。不要追問、不要要求他打字、不要確認他有沒有做——他回來時已經準備
動手了，這時候加摩擦只會讓他關掉整套流程。

---

## 收工時

整個收工流程**大約五分鐘**，並直接整合進使用者原本的 review 流程。

這個數字是建議不是上限。它要擋的是兩件事：拖太久，以及卡在回想上出不來。
如果使用者對今天做的事很有想法、想寫得詳細，那不是問題——紀錄詳細本身沒有壞處，
不要因為時間到了就催他收尾。

### 第一階段 — 請使用者關閉工作畫面，憑記憶整理

請使用者先離開目前的工作畫面，再憑記憶寫下四項內容。寫進 `handoff.md` 時的標題必須逐字用這四個——**腳本靠標題原文解析，改了字就讀不到，而且不會報錯**：

```
## 我叫它做什麼，做到哪裡
## 下一步
## 關鍵詞
## 不確定的地方
```

第一項的提問方式很重要。

不要問「這次做了什麼」，因為實際執行工作的是 agent，而使用者主要負責提出需求、檢視結果與做出判斷。若要求他描述具體實作內容，很容易變成憑印象推測 agent 實際修改了什麼。

相較之下，使用者比較容易記得的是：自己原本要求 agent 完成什麼，以及 agent 最後交付了什麼結果。從這兩個角度提問，才能準確喚回他真正保留下來的工作脈絡，而不是要求他回想自己沒有直接執行的細節。

同樣地，如果過程中曾做出重要決策，也應在收工時一併記錄到 `decisions/`（見下方「決策紀錄」）。

**關鍵是他要在不查看工作畫面的情況下完成**。判斷時看得到答案，延遲效應幾乎完全消失——看著 diff 評估自己懂不懂，等於沒評估。

**不要問他「你懂了嗎」**。這裡沒有任何自評動作。人在疲倦時會傾向點頭同意，而收工正是疲倦的時候。改成請他憑記憶產出東西——哪些地方能清楚說明、哪些地方說不出來**，本身就是理解程度的訊號**，比任何自評都準。

#### 下一步只保留一項

一次留下多個下一步會增加重新接手時的判斷成本，所以只留一個。

寫到什麼程度分三層，**不是通過或不通過**：

```
最好    具體對象 ＋ 怎麼算做完
        把 refunds 的 retry 上限調成 60 秒，改完跑 tests/test_retry_utils.py

可接受  只有具體對象
        調 refunds 的 retry 上限

不行    沒有對象
        繼續做 retry ／ 弄一下那個
```

中間層明顯比較弱，但不是沒用——回來時仍然知道從哪裡切入。底線是連對象都沒有，
那等於沒寫。

**中間層直接收下，不要催他補齊**。收工時人已經累了，為了補一格把流程拉長，
下次他就不寫了。

**只有掉到底線時問一句**：「這個要怎麼算做完？」問一句就好，不要要求重寫。
這跟代號展開是同一種處理——agent 問、使用者答，不是 agent 代寫。

#### 所有代號都要補上實際內容

像是「`T-3`」「`那個 bug`」「`上次那個問題`」這類寫法，都高度依賴當下的工作脈絡。隔了一段時間之後，使用者往往還得重新查文件，才能知道這些代號實際指的是什麼。

因此代號本身不足以成為有效的回憶線索。它只能指向某個已知內容，但前提是使用者仍然記得那段脈絡——而這套流程要處理的，正是工作中斷後脈絡已經變得模糊的情況。

```
好： T-3（把訂單重試邏輯抽成獨立的 retry-utils 模組）
壞： T-3
```

或直接寫出完整的任務內容。

使用者寫下的內容不要代為潤飾，也不要自行補充。這些文字的價值在於保留他當下實際記得與理解的內容，因此應盡量維持原貌。

**唯一的例外是代號展開**。補上代號的實際含義不是為了讓文字更漂亮，而是避免只有當下的使用者看得懂、隔一段時間後卻失去辨識依據。看到這類代號時，只需要追問一句：「這個代號具體指的是什麼？」

### 第二階段 — 校驗

**由目前這個 agent 直接校驗，不要另開 subagent。**

另開一個乾淨脈絡的 agent 要重讀 diff、重讀檔案，慢。而整個收工流程只有五分鐘的預算，
慢下來的每一分鐘都在增加使用者下次直接跳過的機率。**流程被跳過的損失大於偏誤本身。**

代價是你已經參與整個過程，使用者的描述只要沾到邊，你就會自動補完缺的部分然後判他
答對。知道答案的人測不出別人答了多少——所以**判斷標準必須外部化**，靠下面三條規則，
不能靠你覺得他寫得對不對：

1. **不問「他寫的對不對」，問「這句話單獨拿給一個沒參與的人看，指得出具體對象嗎」。**
   前者你會用脈絡補完，後者不會。
2. **要指出對不上，必須引他寫的那一句原文，加上 diff 裡對應的位置。** 不准拿對話裡
   講過、但他沒寫進紀錄的東西，當作他記得。
3. **他沒寫的就是沒寫。** 你知道他其實懂，不算數——三天後的他只有紙上那幾行。

需要更嚴的校驗時才走 `references/verifier-prompt.md`：開一個乾淨脈絡的 agent，或請
使用者另開對話。**那是選用路徑，不是預設。** 什麼時候值得付那個時間：這次改動特別大、
或者你發現自己一直在替他補完。

校驗分成兩類，處理方式不同：

- **事實資訊**：例如修改了哪些檔案、執行了哪些測試、結果如何。這類內容可以直接與實際紀錄比對，若有落差，可以明確指出「這裡與紀錄不一致」。
- **理解內容**：例如某個機制為什麼這樣設計、各元件之間如何運作。這類判斷只能表達為 **「agent 認為」**，不能當成絕對結論。

理解那類不要寫成「你理解錯了」。寫成判決他會照單全收，留成意見他才會反駁——
而反駁的過程本身就是在確認他懂多少。

**校驗結果最多三項，由校驗者自己排序**。十項他會整批略過，三項才會真的讀。

此外，校驗時再從既有的理解債中**挑選一項舊問題讓使用者回答**，詳見下方「還債」。

### 第三階段 — 根據校驗結果修正紀錄

使用者完成修正後，**原始版本仍然要保留**，寫入 `handoff.md` 的 `## 我當初記錯的`。

原始與修正版之間的差異**就是理解債清單**，自動產生，不需要他自評或動手標記。

如果對不上的比例很高，在 frontmatter 加一則 `warning`，讓他下次回來優先看到。
它只保留到下一次收工，不是永久紀錄。

### 第四階段 — 整理任務狀態與理解債

```bash
python3 "$SKILL_DIR"/scripts/reentry_artifacts.py <專案名> <專案工作目錄>
```

腳本會把可以直接取得的客觀資訊（路徑、增減行數、測試結果）寫進 `## 明細` 與 `## 驗證`。其中 **`## 改了什麼` 那節要你自己寫**——腳本不知道 `store/migration.py` 是「migration runner」，那需要理解。

寫**功能層**：

```
好： 修改 2 個設定載入檔與 1 個 CLI 進入點，新增 3 個測試檔驗證分層契約
壞： 改了 6 個檔（+412 −0）
```

如果改動涉及專案核心的檔案要特別標出來。**必須從 `## 明細` 推，不能憑印象編**——
你剛做完這些事，很容易寫出「應該有做」而不是「確實做了」。

把使用者打的東西**如實寫進 `handoff.md`，不改寫、不美化**（代號展開是唯一例外）。他寫的句子是他的檢索線索。

**把 `## 不確定的地方` 升級成 `open-questions.md` 的條目**（已經在這次解掉的就不用）。
`handoff.md` 每次整份覆寫，不升級的話那些疑問下次收工就消失了。

待確認與理解債不共用檔案，兩者的還法不同（見 `references/file-formats.md`）。

然後把記錯裡屬於理解問題的那些升級成 `debt.md` 的條目：

- 對「為什麼必須這樣設計」理解錯誤 → **屬於**理解債
- 記錯檔名、行數、測試數量 → **不屬於**，那是記憶誤差

每一條都**寫成問題並附上對應的 commit SHA，不要附答案**。答案留在 diff 裡，
他得自己走一趟才拿得到，那趟路就是還債本身。

---

## 還債

理解債不另外安排處理流程，**整合到下一次收工時的校驗階段**。

- 校驗者除了檢查本次工作的內容之外，**再從既有的理解債中挑選一項提問**。如果使用者能正確回答，就把該項目的 `- [ ]` 改成 `- [x]`。
- **每次只處理一項。**
- **優先選擇與目前「下一步」相關的理解債**；如果沒有直接相關的項目，再從其他尚未解決的挑選。
- 是否已經理解，由校驗者根據回答判斷，不需要另外設計一套判定流程。

在詢問舊的理解債時，校驗者必須取得該條目所記錄的 commit SHA 對應的 diff，而不是使用這次工作的 diff。如果找不到對應的 diff，就直接說明無法取得足夠資訊，不要用目前的變更內容推測過去問題的答案。

**沒有足夠依據時，不應判定使用者已經理解。**

---

## 決策紀錄

收工時如果做了值得留的決定，寫進 `decisions/`（格式見 `references/file-formats.md`）。

判準：**如果之後由其他人接手，這項資訊是否仍然重要**。操作上看這個決定有沒有留下
後續待辦、或產生技術債——接手的人最需要知道的就是這兩件事。

**技術債不進 `debt.md`**，跟著決策紀錄走。理解債靠回答問題還，技術債靠寫程式還，
還法不同。

決策紀錄分兩層：第一層留在 `decisions/`，第二層由使用者自己挑進專案 repo。
**第二層沒有固定時機，不要主動提醒**。搬過去時可以改寫成給別人看的樣子——
第一層給自己，第二層給接手的人。

---

## 參考檔案

| 檔案 | 什麼時候讀 |
|---|---|
| `references/file-formats.md` | 寫任何一個檔案之前 |
| `references/verifier-prompt.md` | 第二階段想要更嚴的校驗時（選用） |
| `references/evidence.md` | 想知道某條規則為什麼這樣訂、或想改設計時 |
| `assets/templates/` | 第一次替某個專案建資料夾時 |

## 幾個不應過度優化的地方

這套流程中有些步驟看起來可以進一步簡化或自動化，但如果處理方式不當，反而會削弱原本的效果。以下幾點應特別避免：

- **不要幫使用者把交接紀錄補得更完整**。第一階段的重點，是觀察他在沒有提示的情況下實際能回想並說明多少內容。由 agent 主動補充的話，就無法再判斷哪些部分是他真正記得與理解的。

- **不要在使用者回來時重新整理或改寫輸出**。固定的內容順序與他原本的用詞，本身就是重新建立工作脈絡的重要線索。每次都重新組織或改寫，反而會增加閱讀與理解的成本。

- **不要把理解層面的校驗結果寫成確定結論**。這類結果應保留為 agent 的判斷，而不是直接告訴使用者「正確答案」。結論過於明確的話，他可能直接接受，而沒有重新思考或解釋自己的理解。

- **不要在理解債旁直接附上答案**。理解債的目的，是讓使用者之後透過回想、查閱與重新說明來確認自己是否真正理解。答案直接附在問題旁，這個確認過程就會失去作用。

- **不要持續提醒使用者還有多少理解債尚未處理**。理解債刻意設計成不阻擋目前工作的項目，只在既有的校驗階段中逐步處理。額外加入提醒、清單或待辦壓力的話，他很可能在忙碌時選擇忽略甚至停用整套流程。

- **不要替尚未登記的專案自動建立資料夾**。專案登記代表使用者主動決定將這個專案納入管理。系統自動建立的話，就會失去這個明確的管理邊界。