VS Code에서 컨텍스트 엔지니어링 워크플로 설정

이 가이드에서는 사용자 지정 지침, 사용자 지정 에이전트 및 프롬프트 파일을 사용하여 VS Code에서 컨텍스트 엔지니어링 워크플로를 설정하는 방법을 보여줍니다.

컨텍스트 엔지니어링은 AI 에이전트에게 대상 프로젝트 정보를 제공하여 생성된 코드의 품질과 정확성을 향상시키는 체계적인 접근 방식입니다. 사용자 지정 지침, 구현 계획 및 코딩 지침을 통해 필수 프로젝트 컨텍스트를 큐레이션함으로써 AI가 더 나은 결정을 내리고 정확성을 개선하며 상호 작용 전반에 걸쳐 지속적인 지식을 유지하도록 할 수 있습니다.

컨텍스트 엔지니어링 워크플로

VS Code의 컨텍스트 엔지니어링에 대한 높은 수준의 워크플로는 다음 단계로 구성됩니다.

1. 프로젝트 전체 컨텍스트 큐레이션: 사용자 지정 지침을 사용하여 관련 문서(예: 아키텍처, 디자인, 기여자 지침)를 모든 에이전트 상호 작용의 컨텍스트로 포함합니다.
2. 구현 계획 생성: 사용자 지정 에이전트와 프롬프트를 사용하여 계획 페르소나를 만들어 자세한 기능 구현 계획을 생성합니다.
3. 구현 코드 생성: 사용자 지정 지침을 사용하여 구현 계획을 기반으로 코드를 생성하고 코딩 지침을 준수하도록 합니다.

단계별로 진행하면서 채팅에서 후속 프롬프트를 사용하여 출력을 반복하고 개선할 수 있습니다.

다음 다이어그램은 VS Code의 컨텍스트 엔지니어링 워크플로를 보여줍니다.

1단계: 프로젝트 전체 컨텍스트 큐레이션

AI 에이전트를 프로젝트의 특정 사항에 기반하기 위해 제품 비전, 아키텍처 및 기타 관련 문서와 같은 핵심 프로젝트 정보를 수집하고 사용자 지정 지침을 통해 채팅 컨텍스트로 추가합니다. 사용자 지정 지침을 사용하면 에이전트가 이 컨텍스트에 일관되게 액세스하고 각 채팅 상호 작용에 대해 다시 학습할 필요가 없도록 할 수 있습니다.

이 점이 도움이 되는 이유: 에이전트는 코드베이스에서 이 정보를 찾을 수 있지만 주석에 묻혀 있거나 여러 파일에 분산되어 있을 수 있습니다. 가장 중요한 정보에 대한 간결한 요약을 제공함으로써 에이전트가 의사 결정을 위해 중요한 컨텍스트를 항상 사용할 수 있도록 돕습니다.

1. 저장소의 Markdown 파일에 관련 프로젝트 문서를 설명하고, 예를 들어 PRODUCT.md, ARCHITECTURE.md 및 CONTRIBUTING.md 파일을 만듭니다.

   팁

   기존 코드베이스가 있는 경우 AI를 사용하여 이러한 프로젝트 문서 파일을 생성할 수 있습니다. 정확성과 완전성을 보장하기 위해 생성된 문서 파일을 검토하고 개선해야 합니다.

   • 프로젝트의 전체 아키텍처를 설명하는 ARCHITECTURE.md(최대 2페이지) 파일을 생성합니다.
   • 프로젝트의 제품 기능을 설명하는 PRODUCT.md(최대 2페이지) 파일을 생성합니다.
   • 프로젝트에 기여하는 개발자 지침 및 모범 사례를 설명하는 CONTRIBUTING.md(최대 1페이지) 파일을 생성합니다.

2. 저장소의 루트에 .github/copilot-instructions.md 지침 파일을 만듭니다.

   이 파일의 지침은 AI 에이전트의 컨텍스트로 모든 채팅 상호 작용에 자동으로 포함됩니다.

3. 프로젝트 컨텍스트 및 지침을 포함하여 에이전트에 대한 높은 수준의 개요를 제공합니다. Markdown 링크를 사용하여 관련 지원 문서 파일을 참조합니다.

   다음 예제 .github/copilot-instructions.md 파일은 시작점을 제공합니다.

   # [Project Name] Guidelines
   
   * [Product Vision and Goals](../PRODUCT.md): Understand the high-level vision and objectives of the product to ensure alignment with business goals.
   * [System Architecture and Design Principles](../ARCHITECTURE.md): Overall system architecture, design patterns, and design principles that guide the development process.
   * [Contributing Guidelines](../CONTRIBUTING.md): Overview of the project's contributing guidelines and collaboration practices.
   
   Suggest to update these documents if you find any incomplete or conflicting information during your work.
   

