GitHub Copilot을 현명하게 사용하는 컨텍스트 전략

IT/코딩툴

GitHub Copilot을 현명하게 사용하는 컨텍스트 전략

개발자 두더지 2026. 8. 2. 21:32

728x90

※일본의 한 블로그 글을 번역한 포스트입니다. 오역 및 의역, 직역이 있을 수 있으며 틀린 내용을 지적해주시면 감사하겠습니다.

이 글의 타켓층

GitHub Copilot Chat 및 Agent mode를 업무에서 사용하기 시작한 분
MCP나 Agent Skills를 도입하고 있거나 도입을 검토하고 있는 분
AGENTS.md이나 설계 문서의 두는 장소에 헤매고 있는 분
AI 개발의 속도, 품질, 비용을 관리하는 테크 리드
AI에 의한 자동화와 인간에 의한 리뷰의 경계를 설계하고 싶은 분

GitHub Copilot을 사용하기 시작하면, 아래의 내용들이 신경쓰이기 시작한다.

어떻게 질문하면 올바른 코드를 작성할 수 있을까?
어디까지 구체적으로 지시하면 좋을까?
프롬프트를 짧게하는 것이 좋을까?
여러 번 다시 실행하는 것은 질문을하는 방법이 나쁘기 때문일까?

물론, 질문의 방법은 중요하다. 그러나 Copilot Chat, Agent mode, MCP, Agent Skills, 커스텀 지시 등을 활용하면 활수록, 직면하는 과제는 조금씩 바뀐다. 즉, '어떻게 질문하는지'뿐만 아니라 무엇을 AI에 읽을 수 있는지 가 중요하다고 할 수 있다.

예를 들어 AI가 의도와 다른 구현을했다고 가정하자. 이 원인은 반드시 프롬프트가 잘못되었기 때문은 아니며, 다음과 같은 것이 원인이 될 수 있다.

필요한 설계 문서를 읽지 않았다.
관련없는 도구가 대량으로 제시되었다.
검색 결과나 명령 출력이 너무 길었다.
낡은 대화 이력을 주력으로 봤다.
중요한 제약이 거대한 지시 파일에 묻혀 있었다.
AI에 맡겨서는 안되는 판단까지 자동화하고 있었다

이러한 문제는 프롬프트의 말하기만으로는 해결할 수 없다. AI가 작업할 때 사용하는 전체 정보, 즉 컨텍스트 를 설계해야 한다. 이번 포스트에서 제일 전하고 싶은 것은 다음의 내용이다.

토큰을 줄이는 것이 목적이 아니다. AI가 좋은 판단을 하기 위한 정보를 적절한 타이밍과 입도로 전달하는 것이 목적이다.

단순히 토큰을 절약하는 것은 필요한 설계 정보와 리뷰까지 잃을 수 있다. 반대로, 만약을 위해서 모든 자료를 건네주면, 코스트 뿐만이 아니라 판단의 노이즈도 늘어나게 된다.

그래서 이 글에서는 GitHub Copilot에 건네는 정보를 다음과 같이 분해한다.

항상 지키는 고정 지시
특정 작업에서 사용하는 절차
필요할 때 읽는 디자인 시스템과 설계 지식
사용 가능한 도구 정의
도구 실행 결과
대화 이력
캐시 및 압축으로 재사용하는 정보
작업에 맞는 모델 선택

더욱이 MCP, Skills, AGENTS.md, DESIGN.md, CLI, 모델 선택을 어떻게 구분할지, 초보자도 알 수 있도록 정리하도록 하겠다.

1. 토큰은 질문문만으로 늘어나는 것이 아니다.

먼저 토큰과 컨텍스트의 기본 내용부터 정리핮. 생성 AI에 입력하는 문장은 작은 단위로 분할되어 처리된다. 이 단위는 토큰 입니다. 한국어의 경우 반드시 「1문자=1토큰」은 아니다. 영어 단어, 기호, 코드, JSON, 파일 경로 등도 모델 방법에 따라 여러 토큰으로 나뉜다. 그러나 실무에서 매번 "이 문자열은 몇 토큰인가"를 계산할 필요는 없다. 중요한 것은 질문문 이외에 많은 정보가 모델에 건네는 지는 것이다.

컨텍스트 창은 AI작업 책상

컨텍스트 창은 AI가 이번 처리에서 참조할 수 있는 정보의 범위이다. 초보자용으로는, AI의 작업 책상 이라고 생각하면 알기 쉽다. 작업 책상에는 사용자가 입력한 질문뿐만 아니라 다음과 같은 것이 있다.

시스템 측 지시
AGENTS.md등의 맞춤 지침
사용 가능한 도구의 이름, 설명, 입력 스키마
사용자 질문
AI의 과거 답변
가져온 소스 코드 및 설계서
도구 호출 인수
검색 결과, 로그, JSON 등의 도구 실행 결과
궁극적으로 생성되는 답변

GitHub Copilot의 컨텍스트는 질문문뿐만 아니라 지시, 도구, 실행 결과, 대화 이력의 합계로 소비된다. 여기서 주목하고 싶은 것은 툴의 실행 결과 이다. 툴 호출 자체는, 툴명과 짧은 인수만으로 끝날 수가 있다다. 그러나 그 결과로 다음과 같은 정보가 반환되면 단번에 컨텍스트를 사용한다.

Slack의 메시지 500건
GitHub Issue 200건
수만 줄의 빌드 로그
소스 코드의 모든 파일
데이터베이스 검색 결과 1000행
거대한 JSON 응답

질문문을 20문자 짧게 하는 것보다, 불필요한 검색 결과를 500건에서 20건으로 줄이는 것이, 훨씬 효과가 큰 경우가 있다. 즉, 토큰을 생각할 때는 "프롬프트를 짧게"하는 것만으로는 충분하지 않다.

AI가 항상 가진 정보와 작업 중에 추가되는 정보를 모두 살펴보십시오.

입력 토큰, 출력 토큰, 캐시 토큰의 차이

"토큰"이라는 단어는 여러 가지 의미로 사용된다. 혼동하기 쉽기 때문에 여기에서 개념을 나누어 두자.

컨텍스트 창	모델이 한 번에 참조할 수 있는 정보 범위
입력 토큰	모델에 전달된 지침, 질문, 기록, 도구 정의, 도구 결과 등
출력 토큰	모델이 생성한 설명, 코드, 요약 등
현금 토큰	이전 요청과 공통으로 재사용된 입력 부분
요금 · AI Credits	제품, 모델, 계약, 현금 단가 등을 기준으로 산출되는 이용량

여기서 중요한 것은 컨텍스트 양과 요금이 완전히 동일한 개념이 아니라는 것이다. 예를 들어 동일한 긴 고정 명령을 매번 모델에 전달해도 Prompt Caching이 효과가 있다면 일반 입력과는 다른 단가 또는 계산 방법이 될 수 있다.

한편, 캐시되었다고 해서 불필요한 정보가 AI의 판단에 미치는 영향까지 사라지는 것은 아니다. 「금액상 싸게 재이용할 수 있다」와 「AI가 읽을 가치가 있다」는 다른 판단이다.

MCP 통신이 발생하는 것으로는 LLM 토큰 사용이라고 한정할 수 없다

