code-tour

Tổng quan về skill code-tour

skill code-tour làm được gì

skill code-tour tạo các file CodeTour .tour có thể tái sử dụng để dẫn người đọc đi qua một repository bằng đúng đường dẫn file và khoảng dòng thực tế. Thay vì một phần giải thích trong chat chỉ dùng một lần, nó tạo ra một artifact nằm trong .tours/ và có thể mở thành chuỗi hướng dẫn từng bước trong các công cụ tương thích với CodeTour.

Ai nên dùng và công việc phù hợp nhất

skill này phù hợp với maintainer, reviewer và technical writer khi cần một lộ trình có cấu trúc để đi qua code: tour onboarding, tour kiến trúc, walkthrough cho PR, lần vết RCA, hoặc tuyến review bảo mật. Nhu cầu thực sự ở đây không phải là “tóm tắt repo”, mà là “dẫn đúng người đọc qua đúng file theo đúng thứ tự”.

Vì sao nên chọn code-tour thay vì prompt chung chung

Prompt chung thường chỉ trả về phần diễn giải tách rời khỏi code. code-tour hẹp hơn, nhưng hữu ích hơn khi bạn cần cách điều hướng bền vững: mỗi bước đều trỏ tới file thật và khoảng dòng cụ thể, kèm ngữ cảnh tường thuật và mạch chuyển sang bước tiếp theo. Vì vậy, nó đặc biệt mạnh khi dùng làm code-tour cho Technical Writing, onboarding và các quy trình review lặp lại.

Những ràng buộc chính trước khi cài đặt

skill code-tour chỉ tạo file JSON .tour; nó không dùng để chỉnh sửa source code, viết lại tài liệu diện rộng, hay trả lời hỏi đáp thông thường. Nó phát huy hiệu quả nhất khi repository đã có cấu trúc file rõ ràng và yêu cầu được giới hạn vào một service, feature, luồng sự cố, hoặc diff của PR thay vì kiểu “giải thích toàn bộ”.

Cách dùng skill code-tour

Ngữ cảnh cài đặt và nên đọc gì trước

Hãy cài parent skills repo theo workflow skills bạn đang dùng, rồi gọi code-tour từ chính môi trường đó. Trong thư mục skill này, SKILL.md là file nguồn duy nhất, nên hãy đọc nó trước. Ở đây không có script hỗ trợ hay tài liệu tham chiếu bổ sung, nghĩa là việc áp dụng khá đơn giản nhưng bạn phải tự cung cấp ngữ cảnh repo đủ tốt.

skill code-tour cần đầu vào gì

Để dùng code-tour hiệu quả, hãy cung cấp:

• audience: “new backend engineer”, “security reviewer”, “technical writer”
• goal: onboarding, architecture, PR review, RCA, trust-boundary review
• scope: package, service, feature, hoặc các file đã thay đổi
• output target: .tours/<name>.tour
• repo anchors: file chính, entrypoint, module, hoặc ngữ cảnh commit/PR

Một yêu cầu yếu là: “Make a tour of this repo.”
Một yêu cầu tốt hơn là: “Create a code-tour for Technical Writing that explains how auth requests flow through src/server.ts, middleware, token validation, and session storage. Keep it to 8–10 stops and optimize for a new doc writer.”

Biến một mục tiêu thô thành prompt dùng được

Một prompt tốt cho code-tour nên nêu rõ người đọc, đường đi và phần cần loại trừ. Ví dụ:

• “Create a code-tour onboarding tour for new maintainers of the billing service.”
• “Anchor each stop to real files and line ranges.”
• “Start from the request entrypoint, then config loading, domain logic, persistence, and tests.”
• “Avoid unrelated admin tooling.”
• “Write concise step text that explains why this file matters and where to look next.”

Cách viết này giúp skill ưu tiên mạch dẫn dắt thay vì chỉ tóm lược. Nếu thiếu khung định hướng đó, tour thường dễ biến thành danh sách file phẳng, thiếu trọng tâm.

Quy trình thực tế và cách kiểm tra đầu ra

Workflow gợi ý:

1. Xác định người đọc và câu hỏi cụ thể cần trả lời.
2. Khảo sát repo để tìm entrypoint, module cốt lõi và các test hỗ trợ.
3. Phác thảo thứ tự các stop sao cho phản ánh đúng cách hệ thống nên được hiểu.
4. Tạo file .tour trong .tours/.
5. Kiểm tra lại mọi đường dẫn file và line anchor.
6. Mở tour ra và cắt bớt các stop yếu.

