lesson-learned

Tổng quan về skill lesson-learned

lesson-learned skill biến hoạt động Git gần đây thành những bài học kỹ thuật phần mềm cụ thể. Thay vì đưa ra lời khuyên trừu tượng, nó đọc diff thực tế, lịch sử commit và các file đã thay đổi, rồi đối chiếu những gì đã xảy ra với các nguyên tắc có tên rõ ràng như SRP, DRY, KISS, YAGNI và các anti-pattern liên quan. Vì vậy, lesson-learned đặc biệt phù hợp với lập trình viên đã vừa sửa code và muốn trả lời các câu hỏi như: công việc này dạy mình điều gì, mình đã chấp nhận trade-off nào, và lần sau nên lặp lại hay tránh điều gì?

lesson-learned skill phù hợp với ai

Những nhóm người dùng phù hợp nhất gồm:

• lập trình viên vừa hoàn thành một feature, đợt refactor, bug fix hoặc cleanup
• reviewer muốn có phần tổng kết mang tính học hỏi sau một PR
• team lead muốn xây dựng thói quen nhìn lại kỹ thuật theo cách gọn nhẹ
• agent cần giải thích nguyên tắc đứng sau các thay đổi code gần đây

Nếu bạn muốn nhìn lại thiết kế dựa trên chính lịch sử repository, lesson-learned skill mạnh hơn một prompt chung chung kiểu “review đoạn code này”.

lesson-learned skill thực sự giải quyết bài toán gì

Nhiệm vụ cốt lõi ở đây không phải code review theo kiểu pass/fail thông thường. lesson-learned nhìn ngược lại phần việc đã hoàn thành hoặc đang tiến hành, rồi rút ra 1–3 bài học có căn cứ từ diff. Một đầu ra tốt thường bao gồm:

• tên nguyên tắc
• thay đổi đó thể hiện nguyên tắc này như thế nào
• vì sao điều đó quan trọng
• khuyến nghị cho bước tiếp theo

Cách đóng khung này khiến nó đặc biệt hữu ích cho retrospective, mentoring và ghi chú học hỏi trong PR.

Điều gì khiến lesson-learned khác với một prompt chung chung

Có hai điểm quan trọng nhất:

1. Nó được dẫn dắt bởi Git history, nên phân tích thay đổi thực tế thay vì các snippet giả định.
2. Nó cần một bộ tham chiếu về nguyên tắc, đặc biệt là references/se-principles.md, để mô hình có từ vựng nhất quán khi gọi tên các pattern.

Sự kết hợp này giúp skill tạo ra những bài học “rút ra từ code” thật sự, thay vì nghe như sao chép từ giáo trình kỹ thuật phần mềm.

Khi nào không nên chọn lesson-learned

Bỏ qua lesson-learned nếu mục tiêu thực sự của bạn là:

• tìm bug theo từng dòng trước khi merge
• audit bảo mật
• phản hồi chỉ xoay quanh style/lint
• lên kế hoạch kiến trúc khi chưa có thay đổi code nào
• review một codebase lớn mà không có phạm vi rõ ràng

Trong các trường hợp đó, một skill chuyên về code review, security hoặc design thường là lựa chọn đầu tiên phù hợp hơn.

Cách dùng lesson-learned skill

Ngữ cảnh cài đặt lesson-learned

Repository này không công bố một lệnh cài đặt riêng ngay trong skills/lesson-learned/SKILL.md, nên cách cài đặt sẽ phụ thuộc vào cách môi trường của bạn nạp skill từ softaworks/agent-toolkit. Nếu môi trường hỗ trợ thêm skill từ repository đó, mẫu dùng phổ biến là:

npx skills add softaworks/agent-toolkit --skill lesson-learned

Nếu agent của bạn nạp skill trực tiếp từ repo, hãy dùng đường dẫn skill:

skills/lesson-learned

Dù theo cách nào, hãy xem SKILL.md là bản đặc tả hành vi lúc chạy, không chỉ là README.

Hãy đọc các file này trước khi dùng lesson-learned lần đầu

Để bắt đầu nhanh và ít phải đoán, hãy đọc file theo thứ tự sau:

1. skills/lesson-learned/SKILL.md
2. skills/lesson-learned/references/se-principles.md
3. skills/lesson-learned/references/anti-patterns.md
4. skills/lesson-learned/README.md

Chi tiết quan trọng nhất khi triển khai rất dễ bị bỏ sót: skill này nói rõ là không nên tiếp tục trước khi nạp se-principles.md.

lesson-learned skill cần đầu vào gì

lesson-learned usage cho kết quả tốt nhất khi mô hình có thể truy cập:

• một repository có Git history
• tên branch hiện tại hoặc một mốc so sánh như main
• một khoảng commit, commit SHA, branch diff hoặc working tree diff
• đủ ngữ cảnh file để xem các file thay đổi nhiều nhất

Nếu không có ngữ cảnh Git, đầu ra sẽ nhanh chóng trở nên chung chung.

Hãy chọn đúng phạm vi phân tích cho lesson-learned ngay từ đầu

