VS Code: 나만의 AI 에이전트 구축하기(2) - Prompt file

AI와 협업하며 매번 같은 지시를 반복하는 것은 비효율적이다. 특히 프로젝트가 커질수록 특정 스타일이나 규칙을 유지하는 일이 어려워지는데, 이를 해결하기 위해 단순한 질문 단계를 넘어 프롬프트를 '자산화'하는 전략이 필요하다. Visual Studio Code(이하 VS Code)의 `Prompt file`은 바로 이런 고민을 조금이나마 덜어 줄 수 있는 기능이다.

 

---

 

반복되는 명령을 규격화하는 Prompt file

`Prompt file`은 코드 생성, 리뷰, 프로젝트 구조 설계와 같이 자주 발생하는 개발 작업을 마크다운 문서로 미리 정의해 둔 일종의 `업무 가이드`다. 채팅창에서 즉시 실행할 수 있는 독립적인 명령 파일로, 이를 통해 팀이나 개인의 개발 워크플로우를 표준화된 라이브러리 형태로 구축할 수 있다.

예를 들어, 웹 프로젝트를 처음 구성할 때 수행하는 스캐폴딩(Scaffolding) 작업이나 깃(git) 저장소로부터 릴리스 노트를 생성하는 작업을 Prompt file로 구성할 수 있다.

 

Prompt file 을 한마디로 정리하면 재사용 가능한 지침 파일이다.

많은 이들이 사용하는 이전에 살펴본 Custom Instructions이 모든 대화에 기본적으로 깔리는 AI의 `배경 지식`이라면, Prompt file은 필요한 순간에만 소환하여 특정 임무를 수행하게 만드는 `정밀 타격 지침서`다. 특정 작업에 최적화된 세부 가이드를 담고 있어 상황에 따라 훨씬 유연하고 정확한 결과물을 만들어낸다. Custom Instructions 에 대해 알아보려면 이전 포스트를 참고하자.

 

VS Code: 나만의 AI 에이전트 구축하기(1) - Custom Instructions

 

---

 

Prompt File 구조 살펴보기

Prompt file은 기본적으로 마크다운 형식을 따르며, 크게 헤더(Header)와 본문(Body) 두 가지 영역으로 나뉜다. 파일 확장자는 반드시 `.prompt.md`를 사용해야 시스템이 이를 올바르게 인식한다.

Header (YAML Frontmatter) 구조

파일 최상단에 `- - -`로 구분하여 작성하는 선택적 영역이다. 이곳에서 프롬프트의 이름, 설명, 사용할 모델 및 도구 등을 정의한다.

필드명	설명
name	채팅창에서 `/` 입력 후 호출할 때 사용하는 이름이다. 지정하지 않으면 파일명이 기본값이 된다.
description	프롬프트에 대한 짧은 설명으로, 호출 리스트에서 용도를 확인할 때 도움을 준다.
agent	프롬프트를 실행할 에이전트를 지정한다 (ask, edit, agent 등).
model	실행 시 사용할 언어 모델을 특정한다. 지정하지 않으면 현재 설정된 모델을 사용한다.
tools	프롬프트에서 사용할 수 있는 도구 목록을 정의한다. MCP 서버 도구도 포함 가능하다.

Body 구조

헤더 아래에 위치하며 AI에게 전달할 실제 지침이 담긴다. 일반적인 텍스트 지시사항 외에도 워크스페이스의 다른 파일을 참조하거나 동적인 변수를 주입하여 상황에 맞는 응답을 유도할 수 있다.

본문 영역에서는 `${variableName}` 문법을 사용하여 현재 작업 중인 코드의 맥락을 AI에게 즉시 전달할 수 있다.

컨텍스트 변수

• 워크스페이스 변수 - `${workspaceFolder}`을 통해 현재 프로젝트의 경로 정보를 제공한다.
• 선택 영역 변수 - `${selection}` 를 사용하여 사용자가 현재 에디터에서 드래그한 코드 블록을 프롬프트에 포함한다.
• 파일 정보 변수 - `${file}` 등을 통해 현재 열려 있는 파일의 이름이나 경로를 참조한다.
• 입력 변수 - `${input:variableName}`을 사용하면 프롬프트 호출 시 사용자에게 추가적인 값을 직접 입력받아 처리할 수 있다.

외부 참조 및 도구 연결

• 파일 링크 - 마크다운의 링크 문법([설명](../path/to/file.md))을 사용하여 워크스페이스 내의 다른 가이드라인 파일을 참조하도록 지시할 수 있다.
• 에이전트 도구 - `#tool:` 문법을 사용하여 프롬프트가 실행될 때 특정 도구(예: githubRepo)를 활용하도록 명시한다.

작성 예시

아래는 현재 선택한 코드를 분석하여 테스트 코드를 짜주는 `test-gen.prompt.md` 파일의 예시다.

---
name: test-gen
description: Generates unit tests for the selected code.
agent: agent
---

You are a software testing expert. 
Analyze the provided code and write Jest-based test suites, 
ensuring they include comprehensive boundary value analysis.

Code to analyze:
${selection}

 

---

 

Prompt file 생성 방법

프롬프트 파일은 `.prompt.md` 확장자를 사용하며, VS Code가 이를 자동으로 인식하게 하려면 정해진 규칙을 따라야 한다. 파일 생성은 Chat View 메뉴를 사용하는 방법 또는 커맨드 팔레트에서 생성하는 방법 2가지 있다.

워크스페이스 루트에 `.github/prompts` 경로로 직접 파일을 생성해도 된다.

Chat View - 프롬프트 파일 메뉴