Các tiêu chí kiểm tra chất lượng quan trọng:

• mỗi stop đều có lý do tồn tại rõ ràng
• cả chuỗi phải kể được một câu chuyện, không chỉ là một danh sách
• line anchor phải trỏ tới đoạn code có ý nghĩa, không phải các khối import
• tour nên kết lại bằng “nên xem tiếp gì” hoặc một bước tổng hợp

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

code-tour có phù hợp với người mới bắt đầu không?

Có, nếu phạm vi đủ gọn. Người mới hưởng lợi nhiều nhất từ một code-tour xoay quanh một flow, một service hoặc một PR. Một code-tour bao trùm toàn repo thường sẽ khiến họ bị quá tải. Nếu bạn đang onboarding người mới, hãy yêu cầu một lộ trình ngắn qua execution path chính cộng thêm 1–2 file hỗ trợ.

Khi nào nên dùng code-tour thay vì tài liệu thông thường?

Hãy dùng code-tour khi người đọc cần điều hướng theo từng file và bám sát source. Hãy dùng tài liệu thông thường khi bạn cần phần tổng quan khái niệm, mô tả hành vi sản phẩm, hoặc văn bản dài dạng giải thích. Với các nhóm technical writing, code-tour phù hợp nhất ở vai trò tài liệu đồng hành bám theo source, không phải thay thế cho bộ docs đã được biên tập hoàn chỉnh.

Giới hạn chính của skill code-tour là gì?

Nó không triển khai feature, không refactor code, và cũng không viết cả bộ tài liệu diện rộng. Nó còn phụ thuộc vào đường dẫn file ổn định và cấu trúc code có ý nghĩa. Nếu repo lộn xộn, sinh tự động, hoặc đặt tên kém rõ ràng, skill vẫn có thể tạo tour, nhưng kết quả sẽ cần review thủ công nhiều hơn.

Khi nào đây là lựa chọn không phù hợp?

Bỏ qua code-tour nếu chỉ cần câu trả lời nhanh trong chat, nếu người dùng muốn tài liệu Markdown thay vì artifact .tour, hoặc nếu yêu cầu quá rộng nên khó sắp xếp thành chuỗi hợp lý. Nó cũng không phù hợp lắm khi chưa xác định rõ audience; tour sẽ tốt hơn đáng kể khi bạn biết chính xác đang viết cho ai.

Cách cải thiện skill code-tour

Cung cấp hướng dẫn đọc repo tốt hơn cho code-tour

Mức cải thiện chất lượng lớn nhất đến từ việc đưa sẵn một lộ trình khám phá trước khi tạo tour. Hãy nói rõ cho skill biết nên bắt đầu ở đâu: entrypoint, router, handler, core service, test và config. Nếu phù hợp, hãy kèm thêm diff của PR hoặc ghi chú về incident. Anchor tốt hơn sẽ tạo ra tour tốt hơn.

Tránh các lỗi phổ biến của code-tour

Những đầu ra yếu thường gặp:

• quá nhiều stop
• stop bám vào các dòng không quan trọng
• nhận xét chung chung có thể áp vào bất kỳ repo nào
• không có audience rõ ràng
• không có chuyển ý tường thuật giữa các bước

Để tránh các lỗi này, hãy đặt ngân sách số stop, nêu rõ người đọc là ai, và yêu cầu mỗi stop phải có cả “why this matters” lẫn “what to inspect next”.

Cải thiện prompt bằng audience và mục đích sử dụng

Với code-tour cho Technical Writing, hãy yêu cầu nêu thuật ngữ, định nghĩa ranh giới và các khái niệm đáng đưa vào tài liệu. Với PR review, hãy yêu cầu sắp thứ tự theo changed files và chỉ ra các điểm rủi ro. Với onboarding, hãy yêu cầu sắp theo hướng kiến trúc trước, test để sau. Cùng một repo, nhưng prompt khác nhau sẽ cho chất lượng tour rất khác nhau.

Lặp lại sau bản nháp đầu tiên

Hãy xem đầu ra đầu tiên như một bản đồ, không phải artifact cuối cùng. Mở file .tour, bỏ các stop trùng lặp, thu gọn khoảng dòng, và thêm một stop tổng hợp ở gần cuối. Nếu tour có cảm giác như đang liệt kê thư mục, hãy thu hẹp phạm vi rồi tạo lại. Kết quả tốt nhất từ skill code-tour thường đến sau một vòng chỉnh sửa có chủ đích, chứ không phải một lượt đầu tiên quá rộng.