code-tour

code-tour skill 개요

code-tour가 만드는 것

code-tour skill은 AI 에이전트가 VS Code CodeTour 확장 프로그램에서 사용할 수 있는 CodeTour .tour JSON 파일을 만들도록 돕습니다. 투어는 설명 단계를 실제 파일과 줄 번호에 연결하는 안내형 워크스루이며, 보통 .tours/ 아래에 저장됩니다. 이 skill은 코드 편집이 아니라 구조적인 저장소 탐색을 위해 설계되었습니다. 핵심 경계는 투어 파일만 만들고 소스 코드는 수정하지 않는 것입니다.

Technical Writing과 온보딩에 가장 잘 맞는 경우

온보딩 경로, 기여자 가이드, 아키텍처 워크스루, PR 리뷰 투어, 보안 검토 경로, 원인 분석 흐름, 또는 “이게 어떻게 동작하는지 설명해줘” 유형의 워크스루가 필요할 때 Technical Writing 용도로 code-tour를 사용하세요. 새 백엔드 엔지니어, 프런트엔드 메인테이너, 리뷰어, 인시던트 대응자, 스태프 엔지니어, 구현 세부 사항을 선별된 경로로 이해해야 하는 비개발 이해관계자처럼 읽는 사람의 페르소나가 명확할수록 효과가 좋습니다.

일반 프롬프트보다 나은 점

일반 프롬프트는 파일을 느슨하게 요약하는 데 그칠 수 있습니다. code-tour skill은 에이전트가 바로 사용할 수 있는 산출물, 즉 구체적인 파일과 줄 위치에 고정된 페르소나 맞춤형 내러티브 단계를 만들도록 유도합니다. 투어는 VS Code에서 실제로 탐색할 수 있어야 하고, 존재하는 경로를 참조해야 하며, 단순한 폴더 요약을 늘어놓는 대신 각 지점이 왜 중요한지 설명해야 하기 때문에 이 차이가 중요합니다. 유용한 결과물은 “이 저장소에 무엇이 들어 있는가”가 아니라 “이 독자가 어디를 먼저, 그다음 어디를 클릭해야 하며 왜 그래야 하는가”입니다.

설치 전에 고려할 점

이 skill은 집중도 높은 SKILL.md만 포함하며 추가 스크립트, 규칙, 레퍼런스 팩은 없습니다. 그래서 code-tour install은 가볍게 진행할 수 있지만, 품질은 저장소 접근 권한과 프롬프트의 구체성에 크게 좌우됩니다. 에이전트가 파일 트리, README, 설정 파일, 소스 진입점을 확인할 수 있을 때 가장 잘 작동합니다. 순수한 문서 텍스트, Mermaid 다이어그램, 소스 수정, 또는 에이전트가 읽을 수 없는 파일을 대상으로 한 투어가 필요하다면 적합하지 않습니다.

code-tour skill 사용 방법

code-tour install과 저장소 컨텍스트

사용 중인 skills 도구로 원본 저장소에서 설치합니다. 예를 들면 다음과 같습니다.

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

설치 후 필요하다면 skill 경로를 확인하세요: engineering/code-tour/skills/code-tour/SKILL.md. 대상 프로젝트에서는 에이전트가 초안을 쓰기 전에 먼저 루트 디렉터리, README.md, 패키지 또는 빌드 설정, 그리고 상위 한두 단계의 폴더 구조를 확인해야 합니다. 투어는 VS Code CodeTour 확장 프로그램과 호환되는 .tour JSON 파일로 .tours/ 아래에 저장해야 합니다.

skill에 필요한 입력

좋은 code-tour usage를 위해서는 다섯 가지를 제공하세요. 대상 독자, 목표, 범위, 원하는 깊이, 그리고 반드시 포함해야 할 파일이나 기능 이름입니다. 약한 요청은 “이 저장소 투어를 만들어줘”입니다. 좋은 요청은 “새 백엔드 엔지니어를 위해 로그인 요청 생명주기를 설명하는 CodeTour를 만들어줘. 라우트 등록부터 검증, 서비스 로직, 데이터베이스 접근, 오류 처리까지 포함해. 8–12단계로 제한하고 모든 단계는 실제 파일과 줄에 연결해.”입니다.

투어가 Technical Writing 용도라면 온보딩 문서, 릴리스 노트 보조 자료, 내부 아키텍처 가이드, 리뷰 보조 자료, 인시던트 학습 자료 등 게시 목적도 함께 추가하세요.

첫 투어를 만들 때 권장하는 워크플로

바로 작성하지 말고 탐색부터 시작하세요. 에이전트에게 프로젝트의 목적, 언어, 프레임워크, 진입점, 중요한 디렉터리를 먼저 파악하게 하세요. 그런 다음 내러티브 경로를 선택합니다. 예를 들어 setup-to-first-feature, request-to-response, UI-action-to-API, bug-symptom-to-root-cause, PR-diff-to-risk 같은 흐름이 될 수 있습니다. 그다음에야 .tour 파일을 생성하도록 해야 합니다. 이 순서는 깨진 앵커를 줄이고, 디렉터리 이름만 나열할 뿐 시스템이 어떻게 작동하는지 가르치지 못하는 얕은 “폴더 투어”를 방지합니다.

