Code Tour
코드베이스 워크스루를 위한 CodeTour .tour 파일을 생성합니다. 투어는 실제 파일과 라인 범위로 직접 연결됩니다. 투어 파일은 .tours/ 디렉토리에 저장되며, CodeTour 형식을 따릅니다. 임시 Markdown 노트가 아닌 CodeTour 형식이어야 합니다.
좋은 투어는 특정 독자를 위한 내러티브입니다:
- 그들이 보고 있는 것
- 왜 중요한지
- 다음에 따라야 할 경로
.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/<persona>-<focus>.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
각 설명은 다음을 답해야 합니다:
- Situation (상황): 독자가 보고 있는 것
- Mechanism (메커니즘): 어떻게 작동하는지
- Implication (의미): 이 페르소나에게 왜 중요한지
- Gotcha (주의점): 똑똑한 독자가 놓칠 수 있는 것
설명을 간결하고 구체적으로 유지하며 실제 코드에 기반을 두세요.
내러티브 구조
작업이 명확히 다른 것을 요구하지 않는 한 이 호를 사용하세요:
- 방향 설정
- 모듈 맵
- 핵심 실행 경로
- 엣지 케이스 또는 주의점
- 마무리 / 다음 행동
투어는 인벤토리가 아닌 경로처럼 느껴져야 합니다.
예시
{
"$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