또 하나, 먼저 구별해 두고 싶은 것이 있다. MCP 통신 및 로컬 명령 실행 자체와 LLM 토큰 소비는 동일하지 않다. 예를 들어, MCP 클라이언트가 MCP 서버로 tools/list전송하여 도구 목록을 검색했다고 가정하자.

MCP클라이언트
    ↓ tools/list
MCP서버
    ↓ 툴 목록
MCP클라이언트

이것은 MCP의 RPC 통신이다. 취득한 툴 목록 중, 어느 정보를 모델에 건네줄지는, 클라이언트나 에이전트 런타임의 구현에 좌우된다. 모델이 건네받았을 경우는, 툴 이름, description, input schema등이 입력 문맥에 영향을 준다. 한편, 클라이언트 내부에 유지되는 것만으로 모델에 건네주지 않는 정보는, 반드시 LLM 입력 토큰이 되는 것은 아니다.

따라서 다음과 같이 생각하면 정리하기 쉽다.

통신이 발생했다
    ↓
클라이언트가 정보를 획득했다
    ↓
그 정보를 모델에게 건넨다
    ↓
모델의 입력 컨텍스트에 영향을 준다

"MCP로 접속하는 순간에 모든 정의와 리소스 본문이 매번 모델에게 건넨다"라고 설명하는 것은 정답이 아니라는 것이다. 그러나, AI툴을 선택함에 있어서 어떠한 형태로 이용 가능한 툴의 정보를 알고 있을 필요가 있다. 그러므로, 툴의 수와 shema의 크기는 컨텍스트 설계상 중요한 시점이다.

최적화 하기 전에 관찰한다

토큰을 줄이고 싶을때, 갑자기 지시 파일을 짧게 하는 것을 추천하지 않는다. 먼저 어디가 문제인지 관찰하자. GitHub Copilot CLI에서는 컨텍스트나 사용량을 확인하기 위해 커맨드가 제공되고 있다.

/context

다음의 커맨드로 현재 컨텍스트 윈도우의 사용 상황을 확인할 수 있다.

/usage

세션의 사용량과 모델 별 토큰 사용 등을 다음의 커맨드를 확인할 수 있다.

/compact

길어진 대화 이력을 요약하여, 컨텍스트를 압축한다. 커맨드의 대응 상황이나 표현 방법은 제품 갱신에 따라 바뀔 가능서이 있으므로 GitHub Copilot CLI의 컨텍스트 관리도 병행하여 확인하길 바란다.

관찰할 때의 포인트

동일한 작업을 다음 조건과 비교하면 원인을 발견하기 쉬워진다.

MCP 활성화/비활성화	도구 정의 추가로 고정 영역이 얼마나 바뀌는지
검색 결과 500건/20건	도구 결과가 컨텍스트에 미치는 영향
파일 전문 / 해당 범위	읽는 파일의 양의 영향
긴 대화/새 세션	대화 이력 축적의 영향
압축 전/ /compact후	이력 요약에 따른 변화
Auto/수동 모델 지정	모델 선택으로 품질, 속도, 이용량이 어떻게 바뀌는지

모델, 설정, 리포지토리, 질문을 나열해두고 비교하는 것이 중요하다. 복수의 조건을 한 번에 바꾸면, 어떤 것이 효과가 있었는지 알 수 없어진다.

2. AGENTS.md・Skills・DESIGN.md는 정보의 수명으로 구분한다.

AI로 필요한 정보를 정리할 때 모든 것을 하나의 거대한 지시 파일로 작성하고 싶을 경우가 있다. "몇 번이나 읽히면, 놓치는 부분이 없겠지"라는 생각으로 말이다. 그러나 그것을 인간의 일로 바꿔서 생각해보면, 매일 아침 모든 작업 순서도, 제품 설계도, 과거 회의록을 읽은 뒤 일을 하도록 시키는 것과 동일하다. 필요한 정보는 정보의 수명과 적용 범위로 나누자.

거의 모든 작업에서 지키는 정보
특정 작업만으로 필요한 정보
설계 변경 시에만 필요한 정보
대상 파일이나 디렉토리에 따라 변경되는 정보
이번 의뢰만으로 필요한 정보

AGETS.md는 "지식의 창고"가 아닌 입구

GitHub Copilot에서는 AGENTS.md를 에이전트용의 지시로서 이용할 수 있다. 이 파일명을 주의하도록 하자. 복수형이다. AGENT.md가 아니다.

AGENTS.md에 두는 것은 거의 모든 태스크에서 지켜야할 짧은 룰과 필요한 자료의 동선이다.

# Repository rules

- 답변과 코드 주석은 한국어로 작성한다.
- 기존 공개 API를 변경하기 전에 영향 범위를 열거한다.
- 작업 후에는 변경 대상에 대응하는 테스트를 실행한다.
- 무관한 파일은 변경하지 않는다.

# Architecture and design rules

- 공개 API를 변경하기 전에 `docs/adr/0002-api-versioning.md` を読む.
- UI 외관을 바꾸기 전에 `DESIGN.md ` 를 읽는다.
- DB 스키마를 변경할 때는 `docs/database/` 해당 ADR을 확인한다.
- UI만 변경해도 백엔드 설계 문서를 읽지 않는다.

포인트는 DESIGN.md의 내용을 모두 복사하지 않는 것이다. AGENTS.md는 다음과 같은 역할을 가진 루터로 한다.

이번 일은 무엇인가
    ↓
항상 지켜야할 룰은 무엇인가
    ↓
추가로 읽어야할 것이 있는가

이 구성이라면 일반적인 작은 변경에서는 짧은 공통 규칙만 사용하고, 설계 변경 시에만 상세한 자료를 추가할 수 있다.

Agent Skills는 필요할 때에 열어보는 작업 순서도

Agent Skills는 특정의 작업에 필요한 순서, 지식, 스크립트, 참조자료등을 정리하는 구조이다. 초심자의 경우 전문작업의 메뉴얼이라고 이미지하면 알기 쉬울 것이다.

예를 들어, 다음과 같은 작업은 Skill로 분류할 수 있다.

기술 기사 만들기
보안 검토 수행
출시 노트 만들기
데이터베이스 마이그레이션 확인
일러스트레이션 생성
Azure에 배포

Skill에서는 처음부터 모든 본문을 항시 읽는 것이아닌, 먼저 name이나 description등의 정보를 바탕으로 태스트에 적용할까를 설계로 생각할 수 있다. 선택됐을 때는 SKILL.md본문이나 필요한 참조 파일을 읽는다.

Skill의 description는 발화조건을 쓴다

다음은 나쁜 예이다.

description: 개발을 지원합니다.

이것만으로 언제 사용하는 Skill인지 알 수 없다. 좋은 예를 살펴보자. 대상 작업과 이용 조건을 구체적으로 작성하는 것이 좋은 작성법이다.

description: >
  GitHub Copilot을 주제로 한 기술 기사 섹션 초안에서,
  Qiita용 Markdown 글 본문을 만들 때 사용합니다.
  원본, 도식 생성 기록, 문체 규칙을 참고합니다.

description이 애매하면 필요한 Skill이 선택되지 않거나 관계가 없는 태스크에서 발화되거나 한다. 이것은 토큰의 문제가 아니다. AI가 착각하여 작업 순서를 적용하는 원인이 되기도 한다.

Skill 본문을 거대화하지 않는다

