Skip to content
Skills Library
Programming · Planning

dev-docs

/dev-docs

為跨 session 的長任務建立並維護一份「下一個 session 讀得懂」的文件系統(plan / context / tasks),並在壓縮前更新它。Use when starting a large multi-session task, before major refactoring, when work will survive context compaction, or when resuming a task started in an earlier session.

Repository
dotfiles ↗
Licence
MIT
Last repository change
10.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

為跨 session 的長任務建立並維護一份「下一個 session 讀得懂」的文件系統(plan / context / tasks),並在壓縮前更新它。Use when starting a large multi-session task, before major refactoring, when work will survive context compaction, or when resuming a task started in an earlier session.

Arguments

/dev-docs [任務名稱 | resume]
Original author description

為跨 session 的長任務建立並維護一份「下一個 session 讀得懂」的文件系統(plan / context / tasks),並在壓縮前更新它。Use when starting a large multi-session task, before major refactoring, when work will survive context compaction, or when resuming a task started in an earlier session.

How it works

  1. 什麼時候用
  2. Step 1 — 先看有沒有既有的
  3. Step 2 — 建立結構
  4. Step 3 — 三份檔案,各有嚴格的職責
  5. Step 4 — 更新紀律
  6. Step 5 — 恢復(/dev-docs resume)
  7. Step 6 — 收工
  8. 常見的自我開脫
  9. 紅旗
  10. 驗收
Original SKILL.md headings · 185 lines, 519 words
SKILL.md preview
---
name: dev-docs
description: 為跨 session 的長任務建立並維護一份「下一個 session 讀得懂」的文件系統(plan / context / tasks),並在壓縮前更新它。Use when starting a large multi-session task, before major refactoring, when work will survive context compaction, or when resuming a task started in an earlier session.
argument-hint: "[任務名稱 | resume]"
allowed-tools: Read Write Edit Glob Grep Bash(git status:*) Bash(git log:*) Bash(ls:*)
---

# /dev-docs — 讓下一個 session 不用重新考古

context 會被壓縮,session 會結束,你會忘記為什麼三天前選了那個做法。
這支 skill 把「必須活過壓縮的東西」寫進檔案。

`/context-engineering` 管的是**這個任務該看到什麼**;
這支管的是**跨 session 該留下什麼**。

---

## 什麼時候用

- 任務跨多個 session,或預期會被壓縮至少一次
- 大型重構、需要多階段推進的功能
- 恢復一個之前 session 開的任務(`/dev-docs resume`)

### 不要用在

| 情境 | 理由 |
| --- | --- |
| 單一 session 做得完 | 建三個檔案的成本大於收益,用任務清單就好 |
| 一次性的小修 | 文件比改動還長 |
| 只是想記錄結論 | 那該進 commit message 或 repo 文件 |

⚠️ **文件不是目的。** 每一段的存在理由都是「下一個 session 少讀 20 個檔案」。
寫不出這個理由的段落就刪掉。

---

## Step 1 — 先看有沒有既有的

```bash
ls dev/active/
```

有同名或相近的目錄 → **讀它,接續**,不要另開一份。
兩份半殘的計畫比一份完整的更糟。

## Step 2 — 建立結構

```
dev/active/<task-name>/
├── plan.md      # 為什麼、要做什麼、怎麼算完成
├── context.md   # 事實與決策(這份最值錢)
└── tasks.md     # 進度
```

`<task-name>` 用 kebab-case,跟分支名對齊(`feat/admin-analyze` → `admin-analyze`)。

## Step 3 — 三份檔案,各有嚴格的職責

### plan.md — 意圖

```markdown
# <任務> — 實作計畫

## 目標
一句可驗收的完成條件:「當 ___ 時,___ 應該 ___」

## 策略
高層做法,3–5 句。為什麼是這個做法,不是另一個。

## 架構決策
| 決策 | 理由 | 被否決的選項與原因 |
| --- | --- | --- |

## 風險
| 風險 | 緩解 |
| --- | --- |

## 驗收條件
- [ ] 具體、可檢查的條件
```

⚠️ **「被否決的選項」欄位不能空。** 下一個 session 最容易犯的錯,
就是重新提議一個三天前已經否決過的方案。

### context.md — 事實與決策(最值錢的一份)

```markdown
# <任務> — Context

## 關鍵檔案
| 路徑 | 為什麼相關 |
| --- | --- |

## 既有 pattern
從 codebase 找到、要照抄的寫法(附 `file.ts:45-60`)

## 相依
| 套件@版本 | 為什麼需要 | 來源 |
| --- | --- | --- |

## 決策紀錄
| 日期 | 決策 | 理由 |
| --- | --- | --- |

## 已知地雷
踩過的坑、繞過的問題、不要再試的方向
```

⚠️ 日期寫**絕對日期**(`2026-08-10`),不要寫「昨天」「上週」。

⚠️ 「已知地雷」是這份文件裡回報率最高的一段 ——
它擋掉的是下一個 session 重蹈同一個覆轍的兩小時。

### tasks.md — 進度

