코드 투어
CodeTour .tour 파일을 생성하여 코드베이스 워크스루를 만듭니다. 이 파일은 실제 파일과 라인 범위로 바로 열립니다. 투어는 .tours/ 디렉터리에 저장되며, CodeTour 형식을 따릅니다. 임시 Markdown 노트용이 아닙니다.
좋은 투어는 특정 독자를 위한 내러티브입니다:
- 지금 보고 있는 것
- 그것이 왜 중요한지
- 다음에 어떤 경로를 따라야 하는지
.tour JSON 파일만 생성하세요. 이 스킬의 일부로 소스 코드를 수정하지 마세요.
사용 시기
다음과 같은 경우 이 스킬을 사용합니다:
- 사용자가 코드 투어, 온보딩 투어, 아키텍처 워크스루 또는 PR 투어를 요청하는 경우
- 사용자가 "X가 어떻게 동작하는지 설명해줘"라고 말하면서 재사용 가능한 가이드 아티팩트를 원하는 경우
- 사용자가 신입 엔지니어나 리뷰어를 위한 온보딩 경로를 원하는 경우
- 작업이 단순 요약보다는 안내된 순서로 설명하는 것이 더 적합한 경우
예시:
- 새로운 관리자 온보딩
- 하나의 서비스나 패키지에 대한 아키텍처 투어
- 변경된 파일에 고정된 PR 리뷰 워크스루
- 실패 경로를 보여주는 RCA 투어
- 신뢰 경계와 주요 검사를 살펴보는 보안 검토 투어
사용하지 말아야 할 경우
| code-tour 대신 | 사용할 것 |
|---|---|
| 채팅에서 한 번 설명하는 것으로 충분하면 | 직접 답변 |
사용자가 .tour 아티팩트가 아닌 문서를 원하면 | documentation-lookup 또는 저장소 문서 편집 |
| 작업이 구현 또는 리팩토링이면 | 구현 작업 수행 |
| 투어 아티팩트 없이 광범위한 코드베이스 온보딩이면 | codebase-onboarding |
워크플로
1. 탐색
무언가를 작성하기 전에 저장소를 탐색합니다:
- README와 패키지/앱 진입점
- 폴더 구조
- 관련 설정 파일
- PR 관련 투어라면 변경된 파일
코드 구조를 이해하기 전에 단계를 작성하지 마세요.
2. 독자 추론
요청에서 페르소나와 깊이를 결정합니다.
| 요청 형태 | 페르소나 | 권장 깊이 |
|---|---|---|
| "온보딩", "신입" | new-joiner | 9-13단계 |
| "간단 투어", "전체적인 분위기" | vibecoder | 5-8단계 |
| "아키텍처" | architect | 14-18단계 |
| "이 PR 투어" | pr-reviewer | 7-11단계 |
| "왜 이게 깨졌나요" | rca-investigator | 7-11단계 |
| "보안 검토" | security-reviewer | 7-11단계 |
| "이 기능이 어떻게 작동하는지 설명" | feature-explainer | 7-11단계 |
| "이 경로 디버깅" | bug-fixer | 7-11단계 |
3. 앵커 읽기 및 확인
모든 파일 경로와 라인 앵커는 실제여야 합니다:
- 파일이 존재하는지 확인
- 라인 번호가 범위 내에 있는지 확인
- 선택 영역을 사용하는 경우 정확한 블록을 확인
- 파일이 변동성이 크면 패턴 기반 앵커 선호
절대 라인 번호를 추측하지 마세요.
4. .tour 작성
다음 위치에 작성:
.tours/<페르소나>-<초점>.tour
경로를 결정적이고 읽기 쉽게 유지합니다.
5. 검증
완료하기 전에:
- 참조된 모든 경로가 존재하는지 확인
- 모든 라인 또는 선택 영역이 유효한지 확인
- 첫 번째 단계가 실제 파일이나 디렉터리에 고정되어 있는지 확인
ref가 투어가 참조하는 모든 파일이 실제로 존재하는 브랜치나 커밋을 가리키는지 확인 (아래 참조)- 투어가 파일을 나열하는 것이 아니라 일관된 이야기를 전달하는지 확인
ref 필드
ref는 투어를 git 브랜치나 커밋에 연결합니다. 생각보다 중요합니다: ref가 독자가 체크아웃한 브랜치가 아닌 경우, CodeTour는 각 단계의 파일을 디스크에 있는 파일이 아닌 해당 리비전의 git에서 엽니다. 파일이 해당 리비전에 없으면 단계가 열리지 않습니다 — 파일이 바로 거기에 있음에도 "파일을 찾을 수 없어 편집기를 열 수 없습니다" 라는 메시지가 표시됩니다. 투어와 설명은 여전히 보이므로 실제 원인을 놓치기 쉽습니다.
투어 유형에 따라 ref를 선택:
| 투어 유형 | ref 설정값 |
|---|---|
| PR 투어 | PR 브랜치 — 절대 기본 브랜치로 설정하지 마세요 |
| 온보딩 / 아키텍처 | 독자가 사용할 브랜치 (보통 main), 또는 생략 |
| 확실하지 않음 | ref를 생략하면 CodeTour가 디스크에서 직접 파일을 읽습니다 |
PR의 경우가 일반적인 함정입니다: PR은 보통 새 파일을 추가하는데, 새 파일은 아직 기본 브랜치에 존재하지 않습니다. ref를 기본 브랜치(예: develop)로 설정하면 새 파일의 모든 단계가 열리지 않습니다.
완료하기 전에 각 단계의 파일이 선택한 ref에 실제로 존재하는지 확인하세요.
단계 유형
내용
드물게 사용하며, 보통 마무리 단계에만 사용:
{ "title": "다음 단계", "description": "이제 요청 경로를 처음부터 끝까지 추적할 수 있습니다." }
첫 번째 단계를 내용만으로 만들지 마세요.
디렉터리
독자를 모듈로 안내할 때 사용:
{ "directory": "src/services", "title": "서비스 계층", "description": "핵심 오케스트레이션 로직이 여기에 있습니다." }
파일 + 라인
기본 단계 유형입니다:
{ "file": "src/auth/middleware.ts", "line": 42, "title": "인증 게이트", "description": "보호된 모든 요청이 먼저 이곳을 통과합니다." }
선택 영역
전체 파일보다 특정 코드 블록이 더 중요할 때 사용:
{
"file": "src/core/pipeline.ts",
"selection": {
"start": { "line": 15, "character": 0 },
"end": { "line": 34, "character": 0 }
},
"title": "요청 파이프라인",
"description": "이 블록은 유효성 검사, 인증 및 하위 실행을 연결합니다."
}
패턴
정확한 라인이 변경될 가능성이 있을 때 사용:
{ "file": "src/app.ts", "pattern": "export default class App", "title": "애플리케이션 진입점" }
URI
PR, 이슈 또는 문서에 유용할 때 사용:
{ "uri": "https://github.com/org/repo/pull/456", "title": "PR" }
작성 규칙: SMIG
각 설명은 다음을 답해야 합니다:
- 상황: 독자가 보고 있는 것
- 메커니즘: 어떻게 작동하는지
- 함의: 이 페르소나에게 왜 중요한지
- 주의점: 똑똑한 독자가 놓칠 수 있는 것
설명을 간결하고 구체적으로 유지하며 실제 코드에 기반을 둡니다.
내러티브 구조
작업이 명확히 다른 것을 요구하지 않는 한 이 구조를 사용합니다:
- 오리엔테이션
- 모듈 맵
- 핵심 실행 경로
- 예외 사항 또는 주의점
- 마무리 / 다음 동작
투어는 목록이 아닌 경로처럼 느껴져야 합니다.
예시
{
"$schema": "https://aka.ms/codetour-schema",
"title": "API 서비스 투어",
"description": "결제 서비스의 요청 경로 워크스루입니다.",
"ref": "main",
"steps": [
{
"directory": "src",
"title": "소스 루트",
"description": "서비스의 모든 런타임 코드가 여기서 시작됩니다."
},
{
"file": "src/server.ts",
"line": 12,
"title": "진입점",
"description": "서버가 여기서 부팅되고, 모든 경로에 도달하기 전에 미들웨어를 연결합니다."
},
{
"file": "src/routes/payments.ts",
"line": 8,
"title": "결제 라우트",
"description": "모든 결제 요청은 서비스 로직에 도달하기 전에 이 라우터를 통해 들어옵니다."
},
{
"title": "다음 단계",
"description": "이제 주요 앵커를 바탕으로 모든 결제 요청을 처음부터 끝까지 추적할 수 있습니다."
}
]
}
안티 패턴
| 안티 패턴 | 수정 방법 |
|---|---|
| 평면 파일 나열 | 단계 간 의존성이 있는 스토리 전달 |
| 일반적인 설명 | 구체적인 코드 경로나 패턴 명시 |
| 추측한 앵커 | 모든 파일과 라인을 먼저 확인 |
| 간단한 투어에 너무 많은 단계 | 과감히 줄이기 |
| 첫 번째 단계가 내용만으로 구성 | 첫 번째 단계를 실제 파일이나 디렉터리에 고정 |
| 페르소나 불일치 | 일반 엔지니어가 아닌 실제 독자를 위해 작성 |
모범 사례
- 단계 수를 저장소 크기와 페르소나 깊이에 비례하게 유지
- 오리엔테이션에는 디렉터리 단계, 내용에는 파일 단계 사용
- PR 투어의 경우 변경된 파일을 먼저 다루기
- 모노레포의 경우 모든 것을 투어하지 말고 관련 패키지로 범위 제한
- 요약이 아닌 독자가 이제 무엇을 할 수 있는지로 마무리
관련 스킬
codebase-onboardingcoding-standardscouncil- 공식 업스트림 형식:
microsoft/codetour