SKILL.md로 샘플코드, 전 API 사양, 과거의 사례, 긴 체크 리스트를 모두 읽도록 하면 발화시의 컨텍스트가 엄청 크게 되어버린다. 다음과 같이 나누면 정리하기 쉬워진다.

my-skill/
├─ SKILL.md
├─ scripts/
│  └─ validate.ps1
├─ references/
│  ├─ api-rules.md
│  └─ review-checklist.md
└─ assets/
   └─ template.md

SKILL.md에는 작업의 입구와 판단 순서를 작성한다. 상세한 API 규약이 필요해졌을 땐 references/api-rules.md를 읽어들이고, 검증 처리는 기존의 scripts/validate.ps1을 실행시킨다.

이러한 방법으로 매번 모든 것을 읽어 들이는 것이 아닌, 필요한 정보만 단계적으로 읽어들이도록 할 수 있다.

DESIGN.md는 필요시에 참조

DESIGN.md는 Google Labs의 공식 리포지토리에서는 "coding agents에 visual identity를 설명하기 위한 포맷"으로 공개되어 있다. 즉, 아키텍처 설계서나 DB설계서가 아닌, AI 브랜드나 프로덕트의 겉모습을 일괄적으로 다루기위한 디자인 문서이다.

공식 사양에선, DESIGN.md는 주로 다음의 두 계층으로 있다.

YAML front matter: 기계 판독 가능 디자인 토큰. 필요에 따라 붙임.
Markdown body: 인간도 읽을 수 있는 디자인상의 이유와 지침.

YAML front matter는 다음과 같은 토큰을 정의할 수 있다.

version//namedescription
colors
typography
rounded
spacing
components

색상은 CSS 색상 값, 크기는 px// em등 rem단위 단위 Dimension으로 작성할 수 있다. {colors.primary}같은 토큰 참조도 사용할 수 있다. Markdown 본문은 필요한 섹션만 작성할 수 있다. 공식 사양에서는, 존재하는 섹션은 다음의 순서로 하는 것을 추천되고 있다.

Overview
Colors
Typography
Layout
Elevation & Depth
Shapes
Components
Do's and Don'ts

여기서 중요한 것은 모든 작업에서 항상 읽힐 필요가 없다는 것이다.DESIGN.md라는 이름을 붙인 것만으로 GitHub Copilot이 모든 작업에서 항상 자동으로 읽을 수는 없다. 반면에 프롬프트 AGENTS.md에서 명시적으로 참조하면 GitHub Copilot에서도 UI 생성 및 디자인 판단의 맥락으로 사용할 수 있다. 그러므로 AGENTS.md또는 Skill에서 조건부로 참조하도록 한다.

# AGENTS.md

- UI를 새로 만들거나 외관을 변경하려면 `DESIGN.md `를 읽는다.
- 색상, 문자, 여백, 모서리 둥글기, 컴포넌트 상태를 지정하려면 `DESIGN.md `의 해당 섹션을 확인한다.
- API, DB, 인증·인가 구조를 변경할 경우 ADR이나 `docs/architecture.md ` 등 다른 설계 문서를 확인한다.

이 구성에는 두 가지 이점이 있다.

작은 변경으로 디자인 시스템 전문을 매번 읽지 않고 끝낸다.
UI나 외형의 판단으로 필요한 토큰과 지침을 확실히 읽을 수 있다.

즉, 단순히 "읽지 않음"이 아니라 읽기 조건을 설계하는 것이다.

세 가지 역할을 정리

역할을 짧게 정리하면 다음과 같습니다.

AGENTS.md	영구 규칙 및 참조 대상	대상 태스크 입구
SKILL.md	특정 작업 절차	해당 작업으로 발화했을 때
DESIGN.md	디자인 시스템	UI나 외형의 판단이 필요할 때
*.instructions.md	경로별 규칙	대상 파일이나 디렉토리를 다룰 때
사용자 프롬프트	이번만의 조건	그 요청을 할 때

어디에 작성할지 고민될 때 판단하는 방법

다음 질문을 순서대로 작성하길 바란다.

질문1 : 거의 모든 작업에 필요합니까?

Yes이면, AGENTS.md또는 리포지토리 공통의 Copilot instructions를 후보로 둔다.

예:

사용 언어
테스트 실행 정책
관련없는 파일을 변경하지 않음
비밀 정보를 출력하지 않음

질문2 : 특정 유형의 작업만으로 필요합니까?

Yes라면 Agent Skill을 추천한다.

예:

기사 작성 절차
배포 절차
보안 스캔 절차
릴리스 작업

질문3: 상세한 배경이나 설계 이유입니까?

Yes라면 내용에 따라 놓는 장소를 나눈다. UI나 외형의 판단이라면 DESIGN.md, 아키텍처나 과거의 기술 판단이라면 ADR이나 docs/부하의 설계 문서를 후보로 둔다.

질문4:특정 경로에만 적용할 예정입니까?

Yes라면, 경로 고유의 instructions나 대상에 가까운 AGENTS.md것을 후보로 하자.

질문5: 이번 의뢰에만 필요합니까?

예인 경우 사용자 프롬프트나 작업 문서에 작성한다.

3. MCP는 연결 수가 아니라 정의 및 실행 결과를 설계합니다.

MCP는 AI 애플리케이션이 외부 도구와 데이터에 연결하는 공통 프로토콜이다. MCP 서버는 주로 다음 능력을 가지고 있다.

기능	내용
Tools	모델이 수행할 수 있는 작업
Resources	파일, DB 스키마, 문서 등의 컨텍스트
Prompts	정형 메시지 및 워크플로

MCP를 사용하면 GitHub, 데이터베이스, 사내 시스템, 브라우저 등의 기능을 AI에서 쉽게 사용할 수 있다. 반면에 사용 가능한 MCP 서버와 도구를 무제한으로 늘리면 모델이 선택하는 정보와 도구 실행 결과가 커질 수 있다. 여기에서는 MCP를 "연결할지, 연결하지 않을지"가 아니라, 무엇을 모델에 보여주고, 무엇을 돌려 받을까로 생각한다.

MCP 통신과 모델 입력을 분리

MCP 서버와 클라이언트 간에는 도구 목록 검색, 리소스 목록 검색, 도구 실행, 리소스 읽기 등의 통신이 이루어진다. 개념적으로는 다음과 같은 흐름을 가지고 있다.

MCP 서버
  ├─ Tools
  ├─ Resources
  └─ Prompts
        ↓ MCP 통신
MCP 클라이언트 / 에이전트 런타임
        ↓ 필요한 정의·본문·결과를 선택
LLM의 컨텍스트

MCP 서버에서 반환된 정보를 클라이언트가 모델에 전달하는 방법은 구현에 따라 다르다. 즉, 다음 두 가지로 나눌 수 있다.

MCP 통신으로 획득한 정보
실제로 LLM에 전달된 정보

LLM의 입력에 영향을 미치는 대표적인 예는 다음과 같다.

도구 이름
tool description
입력 스키마
prompt 본문
resource 본문
tool call 인수
tool result

MCP에서 무거워지기 쉬운 세 곳

1. 대량·거대한 tool schema

AI가 도구를 선택하려면 도구의 역할과 인수를 이해할 필요가 있다. 예를 들어, 다음과 같은 정의가 존재한다고 하자.

