code-tour

code-tour 스킬 개요

code-tour 스킬이 하는 일

code-tour 스킬은 저장소를 실제 파일 경로와 라인 범위를 따라 안내하는 재사용 가능한 CodeTour .tour 파일을 만듭니다. 일회성 채팅 설명 대신, .tours/에 저장되는 아티팩트를 만들어 CodeTour 호환 도구에서 가이드된 순서로 열 수 있게 합니다.

가장 잘 맞는 사용자와 작업

이 스킬은 코드에 대한 구조화된 안내가 필요한 유지보수자, 리뷰어, 기술 문서 작성자에게 적합합니다. 온보딩 투어, 아키텍처 투어, PR 워크스루, RCA 추적, 보안 리뷰 경로처럼 “이 저장소를 요약해 달라”가 아니라 “특정 독자를 올바른 순서로 올바른 파일에 안내해 달라”는 작업에 맞습니다.

일반 프롬프트보다 code-tour를 선택하는 이유

일반 프롬프트는 보통 코드와 분리된 산문형 답변을 돌려줍니다. code-tour는 더 좁지만, 지속적인 탐색 경로가 필요할 때 훨씬 유용합니다. 각 단계가 실제 파일과 라인 구간을 가리키고, 내러티브 맥락과 다음 단계 흐름까지 포함하기 때문입니다. 그래서 기술 문서 작성, 온보딩, 반복 가능한 리뷰 워크플로에서 code-tour로 특히 강합니다.

설치 전에 확인할 핵심 제약

code-tour 스킬은 .tour JSON 파일만 만듭니다. 소스 코드 편집, 광범위한 문서 재작성, 가벼운 Q&A 용도는 아닙니다. 저장소에 이미 명확한 파일 구조가 있고, 요청 범위가 “모든 걸 설명해 달라”가 아니라 특정 서비스, 기능, 장애 경로, PR diff처럼 한정되어 있을 때 가장 잘 동작합니다.

code-tour 스킬 사용 방법

설치 맥락과 먼저 읽을 내용

평소 사용하는 skills 워크플로에서 부모 skills 저장소를 설치한 뒤, 그 환경에서 code-tour를 호출하세요. 이 스킬 폴더에서는 SKILL.md만 소스 파일이므로, 먼저 이 파일을 읽는 것이 좋습니다. 보조 스크립트나 참고 자료가 따로 없기 때문에 시작은 단순하지만, 저장소 맥락은 사용자가 직접 잘 제공해야 합니다.

code-tour 스킬에 필요한 입력

code-tour을 잘 쓰려면 다음 정보를 함께 주세요:

• 대상 독자: “신규 백엔드 엔지니어”, “보안 리뷰어”, “기술 문서 작성자”
• 목표: 온보딩, 아키텍처, PR 리뷰, RCA, 신뢰 경계 검토
• 범위: 패키지, 서비스, 기능, 변경된 파일
• 출력 대상: .tours/<name>.tour
• 저장소 기준점: 핵심 파일, 진입점, 모듈, 커밋/PR 맥락

약한 요청은: “이 저장소 투어를 만들어줘.”
더 강한 요청은: “src/server.ts, 미들웨어, 토큰 검증, 세션 저장소를 따라 인증 요청이 어떻게 흐르는지 설명하는 Technical Writing용 code-tour를 만들어줘. 8~10개 스톱으로 제한하고, 신규 문서 작성자에게 맞춰줘.”

대략적인 목표를 쓸모 있는 프롬프트로 바꾸기

좋은 code-tour 프롬프트는 독자, 경로, 제외 항목을 분명히 지정해야 합니다. 예:

• “청구 서비스의 신규 유지보수자를 위한 code-tour 온보딩 투어를 만들어줘.”
• “각 스톱은 실제 파일과 라인 범위에 묶어줘.”
• “요청 진입점에서 시작해서 설정 로드, 도메인 로직, 저장, 테스트 순으로 진행해줘.”
• “관련 없는 관리자 도구는 빼줘.”
• “이 파일이 왜 중요한지, 다음에 어디를 보면 되는지 설명하는 간결한 스텝 텍스트를 써줘.”

이렇게 해야 스킬이 요약보다 순서를 우선시합니다. 이런 프레이밍이 없으면 투어가 파일 목록만 나열한 평면적인 결과가 되기 쉽습니다.

실무 워크플로와 출력 검증

권장 워크플로는 다음과 같습니다:

