GitHub Copilot 워크스페이스 멀티파일 컨텍스트 활용법: #file 참조와 @workspace로 대규모 리팩토링 자동화
GitHub Copilot 멀티파일 컨텍스트란?
GitHub Copilot Chat은 단일 파일이 아닌 프로젝트 전체를 이해할 수 있습니다. #file 참조로 특정 파일을 명시적으로 지정하거나, @workspace 명령으로 워크스페이스 전체를 탐색 대상으로 삼아 파일 간 의존성을 파악하고 일관된 리팩토링을 수행할 수 있습니다. 이 가이드에서는 실전 워크플로우를 단계별로 안내합니다.
Step 1: 환경 설정 및 사전 준비
1-1. 확장 설치
VS Code에서 GitHub Copilot과 GitHub Copilot Chat 확장을 설치합니다.
# VS Code 명령줄에서 설치
code —install-extension GitHub.copilot
code —install-extension GitHub.copilot-chat
1-2. 구독 확인
GitHub Copilot Individual, Business, 또는 Enterprise 구독이 활성화되어 있어야 합니다. GitHub 계정 설정 > Copilot 탭에서 상태를 확인하세요.
1-3. 설정 최적화
VS Code의 settings.json에서 다음 옵션을 확인합니다.
{
“github.copilot.chat.localeOverride”: “ko”,
“github.copilot.chat.useProjectContext”: true,
“github.copilot.enable”: {
”*”: true,
“markdown”: true,
“plaintext”: false
}
}
Step 2: #file 참조로 특정 파일 컨텍스트 지정하기
#file 태그를 사용하면 Copilot Chat에 분석할 파일을 명시적으로 전달할 수 있습니다. 이 방식은 관련 파일이 명확할 때 가장 효과적입니다.
기본 사용법
Copilot Chat 패널을 열고(Ctrl+Shift+I) 다음과 같이 입력합니다.
#file:src/services/userService.ts #file:src/models/user.ts
이 두 파일의 User 인터페이스를 통합하고,
userService에서 사용하는 타입을 일관되게 수정해줘.
다중 파일 참조 예시
리팩토링 대상 파일이 여러 개일 경우 한번에 참조할 수 있습니다.
#file:src/api/routes/auth.ts #file:src/middleware/auth.ts #file:src/utils/jwt.ts
현재 JWT 인증 로직이 세 파일에 분산되어 있어.
auth.ts 미들웨어로 통합하고 routes에서는 미들웨어만 호출하도록 리팩토링해줘.
### #file 참조 실전 팁
- 채팅 입력창에서 #을 입력하면 파일 자동완성이 나타납니다.- 최대 약 10개 파일까지 동시에 참조할 수 있으며, 토큰 한도에 따라 달라집니다.- 파일 경로는 워크스페이스 루트 기준 상대 경로를 사용합니다.
## Step 3: @workspace 명령으로 프로젝트 전체 탐색
@workspace는 프로젝트의 인덱싱된 전체 구조를 Copilot에 전달합니다. 영향 범위를 모를 때나 프로젝트 전반에 걸친 변경이 필요할 때 사용합니다.
기본 사용법
@workspace 이 프로젝트에서 deprecated된 lodash의 _.pluck 사용을
모두 찾아서 _.map으로 교체하는 방법을 알려줘.
구조 파악 후 리팩토링
@workspace 현재 프로젝트의 API 엔드포인트 구조를 분석하고,
REST 컨벤션에 맞지 않는 라우트를 목록으로 정리해줘.Copilot은 프로젝트 내 파일을 자동으로 탐색하여 관련 코드를 찾고 수정안을 제시합니다.
Step 4: 대규모 리팩토링 자동화 워크플로우
아래는 실제 프로젝트에서 멀티파일 컨텍스트를 활용해 리팩토링을 수행하는 전체 워크플로우입니다.
4-1. 영향 범위 분석
@workspace UserDTO 클래스를 사용하는 모든 파일을 찾고,
각 파일에서 어떤 필드에 접근하는지 정리해줘.
4-2. 변경 계획 수립
#file:src/dto/UserDTO.ts
UserDTO에서 email 필드를 contactEmail로 이름을 변경하려고 해.
@workspace 이 변경이 영향을 미치는 파일 목록과 수정 계획을 작성해줘.4-3. 파일별 수정 적용
#file:src/dto/UserDTO.ts #file:src/services/userService.ts #file:src/controllers/userController.ts
위 세 파일에서 email → contactEmail 리네이밍을 적용해줘.
import 구문과 테스트 파일도 함께 수정해줘.4-4. 테스트 검증
@workspace contactEmail로 이름이 변경된 후
깨질 수 있는 테스트 파일을 찾아서 수정안을 제시해줘.Step 5: Copilot Edits(멀티파일 편집 모드) 활용
Copilot Edits 기능을 사용하면 여러 파일을 동시에 직접 수정할 수 있습니다.
- Ctrl+Shift+I로 Copilot Chat을 열고 상단의 **Edits** 모드를 선택합니다.- **Add Files** 버튼으로 수정 대상 파일을 추가합니다.- 리팩토링 지시를 입력하면 각 파일에 diff 형태로 변경안이 표시됩니다.- **Accept** 또는 **Discard**로 파일별로 변경을 제어합니다.# Edits 모드 프롬프트 예시
모든 API 호출 함수에 에러 핸들링 try-catch 블록을 추가하고,
커스텀 AppError 클래스를 사용하도록 변경해줘.
## Pro Tips: 파워 유저를 위한 고급 활용법
| 팁 | 설명 |
|---|---|
#selection 활용 | 에디터에서 코드를 선택한 뒤 #selection으로 참조하면 선택 영역만 컨텍스트로 전달됩니다. |
#terminalSelection | 터미널 출력을 선택 후 참조하여 에러 로그 기반 디버깅에 활용합니다. |
| 슬래시 명령 조합 | /fix, /explain, /tests 등 슬래시 명령과 #file을 조합해 정밀한 작업을 수행합니다. |
| 컨텍스트 우선순위 | #file이 @workspace보다 정확도가 높으므로 핵심 파일은 명시적으로 지정하세요. |
| .github/copilot-instructions.md | 프로젝트 루트에 이 파일을 두면 Copilot에 프로젝트별 코딩 컨벤션을 전달할 수 있습니다. |
| Commit Message 생성 | 변경 후 Source Control 패널에서 Copilot 아이콘을 클릭하면 자동으로 커밋 메시지를 생성합니다. |
| 증상 | 원인 | 해결 방법 |
|---|---|---|
@workspace 응답이 느리거나 불완전 | 워크스페이스 인덱싱 미완료 | VS Code 하단 상태바에서 인덱싱 진행률을 확인하고 완료될 때까지 대기합니다. 대규모 프로젝트는 .gitignore에 불필요한 폴더(node_modules 등)를 추가하세요. |
#file 참조 시 파일을 찾지 못함 | 경로 오류 또는 파일이 열려있지 않음 | 워크스페이스 루트 기준 상대 경로를 사용하고, # 입력 후 자동완성 목록에서 선택합니다. |
| 응답이 토큰 한도 초과로 잘림 | 너무 많은 파일을 참조 | 참조 파일 수를 줄이거나, 핵심 파일만 #file로 지정하고 나머지는 @workspace에 맡기세요. |
| Copilot Chat이 한국어로 응답하지 않음 | 로케일 설정 누락 | settings.json에 "github.copilot.chat.localeOverride": "ko"를 추가합니다. |
| Edits 모드에서 파일이 추가되지 않음 | 지원하지 않는 파일 형식 | 바이너리 파일은 지원하지 않습니다. 텍스트 기반 소스 파일만 추가하세요. |
Q1: #file과 @workspace를 동시에 사용할 수 있나요?
네, 동시에 사용할 수 있습니다. 핵심 파일은 #file로 명시하고 추가 탐색이 필요한 부분은 @workspace에 맡기는 것이 가장 효과적인 패턴입니다. 예를 들어 #file:src/config.ts @workspace 이 설정 파일을 참조하는 모든 서비스를 찾아줘처럼 사용합니다. #file로 지정한 파일이 더 높은 우선순위로 분석되므로 정확도가 향상됩니다.
Q2: 멀티파일 리팩토링 시 Git과 어떻게 연계하면 좋을까요?
대규모 리팩토링 전에 반드시 새 브랜치를 생성하세요. git checkout -b refactor/rename-user-fields로 작업 브랜치를 만들고, Copilot Edits로 변경을 적용한 뒤 파일별로 diff를 검토합니다. 변경이 확인되면 git add -p로 의미 단위별 커밋을 나누어 PR 리뷰를 수월하게 만드세요. Copilot의 커밋 메시지 자동 생성 기능도 함께 활용하면 효율적입니다.
Q3: @workspace 인덱싱 성능을 개선하려면 어떻게 해야 하나요?
.gitignore 파일에 node_modules, dist, build, .next 같은 빌드 산출물 폴더를 반드시 포함시키세요. 또한 VS Code 설정에서 files.exclude를 활용해 불필요한 파일을 워크스페이스 탐색 대상에서 제외하면 인덱싱 속도와 응답 품질이 크게 향상됩니다. 매우 큰 모노레포의 경우 Multi-root Workspace를 구성하여 관련 폴더만 포함시키는 것을 권장합니다.