엔지니어링 조직이 AI 코딩 어시스턴트를 대규모로 도입할 때 흔히 겪는 협업 장애물 중 하나는 개발자 간의 프롬프트 작성 역량 격차입니다. 시니어 엔지니어가 명확한 제약 조건과 아키텍처 경계를 포함한 정교한 프롬프트를 작성하는 반면, 다른 팀원들은 "버그 수정해줘"나 "단위 테스트 작성해줘"와 같은 모호한 문장에 의존하기 쉽습니다. 이로 인해 테스트 프레임워크 혼용, 불일치하는 단언문(Assertion) 스타일, 불안정한 에러 핸들링 등 결과물 코드 품질이 파편화되며 팀의 엔지니어링 모범 사례가 누적되지 못합니다.
Sourcegraph Cody는 저장소 단위에서 이러한 문제를 근본적으로 해결하는 커스텀 커맨드(Custom Commands) 메커니즘을 제공합니다. 프로젝트 루트의 .vscode/cody.json 파일에 검증된 프롬프트 템플릿, 실행 모드 및 정밀한 컨텍스트 수집 범위를 정의함으로써, 프롬프트 엔지니어링을 버전 관리되는 공유 인프라("Prompts as Code")로 전환할 수 있습니다. 리포지토리를 클론한 모든 개발자는 동일한 슬래시 커맨드를 즉시 사용하여 일관된 품질의 코드 생성, 리팩터링 및 테스트 작성을 수행할 수 있습니다.
.vscode/cody.json 아키텍처 및 동작 원리
Cody는 사용자 개인 설정에 저장되는 전역 커맨드와 특정 리포지토리에 종속되는 워크스페이스(Workspace) 커맨드를 구분합니다. 프로젝트 루트의 .vscode/ 디렉터리 내에 cody.json을 배치하면, 커맨드가 해당 코드베이스의 기술 스택, 의존성 및 테스트 규칙에 강력하게 결합됩니다.
repository-root/
├── .vscode/
│ ├── cody.json <-- 팀 공유 워크스페이스 커스텀 커맨드
│ └── settings.json
├── src/
├── tests/
└── package.json
해당 파일이 Git에 커밋되면, 팀원이 VS Code에서 워크스페이스를 열 때 Cody 확장 프로그램이 이를 자동으로 감지하여 로드합니다. 개발자는 커맨드 팔레트 단축키(macOS: Option + C, Windows/Linux: Alt + C)를 사용하거나 Cody Chat 입력창에서 직접 슬래시 커맨드(예: /unit-test)를 입력하여 실행할 수 있습니다.
JSON 스키마 구조 분석
.vscode/cody.json 파일은 최상위 commands 객체를 기반으로 하며, 각 키는 호출 가능한 슬래시 커맨드 식별자가 됩니다.
{
"commands": {
"command-identifier": {
"prompt": "하위 대규모 언어 모델(LLM)에 전달되는 상세 지시 템플릿.",
"description": "Cody 커맨드 메뉴에 노출되는 간략한 기능 설명.",
"mode": "ask",
"context": {
"codebase": false,
"selection": true,
"currentDir": false,
"openTabs": false
}
}
}
}
핵심 속성 설명:
| 필드 | 타입 | 설명 |
|---|---|---|
prompt | String | AI 모델에 전달될 시스템 지시문 템플릿입니다. 역할 정의, 비즈니스 제약, 테스트 규격 및 출력 형식이 포함됩니다. |
description | String | Cody 커맨드 메뉴에 표시되는 설명문으로, 팀원이 커맨드의 용도를 직관적으로 파악하도록 돕습니다. |
mode | String | 결과물이 에디터와 상호작용하는 방식 및 전달 경로를 정의합니다 (ask, edit, insert). |
context | Object | 커맨드 실행 시 Cody가 프롬프트와 함께 모델에 주입할 소스 코드 컨텍스트의 범위를 제어합니다. |
실행 모드(mode): 결과물 반영 방식 제어
mode 속성은 LLM이 생성한 결과물이 에디터 작업 환경에 전달되는 방식을 결정합니다.
-
ask(대화형 검토 모드):- 결과물을 에디터 사이드바의 Cody Chat 패널에 출력합니다.
- 보안 취약점 감사, 아키텍처 유효성 검토, 복잡한 알고리즘 분석, PR 요약 작성 등 개발자가 변경 사항을 직접 확인하고 판단해야 하는 작업에 적합합니다.
-
edit(인라인 즉시 수정 모드):- 현재 에디터에서 선택된 코드 블록을 LLM이 생성한 코드로 직접 교체합니다.
- 엄격한 TypeScript 타입 지정, 중첩 삼항 연산자 제거, 순수 함수 기반의 불변성 리팩터링 등 확정적인 코드 수정 작업에 이상적입니다.
-
insert(지정 위치 삽입 모드):- 현재 커서 위치 또는 선택 영역 바로 위에 생성된 코드를 삽입합니다.
- 함수 상단에 표준 TSDoc/JSDoc 주석을 추가하거나 빈 테스트 파일에 테스트 스위트 보일러플레이트를 생성할 때 유용합니다.
컨텍스트 수집 범위 제어: 품질과 응답 속도의 균형
AI 코드 생성 시 컨텍스트가 부족하면 모델의 환각(Hallucination)이 발생하고, 무관한 파일이 과도하게 주입되면 토큰 낭비와 응답 지연이 심화됩니다. context 객체를 통해 수집 범위를 정밀하게 조정할 수 있습니다.
selection(boolean): 현재 에디터에서 하이라이트된 코드 블록을 전달합니다. 특정 함수 리팩터링이나 주석 작성과 같은 로컬 작업 시true로 설정하여 모델의 집중도를 유지합니다.codebase(boolean): Sourcegraph의 시맨틱 검색과 임베딩 인덱스를 활용하여 전체 저장소를 탐색합니다. 프로젝트 내 공통 헬퍼, 도메인 모델, 모의(Mock) 함수 등을 참조해야 하는 테스트 생성 작업에는 필수적이지만, 단순 로컬 수정 시에는 불필요한 대기 시간을 줄이기 위해false로 두는 것이 좋습니다.currentDir(boolean): 활성 파일과 동일한 디렉터리에 있는 인접 파일들을 컨텍스트에 포함합니다. 컴포넌트, 스타일 파일, 목 데이터가 동일 폴더에 공존하는 기능별 모듈 구조에서 효과적입니다.openTabs(boolean): 현재 에디터에 열려 있는 탭의 내용을 포함합니다. 다중 파일 연동 구현에는 유용하지만, 무관한 파일이 열려 있을 경우 노이즈가 주입될 수 있습니다.
엔지니어링 팀을 위한 실전 설정 레시피
다음은 TypeScript/React 기반 프로젝트를 위해 구성된 표준 .vscode/cody.json 예시입니다.
{
"commands": {
"unit-test": {
"description": "팀 Vitest 표준에 맞춰 Mock 및 경계 조건을 포함한 단위 테스트 생성",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": true,
"openTabs": false
},
"prompt": "당신은 시니어 테스트 자동화 엔지니어입니다. 선택된 코드에 대해 Vitest 및 @testing-library/react를 사용하는 포괄적인 테스트 스위트를 작성하세요.\n\n엄격 준수 규칙:\n1. 모든 테스트는 AAA(Arrange-Act-Assert) 패턴으로 구성할 것.\n2. 코드베이스에 기존 존재하는 테스트 fixture 및 mock 규칙을 준수할 것.\n3. 정상 흐름, 경계값, null/undefined 입력, 비동기 Promise reject 시나리오를 빠짐없이 커버할 것.\n4. 프로젝트에서 승인되지 않은 외부 mock 라이브러리를 사용하지 말고 Vitest 내장 vi.fn() 및 vi.spyOn()을 사용할 것.\n5. '// 여기에 구현'과 같은 생략 주석 없이 즉시 실행 가능한 완전한 코드를 작성할 것."
},
"refactor-clean": {
"description": "엄격한 TypeScript 규격과 불변성 원칙을 적용하여 선택 코드를 인라인 리팩터링",
"mode": "edit",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "선택된 코드 블록을 클린 코드 원칙과 엄격한 TypeScript 기준에 맞춰 리팩터링하세요:\n1. 기존 공개 API 시그니처, 매개변수 계약 및 런타임 동작을 완전히 유지할 것.\n2. 느슨한 'any' 타입을 명확한 구별된 유니온(Discriminated Union)이나 제네릭 제약 조건으로 변경할 것.\n3. 가변 상태 변경 패턴을 순수 함수와 불변 데이터 업데이트로 대체할 것.\n4. 깊게 중첩된 조건문이나 삼항 연산자를 조기 반환(Early Return) 구조로 정리할 것.\n5. 설명문이나 마크다운 서식 없이 오직 교체할 순수 코드만을 출력할 것."
},
"security-audit": {
"description": "선택된 코드의 OWASP Top 10 보안 취약점 및 민감 정보 노출 감사",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": false,
"openTabs": false
},
"prompt": "선택된 코드 세그먼트에 대해 엄격한 보안 및 규정 준수 코드 리뷰를 수행하세요.\n\n다음 위험 요소를 집중 점검할 것:\n1. 인젝션 취약점(SQL, NoSQL, 시스템 커맨드, 템플릿 인젝션, XSS).\n2. 인가 실패, 접근 제어 부재 및 권한 상승 위험.\n3. 안전하지 않은 직접 객체 참조(IDOR) 및 사용자 입력값 미검증.\n4. 소스 코드나 로그에 노출된 API 키, 비밀번호, 개인식별정보(PII).\n5. 내부 스택 트레이스를 외부에 유출할 수 있는 미처리 예외 처리 누락.\n\n출력 형식: [위험도: 상/중/하] | [취약점 유형] | [해당 코드 라인] | [수정 권고 및 Diff]."
},
"doc-api": {
"description": "함수 또는 인터페이스에 표준 TSDoc 문서 주석 블록 생성 및 삽입",
"mode": "insert",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "선택된 함수 또는 인터페이스에 대해 고품질 TSDoc 주석 블록을 작성하세요:\n1. 첫 줄에 간결한 한 줄 요약을 작성하고 이어 상세 동작 방식을 서술할 것.\n2. 모든 @param 태그에 정확한 타입과 의미를 기술할 것.\n3. @returns 태그에 반환 타입과 조건부 반환값을 명시할 것.\n4. 발생 가능한 모든 에러를 @throws 태그로 상세히 설명할 것.\n5. 표준 호출 방식을 보여주는 실용적인 @example 블록을 포함할 것.\n6. 코드 바로 위에 즉시 삽입할 수 있는 표준 JSDoc/TSDoc 형식으로 출력할 것."
}
}
}
거버넌스 및 워크플로 발전 전략
.vscode/cody.json의 도입 효과를 극대화하기 위해 엔지니어링 팀은 다음과 같은 프로세스를 정립해야 합니다.
1. 프롬프트를 프로덕션 코드로 관리 (Prompts as Code)
.vscode/cody.json은 팀의 공유 엔지니어링 인프라입니다. 프롬프트의 변경이나 신규 커맨드 추가는 일반 코드와 마찬가지로 Pull Request를 거쳐 동료 리뷰를 받아야 하며, CI 파이프라인에서 JSON 스키마 검증을 수행하여 문법 오류로 인한 에디터 로드 실패를 방지해야 합니다.
2. 전역 코드베이스 컨텍스트 비용 최적화
모든 커맨드에 "codebase": true를 무분별하게 설정하면 단순 로컬 리팩터링 작업에서도 네트워크 호출이 발생하여 응답 속도가 현저히 느려집니다. 크로스 파일 의존성 파악이 필수적인 커맨드에만 한정하고, 로컬 코드 변환은 "selection": true 위주로 구성하는 것이 바람직합니다.
3. Sourcegraph Prompt Library로의 확장
마이크로서비스 환경에서 수십 개의 리포지토리를 운영하는 조직의 경우, 각 저장소마다 개별 .vscode/cody.json을 유지하면 동기화 문제가 발생할 수 있습니다. Sourcegraph Enterprise 및 Cody v1.30 이상 버전에서는 웹 기반의 **Prompt Library(프롬프트 라이브러리)**를 제공합니다.
팀은 먼저 단일 리포지토리의 .vscode/cody.json에서 커맨드를 실험하고 검증한 후, 성숙한 프롬프트를 전사 Prompt Library로 승격시킬 수 있습니다. 이를 통해 태그 관리, 관리자 추천 프롬프트(Promoted Prompts), 동적 @selection 및 @file 멘션 기능을 활용하여 VS Code와 JetBrains 등 다양한 IDE 환경 전반에 표준 프롬프트를 손쉽게 확장할 수 있습니다.