code-tour

Tổng quan về code-tour skill

code-tour tạo ra những gì

code-tour skill giúp AI agent tạo các tệp JSON CodeTour .tour cho extension VS Code CodeTour. Một tour là lộ trình hướng dẫn có liên kết từng bước giải thích với tệp thật và số dòng cụ thể, thường được lưu trong .tours/. Skill này được thiết kế cho việc khám phá repository có cấu trúc, không phải để chỉnh sửa code: ranh giới cốt lõi của nó là chỉ tạo tệp tour và tránh thay đổi mã nguồn.

Phù hợp nhất cho Technical Writing và onboarding

Hãy dùng code-tour cho Technical Writing khi bạn cần một lộ trình onboarding, hướng dẫn cho contributor, walkthrough kiến trúc, tour review PR, tuyến kiểm tra bảo mật, dấu vết phân tích nguyên nhân gốc, hoặc walkthrough “giải thích cách phần này hoạt động”. Skill này phát huy tốt nhất khi người đọc có persona rõ ràng: backend engineer mới, frontend maintainer, reviewer, incident responder, staff engineer, hoặc stakeholder không trực tiếp viết code nhưng cần một lộ trình được tuyển chọn qua các chi tiết triển khai.

Vì sao tốt hơn một prompt chung chung

Một prompt chung chung có thể chỉ tóm tắt các tệp một cách lỏng lẻo. code-tour skill hướng agent đến một artifact có thể dùng được: các bước kể chuyện theo persona, có neo cụ thể vào tệp và dòng. Điều này quan trọng vì một tour phải điều hướng được trong VS Code, phải tham chiếu đúng các path đang tồn tại, và phải giải thích vì sao từng điểm dừng đáng chú ý thay vì đổ ra một bản tóm tắt thư mục. Đầu ra hữu ích không phải là “repo này có gì”, mà là “người đọc này nên bấm vào đâu trước, tiếp theo là đâu, và vì sao.”

Cân nhắc trước khi cài đặt

Skill này có SKILL.md tập trung và không kèm script, rule hay gói tham chiếu bổ sung. Vì vậy code-tour install khá nhẹ, nhưng cũng đồng nghĩa chất lượng phụ thuộc nhiều vào quyền truy cập repository và mức chi tiết của prompt. Skill hoạt động tốt nhất khi agent có thể xem cây thư mục, README, tệp cấu hình, và các điểm vào của mã nguồn. Đây không phải lựa chọn phù hợp nếu bạn chỉ muốn tài liệu dạng prose, sơ đồ Mermaid, chỉnh sửa mã nguồn, hoặc tạo tour cho những tệp mà agent không đọc được.

Cách sử dụng code-tour skill

Cài đặt code-tour và cung cấp ngữ cảnh repository

Cài đặt từ source repository bằng công cụ skills của bạn, ví dụ:

npx skills add alirezarezvani/claude-skills --skill code-tour

Sau khi cài đặt, nếu cần, hãy kiểm tra skill path: engineering/code-tour/skills/code-tour/SKILL.md. Trong project đích, trước khi soạn bản nháp, agent nên xem thư mục gốc, README.md, package hoặc build config, và một đến hai tầng thư mục đầu tiên. Tour nên được lưu dưới dạng tệp JSON .tour trong .tours/, tương thích với extension VS Code CodeTour.

Các đầu vào skill cần

Để có code-tour usage chất lượng, hãy cung cấp năm thứ: đối tượng đọc, mục tiêu, phạm vi, mức độ chi tiết mong muốn, và mọi tệp hoặc tên tính năng bắt buộc phải có. Yêu cầu yếu: “make a tour of this repo.” Yêu cầu tốt: “Create a CodeTour for a new backend engineer explaining the request lifecycle for login, from route registration through validation, service logic, database access, and error handling. Keep it to 8–12 steps and anchor every step to real files and lines.”

Nếu tour phục vụ Technical Writing, hãy thêm mục đích xuất bản: tài liệu onboarding, hỗ trợ release note, hướng dẫn kiến trúc nội bộ, công cụ hỗ trợ review, hoặc artifact học hỏi sau sự cố.

Quy trình gợi ý cho tour đầu tiên

Hãy bắt đầu bằng khám phá, không phải viết ngay. Yêu cầu agent xác định mục đích project, ngôn ngữ, framework, entry point, và các thư mục quan trọng. Sau đó chọn một mạch kể chuyện: từ setup đến tính năng đầu tiên, từ request đến response, từ thao tác UI đến API, từ triệu chứng bug đến nguyên nhân gốc, hoặc từ diff PR đến rủi ro. Chỉ sau đó mới tạo tệp .tour. Trình tự này giảm nguy cơ neo sai và tránh kiểu “folder tour” nông, chỉ nêu tên thư mục mà không giúp người đọc hiểu hệ thống vận hành thế nào.

