code-tour

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: 똑똑한 독자도 놓치기 쉬운 점은 무엇인가

설명은 짧고, 구체적이며, 실제 코드에 근거해야 합니다.

내러티브 구조

특별한 이유가 없다면 다음 흐름을 사용합니다.

1. 방향 잡기
2. 모듈 맵
3. 핵심 실행 경로
4. 엣지 케이스 또는 주의점
5. 마무리 / 다음 행동

투어는 목록이 아니라 경로처럼 느껴져야 합니다.

예시

{
  "$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-onboarding
• coding-standards
• council
• 공식 upstream 형식: microsoft/codetour