Handoff Skill — bàn giao context & tài liệu sống cho agent

Đây là phần tiếp theo của series Cursor AI Agent, sau Cursor Skills cho người mới và Cursor Sub-agents.

Ở bài sub-agent có một dòng dễ bị bỏ qua: lưu output quan trọng ra file để không mất khi context parent dài. Bài này biến ý đó thành một skill cụ thể — handoff — giữ một bộ tài liệu sống để mỗi phiên làm việc bàn giao được cho phiên sau.

1. Vấn đề: context chết giữa các phiên

Mỗi conversation với agent là một context window riêng. Khi bạn đóng chat hoặc nó reset vì context đầy, mọi thứ nó học được — cấu trúc, file nào làm gì, đã quyết định gì và vì sao — biến mất.

Session 1:  explore 30 files → understand → 60% done → out of context
              │
              ▼  (close chat / reset)
Session 2:  "Wait, what is this project?" → explore 30 files again → ...

Bạn trả token 2 lần cho cùng việc “hiểu codebase”, và tệ hơn: phiên 2 có thể quyết định khác vì không biết lý do của quyết định cũ.

Giải pháp không phải context to hơn, mà là ghi state ra ngoài context — vào file — để phiên sau đọc lại. Đó là handoff.

2. Từ “lưu một file” tới một hệ tài liệu sống

Một file notes.md đơn lẻ mục rất nhanh. Mẹo là tách tài liệu theo tần suất thay đổi và update mỗi lần đổi code, không phải chỉ lúc cuối.

notes/
├── progress.md            # status table — what's done / doing / next
├── handoff.md             # chronological log — date+time, files, what/next
├── architectures.md       # the map — structure + links to split docs
├── getting-started.md     # setup / run / build           (optional)
├── frontend-architecture.md  # component & layout tree     (optional)
├── content-architecture.md   # data layer / schemas        (optional)
└── {feature-name}.md      # one file per LARGE feature

working.md (ở gốc repo) là scratch nhẹ “request hiện tại vs trước đó”. Mọi thứ bền vững nằm trong notes/.

3. Hai file gánh phần nặng nhất

progress.md và handoff.md trả lời hai câu khác nhau.

progress.md là trạng thái hiện tại — ghi đè thoải mái, giữ ngắn. handoff.md là lịch sử — append từng phiên, mỗi entry có date+time chính xác, file đã đổi, đã làm gì, làm tiếp gì.

Tách lịch sử khỏi progress.md chính là cái giữ nó không phình — đúng cái bẫy khiến cách 1-file cũ thành vô dụng.

4. Vì sao là notes/ chứ không phải .cursor/

Đây là quyết định có chủ đích: notes/ là tài liệu của project, không phải config của tool.

• Con người cũng đọc — dev mới mở notes/architectures.md là hiểu hệ thống mà không cần agent.
• Nó độc lập với tool — đổi khỏi Cursor thì notes/ vẫn còn giá trị; .cursor/ thì gắn chặt một tool.
• Quyền commit là của bạn — commit notes/ làm “bộ nhớ chung”, hoặc gitignore nếu coi là scratch. Đều được.

Quy ước: mọi project dùng ./notes/, nên skill chỉ cần biết một đường dẫn duy nhất.

5. Quy tắc cốt lõi: update MỖI lần đổi code

Skill không đợi tới lúc “save progress”. Nó kích hoạt sau mỗi edit đáng kể:

• Làm hoặc sửa một screen / route / component
• Thêm hoặc đổi API endpoint hoặc data model
• Đổi dependency, config, hoặc bất kỳ kiến trúc nào

Vì sao gắt vậy? Vì tài liệu để “viết sau” thì không bao giờ được viết. Gắn update vào edit giữ chúng luôn đúng.

6. Build skill từng bước

Theo 4 phase: Discovery → Design → Implementation → Verification.

Trả lời 5 câu.

1. Giải quyết gì? Bàn giao state giữa các phiên và giữ tài liệu luôn mới.
2. Personal hay project? Project trước; nâng lên global sau.
3. Khi nào load? Lúc resume, và sau mỗi lần đổi code.
4. Output đặc biệt? Có — bộ doc notes/ + template.
5. Pattern sẵn? Workflow Pattern (vòng read → work → write).

description quyết định skill có được trigger không. Ngôi thứ ba, WHAT + WHEN, nhồi trigger terms:

description: Maintain living project docs in notes/ and hand off between sessions. Update docs on EVERY code change (new screen, feature, flow, bug fix, schema, architecture) and read them first on resume. Use when implementing, modifying, fixing, refactoring, resuming, saving progress, or updating notes.

Cấu trúc thư mục, references chỉ 1 cấp sâu:

.cursor/skills/handoff/
├── SKILL.md
├── progress-template.md
├── handoff-template.md
└── architecture-template.md

