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

개발 생산성을 극대화하기 위한 AI 도구의 활용이 중요해지는 가운데, Visual Studio Code (이하 VS Code)의 Copilot은 많은 개발자에게 필수적인 도구가 되었다. 이 강력한 도구를 단순한 코드 보조 도구로만 사용하는 것은 그 잠재력을 절반도 활용하지 못하는 것과 같다.

이 글에서는 VS Code의 Custom Instructions 기능을 활용하여 나만의 AI 에이전트를 구축하고, AI와 더 효율적으로 협업하는 방법을 자세히 소개한다.

 

---

 

AI 에이전트, 지침(Instructions)이 중요한 이유

AI 에이전트를 효과적으로 사용하려면 명확하고 구체적인 지침을 제공하는 것이 가장 중요하다. 마치 신입 개발자에게 작업을 지시하듯, AI에게도 명확한 `instructions(지침)`이 있어야 원하는 결과물을 얻을 수 있다. 지침의 질에 따라 AI가 생성하는 코드나 문서의 품질은 극명하게 달라진다.

예를 들어, "함수를 만들어줘"라고 요청하는 것과 "파이썬으로 사용자의 입력을 받아 유효성을 검사하고, 유효한 경우 'Hello, [사용자 이름]!'을 출력하는 greet_user 함수를 만들어줘. docstring을 포함하고 타입 힌트를 반드시 사용해야 해"라고 요청하는 것은 전혀 다른 결과물을 낳는다. 후자의 경우, AI는 훨씬 더 의도에 부합하는 완성도 높은 코드를 제공한다.

 

이처럼 AI에게 주입하는 지침, 즉 프롬프트는 AI의 능력을 100% 끌어내기 위한 핵심 요소다.

 

---

Custom Instructions 은 크게 아래 2가지 타입의 마크다운 기반의 지침파일을 지원한다.

`.github/copilot-instructions.md` 파일

• 워크스페이스 루트 디렉토리에 있는 `.github` 폴더에 생성
• 워크스페이스의 모든 채팅 요청에 대해 자동으로 적용된다.
• 워크스페이스에 저장되는 가장 기본적인 지침 파일로 보면 된다.
• 보통 프로젝트의 일반적인 코딩 규칙이나 가이드라인을 정의할 때 유용하다.

 

`.instruction.md` 파일

• 특정 작업이나 파일 유형에만 적용되는 규칙을 정의할 때 사용한다.
• 파일 헤더에 `applyTo` 프런트매터를 사용하여 적용 대상을 한정할 수 있다. 예를 들어, `applyTo: "**/*. ts,**/*. tsx"`는 TypeScript 파일에만 해당 명령어를 적용하라는 의미다.

위 내용을 좀더 자세히 살펴보자.

---

 

.github/copilot-instructions.md 파일 생성 및 사용

위에서 잠깐 언급했듯이 `.github/copilot-instructions.md` 파일은 워크스페이스의 루트에 위치하여 모든 채팅 요청에 대해 자동으로 첨부되어 전송된다. 보통 해당 프로젝트의 전반적인 구조를 요약하여 기술하거나 기본적인 코딩 가이드라인을 정의하는 데 사용된다.

모든 채팅 요청에 자동으로 해당 파일을 사용하기 위해서는 우선 :fa-regular fa-gear: github.copilot.chat.codeGeneration.useInstructionFiles설정을 활성화 해야한다.

 

파일 생성 방법 1 - 수동

• 워크스페이스의 루트에 `.github` 폴더를 생성한다.
• 해당 폴더에 `copilot-instructions.md` 파일을 생성한다. (주의 :  .github 폴더 바로 아래 동일 이름으로 생성)
• 마크다운 포맷으로 간단명료하게 지침 내용을 작성한다.
• 한글로 작성해도 문제없지만 영문으로 작성하는 걸 추천한다.