Mẫu prompt thực tế

Dùng một prompt như sau:

“Use the code-tour skill to create .tours/auth-onboarding.tour. Audience: new full-stack engineer. Goal: understand authentication flow well enough to make a safe change. Scope: login, session creation, middleware, and tests only. Exclude unrelated account settings. Inspect the repo first, then produce a 10-step CodeTour with real file paths and line numbers. Each step should explain what the reader should notice and why it matters.”

Cách này hiệu quả vì nó cho agent một khung ra quyết định, không chỉ là một chủ đề.

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

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

Dùng code-tour khi chính việc điều hướng qua code là sản phẩm cần tạo. Tài liệu truyền thống phù hợp hơn cho khái niệm, chính sách, hoặc API reference. CodeTour phù hợp hơn khi người đọc cần mở các tệp theo trình tự và hiểu mối quan hệ giữa routes, services, tests, configs, và entry points.

Người mới có dùng được code-tour skill không?

Có, nhưng người mới nên giới hạn yêu cầu. Hãy bắt đầu bằng một tour nhỏ: một tính năng, một đường đi của bug, hoặc một lát cắt kiến trúc. Những yêu cầu rộng như “explain the entire codebase” thường tạo ra tour nhiễu, trừ khi repository rất nhỏ. Với các repository rất nhỏ, chỉ có chưa đến vài tệp mã nguồn, một tour ngắn nhưng đủ chiều sâu thường là đủ.

code-tour có chỉnh sửa application code của tôi không?

Không. Đầu ra dự kiến là một tệp JSON .tour, thường đặt trong .tours/. Ranh giới rõ ràng của skill là tránh sửa đổi mã nguồn. Nếu workflow của bạn cần sửa code, viết test, hoặc refactor, hãy dùng một engineering skill khác trước, rồi dùng code-tour để ghi lại lộ trình kết quả.

Điều gì có thể cản trở một kết quả code-tour tốt?

Các rào cản lớn nhất là thiếu quyền truy cập repository, đối tượng đọc mơ hồ, không giới hạn phạm vi, và path tệp chưa được xác minh. Các bước CodeTour phụ thuộc vào neo thật. Nếu agent không đọc được tệp đích hoặc số dòng thay đổi nhiều trong lúc đang chỉnh sửa tích cực, hãy tạo tour sau khi code ổn định, hoặc yêu cầu neo ở cấp path trước rồi tinh chỉnh số dòng sau.

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

Viết prompt cho code-tour theo persona cụ thể

Cách nhanh nhất để cải thiện đầu ra của code-tour là gọi tên người đọc. “New contributor” sẽ tạo ra một lộ trình khác với “security reviewer” hoặc “technical writer preparing onboarding material.” Hãy nêu rõ người đọc đã biết gì và sau tour họ phải làm được gì. Điều này thay đổi cách chọn bước, độ sâu giải thích, và từ vựng sử dụng.

Yêu cầu mạch kể chuyện, không phải bảng kê

Một tour yếu chỉ liệt kê tệp. Một tour mạnh kể một câu chuyện: execution bắt đầu ở đâu, dữ liệu di chuyển thế nào, quyết định xảy ra ở đâu, rủi ro nằm ở đâu, và test nào chứng minh hành vi. Hãy yêu cầu agent nối từng điểm dừng với điểm trước đó và thêm một câu “vì sao điều này quan trọng” cho mỗi bước. Điều này đặc biệt có giá trị với Technical Writing vì artifact cuối cùng trở nên dễ dạy, không chỉ dễ bấm.

Lặp lại sau đầu ra đầu tiên

Sau bản nháp .tour đầu tiên, hãy review ba vấn đề: path tệp bị hỏng hoặc thiếu chính xác, các bước quá rộng, và thiếu chuyển tiếp giữa các bước. Sau đó yêu cầu chỉnh sửa có mục tiêu: “split step 4 into route and service steps,” “add the test that covers this behavior,” hoặc “reduce frontend detail and focus on API error handling.” Lặp lại thường hiệu quả hơn việc yêu cầu một tour hoàn hảo cho toàn bộ repo chỉ trong một lần.

Xác thực neo trước khi chia sẻ

Trước khi xuất bản CodeTour, hãy mở nó trong VS Code với extension CodeTour và xác nhận mọi path, mọi dòng đều nhảy đến đúng vị trí. Nếu repository thay đổi thường xuyên, nên ưu tiên các tour gắn với tệp kiến trúc ổn định, tests, hoặc entry points, và tạo lại số dòng sau các đợt refactor lớn. Điều này giữ cho code-tour skill hữu ích như một tài sản onboarding thay vì trở thành một bản đồ lỗi thời.