2단계: 구현 계획 생성

프로젝트별 컨텍스트가 마련되면 AI를 사용하여 새 기능 또는 버그 수정을 위한 구현 계획 생성을 프롬프트할 수 있습니다. 구현 계획을 생성하는 것은 완료되고 정확한지 확인하기 위해 여러 차례의 개선이 필요할 수 있는 반복적인 프로세스입니다.

계획을 위한 사용자 지정 에이전트를 사용하면 계획별 지침 및 도구(예: 읽기 전용 액세스 권한)를 가진 전용 페르소나를 만들 수 있습니다. 또한 프로젝트 및 팀을 위한 브레인스토밍, 조사 및 협업에 대한 특정 워크플로를 캡처할 수 있습니다.

1. 구현 계획 문서의 구조와 섹션을 정의하는 계획 문서 템플릿 plan-template.md를 만듭니다.

   템플릿을 사용하면 에이전트가 필요한 모든 정보를 수집하고 일관된 형식으로 표시하도록 할 수 있습니다. 또한 계획에서 생성되는 코드 품질을 향상시키는 데 도움이 됩니다.

   다음 plan-template.md 파일은 구현 계획 템플릿에 대한 샘플 구조를 제공합니다.

   ---
   title: [Short descriptive title of the feature]
   version: [optional version number]
   date_created: [YYYY-MM-DD]
   last_updated: [YYYY-MM-DD]
   ---
   # Implementation Plan: <feature>
   [Brief description of the requirements and goals of the feature]
   
   ## Architecture and design
   Describe the high-level architecture and design considerations.
   
   ## Tasks
   Break down the implementation into smaller, manageable tasks using a Markdown checklist format.
   
   ## Open questions
   Outline 1-3 open questions or uncertainties that need to be clarified.
   

2. 계획 에이전트 .github/agents/plan.agent.md를 만듭니다.

   계획 에이전트는 계획 페르소나를 정의하고 에이전트가 구현 작업을 수행하지 않고 계획 생성에 집중하도록 지시합니다. 계획이 완료된 후 구현 에이전트로 전환하기 위한 핸드오프를 지정할 수 있습니다.

   사용자 지정 에이전트를 만들려면 명령 팔레트에서 **채팅: 새 사용자 지정 에이전트** 명령을 실행합니다.

   컨텍스트에 대한 GitHub 이슈에 액세스하려면 GitHub MCP 서버를 설치했는지 확인하십시오.

   추론 및 심층 이해에 최적화된 언어 모델을 사용하도록 model 메타데이터 속성을 구성하는 것이 좋습니다.

   다음 plan.agent.md 파일은 계획 사용자 지정 에이전트 및 TDD 구현 에이전트로의 핸드오프를 위한 시작점을 제공합니다.

   ---
   description: 'Architect and planner to create detailed implementation plans.'
   tools: ['fetch', 'githubRepo', 'problems', 'usages', 'search', 'todos', 'runSubagent', 'github/github-mcp-server/get_issue', 'github/github-mcp-server/get_issue_comments', 'github/github-mcp-server/list_issues']
   handoffs:
   - label: Start Implementation
       agent: tdd
       prompt: Now implement the plan outlined above using TDD principles.
       send: true
   ---
   # Planning Agent
   
   You are an architect focused on creating detailed and comprehensive implementation plans for new features and bug fixes. Your goal is to break down complex requirements into clear, actionable tasks that can be easily understood and executed by developers.
   
   ## Workflow
   
   1. Analyze and understand: Gather context from the codebase and any provided documentation to fully understand the requirements and constraints. Run #tool:runSubagent tool, instructing the agent to work autonomously without pausing for user feedback.
   2. Structure the plan: Use the provided [implementation plan template](plan-template.md) to structure the plan.
   3. Pause for review: Based on user feedback or questions, iterate and refine the plan as needed.
   

3. 이제 채팅 보기에서 **계획** 사용자 지정 에이전트를 선택하고 새 기능 구현 작업을 입력할 수 있습니다. 제공된 템플릿을 기반으로 구현 계획이 포함된 응답을 생성합니다.

   예를 들어, 새 기능에 대한 구현 계획을 생성하려면 다음 프롬프트를 입력합니다. 등록, 로그인, 로그아웃 및 암호 재설정 기능을 포함하여 이메일 및 암호로 사용자 인증 추가.

   GitHub 이슈를 참조하여 특정 컨텍스트를 제공할 수도 있습니다. 이슈 #43의 기능 구현. 이 경우 에이전트는 이슈 설명 및 댓글을 가져와 요구 사항을 파악합니다.