모든 요청에 첨부되어 전송되기 때문에 영문을 사용하는 것이 토큰 절약에도 도움이 된다.

 

다음은 `.github/copilot-instructions.md` 파일로 사용된 Project General Coding Guideline 지침 파일 예시이다.

# Project General Coding Standards
 
## General Principles
- **Readability is key**: Write code that is easy for others (and your future self) to understand.
- **Consistency is crucial**: Follow these standards to ensure a uniform codebase. Use automated tools to enforce rules where possible.
- **Maintainability matters**: Write code that is simple to update and debug over time.

## Code Style & Formatting
- Use **Prettier** and **ESLint** to automate formatting and linting.
- Use **single quotes** for strings.
- Keep lines concise, ideally under **100 characters**.
 
## Naming Conventions
- Use descriptive, meaningful names for all variables, functions, and components.
- Components, classes, and types: **PascalCase**.
- Variables, functions, and methods: **camelCase**.
- Constants: **ALL_CAPS**.
 
## Readability & Maintainability
- Use **JSDoc** to document complex functions, their parameters, and return values.
- Add comments only when the code's purpose is not immediately obvious.
- Avoid duplicate code; use functions or components for repeated logic.

## Error Handling
- Proactively handle potential errors using `try/catch` blocks.
- Provide clear and useful error messages.
- Implement React **Error Boundaries** to gracefully handle component-level errors.

 

파일 생성 방법 2 - 자동

만약 프로젝트가 이미 구성되어 있을 경우 수동으로 생성하지 않고 Chat View 또는 커맨드 팔레트에서 자동으로 생성할 수도 있다. 이 기능을 활용하여 초기 설정 시간을 줄일 수 있다.

해당 방법을 사용할 경우 기존 `.github/copilot-instructions.md`이 존재한다면 적절하게 병합(merge)하여 작성해 준다.

 

Chat View 메뉴 사용

• Chat View 화면에서 :fa-gear: 아이콘을 클릭하여 `지침 생성`을 선택한다.
• 프로젝트 구조 및 코드를 분석하여 `.github/copilot-instructions.md` 파일을 자동으로 생성해 준다.

커맨드 팔레트 사용

• VS Code 커맨드 팔레트(Ctrl + Shift + P 또는 Cmd + Shift + P)를 연다.
• `채팅: 지침 구성...(Chat: Configure Instructions...`)을 검색하고 실행한다.
• `:fa-arrow-rotate-right: 지침 생성` 을 선택한다.
• 워크스페이스를 분석하여 `.github/copilot-instructions.md` 파일을 자동으로 생성해 준다.

 

만약 chat 요청에 자동으로 지침파일이 첨부되지 않는다면 파일 이름 및 경로를 다시 확인해보자. `copilot-instructions.md` 파일은 파일 위치 및 이름이 미리 정해져 있기 때문에 다른 경로에 파일이 있거나 파일명이 다를경우 자동으로 첨부되지 않는다. 파일경로는 반드시 `.github`  폴더 바로 아래에 위치해야하고  파일명은 `copilot-instructions.md` 로 설정해야 한다.

---

 

.instruction.md 파일 생성 및 사용

`.github/copilot-instructions.md` 파일이 코딩 스타일과 같은 워크스페이스 전반에 걸쳐 범용적으로 사용되는 부분에 대한 지침(instructions)이라면 `.instructions.md` 파일은 :fa-brands fa-react:React 프로젝트 구조정의`react-structure.instructions.md`나 :fa-brands fa-python:Python 프로젝트의 코드 컨벤션`python-code-conventions.instructions.md`과 같은 특정 작업이나 파일 유형에 적용할 수 내용에 대한 지침(instructions)이다.

 

파일 생성하기

파일 생성은 Chat View 메뉴를 사용하는 방법 또는 커맨드 팔레트에서 생성하는 방법 2가지 있다.

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