{
  "name": "search_issues",
  "description": "Search issues in the selected repository.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "repository": {
        "type": "string"
      },
      "query": {
        "type": "string"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      }
    },
    "required": ["repository", "query"]
  }
}

하나라면 큰 문제가 되지 않지만 비슷한 도구가 수십개, 수백개 있으면 모델에 제시하는 정의량이 늘어나게 된다. 또한 description이 긴 문장이거나 input schema가 복잡하고 예와 제약을 대량으로 포함하면 하나의 툴임에도 내용이 거대해진다.

대책으로서, 클라이언트측에서는 다음을 것을 고려할 수 있다.

이번 작업과 관련된 네임스페이스만 제시
필요한 도구만 동적으로 선택
비슷한 도구 정리
설명을 짧고 구체적으로 만들기
거대한 하나의 도구를 용도별로 나누기

그러나 어떤 방법을 사용하는가는 클라이언트와 에이전트 런타임에 따라 다르다.

2. 긴 tool result

실무에서는 tool schema 이상으로 tool result가 커질 수 있다. 다음은 나쁜 예입니다.

{
  "issues": [
    {
      "number": 1,
      "title": "...",
      "body": "긴 문장...",
      "comments": ["모든 코멘트..."],
      "events": ["모든 코멘트..."]
    }
  ]
}

목록 표시만이 목적인데, 본문, 전체 코멘트, 모든 이벤트까지 반환되면, 모델이 읽는 정보가 늘어나게 된다. 목록용 도구는 필요한 필드만 반환하도록 한다.

{
  "issues": [
    {
      "number": 1,
      "title": "로그인 처리로 타임아웃으로한다",
      "state": "open",
      "updatedAt": "2026-06-15"
    }
  ],
  "nextCursor": "..."
}

자세한 내용이 필요할 때만 다른 도구로 Issue 본문이나 주석을 가져오도록 한다.

search_issues
    ↓ 목록 20건 반환
AI가 대상을 선택한다
    ↓
get_issue
    ↓ 선택한 1건의 상세 정보를 반환한다

이 '목록과 세부사항 분리' 설계는 MCP뿐만 아니라 API 설계 전반에서 유효하다.

3. 장문의 resource 본문

resources/list에서 리소스 목록을 얻는 것과 resources/read에서 본문을 읽는 것은 나누어 생각할 수 있다. 목록이 짧아도 본문이 거대하면 읽을 때 컨텍스트를 사용한다. 예를 들어, 5000줄의 DESIGN.md전체 텍스트를 매번 읽는 대신 다음 방법을 고려할 수 있다.

제목 목록을 먼저 확인
대상 키워드로 검색
관련 섹션만 읽기
문서를 기능별로 분할
요약판과 상세판을 구분

MCP 서버 측에서 결과 제어

모델에 반환하는 결과를 줄이려면 MCP 서버의 도구 설계도 중요하다. 다음 인수를 제공하면 클라이언트와 AI가 출력량을 제어할 수 있다.

{
  "name": "search_issues",
  "description": "Search issues and return a limited summary.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 20,
        "default": 10
      },
      "fields": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["number", "title", "state", "updatedAt"]
        }
      }
    },
    "required": ["query"]
  }
}

실무에서 사용하기 쉬운 제어 항목은 다음과 같다.

limit: 최대 건수
cursor: 페이지네이션
fields: 반환할 항목
top_k: 관련도 상위만 반환
include_body: 본문 포함 여부
max_chars: 최대 문자 수
summary: 전체 텍스트가 아닌 요약을 반환합니까?

중요한 것은 AI에 "결과를 짧게 해라"라고 부탁 할뿐만 아니라, 도구의 인터페이스로도 제한 할 수 있다.

MCP보다 CLI가 적절할 때

MCP는 편리하지만 모든 처리를 MCP 도구로 만들 필요는 없다. 특히 Skill 또는 고정 프롬프트에서 사용하는 도구와 실행 절차가 완전히 결정된 경우 CLI 명령을 고정하는 것이 더 간결해질 수 있다.

예를 들어 Skill에 다음 단계를 작성했다고 가정하자.

변경 파일 목록 얻기
대상 프로젝트의 테스트 실행
실패한 테스트 이름만 추출

사용할 명령이 고유하게 결정된 경우 AI에 여러 MCP 도구를 제공하고 선택하지 않아도 다음 명령을 실행할 수 있다.

git diff --name-only
dotnet test --logger "console;verbosity=minimal"

이 경우 CLI를 고정 지정하는 장점은 다음과 같다.

AI가 여러 툴 중에서 선택하는 프로세스를 줄일 수 있다.
선택 재료로 MCP 도구의 description이나 schema를 제시할 필요가 거의 없어진다.
Skill의 실행 절차를 재현 가능한 형태로 고정할 수 있다.
개발자가 평상시 사용하는 명령을 그대로 사용할 수 있다.
같은 명령을 인간도 CI도 실행하기 쉽다

판단 기준을 한 문장으로 하면 다음과 같이 됩니다.

AI에 "어떤 도구를 사용할 것인가"를 선택한다면 MCP. Skill이 "이 명령을 사용"이라고 결정한 경우 CLI를 사용한다.

CLI에서도 출력이 크면 무겁다.

이것은 쉽게 오해하기 쉬운 포인트이다. CLI를 사용하면 자동으로 토큰이 사용되는 것이 아니다. 다음과 유사한 명령은 많은 양의 출력을 리턴할 수 있다.

git log
dotnet test --verbosity diagnostic
Get-ChildItem -Recurse
kubectl logs deployment/my-app

대량의 출력을 그대로 모델에 건네주면 MCP의 tool result와 같이 컨텍스트를 사용하게 된다. 따라서CLI에서도 다음과 같이 출력을 줄이도록 하자.

# 변경된 파일명만
git diff --name-only

# 최근 20거만
git log -n 20 --oneline

# 에러를 포함하는 행만
dotnet test --logger "console;verbosity=minimal" |
  Select-String -Pattern 'Failed|Error'

# JSON를 필요한 항목으로 좁힘
gh issue list --limit 20 --json number,title,state

CLI와 MCP의 차이보다 궁극적으로 모델에 반환하는 정보량이 중요하다.

MCP를 선택할 가치가 있는 순간

한편, 다음과 같은 경우에는 MCP가 적합하다.

작업에 따라 AI 자체가 여러 작업 중에서 선택
형식화된 schema로 인수 확인
인증, 권한, 감사, 승인을 공통화
로컬에 CLI를 배포할 수 없는 외부 서비스 처리
IDE, CLI, 클라우드 에이전트에서 동일한 기능 사용
서버 측에서 검색, 페이징, 요약을 통합
사용자에게 내부 API 구현을 보지 않고 기능 공개

목적별로는 다음 표로 정리할 수 있다.

조건	MCP	CLI
AI가 조작을 동적으로 선택	적합하다	고정 처리에 적합
형식화된 인수	schema로 표현하기 쉬움	명령 인수로 관리
인증 및 권한 공통화	서버 측에서 구현하기 쉬움	CLI마다 다름
기존 개발 명령 재사용	MCP화 필요	그대로 사용하기 쉬운
여러 클라이언트에서 사용	향하다	환경 차이가 나기 쉽다.
고정된 일련의 처리	과도해질 수 있음	향하다
출력 제어	툴 설계로 제어	옵션 및 후처리로 제어

