| name | code-tour |
| description | 실제 파일과 라인 앵커를 가진 CodeTour `.tour` 파일을 만듭니다. 온보딩 투어, 아키텍처 워크스루, PR 투어, RCA 투어, 구조화된 "이게 어떻게 동작하는지 설명해줘" 요청에 사용합니다. |
| origin | ECC |
코드 투어
실제 파일과 라인 범위로 바로 열리는 코드베이스 워크스루용 CodeTour .tour 파일을 만듭니다. 투어는 .tours/에 저장되며, 임시 Markdown 메모가 아니라 CodeTour 형식용 산출물입니다.
좋은 투어는 특정 독자를 위한 내러티브입니다.
- 지금 무엇을 보고 있는지
- 왜 중요한지
- 다음에 어떤 경로를 따라가야 하는지
이 스킬은 .tour JSON 파일만 만듭니다. 소스 코드는 수정하지 않습니다.
사용 시점
다음 경우 이 스킬을 사용합니다.
- 사용자가 코드 투어, 온보딩 투어, 아키텍처 워크스루, PR 투어를 요청할 때
- 사용자가
"explain how X works"라고 하며 재사용 가능한 가이드형 산출물을 원할 때
- 새 엔지니어나 리뷰어를 위한 빠른 적응 경로가 필요할 때
- 단순 요약보다 안내형 시퀀스가 더 적합한 작업일 때
예시:
- 새 유지보수자 온보딩
- 특정 서비스나 패키지의 아키텍처 투어
- 변경 파일 중심의 PR 리뷰 워크스루
- 실패 경로를 보여주는 RCA 투어
- 신뢰 경계와 핵심 점검 지점을 다루는 보안 리뷰 투어
사용하지 말아야 할 때
| code-tour 대신 | 사용 |
|---|
| 채팅으로 한 번 설명하면 충분할 때 | 직접 답변 |
.tour 산출물이 아니라 문서형 설명이 필요할 때 | documentation-lookup 또는 저장소 문서 편집 |
| 구현이나 리팩터링 작업일 때 | 구현 작업 수행 |
| 투어 산출물 없는 광범위 코드베이스 온보딩일 때 | codebase-onboarding |
워크플로
1. 탐색
무언가를 쓰기 전에 저장소를 먼저 탐색합니다.
- README와 패키지/앱 엔트리포인트
- 폴더 구조
- 관련 설정 파일
- PR 중심 투어라면 변경 파일
코드의 형태를 이해하기 전에 step을 쓰기 시작하지 않습니다.
2. 독자 추정
요청에서 페르소나와 깊이를 판단합니다.
| 요청 형태 | 페르소나 | 권장 깊이 |
|---|
"onboarding", "new joiner" | new-joiner | 9-13 steps |
"quick tour", "vibe check" | vibecoder | 5-8 steps |
"architecture" | architect | 14-18 steps |
"tour this PR" | pr-reviewer | 7-11 steps |
"why did this break" | rca-investigator | 7-11 steps |
"security review" | security-reviewer | 7-11 steps |
"explain how this feature works" | feature-explainer | 7-11 steps |
"debug this path" | bug-fixer | 7-11 steps |
3. 앵커 읽기 및 검증
모든 파일 경로와 라인 앵커는 실제여야 합니다.
- 파일이 실제로 존재하는지 확인
- 라인 번호가 유효 범위인지 확인
- selection을 쓰면 해당 블록이 정확한지 검증
- 파일이 자주 바뀌는 경우 pattern 기반 앵커를 우선
라인 번호를 추측하지 않습니다.
4. .tour 작성
다음 경로에 작성합니다.
.tours/<persona>-<focus>.tour
경로는 결정론적이고 읽기 쉬워야 합니다.
5. 검증
마무리 전에 다음을 확인합니다.
- 모든 참조 경로가 존재하는가
- 모든 라인 또는 selection이 유효한가
- 첫 번째 step이 실제 파일 또는 디렉터리에 앵커링되어 있는가
- 투어가 단순 파일 목록이 아니라 일관된 이야기를 전달하는가
Step 유형
Content
주로 마지막 step처럼, 꼭 필요할 때만 제한적으로 사용합니다.
{ "title": "Next Steps", "description": "You can now trace the request path end to end." }
첫 번째 step을 content-only로 만들지 않습니다.
Directory
모듈 방향을 잡아줄 때 사용합니다.
{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }
File + line
기본 step 유형입니다.
{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }
Selection
파일 전체보다 특정 코드 블록이 중요할 때 사용합니다.
{
"file": "src/core/pipeline.ts",
"selection": {
"start": { "line": 15, "character": 0 },
"end": { "line": 34, "character": 0 }
},
"title": "Request Pipeline",
"description": "This block wires validation, auth, and downstream execution."
}
Pattern
정확한 라인이 자주 흔들릴 때 사용합니다.
{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }
URI
PR, 이슈, 문서가 유용할 때 사용합니다.
{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" }
작성 규칙: SMIG
각 설명은 다음에 답해야 합니다.
- Situation: 독자가 지금 무엇을 보고 있는가
- Mechanism: 어떻게 동작하는가
- Implication: 이 페르소나에게 왜 중요한가
- Gotcha: 똑똑한 독자도 놓치기 쉬운 점은 무엇인가
설명은 짧고, 구체적이며, 실제 코드에 근거해야 합니다.
내러티브 구조
특별한 이유가 없다면 다음 흐름을 사용합니다.
- 방향 잡기
- 모듈 맵
- 핵심 실행 경로
- 엣지 케이스 또는 주의점
- 마무리 / 다음 행동
투어는 목록이 아니라 경로처럼 느껴져야 합니다.
예시
{
"$schema": "https://aka.ms/codetour-schema",
"title": "API Service Tour",
"description": "Walkthrough of the request path for the payments service.",
"ref": "main",
"steps": [
{
"directory": "src",
"title": "Source Root",
"description": "All runtime code for the service starts here."
},
{
"file": "src/server.ts",
"line": 12,
"title": "Entry Point",
"description": "The server boots here and wires middleware before any route is reached."
},
{
"file":
안티패턴
| 안티패턴 | 수정 방향 |
|---|
| 평면적인 파일 나열 | step 간 의존성과 흐름이 있는 이야기로 바꾸기 |
| 일반적이고 모호한 설명 | 실제 코드 경로나 패턴을 구체적으로 적기 |
| 추측한 앵커 | 모든 파일과 라인을 먼저 검증 |
| 짧은 투어인데 step 수가 너무 많음 | 과감하게 줄이기 |
| 첫 step이 content-only | 실제 파일이나 디렉터리에 앵커링 |
| 페르소나 불일치 | 일반 엔지니어가 아니라 실제 독자를 기준으로 작성 |
모범 사례
- step 수는 저장소 크기와 페르소나 깊이에 맞춥니다.
- 방향 잡기에는 directory step, 핵심 설명에는 file step을 사용합니다.
- PR 투어라면 변경 파일부터 다룹니다.
- 모노레포에서는 전체를 돌기보다 관련 패키지에 범위를 좁힙니다.
- 마무리는 요약보다 "이제 무엇을 할 수 있는가"로 끝냅니다.
관련 스킬
codebase-onboardingcoding-standardscouncil- 공식 upstream 형식:
microsoft/codetour