Skill này chỉ tốt bằng đúng phạm vi bạn cung cấp cho nó. Repository đã định nghĩa sẵn các mặc định thực tế:

• feature branch: so sánh phần việc trên branch với main
• main branch: phân tích 5 commit gần nhất
• commit cụ thể: xem một SHA
• thay đổi đang làm dở: xem diff chưa stage và đã stage

Một lesson-learned guide tốt luôn buộc phải chốt lựa chọn này sớm. Nếu phạm vi mơ hồ, kết quả thường trộn lẫn nhiều bài học không liên quan.

Các lệnh Git hữu ích để dùng lesson-learned hiệu quả hơn

Quy trình của chính skill xoay quanh các góc nhìn Git quen thuộc như:

• git log main..HEAD --oneline
• git diff main...HEAD
• git log --oneline -5
• git diff HEAD~5..HEAD
• git show <sha>
• git diff
• git diff --cached

Bạn không cần dùng mọi lệnh trong mọi lần. Hãy chọn lệnh khớp với “câu chuyện” mà bạn muốn skill giải thích.

Biến một yêu cầu sơ sài thành prompt mạnh cho lesson-learned

Prompt yếu:

“Reflect on my recent work.”

Prompt tốt hơn:

“Use lesson-learned on my feature branch versus main. Read references/se-principles.md first. Focus on the 3 files with the largest behavioral changes. Give me 2 lessons grounded in the diff, each with the principle name, code evidence, trade-off, and one thing I should repeat in future PRs.”

Vì sao prompt này hiệu quả:

• nó xác định rõ phạm vi
• nó chỉ ra file tham chiếu mà skill phụ thuộc vào
• nó giới hạn bề mặt phân tích
• nó chỉ định hình dạng đầu ra

Mẫu prompt lesson-learned cho Code Review

lesson-learned for Code Review hiệu quả nhất khi dùng như một lớp phản tư sau code review thông thường, không phải để thay thế code review. Một prompt thực tế là:

“Run lesson-learned on this PR branch against main. Summarize the engineering lesson behind the changes, not just defects. Highlight 1 positive principle demonstrated, 1 anti-pattern risk if relevant, and cite the changed files that support each point.”

Mẫu này đặc biệt hữu ích khi bạn muốn comment review có giá trị hướng dẫn, chứ không chỉ để chặn.

Định dạng đầu ra nên yêu cầu

Hãy yêu cầu một cấu trúc gọn như:

• Lesson
• Principle
• Evidence from changes
• Why it matters
• Next step

Cách này bám đúng ý đồ của repository và giảm bớt phần chữ đệm chung chung.

Cách xử lý diff lớn trong lesson-learned

Với PR lớn, đừng yêu cầu skill “phân tích tất cả”. Thay vào đó:

• xác định các file thay đổi nhiều nhất
• gom thay đổi theo từng chủ đề
• bỏ qua các chỉnh sửa cơ học quá hiển nhiên
• chỉ yêu cầu 1–3 bài học

Skill này mạnh ở chỗ rút ra pattern, không phải lập danh mục đầy đủ cho mọi thay đổi trong từng file.

Workflow lesson-learned thường dùng để tiết kiệm thời gian

Một quy trình đáng tin cậy là:

1. nạp se-principles.md
2. chọn phạm vi
3. xem Git log và diff
4. đọc các file thay đổi nhiều nhất
5. nếu cần thì nạp anti-patterns.md
6. tạo 1–3 bài học có dẫn chứng
7. tinh chỉnh nếu kết quả quá rộng hoặc quá nặng tính “rao giảng”

Trình tự này quan trọng vì bộ tham chiếu nguyên tắc giúp phần phân tích có vốn từ mạnh và nhất quán hơn.

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

lesson-learned có phù hợp cho người mới bắt đầu không?

Có, miễn là người mới đó có thay đổi thực tế để phân tích. Skill giải thích nguyên tắc thông qua chính phần việc họ vừa làm, và cách này thường dễ tiếp thu hơn so với việc đọc lý thuyết trước. Nó sẽ kém hữu ích hơn với người không có quyền truy cập repo hoặc không có diff gần đây.

lesson-learned có giống code review không?

Không. lesson-learned mang tính nhìn lại và xoay quanh nguyên tắc. Code review thường tập trung vào tính đúng đắn, rủi ro và khả năng bảo trì. Hai việc này có phần giao nhau, nhưng mục tiêu đầu ra là khác nhau.

lesson-learned skill có cần quyền truy cập Git không?

Nếu muốn kết quả mạnh, có. Repository này được thiết kế xoay quanh Git history và diff. Nếu bạn chỉ dán một đoạn code, mô hình vẫn có thể bình luận về nguyên tắc, nhưng khi đó bạn không còn dùng skill ở chế độ mạnh nhất nữa.

Điều gì khiến lesson-learned tốt hơn một prompt thông thường?

Ưu thế nằm ở cấu trúc: chọn phạm vi một cách tường minh, bắt buộc dùng tài liệu tham chiếu nguyên tắc và có quy trình gắn bài học trở lại với tín hiệu code cụ thể. Prompt thông thường thường nhảy thẳng sang kiểu “best practices” rất chung.

