ch-capturing-what-worked

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Ghi lại cách làm đúng

## Vấn đề nó giải

Bạn vừa mất một giờ mò ra cách đúng. Ba tuần sau gặp lại đúng loại việc đó, phiên làm việc
mới không có ký ức gì — nó lại đi đúng cái ngõ cụt cũ, lại mất một giờ, và lần này có thể
dừng ở chỗ sai mà tưởng là đúng.

Thứ đáng cứu **không phải cách làm đúng**. Cách làm đúng, đọc code là suy ra được. Thứ đáng
cứu là **cái bẫy** — lý do cách hiển nhiên lại sai.

**Thông báo khi bắt đầu:** "Tôi dùng skill ch-capturing-what-worked để xem việc này có đáng ghi lại không."

## Cổng chặn — hầu hết task KHÔNG đáng ghi

Ghi bừa thì ba tháng sau có ba chục file rác, không ai đọc, và những file thật sự quý bị chôn
trong đó. Nên phải qua cổng.

**Chỉ đề xuất ghi khi có ít nhất một điều sau đúng:**

- Cách làm đầu tiên tôi chọn đã **sai**, và phải quay lại làm cách khác
- Phải đọc từ ba file trở lên hoặc phải tra tài liệu ngoài mới hiểu được cách làm
- Có một **cái bẫy im lặng**: làm sai mà không có lỗi, không có test đỏ, chỉ sai âm thầm
- Có một quy ước riêng của dự án này mà nhìn code không tự suy ra được

**Không đề xuất ghi khi:**

- Làm đúng ngay từ lần đầu bằng cách hiển nhiên
- Chỉ là kiến thức phổ thông về framework, tra Google ra ngay
- Chỉ đúng một lần này, không lặp lại (sửa một typo, đổi một con số)
- Đã có file ghi rồi — lúc đó **sửa file cũ**, không đẻ file mới

## Bước 1: Chọn một trong ba chỗ ghi

Hai câu hỏi, theo đúng thứ tự này.

### Câu 1: cách làm này có đúng ở một dự án khác không?

**CÓ** → đề xuất skill chung trong source kit dotagents: `skills/<tên>/SKILL.md`. Việc cài đặt sang runtime chỉ thực hiện khi nằm trong phạm vi được người dùng duyệt.

Ví dụ: "cách bắt lỗi hydration mismatch của React", "cách dò rò rỉ bộ nhớ trong test Node".

**Không chắc → coi như KHÔNG.** Nâng lên skill chung sau, khi gặp lại lần thứ hai ở dự án
khác — lần thứ hai đó mới là bằng chứng nó dùng chung được. Đẩy vội là biến quy ước riêng
của một dự án thành luật cho mọi dự án.

### Câu 2: đây là QUY TRÌNH agent phải tự làm theo, hay là KIẾN THỨC để tra?

Chỉ hỏi khi câu 1 trả lời KHÔNG.

**Quy trình** — có các bước phải tuân theo, và tuân sai thì hỏng → **skill riêng của dự án**:
`<dự án>/.claude/skills/<tên>/SKILL.md` (Claude) hoặc `<dự án>/.codex/skills/<tên>/SKILL.md` (Codex), có frontmatter `name` + `description` như mọi skill khác.

Ví dụ: "trước khi sửa schema phải chạy `npm run db:check` rồi mới generate migration",
"deploy staging phải qua `scripts/deploy.sh`, gọi thẳng `vercel` là hỏng biến môi trường".

Chọn skill vì agent **tự thấy nó** trong danh sách skill nhờ dòng `description` — không cần ai
nhắc mới biết là có.

**Kiến thức** — một sự thật cần biết, không có bước nào phải làm theo → `docs/recipes/<slug>.md`.

Ví dụ: "cột `status` trong bảng `orders` còn hai giá trị cũ từ 2023, đừng tưởng chỉ có ba",
"CI chậm 8 phút là do bước cache, không phải do test".

Chọn recipe vì đây là thứ để **tra khi cần**, biến nó thành skill chỉ làm rác danh sách skill.

**Không chắc quy trình hay kiến thức → chọn skill.** Skill thì agent tự thấy; recipe thì phải
chủ động đi tìm mới ra.

### Bảng tóm

| Chỗ | Khi nào | Agent tìm ra bằng cách nào |
|---|---|---|
| `~/dotagents/skills/` | Đúng ở mọi dự án | Tự thấy, mọi máy mọi dự án |
| `<dự án>/.claude/skills/` | Quy trình riêng của dự án này | Tự thấy khi mở dự án này |
| `<dự án>/docs/recipes/` | Kiến thức riêng của dự án này | Phải chủ động `ls` thư mục |

Hai chỗ đầu đi theo git của chính dự án hoặc của dotagents, nên đồng đội clone về là có sẵn.

## Bước 2: Tìm file đã có trước khi viết mới

```bash
ls docs/recipes/ .claude/skills/ 2>/dev/null
grep -ril "<từ khoá>" docs/recipes/ .claude/skills/ ~/dotagents/skills/ 2>/dev/null
```

Có file gần đúng thì **đề xuất sửa nó**. Hai file cùng chủ đề mà lệch nhau còn tệ hơn không có file nào.

## Bước 3: Đề xuất nội dung và xin xác nhận

Trước khi tạo hoặc cập nhật file bài học, trình bày:
- Bài học cụ thể và bằng chứng từ task đã kiểm chứng.
- Bẫy hoặc lỗi sẽ tránh được trong lần sau.
- Hình thức, đường dẫn và nội dung dự kiến; nêu rõ tạo mới hay sửa file hiện có.

Có thể đề xuất recipe cho kiến thức cần tra, skill cho quy trình có điều kiện kích hoạt, hoặc rules cho chính sách ngắn cần áp dụng thường xuyên. Không chép lại hướng dẫn skill vào rules. Với rules của dotagents, sửa source common/overlay phù hợp; không sửa tay block runtime do installer quản lý.

Hỏi người dùng có muốn lưu đề xuất này không. Chỉ ghi sau khi nhận được xác nhận cho đúng nội dung và phạm vi. Im lặng hoặc hết thời gian chờ không phải xác nhận. Nếu người dùng đã yêu cầu rõ việc lưu đúng bài học và nơi lưu đó, thực hiện luôn; không hỏi lại.

Việc tạo draft trong câu trả lời để người dùng duyệt không cho phép tự ghi file. Khi người dùng từ chối, bỏ đề xuất. Khi họ chỉnh đề xuất, làm theo phạm vi đã được đồng ý.

## Bước 4: Ghi sau khi được duyệt

Với recipe, dùng đúng bốn mục dưới đây. Với rules, giữ ngắn và không lặp lại quy trình trong skill. Với skill, theo cấu trúc skill hiện có; dùng `writing-skills` khi cần kiểm chứng khả năng tuân thủ của agent.

```markdown
# <Việc gì>

## Khi nào gặp lại
<Dấu hiệu nhận ra đúng tình huống này. Viết sao cho lần sau ĐỌC LƯỚT là nhận ra.>

## Cách làm đúng
<Các bước. Có lệnh thì dán lệnh. Có file thì ghi đường dẫn kèm số dòng.>

## Cái bẫy
<PHẦN QUAN TRỌNG NHẤT. Cách hiển nhiên là gì, vì sao nó sai, và sai thì
biểu hiện ra sao. Không có mục này thì cả file gần như vô dụng.>

## Kiểm thế nào là đúng

From chauipp/dotagents, MIT.

More from chauipp/dotagents