“MCP와 CLI 중 어느 것이 더 나은가”가 아니라 선택의 필요성, 권한 관리, 재사용성, 결과의 양 으로 결정하는 것이다.

4. 캐시, 압축, 자동화를 품질과 세트로 생각한다

긴 지시, 도구 정의, 대화 기록을 다루면 Prompt Caching이라는 단어가 나온다. Prompt Caching은 유용하지만 컨텍스트 디자인을 대체하지는 않는다.

여기에서는 다음 세 가지로 나눈다.

컨텍스트 디자인
Prompt Caching
컨텍스트 압축

컨텍스트 디자인은 불필요한 정보를 포함하지 않는다.

컨텍스트 설계시 판단에 불필요한 정보를 처음부터 넣지 않지 않도록 한다.

예:

이번에 사용하지 않는 도구를 제시하지 말라.
대상외 설계서를 읽지 말라.
검색결과를 상위 20건으로 제한.
전체 로그가 아닌 오류 주변을 반환한다.
일람 취득과 상세 취득을 나눔.

이것은 입력 토큰을 줄일 뿐만 아니라 AI의 판단 노이즈를 줄여준다.

Prompt Caching은 같은 선두 부분을 재사용합니다.

Prompt Caching은 여러 리퀘스트에서 공통되는 입력의 시작 부분, 즉 prefix 계산을 재사용하는 메커니즘이다. 개념적으로는 다음과 같습니다.

첫 번째
[고정instructions][고정tools] [고정 문서] [질문 A]
 └────── -- 캐시 생성 ────────┘

두 번째
[고정instructions][고정tools] [고정 문서] [질문 B]
 └────── -- 캐시 읽기 ────────┘

고정 부분이 동일하면, 2회째 이후의 처리에 재이용할 수 있다. 캐시의 대상이 될 수 있는 고정 정보는 다음과 같다.

system instructions
동일한 도구 정의
같은 Skill 본문
같은 긴 텍스트 문서
대화 이력의 공통 부분
같은 tool result가 히스토리의 같은 위치에 남아있는 경우

그러나 도구 순서, schema, 타임 스탬프, 전반의 메시지 등이 변경되면 공통 prefix가 무너질 수 있다. 또한 MCP 서버가 결과를 저장하는 것과 Prompt Caching은 메커니즘이 다르다.

MCP 서버 측 캐시
  → API 호출 및 DB 검색 결과를 재활용한다

Prompt Caching
  → 모델에게 전달하는 공통 입력의 계산을 재활용한다

동일한 응답을 반환하는 MCP 도구에서도 그 결과가 다음 모델 입력에서 공통 prefix로 다시 전송되지 않으면, Prompt Caching의 히트라고 할 수는 없다.

컨텍스트 압축은 긴 역사를 요약

컨텍스트 압축은 길어진 대화 기록을 짧은 요약으로 대체하는 개념이다. 예를 들어, 다음과 같은 기록이 있다고 가정하자.

User: 요구사항 설명
Assistant: 조사 결과
Tool: 파일 목록
Assistant: 설계안
User: 수정 요청
Tool: 테스트 결과
Assistant: 수정본

이것을, 다음과 같은 요약으로 압축한다.

지금까지의 결정 사항:
- 공개 API는 변경하지 않는다
- OrderService만 수정한다
- 테스트 3건 추가 완료

미해결:
- 타임아웃 값 결정

다음 작업:
- 설정값을 확인하고 구현을 완료한다

이렇게 하면 오래된 대화를 모두 유지하지 않아도 중요한 판단을 이어받게 된다. 그러나 요약 시 세부 정보가 손실될 수 있다. 나중에 필요한 원문은 파일이나 외부 기록에 남겨 두는 것이 안전하다.

Claude API로 캐시 확인하기.

Claude API를 사용하면 Prompt Caching의 사용 상태를 usage 정보로 확인할 수 있다. 대표적인 값은 다음과 같다.

{
  "usage": {
    "cache_creation_input_tokens": 5000,
    "cache_read_input_tokens": 0,
    "input_tokens": 80
  }
}

cache_creation_input_tokens증가한 경우, 캐시에 기록된 입력이 존재한다. 후속 리퀘스트에서 다음과 같이 cache_read_input_tokens증가하면 캐시에서 실제로 로드된다.

{
  "usage": {
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 5000,
    "input_tokens": 60
  }
}

즉, 확인할 때는 다음과 같이 생각할 수 있다.

cache creation: 다음에 대비하여 캐시를 만들었다.
cache read: 이번 요청에 캐시가 사용되었다.

자세한 내용은 Anthropic의 Prompt Caching 공식 문서 에서 확인하자.

OpenAI API로 캐시 확인

OpenAI API는 대상 긴 프롬프트에 Prompt Caching을 자동으로 적용된다. 사용 상황은 응답의 usage에 포함되어 있는 cached_tokens를 확인한다.

{
  "usage": {
    "prompt_tokens": 4200,
    "prompt_tokens_details": {
      "cached_tokens": 3072
    }
  }
}

고정의 instructions나 툴 정의 등, 공통하는 정보를 전방에 두고, 매회 바뀌는 사용자 입력을 후방에 두면, 공통 prefix를 작성하기 쉬워진다. 자세한 내용은 OpenAI의 Prompt Caching 공식 문서 를 확인하면 된다.

GitHub Copilot과 기반 API를 혼동하지 말자.

GitHub Copilot, Claude API, OpenAI API는 동일한 모델을 사용하는 경우에도 사용자가 조작할 수 있는 설정은 동일하지 않다.

Claude API와 cache_control같은 설정을 일반 GitHub Copilot 프롬프트에 직접 쓰면 유효해지는 것이 아니다. GitHub Copilot에서는 Copilot 서비스 측이나 사용 모델 측이 캐시를 관리한다. 따라서 다음을 나누어 설명하겠다.

이용 형태	캐시처리
Claude API를 직접 사용	API 사양에 따라 설정 · usage 확인
OpenAI API를 직접 사용	자동 캐시 및 사용량 확인
GitHub Copilot 사용	Copilot의 기능·표시·과금 사양에 따른다

"Claude에서는 설정할 수 있기 때문에 Copilot에서도 같은 JSON을 지정할 수 있다"는 것은 아닙니다.

※ 제품 사양, 대응 모델, 요금, 캐시 유지 시간은 갱신될 가능성이 있습니다. 구현시 각 서비스의 최신 공식 문서를 확인하도록 하자.

5. 모델 선택은 작업의 어려움과 위험을 기준으로 결정한다

컨텍스트 디자인에서는 "무엇을 읽힐지"뿐만 아니라 어떤 모델을에 전달할지도 중요하다. 같은 프롬프트, 같은 파일, 같은 툴 결과에서도 사용하는 모델에 따라 다음과 같은 차이가 나온다.

응답 속도
추론의 깊이
긴 문맥에 대한 힘
환각의 적음
코드 변경 안정성
입출력 토큰당 AI Credits

GitHub Copilot에서는 Chat 모델을 선택할 수 있습니다. 또한 사용 가능한 모델은 계약 계획, 조직 정책, IDE 및 GitHub.com과 같은 사용하는 곳에 따라 달라진다. 그 때문에, 「이 모델을 항상 사용하면 좋다」라고 고정하는 것보다, 태스크의 종류로 선택하는 것이 실무적이다.

