archive

Tổng quan về skill archive

archive làm tốt điều gì

Skill archive dành cho các nhóm và cá nhân xây dựng sản phẩm muốn biến kiến thức phát sinh trong từng phiên làm việc thành “bộ nhớ dự án” có thể tái sử dụng. Thay vì để các cách sửa lỗi bị chôn vùi trong lịch sử chat, nó lưu kết quả debug, ghi chú triển khai và các bài học quy trình vào .archive/YYYY-MM-DD/ dưới dạng markdown có cấu trúc, rồi duy trì một chỉ mục gọn nhẹ trong .archive/MEMORY.md.

Ai nên cài archive

Skill archive đặc biệt phù hợp với những người thường xuyên phải quay lại các vấn đề lặp đi lặp lại về hạ tầng, CI, release hoặc debug và muốn rút ngắn thời gian khôi phục ở lần sau. Nó особенно hữu ích khi công việc của bạn trải dài qua nhiều phiên, nhiều agent hoặc nhiều cộng tác viên cùng cần một bản ghi chung kiểu “lần trước đã xảy ra chuyện gì?”.

Nhu cầu thực sự mà archive giải quyết

Người dùng không cần thêm một thói quen ghi chú nữa. Họ cần một cách đáng tin cậy để chốt lại bối cảnh kỹ thuật có giá trị cao ngay sau khi hoàn thành một tác vụ quan trọng, rồi đưa lại bối cảnh đó vào tầm tay trước khi bắt đầu tác vụ tương tự tiếp theo. archive được thiết kế xoay quanh luồng làm việc này, chứ không phải kiểu tài liệu tổng quát.

Vì sao archive khác với một prompt thông thường

Một prompt thông thường có thể bảo AI “hãy tóm tắt những gì chúng ta đã làm”. Skill archive bổ sung một mẫu lưu trữ có thể lặp lại, yêu cầu cập nhật chỉ mục bộ nhớ, và một hook lúc bắt đầu phiên để tự động nạp .archive/MEMORY.md nếu tệp này tồn tại. Nhờ vậy, archive for Knowledge Bases trở nên thực tế hơn: phần lưu trữ này trở thành một phần của ngữ cảnh làm việc về sau, chứ không chỉ là một file markdown bị quên lãng.

Những đánh đổi chính cần biết trước khi cài

archive được chủ đích giữ ở mức đơn giản. Nó không cung cấp database, vector search hay pipeline phân loại tự động. Giá trị của nó đến từ cấu trúc file kỷ luật, tag có thể tìm kiếm và một chỉ mục bộ nhớ. Nếu nhóm của bạn không duy trì .archive/MEMORY.md, skill archive sẽ mất đi phần lớn lợi thế.

Cách dùng skill archive

archive install và các file trong repo nên đọc trước

Một lộ trình archive install thực tế là:

1. Thêm skill từ repository ReScienceLab/opc-skills vào hệ thống skills của bạn.
2. Đọc skills/archive/SKILL.md trước để nắm workflow.
3. Đọc skills/archive/references/TEMPLATE.md để hiểu cấu trúc archive bắt buộc.
4. Đọc skills/archive/hooks/hooks.json và skills/archive/hooks/load-memory.py nếu bạn quan tâm đến việc nạp ngữ cảnh khi khởi động.
5. Kiểm tra skills/archive/.factory-plugin/plugin.json để xác nhận hành vi mà skill hướng tới.

Nếu bạn chỉ lướt qua một file hỗ trợ, hãy chọn references/TEMPLATE.md; file này cho bạn biết “đầu ra archive tốt” trông như thế nào.

Skill archive cần đầu vào gì

Skill archive hoạt động tốt nhất khi bạn cung cấp:

• tác vụ hoặc sự cố đã hoàn tất
• kết quả chính
• các bước quan trọng đã thực hiện
• các lệnh, thay đổi cấu hình hoặc quyết định mã nguồn quan trọng
• các điểm thất bại và cách sửa cuối cùng
• category và các tag nhiều khả năng sẽ dùng
• mọi mục archive cũ có liên quan

Thiếu các đầu vào này, archive tạo ra sẽ quá mơ hồ và khó giúp ích về sau.

Khi nào nên kích hoạt archive

Hãy dùng archive sau:

• một lần triển khai thành công
• một phiên debug khó
• một đợt migration hoặc thay đổi hạ tầng
• việc hoàn thành một tính năng lớn
• bất kỳ chỉ dẫn nào từ người dùng như “archive việc này”

Đừng dùng nó cho mọi chỉnh sửa nhỏ. Skill này dành cho những bài học có giá trị bền lâu, không phải nhật ký hoạt động đầy nhiễu.

archive hoạt động thực tế như thế nào

Workflow được thiết kế như sau:

1. Kiểm tra .archive/MEMORY.md để tìm công việc liên quan đã làm trước đó.
2. Tạo mới hoặc dùng lại .archive/YYYY-MM-DD/.
3. Viết một archive markdown theo đúng cấu trúc template và YAML frontmatter.
4. Thêm một dòng chỉ mục vào .archive/MEMORY.md.
5. Liên kết các mục liên quan bằng trường related.