Phần lõi của SKILL.md — danh sách trigger, bộ doc, và các bước mỗi lần đổi:

---
name: handoff
description: Maintain living project docs in notes/ and hand off between sessions. Update docs on EVERY code change ... Use when implementing, modifying, fixing, resuming, saving progress, or updating notes.
---

# Handoff

## When to trigger
Update docs after: implementing/modifying a screen, changing an endpoint or
schema, adding components, changing auth, deps, or any architecture.
Read docs first when resuming or starting a non-trivial task.

## Steps on every change
1. Identify what changed (files created/modified/deleted; large feature?).
2. Update `notes/progress.md` (status table: ✅ / 🟡 / ⬜).
3. Update `notes/handoff.md` (session entry: date+time, files, what, next).
4. Update architecture docs only if structure changed.
5. Update `working.md` at repo root (current vs previous request).

## If notes/ is missing
Bootstrap from templates: progress-template.md, handoff-template.md,
architecture-template.md.

Template session-log handoff.md là phần mới so với v1:

## Session N — May 29, 2026, 10:15

### What was done
1. [First thing]
2. [Second thing]

### Files changed
- `path/to/file` — what changed

### What's next
- [ ] [Next task]

• SKILL.md dưới 500 dòng.
• Description cụ thể, ngôi thứ ba, nhiều trigger terms.
• References 1 cấp sâu (SKILL.md → template, không sâu hơn).
• Test thật: mở chat mới, gõ “resume where we left off”, xem nó có đọc notes/ trước không.

7. Feature lớn được file riêng

Đừng nhồi 200 dòng mô tả feature vào doc chính. Với feature lớn (module mới, nhóm page mới, flow lớn), tạo notes/{feature-name}.md rồi thêm link tham chiếu từ doc chính.

Quy tắc: tách ra khi nó thêm hơn ~50 dòng vào doc có sẵn, hoặc khi nó là một mảng độc lập (admin panel, payment, OAuth setup).

8. Dùng trong thực tế

Mở chat mới trong repo đã có notes/ và gõ:

Continue working on this project.

Agent đọc notes/progress.md + handoff.md + architectures.md trước, rồi nói còn gì và làm tiếp — không explore lại 30 file.

Sau một mảng việc, hoặc khi thấy context sắp đầy:

Update the notes and hand off.

Nó thêm một entry handoff.md (kèm timestamp + file đã đổi), làm mới bảng progress.md, và đụng vào doc architecture nào có vùng thay đổi.

Demo sống trên blog này

Repo này đã chạy đúng quy ước:

notes/
├── progress.md             # status table of blog tasks
├── handoff.md              # session log (this post was written across sessions)
├── architectures.md        # blog map → links to the split docs below
├── getting-started.md
├── frontend-architecture.md
└── content-architecture.md

9. Nâng lên global skill

Khi đã chạy ổn ở một project, dùng lại ở mọi nơi bằng cách copy sang scope personal:

cp -r .cursor/skills/handoff ~/.cursor/skills/handoff

Không cần sửa gì — skill luôn ghi vào ./notes/ tương đối theo project đang mở, nên cùng quy ước áp dụng ở mọi nơi.

Đừng để trong ~/.cursor/skills-cursor/ — folder đó dành cho skill built-in của Cursor, có thể bị ghi đè khi update.

10. Anti-patterns

Nhét lịch sử vào progress.md. Nó phình. Lịch sử thuộc về handoff.md; progress.md chỉ hiện trạng thái hiện tại.

Kể từng dòng edit. Ghi quyết định và vì sao, không phải “sửa dòng 42”. Diff đã kể cái gì đổi rồi.

architectures.md thành changelog. Nó mô tả cấu trúc hiện tại; git mới là changelog.

Ghi mà không đọc. Vòng lặp bắt đầu bằng read. Nếu agent nhảy vào explore, nhắc nó đọc notes/ trước.

References lồng quá sâu. SKILL.md → a.md → b.md: agent có thể đọc không tới. Giữ 1 cấp.

Tổng kết

Handoff skill biến “bộ nhớ” của agent từ ephemeral (chết theo context window) thành persistent (sống trong notes/):

1. Tách theo tần suất đổi: progress.md (hiện tại), handoff.md (lịch sử), architectures.md (cấu trúc).
2. Update mỗi lần đổi code, không để “lúc sau”.
3. Feature lớn được file riêng, link từ doc chính.
4. notes/ là tài liệu, dùng được cho con người và mọi tool.
5. Project trước, global sau — review qua git, rồi cp sang ~/.cursor/skills/.

Bắt đầu bằng cách thêm notes/progress.md và notes/handoff.md cho project bạn đang làm dở nhất — phiên agent kế tiếp sẽ “nhớ” thay vì hỏi lại bạn từ đầu.