또한 GitHub Docs는 모델마다 강점이 다르며 AI Credits의 소비도 모델의 토큰 가격에 따라 다르다고 설명하고 있다. 기사를 읽을 때의 최신 대응 상황은 GitHub Copilot의 모델 비교 와 모델 변경 절차 를 확인하자.

우선 Auto를 기준으로 한다

초보자는 우선 Auto를 기준으로 하면 좋다. Auto는 해당 환경에서 사용 가능한 상황 등에 따라 모델을 선택한다. 수동으로 모델을 선택하는 이유가 명확하지 않은 동안에는 Auto를 사용하여 모델 선택 자체에 고민하는 시간을 줄일 수 있다. 그러나 Auto에 맡기는 것과 디자인을 포기하는 것은 다르다. 다음과 같은 경우에는 수동으로 모델을 선택할 가치가 있다.

중요한 설계 판단과 함께
원인 불명의 버그를 깊이 조사한다
여러 파일에 걸친 변경 계획
보안 및 인증 허가와 관련된 내용
생성 결과의 품질이 여러 번해도 안정되지 않음
비용과 속도를 우선하여 가벼운 작업을 대량으로 처리하고 싶은 경우

즉, Auto를 기본값으로 하면서 필요한 경우에서 명시적으로 전환한다는 생각이다.

모델은 세 가지 레이어로 생각

모델명은 언제든 바뀐다. 새 모델이 추가되고 프리뷰가 제거되고 조직 정책에서 사용할 수 있는 모델도 변경된다. 따라서 기사와 팀 규칙에서는 특정 모델 이름뿐만 아니라 다음과 같은 역할로 생각하면 오래 기준으로 삼을 수 있다.

레이어	적합한 작업	주의점
높은 추론 모델	설계, 계획, 어려운 디버깅, 검토, 보안 판단	고품질이지만 비용과 대기 시간이 증가하기 쉽습니다.
표준 모델	일반 구현, 테스트 추가, 다중 파일 수정, 문서 업데이트	길을 잃었을 때 중심 후보
경량 모델	작은 리팩토링, 정형 변환, 요약, 간단한 문장 수정	복잡한 설계 판단을 맡기지 않는다.

예를 들어, 다음과 같이 나눠서 사용한다.

조사·계획: 고추론 모델 또는 Auto
일반 구현: 표준 모델 또는 Auto
단순 수정: 경량 모델
리뷰: 고추론 모델
대량의 정형 처리: 경량 모델 + 테스트 린터

중요한 것은, 「높은 모델을 사용할까, 싼 모델을 사용할까」가 아니다. 필요한 충분한 분석력을 가진 모델을 선택하고 부족한 품질은 컨텍스트, 테스트, 인간 리뷰로 보완하는 것이 중요하다.

고성능 모델을 사용하기 전에 정보를 전달하는 방법을 검토합니다.

원하는대로 작동하지 않을 때 바로 상위 모델로 전환하고 싶을 것이다. 그러나 실패의 원인이 모델 능력이 아니라 컨텍스트 설계에 있는 경우도 많다.

필요한 설계 문서를 읽지 않음
관련없는 로그를 대량으로 전달
작업의 목표가 모호
수정할 파일이 식별되지 않음
테스트 조건이 작성되지 않음
오래된 대화 기록이 남아 있음

이 상태에서 고성능 모델로 전환하면 확실히 개선될 수 있다. 다만, 그것은 「모델이 강하기 때문에 잡음의 입력으로도 견뎌냈다」라고 할 수 있을지도 모른다. 재현 가능한 운영을 위해서는 먼저 입력을 정리하도록 하자.

추천 순서는 다음과 같습니다.

/context야 /usage에서 부풀어 오르는 부분을 확인하십시오.
관련없는 파일, 로그 및 도구 결과 줄임
필요한 설계 문서 및 제약 추가
작업을 조사, 계획, 구현, 검토로 나누기
그래도 어려운 판단만 고추론모델로 전달

고성능 모델은 불필요한 정보를 대량으로 처리하는 것이 아니라 어려운 판단에 집중시키기 위해 사용한다.

Chat과 Inline suggestion의 모델은 나누어 생각한다

또 하나 혼동하기 쉬운 점이 있다. GitHub Copilot Chat에서 선택한 모델과 편집기의 Inline suggestion에서 사용되는 모델은 동일한 설정이 아닙니다.

GitHub Docs에서도 Chat의 모델 변경은 Inline suggestion의 모델에 영향을 미치지 않고, Inline suggestion 측도 사용할 수 있는 대체 모델이나 확장 기능의 버전에 조건이 있다고 설명하고 있습니다.

즉, 다음과 같이 나누어 생각합니다.

케이스	주요 용도	모델 선택 방법
Copilot Chat / Agent mode	조사, 설명, 계획, 다중 파일 변경	작업의 어려움과 검토 위험으로 선택
Inline suggestion	입력 중 코드 완성	속도, 쓰기, 사용 가능한 모델로 선택
Cloud agent/CLI	비동기 작업, 긴 작업, 도구 실행	비용, 실행 시간 및 검토 경계를 포함하여 선택

「Chat에서는 고추론 모델을 사용하지만, 보완은 경쾌한 모델로 한다」라고 하는 선택도 있을 수 있습니다.

모델 선택도 AGENTS.md나 Skill에 쓸 수 있다

팀에서 모델 선택을 운용하고 있다면 매회 채팅으로 전달하는 것보다 AGENTS.mdSkill에 판단 기준을 적어두면 편리하다.

아래는 예이다.

# Model selection

- 일반적인 구현과 테스트 추가는 Auto 또는 표준 모델을 사용한다.
- 아키텍처 변경, 인증·인가, 보안 판단에서는 고추론 모델을 검토한다.
- 단순한 문구 수정, 형식 변환, 경미한 리팩토링에서는 경량 모델을 우선한다.
- 모델을 전환한 경우에는 이유를 작업 메모에 남긴다.

여기서도, 특정 모델명만을 고정하지 않는 것이 보수하기엔 쉽다. 즉, 조직에서 사용할 수 있는 모델, 기본 모델, LTS 모델, 요금 및 정책은 변경되므로, 이름이 아니라 어떤 종류의 판단에 어느 정도의 추론력을 사용하는지를 결정해 두자.

💡 모델 선택 결론

망설이면 Auto를 기준으로 하고 어려운 설계·디버그·리뷰에서는 고추론 모델 사용을 검토한다. 가벼운 정형 작업은 경량 모델이나 CLI에 전해져, 품질은 테스트와 리뷰로 보충한다.

6. 자동화는 CDQR로 판단한다

지금까지 토큰과 컨텍스트를 중심으로 설명했다. 그러나 실무에서 최적화하고 싶은 것은 토큰뿐만이 아니다. AI 활용에서는 다음 네 가지를 세트로 생각할 필요가 있다.

비용: 비용
Delivery: 속도
Quality: 품질
Review: 인간에 의한 확인

이 기사에서는 이것을 CDQR 로 정리하도록 하겠다.

Cost: 불필요한 입력 및 출력 감소

Cost에서는 단순히 프롬프트의 문자 수를 보는 대신 전체 처리를 확인한다.