```markdown
# <任務> — Tasks

## Phase 1: 名稱
- [x] 已完成的任務 (S) — 2026-08-10, commit abc1234
- [ ] 進行中的任務 (M)
- [ ] 還沒開始 (L)

Legend: (S)mall / (M)edium / (L)arge
```

⚠️ 打勾的項目要附**證據**(commit hash 或測試輸出),不是自我宣告。

同時把當前 phase 的項目建進任務清單工具,讓進度在對話裡也看得見。

## Step 4 — 更新紀律

| 時機 | 更新什麼 |
| --- | --- |
| 每完成一個任務 | `tasks.md` 打勾 + 附 commit hash |
| 每做一個非顯而易見的決定 | `context.md` 決策紀錄 |
| 每踩一個坑 | `context.md` 已知地雷 |
| **壓縮前 / session 結束前** | 三份都掃一遍 |
| 方向改變 | `plan.md` 策略段,**並把舊策略移到「被否決的選項」** |

⚠️ **文件過期比沒有文件更危險** —— 沒有文件你會去讀程式碼,
過期的文件會讓你相信一件已經不成立的事。

## Step 5 — 恢復(`/dev-docs resume`)

```
1. 讀 plan.md → 我們在做什麼、怎麼算完成
2. 讀 context.md → 有哪些既定事實、哪些方向不要再試
3. 讀 tasks.md → 停在哪
4. git log --oneline -10 → 文件說的跟 repo 實際狀態一致嗎?
5. 不一致 → 先修文件,再繼續工作
```

⚠️ 第 4 步不能跳。文件是上一個 session 的**宣稱**,git 是**事實**。

## Step 6 — 收工

任務完成後把目錄移到 `dev/done/<task-name>/`(用 `command mv`),
不要留在 `active/` —— 下次 `ls dev/active/` 時的雜訊就是下次的困惑來源。

---

## 常見的自我開脫

| 你會這樣想 | 事實 |
| --- | --- |
| 「我記得住,不用寫」 | 壓縮之後的你不是現在的你。寫下來的成本是三分鐘。 |
| 「等做完再一次補文件」 | 做完之後決策理由已經蒸發了,補出來的是「改了什麼」不是「為什麼」。 |
| 「文件寫詳細一點比較保險」 | 這份文件的讀者是下一個 session 的你,不是稽核員。長到沒人讀等於沒有。 |
| 「plan 改了,舊的直接覆蓋掉」 | 被否決的方案必須留痕,否則會被重新提議一次。 |
| 「tasks.md 打勾就好」 | 沒有 commit hash 的打勾,下次無法驗證那件事真的做完了。 |

## 紅旗

- `dev/active/` 裡有三個以上的目錄(同時開太多戰場)
- 文件說某任務完成,但 `git log` 裡找不到對應的 commit
- `context.md` 只有檔案清單,沒有決策紀錄與地雷
- 決策紀錄裡寫著「昨天」「上週」這種相對時間
- 任務完成了但目錄還留在 `active/`
- 文件比它描述的改動還長

## 驗收

- [ ] 動手前先確認過 `dev/active/` 沒有既有的同名任務
- [ ] `plan.md` 的完成條件是一句可驗收的敘述,不是願景
- [ ] 「被否決的選項」有內容
- [ ] `context.md` 有決策紀錄與已知地雷,日期是絕對日期
- [ ] `tasks.md` 的每個勾都附了 commit hash 或測試輸出
- [ ] resume 時比對過 `git log`,文件與 repo 狀態一致
- [ ] 任務結束後目錄已移到 `dev/done/`

Versions

RepositoryScoreLicence
This page · htlin222/dotfiles100MIT
tejitpabari99/tejit-plugin100MIT

Database snapshot: 13.11.2026 · package version 4ebd830e88f3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90dev-planning
    AI DevKit · Planning phase guidance for creating and reconciling feature task plans. Use when the user wants to create an implementation plan, update planning docs, mark task progress, capture blockers or new tasks, or run dev-lifecycle planning work.
  • 90dev-flow
    Start here before writing any code — sizes task (S/L/H/Fix), sets up branch and session rules. Use when: "I'm starting on X", "quick fix for Y", "continuing from yesterday", "hotfix needed", "let's implement X", "skip to coding", "我要開始做 X", "快速修一下", "接續昨天的進度", resuming a feature…
  • 100session-handoff
    Use when context approaches capacity, before /clear or /compact, when switching tasks, or when ending a coding session: produces a structured handoff artifact for the next session.
  • 100gh-issues
    Use when creating, searching, updating, or managing GitHub issues via CLI. Triggers: "issue", "create issue", "gh issue", "task tracking", "context", "handoff", "resume task", "session context", "save progress", "active tasks", "in-progress", "my tasks", "open issues". Covers:…
  • 90dev-flow
    Start here before writing any code — sizes task (S/L/H/Fix), sets up branch and session rules. Use when: "I'm starting on X", "quick fix for Y", "continuing from yesterday", "hotfix needed", "let's implement X", "skip to coding", "我要開始做 X", "快速修一下", "接續昨天的進度", resuming a feature…
  • 100set-session-context
    Use when starting a session on a non-main branch, switching branches (git checkout, git switch), or when a hook prompts for session context update. Also invocable manually via /set-session-context.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.