Việc cập nhật chỉ mục này không phải việc phụ cho có. Chính nó giúp tra cứu ở lần sau nhanh hơn nhiều.

Prompt tốt hơn cho skill archive

Prompt yếu:

• “Archive phiên này.”

Prompt tốt hơn:

• “Use the archive skill to document today’s ECS deploy issue. Include the IAM permission error, the CloudWatch clue, the exact fix, final deploy status, tags for ecs, iam, deploy, category infrastructure, and add a one-line entry to .archive/MEMORY.md. If a related archive exists, link it.”

Phiên bản mạnh hơn cho mô hình đủ cấu trúc để tạo ra thứ bạn thực sự có thể tái sử dụng.

Cách biến một mục tiêu thô thành yêu cầu archive đầy đủ

Nếu mục tiêu ban đầu của bạn chỉ là “lưu lại những gì đã học”, hãy mở rộng nó thành:

• chuyện gì đã xảy ra
• vì sao nó quan trọng
• điều gì đã thất bại
• điều gì đã sửa được
• lần sau nên kiểm tra gì trước
• nội dung này nên nằm ở category nào
• người khác nên tìm lại nó sau này bằng những tag nào

Skill này phát huy tốt nhất khi viết để phục vụ truy xuất, không phải để kể chuyện.

Những trường trong template archive quan trọng nhất

Từ references/TEMPLATE.md, các trường quan trọng nhất là:

• tags: để truy xuất bằng grep
• category: để tổ chức chỉ mục
• related: để nối các sự cố theo thời gian

Trong phần nội dung, các mục thường có giá trị nhất là:

• Summary
• Issues Encountered & Solutions
• Key Changes

Nếu bạn bỏ qua chi tiết sửa lỗi cụ thể, archive sẽ kém hữu ích đi rất nhiều.

Hook bộ nhớ lúc bắt đầu phiên làm thay đổi cách dùng ra sao

Hook này sẽ nạp .archive/MEMORY.md vào ngữ cảnh phiên ngay khi khởi động nếu file tồn tại. Điều đó có nghĩa skill archive không chỉ để ghi lại; nó còn tự động cải thiện khả năng gợi nhớ ở các phiên sau. Xét về mức độ dễ áp dụng, đây là một trong những lý do mạnh nhất để cài skill thay vì dùng một file ghi chú tùy hứng.

archive cho Knowledge Bases và bộ nhớ nhóm

Với archive for Knowledge Bases, hãy hình dung .archive/MEMORY.md là mục lục, còn mỗi file markdown theo ngày là bản ghi của một sự cố hoặc tác vụ. Cách này đặc biệt hợp cho:

• các vấn đề vận hành lặp lại
• checklist release có các “bẫy” dễ quên
• các bản sửa chỉ đúng với từng môi trường cụ thể
• các quyết định thiết kế có hệ quả về sau

Nó ít phù hợp hơn với tài liệu sản phẩm diện rộng hoặc tài liệu hướng dẫn cho người dùng cuối.

Quy trình tìm kiếm và tra cứu thực tế

Skill archive hỗ trợ rõ ràng cho kiểu tìm kiếm nhẹ:

• xem lại .archive/MEMORY.md
• dùng grep -ri "keyword" .archive/

Chừng đó là đủ với nhiều đội kỹ thuật, vì nội dung được lưu thường hẹp, mang tính kỹ thuật và có cấu trúc. Hãy dùng những tag mà sau này mọi người thực sự sẽ tìm: tên service, chuỗi lỗi, tên nền tảng và tên component.

Câu hỏi thường gặp về skill archive

archive có đáng cài nếu tôi đã ghi chú rồi không?

Có, nếu ghi chú hiện tại của bạn khó tìm hoặc không bao giờ quay lại ngữ cảnh làm việc của agent. Skill archive hữu ích vì nó chuẩn hóa vị trí lưu, cấu trúc, cách lập chỉ mục và cơ chế nạp bộ nhớ khi bắt đầu phiên.

Skill archive này có thân thiện với người mới không?

Có, nhìn chung là vậy. Workflow chỉ gồm markdown cộng với một file chỉ mục. Rủi ro lớn nhất với người mới là viết tóm tắt quá trừu tượng. Skill này dễ dùng nhất khi bạn sao chép template rồi điền các cách sửa cụ thể, lệnh cụ thể và bài học rút ra.

Khi nào không nên dùng archive?

Không nên dùng archive cho:

• các chỉnh sửa vụn vặt
• brainstorm tạm thời
• tài liệu dài dạng chính thức
• kiến thức vốn nên nằm trong tài liệu thường trực của repo như README.md hoặc runbook

Nếu thông tin đó cần hướng dẫn tất cả cộng tác viên mọi lúc, nó có thể nên nằm trong tài liệu chuẩn, chứ không chỉ trong .archive/.

archive khác tài liệu dự án thông thường ở điểm nào?

Tài liệu thông thường mô tả hệ thống “được kỳ vọng” hoạt động ra sao. Còn archive ghi lại điều “thực sự đã xảy ra” trong một tác vụ hoặc sự cố: các hướng thử thất bại, cách sửa chính xác và bối cảnh thường bị thất lạc. Nó là một lớp bộ nhớ vận hành mang tính lịch sử, không phải vật thay thế cho tài liệu chuẩn.