• Chat View 화면에서 :fa-gear: 아이콘을 클릭하여 `프롬프트 파일`을 선택하거나 커맨드 팔레트(Ctrl + Shift + P 또는 Cmd + Shift + P)를 열어 `Chat: New Prompt File` 명령어를 사용한다.
• `+ 새 프롬프트 파일 (Chat: New Prompt File)` 을 선택한다.
• 프롬프트 파일을 생성할 위치를 선택한다. (워크스페이스 또는 사용자 데이터 폴더)
• 파일 이름을 입력한다. (예시 : test-gen.prompt.md)

커맨드 팔레트 메뉴를 이용한 프롬프트 파일 생성 과정

`워크스페이스 폴더` : `.github/prompts` 경로에 파일이 저장되며 현재 워크스페이스에만 사용가능하다. :fa-regular fa-gear: chat.promptFilesLocations 설정에서 폴더를 추가하거나 수정할 수 있다.
`사용자 데이터 폴더` : 현재 사용자 프로필 폴더에 저장하게 된다. 프롬프트 파일을 동기화하여 동일 프로필을 사용하는 복수의 디바이스에서 공유하여 사용할 수 있다.

 

---

 

Prompt file 사용 방법

작성한 프롬프트 파일을 사용하는 방법은 매우 직관적이다. 별도의 복사-붙여넣기 과정 없이 채팅창에서 바로 호출할 수 있다.

1. VS Code에서 채팅 뷰를 연다. (단축키 Ctrl + Shift + i 또는 Cmd + Shift + i)
2. 입력창에 `/` 기호를 입력한다. 그러면 현재 워크스페이스에 등록된 프롬프트 파일 목록이 나타난다.
3. 원하는 프롬프트의 name을 선택하거나 직접 입력한다.
4. 엔터를 누르면 파일에 정의된 지침에 따라 AI가 작업을 시작한다.

아래는 나이에 따른 할인율을 계산해 주는 간단한 자바스크립트 코드이다. 위에서 생성한 프롬프트`(test-gen.prompt.md)`를 사용하면 해당 코드에 맞는 테스트 코드를 자동으로 생성해준다.

프롬프트 파일을 이용하여 테스트 코드를 자동으로 생성하는 과정

Sample.js

/**
 * 나이에 따른 할인율을 계산한다.
 * 0-5세: 100% (무료)
 * 6-18세: 20%
 * 19-64세: 0% (일반)
 * 65세 이상: 30%
 */
function calculateDiscount(age) {
  if (typeof age !== 'number') {
    throw new Error("Age must be a number");
  }

  if (age < 0 || age > 120) {
    throw new Error("Invalid age range");
  }

  if (age <= 5) {
    return 1.0;
  } else if (age <= 18) {
    return 0.2;
  } else if (age < 65) {
    return 0.0;
  } else {
    return 0.3;
  }
}

module.exports = calculateDiscount;

Sample.test.js (test-gen.prompt 로 부터 생성된 테스트 파일)

const calculateDiscount = require('../scripts/sample');

describe('calculateDiscount', () => {
  // 타입 체크
  it('should throw if age is not a number', () => {
    expect(() => calculateDiscount('10')).toThrow('Age must be a number');
    expect(() => calculateDiscount(null)).toThrow('Age must be a number');
    expect(() => calculateDiscount(undefined)).toThrow('Age must be a number');
    expect(() => calculateDiscount({})).toThrow('Age must be a number');
  });

  // 경계값: 음수, 0, 5, 6, 18, 19, 64, 65, 120, 121
  it('should throw if age is less than 0', () => {
    expect(() => calculateDiscount(-1)).toThrow('Invalid age range');
  });

  it('should throw if age is greater than 120', () => {
    expect(() => calculateDiscount(121)).toThrow('Invalid age range');
  });

  it('should return 1.0 for ages 0 to 5 (inclusive)', () => {
    expect(calculateDiscount(0)).toBe(1.0);
    expect(calculateDiscount(5)).toBe(1.0);
  });

  it('should return 0.2 for ages 6 to 18 (inclusive)', () => {
    expect(calculateDiscount(6)).toBe(0.2);
    expect(calculateDiscount(18)).toBe(0.2);
  });

  it('should return 0.0 for ages 19 to 64 (inclusive)', () => {
    expect(calculateDiscount(19)).toBe(0.0);
    expect(calculateDiscount(64)).toBe(0.0);
  });

  it('should return 0.3 for ages 65 to 120 (inclusive)', () => {
    expect(calculateDiscount(65)).toBe(0.3);
    expect(calculateDiscount(120)).toBe(0.3);
  });

  // 경계값 인접 테스트
  it('should return correct discounts for boundary-adjacent values', () => {
    expect(calculateDiscount(5)).toBe(1.0);   // 5세
    expect(calculateDiscount(6)).toBe(0.2);   // 6세
    expect(calculateDiscount(18)).toBe(0.2);  // 18세
    expect(calculateDiscount(19)).toBe(0.0);  // 19세
    expect(calculateDiscount(64)).toBe(0.0);  // 64세
    expect(calculateDiscount(65)).toBe(0.3);  // 65세
  });
});

 

 

 

---

 

마무리

프롬프트 파일은 AI를 단순한 질답 대상에서 벗어나 정교하게 설계된 시스템의 일부로 만들어준다. 반복되는 요구사항을 파일로 관리하고 필요할 때마다 꺼내 쓰는 방식은 개발 환경의 일관성을 높이는 가장 실질적인 방법이다. 이제 본인만의 전문적인 프롬프트 라이브러리를 하나씩 구축하여 더 정교한 개발 환경을 완성해 보길 권장한다.