Có thể dùng lesson-learned cho thay đổi chưa commit không?

Có. Skill hỗ trợ thay đổi đang làm dở thông qua git diff và git diff --cached. Điều này hữu ích trước khi commit, khi bạn muốn hiểu bài học hoặc trade-off trong phần mình sắp đưa lên.

Khi nào lesson-learned là lựa chọn không phù hợp?

Nên tránh khi:

• không có thay đổi gần đây nào đủ ý nghĩa
• diff chủ yếu là mã sinh tự động hoặc thay đổi format gây nhiễu
• bạn cần phân loại lỗi hơn là nhìn lại bài học
• branch trộn nhiều đầu việc không liên quan

Trong các trường hợp đó, hãy thu hẹp phạm vi hoặc dùng skill khác trước.

Cách cải thiện lesson-learned skill

Hãy cho lesson-learned một “câu chuyện” hẹp hơn

Đòn bẩy chất lượng lớn nhất là phạm vi. “Cả tháng vừa rồi tôi làm gì” là quá rộng. “Đợt refactor tách API calls khỏi UI rendering này” thì tốt hơn nhiều. Phạm vi càng hẹp, bài học rút ra càng sắc nét về nguyên tắc và càng vững về dẫn chứng.

Luôn nạp tài liệu nguyên tắc cho lesson-learned

Repository này nói rất rõ ở điểm này: cần nạp references/se-principles.md trước khi phân tích. Nếu bỏ qua, mô hình vẫn có thể đưa ra nhận xét, nhưng khả năng gọi tên pattern nhất quán hoặc gắn chúng với các nguyên tắc đã được công nhận sẽ giảm đi rõ rệt.

Dùng anti-patterns để cân bằng, không phải để soi lỗi

references/anti-patterns.md hữu ích nhất khi diff có tín hiệu rủi ro như sửa rải rác, over-abstraction hoặc module kiểu “god” ngày càng phình ra. Hãy yêu cầu cách diễn đạt mềm hơn để kết quả vẫn hữu ích, thay vì nghe như đang khiển trách.

Yêu cầu dẫn chứng gắn với các file đã thay đổi

Một lỗi rất thường gặp là lời khuyên ở tầm cao nhưng không có bằng chứng. Để cải thiện đầu ra của lesson-learned, hãy yêu cầu:

• các file thay đổi liên quan
• thay đổi về cấu trúc thực sự là gì
• trade-off mà nó kéo theo
• vì sao điều đó ánh xạ tới một nguyên tắc cụ thể

Chính phần bằng chứng là thứ tách một bài học thật sự khỏi phần bình luận chung chung.

Giới hạn số lượng bài học

Càng nhiều bài học thì thường mỗi bài càng yếu. Chỉ nên yêu cầu 1–3 điểm rút ra. Điều đó buộc skill phải ưu tiên điều quan trọng nhất, đồng thời làm đầu ra đáng tin hơn và dễ dùng hơn trong ghi chú PR, retrospective hoặc coaching.

Nói rõ bạn muốn lesson-learned rút ra loại bài học nào

Bạn có thể lái hướng phân tích bằng cách thêm một “lăng kính” cụ thể:

• bài học về maintainability
• bài học về refactoring
• bài học từ bug fix
• bài học về design trade-off
• bài học về quy trình nhóm gắn với thay đổi code

Cách này tăng độ liên quan mà không đi ngược workflow vốn có của skill.

Sửa bản nháp lesson-learned còn chung chung bằng một lượt hai

Nếu kết quả đầu tiên còn mơ hồ, đừng vội chạy lại từ đầu. Thay vào đó, hãy yêu cầu:

• “Tie each lesson to a specific file or diff hunk.”
• “Replace general advice with what this branch actually demonstrates.”
• “Name the principle only if the code evidence clearly supports it.”
• “Drop any lesson that is not visible in the diff.”

Cách này thường nâng chất lượng đầu ra nhanh hơn so với việc prompt lại theo kiểu quá rộng.

Cảnh giác với các failure mode thường gặp của lesson-learned

Những đầu ra yếu điển hình gồm:

• gọi tên nguyên tắc nhưng không có bằng chứng từ code
• rút quá nhiều bài học từ một diff
• lẫn lộn lỗi code review với bài học mang tính học hỏi
• dùng giọng điệu lên lớp thay vì nói về trade-off thực tế
• cố gộp các thay đổi không liên quan thành một bài học duy nhất

Nhận ra sớm các dấu hiệu này sẽ giúp việc lặp và chỉnh rất thẳng tay, không mất thời gian.

Hướng cải thiện tốt nhất khi cả team dùng lesson-learned thường xuyên

Nếu team định dùng lesson-learned đều đặn, hãy chuẩn hóa một prompt template bao gồm:

• quy tắc chọn phạm vi
• mốc so sánh
• số bài học tối đa
• định dạng dẫn chứng bắt buộc
• kiểm tra anti-pattern nếu cần

Cách này giảm sự thiếu nhất quán và khiến lesson-learned skill trở nên đáng tin hơn nhiều giữa các PR và các buổi retrospective.