1. 독자와 정확한 질문을 정합니다.
2. 저장소에서 진입점, 핵심 모듈, 지원 테스트를 찾습니다.
3. 시스템을 실제로 이해하는 방식에 맞춰 스톱 순서를 초안으로 만듭니다.
4. .tours/에 .tour 파일을 생성합니다.
5. 모든 파일 경로와 라인 앵커를 검증합니다.
6. 투어를 열어 약한 스톱을 다듬습니다.

중요한 품질 점검 기준:

• 각 스톱마다 존재 이유가 분명해야 합니다
• 순서가 단순한 파일 목록이 아니라 이야기 흐름을 만들어야 합니다
• 라인 앵커는 import 블록이 아니라 의미 있는 코드로 연결되어야 합니다
• 투어가 “다음에 무엇을 볼지” 또는 요약 스텝으로 끝나야 합니다

code-tour 스킬 FAQ

code-tour는 초보자에게도 좋은가요?

네, 범위가 좁다면 좋습니다. 초보자는 하나의 흐름, 하나의 서비스, 하나의 PR을 따라가는 투어에서 가장 큰 도움을 받습니다. 저장소 전체를 아우르는 code-tour는 오히려 부담이 큽니다. 신규 인원을 온보딩할 때는 핵심 실행 경로와 이를 보조하는 파일 1~2개를 짧게 묶어 달라고 요청하세요.

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

독자가 소스에 연결된 파일 단위 안내를 필요로 할 때 code-tour를 사용하세요. 개념적 개요, 제품 동작, 긴 형식의 설명이 필요하면 일반 문서가 더 적합합니다. 기술 문서 팀에는 code-tour가 세련된 문서를 대체하는 수단이 아니라, 소스를 따라가는 보조 자료로 가장 좋습니다.

code-tour 스킬의 주요 한계는 무엇인가요?

기능 구현, 코드 리팩터링, 광범위한 문서 세트 작성은 하지 않습니다. 또한 안정적인 파일 경로와 의미 있는 코드 구조에 의존합니다. 저장소가 혼란스럽거나, 생성물 위주이거나, 명명 규칙이 좋지 않더라도 투어는 만들 수 있지만, 그 결과는 더 많은 수동 검토가 필요합니다.

어떤 경우에는 적합하지 않나요?

채팅 한 번의 짧은 답변으로 충분하거나, 사용자가 .tour 아티팩트 대신 Markdown 문서를 원하거나, 요청 범위가 너무 넓어 순서를 잘 잡기 어려운 경우에는 code-tour를 생략하세요. 또한 명확한 대상 독자가 없을 때도 적합성이 떨어집니다. 투어는 누구를 위한 것인지 분명할수록 훨씬 좋아집니다.

code-tour 스킬 개선 방법

더 강한 저장소 읽기 가이드를 주세요

품질을 가장 크게 끌어올리는 방법은 생성 전에 탐색 경로를 먼저 주는 것입니다. 어디서 시작해야 하는지 알려주세요: 진입점, 라우터, 핸들러, 핵심 서비스, 테스트, 설정. 필요하다면 PR diff나 장애 메모도 포함하세요. 기준점이 더 좋을수록 투어도 좋아집니다.

흔한 code-tour 실패 모드를 막기

전형적인 약한 결과물은 다음과 같습니다:

• 스톱 수가 너무 많음
• 중요하지 않은 라인에 앵커가 잡힘
• 어떤 저장소에도 붙일 수 있는 일반론적 설명
• 명확한 대상 독자 부재
• 스텝 사이의 서사적 전환이 없음

이런 문제는 스톱 예산을 정하고, 독자를 명시하고, 각 스톱마다 “이게 왜 중요한지”와 “다음에 무엇을 볼지”를 요청하면 줄일 수 있습니다.

대상 독자와 의도를 넣어 프롬프트를 개선하기

Technical Writing용 code-tour라면 용어, 경계 정의, 문서화할 만한 개념을 요청하세요. PR 리뷰라면 변경 파일 순서와 리스크가 큰 지점을 요청하세요. 온보딩이라면 아키텍처 우선 순서와 마지막에 보는 테스트 구성을 요청하세요. 같은 저장소라도 프롬프트가 다르면 투어의 품질은 크게 달라집니다.

첫 초안 이후에는 꼭 반복 개선하기

첫 결과물을 최종본이 아니라 지도처럼 다루세요. .tour를 열고 중복되는 스톱을 제거하고, 라인 범위를 더 좁히고, 끝부분에 요약 스톱 하나를 추가하세요. 투어가 파일 목록처럼 느껴진다면 범위를 더 좁혀 다시 생성하세요. 가장 좋은 code-tour 결과는 넓은 첫 시도보다, 한 번의 집중된 수정에서 나옵니다.