실전 프롬프트 패턴

다음과 같은 프롬프트를 사용하세요.

“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.”

이 방식이 효과적인 이유는 에이전트에게 단순한 주제가 아니라 판단 기준을 제공하기 때문입니다.

code-tour skill FAQ

문서 대신 code-tour를 써야 할 때는 언제인가요?

코드를 따라 이동하는 경험 자체가 결과물일 때 code-tour를 사용하세요. 개념, 정책, API 레퍼런스에는 전통적인 문서가 더 적합합니다. 반면 CodeTour는 독자가 파일을 순서대로 열어 보며 라우트, 서비스, 테스트, 설정, 진입점 사이의 관계를 이해해야 할 때 더 적합합니다.

초보자도 code-tour skill을 사용할 수 있나요?

네. 다만 초보자는 요청 범위를 좁혀야 합니다. 먼저 하나의 기능, 하나의 버그 경로, 하나의 아키텍처 단면처럼 작은 투어를 요청하세요. “전체 코드베이스를 설명해줘” 같은 넓은 요청은 저장소가 아주 작지 않은 이상 잡음이 많은 투어로 이어지기 쉽습니다. 소스 파일이 몇 개 되지 않는 매우 작은 저장소라면 빠르게 훑는 정도의 투어로도 충분한 경우가 많습니다.

code-tour가 애플리케이션 코드를 수정하나요?

아니요. 의도한 출력물은 일반적으로 .tours/에 배치되는 .tour JSON 파일입니다. 이 skill의 명시적인 경계는 소스 코드 수정을 피하는 것입니다. 코드 수정, 테스트, 리팩터링이 필요한 워크플로라면 먼저 다른 엔지니어링 skill을 사용한 뒤, 그 결과 경로를 문서화하는 데 code-tour를 사용하세요.

좋은 code-tour 결과를 막는 요인은 무엇인가요?

가장 큰 방해 요인은 저장소 접근 권한 부족, 모호한 대상 독자, 범위 제한 없음, 검증되지 않은 파일 경로입니다. CodeTour 단계는 실제 앵커에 의존합니다. 에이전트가 대상 파일을 읽을 수 없거나 활발한 수정 중이라 줄 번호가 크게 바뀐다면, 코드가 안정된 뒤 투어를 생성하거나 먼저 경로 수준의 앵커를 만들고 나중에 줄 번호를 다듬도록 요청하세요.

code-tour skill 개선 방법

code-tour 프롬프트를 페르소나별로 구체화하기

code-tour 출력 품질을 가장 빠르게 높이는 방법은 독자를 명확히 지정하는 것입니다. “새 기여자”는 “보안 리뷰어”나 “온보딩 자료를 준비하는 테크니컬 라이터”와 다른 경로를 만들어냅니다. 독자가 이미 알고 있는 것과 투어를 마친 뒤 할 수 있어야 하는 일을 함께 포함하세요. 이렇게 하면 단계 선택, 설명 깊이, 사용하는 어휘가 달라집니다.

목록이 아니라 내러티브를 요청하기

약한 투어는 파일을 나열합니다. 좋은 투어는 실행이 어디서 시작되는지, 데이터가 어떻게 이동하는지, 의사결정이 어디서 일어나는지, 위험이 어디에 있는지, 어떤 테스트가 동작을 증명하는지 이야기로 설명합니다. 에이전트에게 각 지점을 이전 단계와 연결하고, 단계마다 “왜 이것이 중요한가”를 설명하는 문장을 넣도록 요청하세요. Technical Writing에서는 최종 산출물이 단순히 클릭 가능한 자료가 아니라 가르칠 수 있는 자료가 되기 때문에 특히 중요합니다.

첫 출력 이후 반복 개선하기

첫 .tour 초안이 나온 뒤에는 세 가지를 검토하세요. 깨졌거나 부정확한 파일 경로, 너무 넓게 잡힌 단계, 빠진 전환 설명입니다. 그런 다음 “4단계를 라우트 단계와 서비스 단계로 나눠줘”, “이 동작을 커버하는 테스트를 추가해줘”, “프런트엔드 세부 사항은 줄이고 API 오류 처리에 집중해줘”처럼 목표가 분명한 수정을 요청하세요. 한 번에 완벽한 전체 저장소 투어를 요청하는 것보다 반복 개선이 대체로 더 효과적입니다.

공유하기 전에 앵커 검증하기

CodeTour를 게시하기 전에 VS Code에서 CodeTour 확장 프로그램으로 열어 모든 경로와 줄이 예상한 위치로 이동하는지 확인하세요. 저장소가 자주 변경된다면 안정적인 아키텍처 파일, 테스트, 진입점에 연결된 투어를 선호하고, 큰 리팩터링 이후에는 줄 번호를 다시 생성하세요. 이렇게 해야 code-tour skill이 오래된 지도 대신 유용한 온보딩 자산으로 남을 수 있습니다.