1. Custom Instructions
- AI를 제대로 활용하기 위한 첫 단계는 ‘프롬프트를 잘 만드는 것’이다.
- AI 모델의 응답 품질은 프롬프트 설계에 크게 영향을 받는다.
- Custom Instructions는 AI가 응답할 때 항상 참고해야 할 기본 지침을 미리 정의하는 기능이다.
- 즉, 사용자의 언어 종류, 작업 스타일 등의 반복되는 지침을 지속적으로 반영하게 하는 개인화 설정이다.
- 이를 통해 매번 같은 프롬프트를 반복하지 않아도 일관된 스타일을 유지하게 할 수 있다.
1.1. GitHub Copilot
GitHub Copilot에서는 프로젝트에서 자동으로 로드되는 지침을 아래 경로의 파일에 작성한다.
.github/copilot-instructions.md
1.2. Gemini Code Assist
Gemini Code Assist에서는 프로젝트 지침을 아래 파일명으로 사용하고 있다.
GEMINI.md
1.3. 작성 예제
Custom Instructions의 목적은 프롬프트를 잘 만드는 것이 아니라, 매번 반복해서 쓰는 요청을 미리 설정해 두는 것이다.
## 지침
* 질문에 대한 응답은 한국어로 작성한다.
* 코드의 주석 및 출력 메시지, 설명은 영문으로 작성한다.
2. Three File System
- Three File System 은 창업가, 개발자로 활동해 온 라이언 카슨(Ryan Carson)이 제안한, 프롬프트를 구조적으로 관리하고, 문서화하기 위한 단순하지만 매우 효과적인 방법이다.
2.1. 핵심 개념
- 프로젝트 관리의 복잡도를 줄이기 위해 모든 프로젝트를 3가지 기본 파일로 단순화하는 것이다.
- 이 구조를 통해 프로젝트를 빠르게 시작하고, 유지보수와 AI 학습 부담을 최소화할 수 있다.
- 프롬프트를 잘 쓰는 방법이라기보다 프롬프트를 잘 관리하는 방법이라고 할 수 있다.
2.2. 구성 요소
무엇을 배경으로, 어떤 방식으로, 이번에는 무엇을 할지 분리해서 적는 구조이다.
prompts/
├── readme.md
├── notes.md
└── examples
├── exam1.py
└── exam2.js
2.2.1. readme
- 프로젝트의 목적, 개요, 사용법을 간단하게 정리한다.
- AI가 프로젝트를 이해하는 설명서 역할을 한다.
2.2.2. examples
- 핵심 실행 코드(MVP: Minimum Viable Product)의 예제를 담는 폴더이다.
- ex) main.py, index.js ...
- 프로젝트가 실제로 “어떻게 동작하는지”를 가장 간단하게 보여주는 부분이다.
- AI에게 예제를 제공하면 더 정확하고 일관된 출력을 생성할 수 있게 된다.
2.2.3. notes
- 아이디어, 배운 점, 느낀 점, TODO 리스트 등을 자유롭게 기록하는 파일이다.
- 개발 중 떠오르는 생각을 정리하고 프로젝트의 맥락을 남기는 용도로 활용된다.
- AI가 수행한 작업과 향후 수행해야 할 작업을 파악할 수 있게 된다.
2.3. Three File System Extend
- 이후 라이언 칼슨의 시스템을 기반으로, "PRD → 작업 리스트 → 작업 실행"의 흐름을 3개의 규칙 파일로 고정하는 것을 제안하고 있다.
- AI 협업 개발 흐름을 체계화한 프레임워크라 할 수 있다.
[출처] YouTube - A 3-step AI coding workflow for solo founders. Ryan Carson (5x founder)
3. Skills
- Claude Skills는 반복되는 프롬프트를 SKILL.md 기반의 스킬 단위로 묶어 프롬프트를 재사용 가능한 모듈 형태로 구성하는 방식이다.
- 자주 쓰는 프롬프트를 하나의 스킬로 묶어 저장하고, 필요 시 자동 또는 수동으로 불러올 수 있다.
3.1. Skill 구조
Skill은 메타데이터와 지침만 포함하는 SKILL.md 파일로 시작한다.
[출처] Claude API Docs - Skill 작성 모범 사례
pdf/
├── SKILL.md # 주요 지침 (트리거될 때 로드됨)
├── FORMS.md # 양식 작성 가이드 (필요에 따라 로드됨)
├── reference.md # API 참조 (필요에 따라 로드됨)
├── examples.md # 사용 예 (필요에 따라 로드됨)
└── scripts/
├── analyze_form.py # 유틸리티 스크립트 (로드되지 않고 실행됨)
├── fill_form.py # 양식 작성 스크립트
└── validate.py # 검증 스크립트
3.2. Skill 사용 방법
| 구분 |
Claude |
Copilot |
| 스킬 호출 방식 |
@skill:name |
/skill-name |
| 자동 로드 지정 |
SKILL.md |
.github/copilot-instructions.md |
4. Harness
- Harness는 AI 에이전트를 안전하고, 예측 가능하게 운영하기 위한 실행 구조다.
- AI를 허용된 범위 안에서 동작하게 하고, 결과를 추적하고, 문제를 지속적으로 개선하는 역할을 한다.
4.1. Harness 예제
4.1.1. Harness 적용 예제
# PDF 분석 Harness
## 목적
AI가 PDF를 분석하여 요약을 생성할 때, 일관된 출력 품질을 검증한다.
## 입력
- INPUT/sample.pdf
## 출력 형식
- JSON 형태 (title, summary, key_points 필드 포함)
## 절차
1. sample.pdf의 텍스트를 추출한다.
2. 핵심 내용 3~5개를 bullet 형태로 요약한다.
3. 결과를 JSON으로 정리한다.
4. validate.py 를 통해 EXPECTED/sample.json과 비교한다.
4.1.2. Harness 사용 여부 비교
| 미사용 |
사용 |
| 매번 다른 입력 처리 |
고정된 입력으로 일관성 확보 |
| 출력 결과 및 형식이 매번 다름 |
정해진 형식(JSON 등) 유지 |
| 작업 순서 불안정 |
RUN.md 절차대로 항상 동일 |
| 수동 확인 필요 |
스크립트로 자동 검증 |
| 같은 요청도 결과 달라짐 |
언제 실행해도 동일 결과 |
| 테스트 방식 공유 어려움 |
동일한 흐름으로 재실행 가능 |
4.2. Harness Engineering
- Harness Engineering은 AI 모델의 불확실성을 통제하는 것이며, 평가를 반복해 모델이 안정적으로 원하는 결과를 내도록 만드는 방법이다.
4.2.1. 프로젝트 구성의 예
제시된 구성은 하나의 예시에 불과하며, 고정된 방식으로 정해진 것은 아니다.
project-root/
├─ README.md # 프로젝트 개요 및 사용법
├─ harness.yaml # Harness 전역 설정
├─ harness/
│ ├─ state_manager.md # 상태 관리, 격리
│ ├─ evaluator_engine.md # 평가 루프
│ ├─ iteration_loop.md # 반복 개선 루프
│ ├─ guardrail_engine.md # 입력/출력 검증
│ └─ router.md # 모델 선택
│
└─ data/
4.2.2. 핵심 설계 원칙 (Harness Design)
- 상태 관리와 격리 (State Management & Isolation):
한 부분에서 문제가 생겨도 다른 부분에 영향을 주지 않도록 한다.
- 가드레일 및 제어 (Guardrails and Control):
AI 모델이 엉뚱한 방향으로 동작하지 않도록 미리 안전장치를 둔다.
- 피드백 루프와 반복 (Feedback Loops and Iteration):
모델이 스스로 결과를 점검해 수정하고, 필요하면 사람이 개입해 방향을 잡을 수 있는 구조를 유지한다.
- 평가 프레임워크 (Evaluation Frameworks):
실행 중에도 계속 성능을 확인하여 품질이 떨어지지 않도록 모니터링한다.
4.2.3. 평가 분리 및 반복
- 실제 일을 처리하는 모델과 그 결과를 검사하는 모델을 서로 분리한다.
- 평가를 계속 반복하면서 목표한 품질에 도달할 때까지 시스템을 꾸준히 개선한다.