상설 지시가 거대하지 않은가?
사용하지 않는 도구 정의를 매번 제공하고 있지 않은가?
모든 검색 결과를 반환하고 있지는 않은가?
로그를 무제한으로 반환하지 않은가?
같은 파일을 여러 번 다시 읽도록 하고 있지는 않았는가?
긴 세션을 방치하지 않았는가?
여러 번 다시 시작하는 원인이 설명 부족하지 않은가?
가벼운 작업에 고추론 모델을 계속 사용하고 있지 않습니까?

적절한 instructions를 조금 늘리면 재실행이 줄어들고 토큰 사용을 줄일 수 있다.「입력을 짧게 한다」뿐만 아니라, 「왕복 횟수를 줄이는」「태스크에 맞는 모델로 전환」하는 것도 코스트 개선이다.

Delivery: AI에 맡기면 정말 빨라질까

AI에 의한 자동화는 다음과 같은 작업과 궁합이 좋다.

리포지토리 내 탐색
변경 후보 열거
상용 코드 생성
형식 변환
테스트 실행
차이의 요약
문서 초안

한편, 작업절차를 AI에 매번 생각하게 하는 것보다 Skill이나 CLI로 고정하는 것이 더 빠를 수 있다. 예를 들어 매번 동일한 테스트 명령을 사용하면 AI가 수십 개의 도구에서 테스트 도구를 찾을 필요가 없어진다.

# SKILL.md

검증할 때는 다음 순서대로 실행한다.

1. `dotnet format --verify-no-changes`
2. `dotnet test --logger "console;verbosity=minimal"`
3. 실패 시 오류 주변만 보고한다

판단이 불필요한 부분은 고정하고 판단이 필요한 부분에 AI의 능력을 사용하는 것이 효율적이다.

Quality: 필요한 설계 의도와 검증 조건 전달

토큰을 줄이기 위해 설계 문서를 읽지 않으면 단기적으로 입력이 줄어 든다. 그러나 다음과 같은 품질 문제가 발생할 수 있다.

기존 아키텍처와 반대
공개 API 끊기
보안 경계를 넘어
데이터 무결성 손상
테스트 정책에 위배됨
비슷한 기능을 중복 구현

품질을 지키기 위해서는, 「디자인서를 전부 읽는다」인가 「아무것도 읽지 않는다」의 2택으로 하지 않는 것이 중요하다.

AGENTS.md에 디자인 문서를 읽는 조건을 쓴다.

- 공개 API 변경에서는 `docs/api-design.md ` 를 읽는다.
- 인증·인가 변경에 관해서 `docs/security/` 를 확인한다.
- DB 변경 시 마이그레이션 및 롤백 절차를 확인한다.

필요한 작업에서만 적절한 정보를 추가하면 컨텍스트 양과 품질을 양립할 수 있다.

Review: 인간이 승인해야 하는 경계를 남긴다

AI 에이전트가 자율적으로 작업할 수 있지만 모든 것을 무조건 승인할 수는 없다. 인간의 리뷰를 남기고 싶은 대표적인 예는 다음과 같다.

공개 API의 파괴적 변경
데이터 삭제
프로덕션 환경에 배포
인증·허가 변경
비밀 정보 및 개인 정보 취급
아키텍처 변경
비용에 큰 영향을 미치는 변경
요구 사항 우선 순위 지정

AI는 후보를 조사하고, 차이를 만들고, 테스트를 수행하고, 검토 자료를 정리할 수 있습니다만, "이 위험을 수락할 것인가" "이 사양을 공식적으로 채택할 것인가"는 조직과 책임자의 판단이다.

▸ AI에 맡기기 쉬운 부분

필요한 파일 찾기
기존 구현 설명
변경안을 여러 개 내기
테스트 추가
정적 분석 수행
영향 범위 나열
풀 리퀘스트 설명문 만들기

▸ 인간의 승인을 남겨야하는 부분

방식의 최종 결정
프로덕션 반영
데이터 삭제 조작
보안이나 예외
예산 및 납기 우선순위
법무·준법 판단

CDQR 판단표

축	확인해야할 질문
Cost	불필요한 입력, 출력, 재시도가 증가하지 않았습니까?
Delivery	AI에 맡기면 전체 작업이 정말 빨라집니다.
Quality	설계 의도, 제약, 검증 조건을 필요한 범위에서 읽었습니까?
검토	인간이 승인해야 할 경계를 남겼는지

모델 선택도 이 표에서 확인할 수 있다.

비용 : 가벼운 작업에 높은 추론 모델을 너무 많이 사용하지 않았는가?
Delivery: 속도가 필요한 작업에서 무거운 모델을 너무 많이 선택하지 않았는가?
Quality：어려운 설계 판단에 경량 모델만으로 도전하고 있지 않은가?
Review: 모델을 강하게 함으로써 인간 리뷰를 생략하지 않았습니까?

토큰 최적화는 이 중 비용만 개선하는 활동이 아니다. 컨텍스트 디자인을 통해 Delivery, Quality 및 Review도 함께 정리해나가야 한다.

7. 예: 리포지토리 컨텍스트 설계

지금까지의 내용을 관리 화면이 있는 가상의 Web API 프로젝트에 적용해 보도록 하겠다.

프로젝트 구성

shop-api/
├─ AGENTS.md
├─ DESIGN.md
├─ README.md
├─ src/
│  ├─ Api/
│  ├─ Application/
│  └─ Infrastructure/
├─ tests/
├─ docs/
│  ├─ architecture.md
│  ├─ security/
│  │  └─ authentication.md
│  └─ adr/
│     ├─ 0001-database.md
│     └─ 0002-api-versioning.md
└─ .github/
   └─ skills/
      ├─ api-review/
      │  └─ SKILL.md
      └─ database-migration/
         └─ SKILL.md

AGENTS.md에 상설 규칙 작성

# General rules

- 답변은 한국어로 작성한다.
- 기존 코딩 규약과 명명 규칙을 따른다.
- 무관한 파일은 변경하지 않는다.
- 작업 후에 대상 테스트를 실행한다.
- 실행하지 않은 테스트를 ‘성공’이라고 보고하지 않는다.

# Context routing

- UI를 새로 만들거나 외관을 변경하려면
  `DESIGN.md ` 를 읽는다.
- 공개 API를 변경하려면 `docs/architecture.md `와
  `docs/adr/0002-api-versioning.md` を読む.
- 인증·인가를 변경하는 경우는
  `docs/security/authentication.md` を読む.
- DB 스키마를 변경하려면
  `database-migration` Skill을 사용한다.
- 단순한 문구 수정만으로는 설계 문서나 `DESIGN.md `을 추가로 읽지 않는다.

# Review boundary

- 실제 배포는 실행하지 않고, 절차와 확인 결과만 제시한다.
- 데이터 삭제가 포함된 명령은 실행하기 전에 인간의 승인을 받아야 한다.

# Model selection

- 일반적인 구현과 테스트 추가는 Auto 또는 표준 모델을 사용한다.
- 공개 API, 인증·인가, DB 설계 변경 시 고추론 모델을 검토한다.
- 단순한 문구 수정이나 형식 변환에서는 경량 모델을 우선한다.

이 파일에는 상세한 설계 내용이 아니라 상설 규칙과 조건을 작성하고 있다.

DB 변경을 Skill로 나누기