`.github/instructions` : 기본값으로 현재 워크스페이스 폴더에 저장하게 된다. :fa-regular fa-gear: chat.instructionsFilesLocations설정에서 폴더를 추가하거나 수정할 수 있다.
`사용자 데이터 폴더` : 현재 사용자 프로필 폴더에 저장하게 된다. 지침 파일을 동기화하여 동일 프로필을 사용하는 복수의 디바이스에서 공유하여 사용할 수 있다. 

 

파일 내용 작성하기

명령어 파일은 마크다운 형식으로 작성하며, 헤더에 applyTo 속성을 추가하여 적용 범위를 지정할 수 있다.

---
description: Python Coding Guidelines
applyTo: "**/*.py"
---

# Python Coding Standards
 
## Style Guide (PEP 8)
- Limit code line length to a maximum of **79 characters**.
- Use **4 spaces** for indentation.
- Use **two blank lines** between function and class definitions, and **one blank line** between methods within a class.
- Place a single space around binary operators.

## Type Hints
- Explicitly use **type hints** for all function parameters and return values.
- Use the typing module for complex types (e.g., List, Dict, Optional).
- Use type hints for variables to improve readability.

## Naming Conventions
- Variables, functions, and modules: **snake_case** (e.g., calculate_total_price).
- Classes: **PascalCase** (e.g., UserManager).
- Constants: **ALL_CAPS** (e.g., MAX_RETRIES).
- Private members start with a single underscore (_).

## Code Structure and Readability
- Organize **import** statements at the top of the file by group.
  1. Standard library
  2. Third-party libraries
  3. Local project modules
- Write clear and concise **docstrings** for all functions, classes, and methods.
- Comments should focus on the 'why' behind the code.

## Exception Handling and Testing
- Use try...except...finally constructs for exception handling.
- Specify concrete exceptions instead of using a broad except clause.
- Write **unit tests** for all critical logic.

 

위 예시처럼 `applyTo`를 사용하면 해당 파일은 파이썬 파일에만 적용된다. 만약 모든 파일에 적용하려면 `applyTo: "**"`로 설정하면 된다.

`applyTo: "**/*.py"`로 설정하면 해당 지침 파일은 파이썬 파일의 생성 및 수정에만 적용되지만, 챗 요청에 자동 첨부되는 것은 아니다. 챗 요청에 첨부되려면 `applyTo: "**"`처럼 전체에 적용하거나 직접 컨텍스트 추가를 해야한다. 즉, applyTo는 적용 범위만 지정할 뿐, 챗봇이 파일을 자동으로 첨부하는 기능과는 별개이다. 

chat 요청에 자동으로 지침파일들이 첨부된 모습

---

 

효율적인 Custom Instructions 작성 팁

• 명확하고 간결하게 작성: 각 지침을 하나의 간단한 문장으로 유지하는 것이 좋다. 여러 정보를 제공해야 할 경우, 여러 문장을 사용한다.
• 파일 분리: 특정 언어나 작업에 대한 지침은 별도의 `.instructions.md` 파일로 분리하여 관리하면 깔끔하고 집중도를 높일 수 있다.  예시 : `python-structure.instructions.md`, `project-doc-guide.instructions.md`
• 버전 관리: 프로젝트별 지침 파일은 Git과 같은 버전 관리 시스템에 포함시켜 팀원들과 공유하는 것이 좋다.

 

---

 

마무리

VS Code의 Custom Instructions는 단순한 AI 보조 도구를 넘어, 개발자 개개인의 작업 방식에 최적화된 나만의 AI 에이전트를 구축할 수 있는 강력한 기능이다. AI의 잠재력을 최대한 끌어내기 위해서는, 단순히 질문을 던지는 것을 넘어 AI에게 명확하고 체계적인 지침을 제공하는 방법에 대해 고민해야 한다.

이러한 도구들을 적극적으로 활용하여 더 스마트하고 생산적인 개발 환경을 만들어보길 바란다.