4. 선택적으로 .github/prompts/plan.prompt.md 프롬프트 파일을 만들어 계획 에이전트를 호출하고 에이전트가 제공된 기능 요청에서 구현 계획을 생성하도록 지시합니다.

   다음 plan-qna.prompt.md 파일은 동일한 워크플로를 사용하지만 명확화 단계를 추가하여 계획 프롬프트에 대한 다양한 시작점을 제공합니다.

   ---
   agent: plan
   description: Create a detailed implementation plan.
   ---
   Briefly analyze my feature request, then ask me 3 questions to clarify the requirements. Only then start the planning workflow.
   

5. 채팅 보기에서 /plan-qna 슬래시 명령을 입력하여 명확화 계획 프롬프트를 호출하고 구현하려는 기능에 대한 세부 정보를 프롬프트에 제공합니다.

   예를 들어 다음 프롬프트를 입력합니다. /plan-qna 고객 정보 표시 및 편집을 위한 고객 세부 정보 페이지 추가

   에이전트는 구현 계획을 생성하기 전에 요구 사항을 더 잘 이해하기 위해 명확화 질문을 하여 오해를 줄입니다.

3단계: 구현 코드 생성

구현 계획을 생성하고 개선한 후에는 AI를 사용하여 구현 계획에서 코드를 생성하여 기능을 구현할 수 있습니다.

1. 작은 작업의 경우 에이전트에게 구현 계획을 기반으로 코드를 생성하도록 프롬프트하여 기능을 직접 구현할 수 있습니다.

   더 크거나 복잡한 기능의 경우 **에이전트**로 전환하고 구현 계획을 파일(예: <my-feature>-plan.md)로 저장하거나 언급된 GitHub 이슈에 주석으로 추가하도록 프롬프트할 수 있습니다. 그런 다음 새 채팅을 열고 프롬프트에서 구현 계획 파일을 참조하여 채팅 컨텍스트를 재설정할 수 있습니다.

2. 이제 이전 단계에서 만든 구현 계획을 기반으로 기능을 구현하도록 에이전트에 지시할 수 있습니다.

   예를 들어, implement #<my-plan>.md와 같이 구현 계획 파일을 참조하는 채팅 프롬프트를 입력합니다.

   팁

   에이전트는 다단계 작업을 실행하고 계획 및 프로젝트 컨텍스트를 기반으로 목표를 가장 잘 달성하는 방법을 파악하도록 최적화되어 있습니다. 계획 파일을 제공하거나 프롬프트에서 참조하기만 하면 됩니다.

3. 더 사용자 지정된 워크플로의 경우 계획을 기반으로 코드를 구현하는 데 특화된 사용자 지정 에이전트 .github/agents/implement.agent.md를 만듭니다.

   다음 tdd.agent.md 파일은 테스트 주도 구현 사용자 지정 에이전트를 위한 시작점을 제공합니다.

   ---
   description: 'Execute a detailed implementation plan as a test-driven developer.'
   ---
   # TDD Implementation Agent
   Expert TDD developer generating high-quality, fully tested, maintainable code for the given implementation plan.
   
   ## Test-driven development
   1. Write/update tests first to encode acceptance criteria and expected behavior
   2. Implement minimal code to satisfy test requirements
   3. Run targeted tests immediately after each change
   4. Run full test suite to catch regressions before moving to next task
   5. Refactor while keeping all tests green
   
   ## Core principles
   * Incremental Progress: Small, safe steps keeping system working
   * Test-Driven: Tests guide and validate behavior
   * Quality Focus: Follow existing patterns and conventions
   
   ## Success criteria
   * All planned tasks completed
   * Acceptance criteria satisfied for each task
   * Tests passing (unit, integration, full suite)
   

   팁

   작은 언어 모델은 명시적인 지침을 따라 코드를 생성하는 데 뛰어나므로, implement 에이전트는 model 속성을 언어 모델로 설정하는 것이 좋습니다.

모범 사례 및 일반적인 패턴

이러한 모범 사례를 따르면 지속 가능하고 효과적인 컨텍스트 엔지니어링 워크플로를 구축하는 데 도움이 됩니다.

컨텍스트 관리 원칙

작게 시작하여 반복: 최소한의 프로젝트 컨텍스트로 시작하고 AI 동작을 관찰하여 점진적으로 세부 정보를 추가합니다. 초점을 희석시킬 수 있는 컨텍스트 과부하를 피합니다.

컨텍스트 최신 상태 유지: 코드베이스가 발전함에 따라 에이전트를 사용하여 프로젝트 문서를 정기적으로 감사하고 업데이트합니다. 오래된 컨텍스트는 오래되거나 부정확한 제안으로 이어집니다.