archive có cần công cụ đặc biệt không?

Không nhiều. Định dạng cốt lõi chỉ là các file markdown cộng với .archive/MEMORY.md. Repo cũng có sẵn một hook để nạp bộ nhớ khi bắt đầu phiên, nhưng ngay cả khi không dùng hook đó, skill archive vẫn hoạt động như một mẫu lưu trữ có kỷ luật.

Phạm vi của hướng dẫn archive này đến đâu?

Hướng dẫn archive này phản ánh đúng những gì repository hỗ trợ: archive dựa trên file, bộ nhớ có chỉ mục, category đơn giản, liên kết liên quan và cơ chế gợi nhớ bằng hook. Nó không hứa hẹn pipeline tóm tắt tự động, semantic search hay đồng bộ với knowledge base bên ngoài.

Cách cải thiện skill archive

Viết mục archive để truy xuất, không phải để kể chuyện

Đầu ra archive tốt nhất là loại có thể quét nhanh về sau. Hãy đặt vấn đề, cách sửa và các lệnh quan trọng ở vị trí mà người đọc tương lai nhìn vào là thấy ngay. Một câu chuyện mượt mà kém giá trị hơn một bản ghi thẳng, rõ và dễ tìm kiếm.

Dùng các tag mà mọi người thực sự sẽ tìm

Tag tốt:

• tên service hoặc công cụ
• tên subsystem chính xác
• tên nền tảng triển khai
• từ khóa lỗi
• tên môi trường bị ảnh hưởng

Tag kém:

• các từ mơ hồ như issue, work hoặc update

Đây là một trong những cải thiện có tác động lớn nhất đến chất lượng sử dụng archive.

Biến MEMORY.md thành thứ hữu ích, không phải nghi thức

Một dòng chỉ mục yếu sẽ là:

• “Đã sửa lỗi deploy”

Một dòng mạnh hơn sẽ là:

• “ECS deploy failed due to missing IAM permission for secret access; resolved by updating task role policy”

Chỉ mục phải giúp người đọc quyết định nhanh nên mở archive nào tiếp theo.

Ghi lại cả những lần thử sai nếu chúng ảnh hưởng đến quyết định về sau

Nếu nhóm đã thử hai cách sửa sai trước khi tìm đúng hướng, hãy ghi chúng lại khi điều đó giúp tránh lãng phí lặp lại. Đây là điểm mà skill archive thường vượt tài liệu chuẩn: nó giữ lại những ngõ cụt nhưng quan trọng.

Cung cấp đầu vào tốt hơn để nhận đầu ra archive tốt hơn

Trước khi yêu cầu skill archive lưu lại nội dung, hãy gom sẵn:

• nguyên văn lỗi
• các lệnh liên quan
• file hoặc thiết lập đã thay đổi
• trạng thái cuối cùng đã được xác nhận
• vì sao cách sửa cuối cùng có hiệu quả

Những chi tiết này cải thiện đáng kể khả năng tái sử dụng và tìm kiếm về sau.

Các kiểu hỏng thường gặp khi dùng skill archive

Những vấn đề điển hình gồm:

• quên cập nhật .archive/MEMORY.md
• tag quá chung chung
• không có category rõ ràng
• chỉ có tóm tắt mà thiếu chi tiết vận hành
• mục archive không liên hệ gì với các sự cố trước đó

Phần lớn kết quả archive kém chất lượng đến từ đầu vào không đầy đủ, không phải do bản thân template.

Rà soát lại sau bản nháp archive đầu tiên

Sau bản nháp đầu tiên, hãy kiểm tra:

• Người khác có thể tìm thấy mục này bằng các từ khóa tìm kiếm hợp lý không?
• Phần tóm tắt có nêu rõ kết quả và nguyên nhân không?
• Các lệnh chính hoặc thay đổi cấu hình đã được đưa vào chưa?
• Một agent ở tương lai có biết nên thử gì trước không?
• Có nên liên kết nó với một mục cũ liên quan không?

Chỉ cần thêm một lượt rà ngắn, chất lượng archive thường tăng lên đáng kể.

Dùng archive song song với tài liệu thường trực, không thay thế

Nếu phiên làm việc hé lộ một quy tắc mang tính lâu dài, hãy cập nhật cả tài liệu chuẩn. Skill archive nên lưu giữ kiến thức ở cấp độ sự kiện; nó không nên trở thành nơi duy nhất chứa hướng dẫn quan trọng của nhóm.

Cải thiện việc áp dụng archive bằng một trigger rõ ràng cho cả nhóm

Các nhóm thường có kết quả tốt hơn khi xác định trigger cụ thể như:

• mọi lần deploy production có bất ngờ phát sinh
• mọi incident có cách sửa không hiển nhiên
• mọi đợt migration
• mọi yêu cầu từ người dùng kiểu “lưu cái này cho lần sau”

Cách này giữ cho archive luôn có giá trị mà không bị đầy bởi quá nhiều nhiễu.