---
name: database-migration
description: >
  DB 스키마 변경, 마이그레이션 생성,
  롤백 확인이 필요한 작업에 사용한다.
---

# 실행 절차

1. `docs/adr/0001-database.md ` 를 읽는다.
2. 대상 Entity와 기존 Migration을 확인한다.
3. Migration을 생성한다.
4. 생성된 SQL을 확인한다.
5. 롤백 가능성을 확인한다.
6. 테스트 DB에 적용한다.
7. 실제 적용은 하지 않고, 리뷰 결과를 보고한다.

# 고정 명령

```powershell
dotnet ef migrations add <MigrationName>
dotnet ef migrations script
dotnet test --filter Category=Database
```

여기에서는 실행할 CLI 명령이 결정된다. MCP에서 여러 DB 조작 도구를 AI로 선택하는 것보다 Skill에 고정 명령을 작성하는 것이 간단하다. 반면에 프로덕션 DB에 연결해야 하며 인증, 승인 및 감사 로그를 공통적으로 관리하려면 MCP 서버를 통하는 것이 좋다.

GitHub 검색은 MCP에서 동적으로 선택 가능

Issue, Pull Request, Review 코멘트 등을 가로질러 조사하는 태스크에서는 AI가 작업을 선택하는 가치가 존재한다.

예:

‘과거에 같은 인증 오류를 수정한 Issue와 PR을 찾아서,
채택된 해결책을 요약해 주세요

이 경우 AI는 다음 작업을 결합할 가능성이 있다.

Issue 검색
관련 PR 획득
PR 차이를 확인
리뷰 코멘트 읽기
채용된 결론을 정리

동적 선택이 필요하므로 MCP가 적합합니다.

하지만 검색결과는 모두 반환하지 않으며 다음과 같이 제한한다.

{
  "query": "authentication timeout",
  "limit": 10,
  "fields": ["number", "title", "state", "updatedAt"]
}

필요한 Issue가 정해진 후 세부 사항을 읽는다.

세션이 길어지면 압축

설문조사, 구현, 테스트 및 수정을 한 세션에서 계속하면 기록이 길어진다. 적절한 구분 기호로 다음 정보를 요약하도록 한다.

이번 목적
읽은 설계 문서
결정한 방식
변경된 파일
수행한 테스트
미해결
다음 작업

요약 예이다.

# 작업 요약

## 목적

인증 타임아웃 시 재시도 처리를 추가한다.

## 읽은 자료

- docs/security/authentication.md
- docs/adr/0002-api-versioning.md

## 결정 사항

- 재시도는 최대 2회
- 4xx는 다시 시도하지 않는다
- 5xx와 타임아웃만 다시 시도한다

## 변경 파일

- src/Infrastructure/AuthClient.cs
- tests/AuthClientTests.cs

## 테스트

- AuthClientTests: 8건 성공

## 미해결

- 실제 타임아웃 값은 담당자 확인 대기 중

이 요약을 남겨두면 이전 도구 결과와 자세한 왕복을 쉽게 압축할 수 있다.

정리 : 읽어야 할 정보가 읽을 순간에 도달하는 구조를 만듭니다.

'질문'만으로는 AI를 제대로 활용 수 없다. AI가 참조하는 전체 컨텍스트를 디자인하자.

이 기사의 요점을 되돌아보자.

질문문만 토큰이 아니다.
고정 지침, 도구 정의, 파일, 대화 기록, 도구 결과, AI 응답이 동일한 컨텍스트를 사용한다.
먼저 관측합니다.
/context , /usage, /compact등을 사용하여 어디에서 커지고 있는지를 확인하자.
AGENTS.md입구로 사용하자.
영구 규칙과 필요한 자료를 읽는 조건을 작성하자.
특정 작업의 절차는 Agent Skills로 나누자.
description을 구체적으로 하고, 상세한 자료나 스크립트는 필요시에 읽도록 한다
DESIGN.md필요할 때 참조합니다.
두는 것만으로 자동 읽기를 기대하진 말고, AGENTS.mdSkill에서 동선을 만들자.
MCP는 연결 수보다 모델에 표시되는 정의와 반환 결과를 설계하자.
건수, 항목, 페이징, top-k, 요약등을 사용하자.
AI가 도구를 선택한다면 MCP, 처리가 고정이라면 CLI도 후보이다.
Skill에서 명령이 결정된 경우 CLI에 고정시키면 간단해질 수 있다.
CLI에서도 출력을 제어해야한다.
대량 로그와 전체 파일을 반환하면 MCP와 마찬가지로 컨텍스트를 사용한다.
디자인, 캐시, 압축을 나눕니다.
불필요한 정보를 넣지 않는, 고정 prefix를 재이용하는, 낡은 이력을 요약한다등 다양한 대책이 있다.
모델 선택은 작업의 어려움과 위험에 따라 결정하자.
헤매면 Auto를 기준으로 어려운 설계 · 디버그 · 리뷰에서는 고추론 모델, 가벼운 정형 작업에서는 경량 모델 사용을 검토하자.
토큰뿐만 아니라 CDQR을 보자.
Cost, Delivery, Quality, Review의 균형을 맞주자.

마지막으로 리포지토리를 검토하는 체크리스트를 게시하도록 하겠다.

AGENTS.md상설해야 할 짧은 규칙으로 좁혀져 있다.
자세한 디자인 문서의 전체 텍스트를 AGENTS.md복사하지 않았다.
설계 문서를 읽는 조건이 작성되어 있다.
특정 작업의 절차를 Skill로 나누고 있다.
Skill의 description에서 발화 조건을 알 수 있다.
Skill 본문과 상세 자료를 나누고 있다.
불필요한 MCP 도구를 항상 제시하지 않도록 하고 있다.
MCP 툴의 일람 취득과 상세 취득을 나누고 있다.
limit, fields, 페이징, top-k 사용 가능한 상태이다.
도구 결과 및 CLI 로그의 양을 제한하고 있다.
고정 처리를 CLI에 전달할 수 없는지 검토했다.
Auto, 표준 모델, 고추론 모델, 경량 모델의 구분법을 결정하고 있다.
Chat, Inline suggestion, CLI/Cloud agent 모델 선택을 혼동하지 않음.
모델을 전환한 이유를 작업 메모나 PR 설명에 남기고 있다.
긴 세션을 적절히 요약하고 압축하고 있다.
캐시 히트를 usage로 확인하고 있다.
AI에 맡기는 범위와 인간의 리뷰 경계를 결정하고 있다.
토큰 감소 전후에 아티팩트의 품질도 비교하고 있다.

참고자료

https://qiita.com/ochtum/items/d442ed23d24245b789a0

728x90

저작자표시 비영리 동일조건 (새창열림)

'IT > 코딩툴' 카테고리의 다른 글

GitHub Copilot의 토큰 소비량을 줄이기 위한 사용 방법 (0)	2026.07.26
Claude 101 (0)	2026.05.16
VSCode(Visual Studio Code)의 GitHub Copilot SKILL.md (0)	2026.02.25
VSCode(Visual Studio Code)의 GitHub Copilot 커스텀 지침(커스텀 인스트럭션)과 MCP (0)	2025.10.25
VSCode(Visual Studio Code)의 GitHub Copilot를 활용하는 6가지 방법 (0)	2025.10.04

현재글GitHub Copilot을 현명하게 사용하는 컨텍스트 전략