점진적 컨텍스트 구축 사용: AI에 포괄적인 정보를 한 번에 부담시키기보다 높은 수준의 개념으로 시작하여 점진적으로 세부 정보를 추가합니다.

컨텍스트 격리 유지: 컨텍스트 혼합 및 혼란을 방지하기 위해 별도의 채팅 세션에서 다른 유형의 작업(계획, 코딩, 테스트, 디버깅)을 유지합니다.

문서 전략

살아있는 문서 만들기: 사용자 지정 지침, 사용자 지정 에이전트 및 템플릿을 진화하는 리소스로 취급합니다. AI의 실수나 단점을 관찰한 내용을 바탕으로 이를 개선합니다.

의사 결정 컨텍스트에 집중: 모든 기술적 세부 정보보다는 AI가 더 나은 아키텍처 및 구현 결정을 내리는 데 도움이 되는 정보에 우선 순위를 둡니다.

일관된 패턴 사용: AI가 일관된 코드를 생성하도록 코딩 규칙, 명명 패턴 및 아키텍처 결정을 설정하고 문서화합니다.

외부 지식 참조: AI가 코드를 생성할 때 고려해야 하는 관련 외부 문서, API 또는 표준에 연결합니다.

워크플로 최적화

에이전트 간 핸드오프: 핸드오프를 사용하여 계획, 구현 및 검토 에이전트 간에 안내된 전환을 만들고 엔드투엔드 개발 워크플로를 구현합니다.

피드백 루프 구현: AI가 컨텍스트를 올바르게 이해하고 있는지 지속적으로 확인합니다. 명확화 질문을 하고 오해가 발생하면 조기에 수정하십시오.

점진적 복잡성 사용: 기능을 점진적으로 구축하고 각 단계를 복잡성을 추가하기 전에 확인합니다. 이렇게 하면 오류가 누적되는 것을 방지하고 작동하는 코드를 유지할 수 있습니다.

관심사 분리: 초점과 관련된 컨텍스트를 유지하기 위해 다른 활동(계획 대 구현 대 검토)에 대해 다른 에이전트를 사용합니다.

컨텍스트 버전 관리: Git을 사용하여 컨텍스트 엔지니어링 설정의 변경 사항을 추적하여 문제가 있는 변경 사항을 되돌리고 무엇이 가장 잘 작동하는지 이해할 수 있도록 합니다.

피해야 할 안티 패턴

컨텍스트 덤핑: 의사 결정에 직접적으로 도움이 되지 않는 과도하고 초점이 맞지 않는 정보를 제공하지 마십시오.

일관성 없는 지침: 모든 문서가 선택한 아키텍처 패턴 및 코딩 표준과 일치하는지 확인합니다.

검증 무시: AI가 컨텍스트를 올바르게 이해한다고 가정하지 마십시오. 복잡한 구현을 진행하기 전에 항상 이해도를 테스트하십시오.

일률적 접근: 다른 팀원이나 프로젝트 단계마다 다른 컨텍스트 구성이 필요할 수 있습니다. 접근 방식에 유연하게 대처하십시오.

성공 측정

성공적인 컨텍스트 엔지니어링 설정은 다음과 같은 결과를 가져와야 합니다.

• 백앤드 감소: AI 응답 수정 또는 재지시 필요성 감소
• 일관된 코드 품질: 생성된 코드가 기존 패턴 및 규칙을 따름
• 더 빠른 구현: 컨텍스트 및 요구 사항 설명에 소요되는 시간 감소
• 더 나은 아키텍처 결정: AI가 프로젝트 목표 및 제약 조건과 일치하는 솔루션 제안

컨텍스트 엔지니어링 확장

팀용: 버전 관리를 통해 컨텍스트 엔지니어링 설정을 공유하고 공유 컨텍스트를 유지하기 위한 팀 규칙을 수립합니다.

대규모 프로젝트용: 지침 파일을 사용하여 프로젝트 전체, 모듈별 및 기능별 컨텍스트 계층을 가진 컨텍스트 계층을 만듭니다.

장기 프로젝트용: 문서를 최신 상태로 유지하고 오래된 정보를 제거하기 위해 정기적인 컨텍스트 검토 주기를 수립합니다.

여러 프로젝트용: 다른 코드베이스 및 도메인에서 채택할 수 있는 재사용 가능한 템플릿 및 패턴을 만듭니다.

이러한 관행을 따르고 접근 방식을 지속적으로 개선하면 AI 지원 개발을 향상시키면서 코드 품질과 프로젝트 일관성을 유지하는 컨텍스트 엔지니어링 워크플로를 개발할 수 있습니다.

관련 리소스

VS Code에서 AI 사용자 지정에 대해 자세히 알아보기

• 지침 파일
• 사용자 지정 에이전트
• 프롬프트 파일