GitHub 리포지토리에서 프롬프트 구성

Completed

팁 (조언)

자세한 내용은 텍스트 및 이미지 탭을 참조하세요.

GitHub 리포지토리 조직은 팀이 프롬프트 개발에 대해 얼마나 효과적으로 찾고, 관리하고, 공동 작업할 수 있는지를 결정합니다.

고객 서비스 시나리오에서 팀은 여러 에이전트 프롬프트, 배포 스크립트 및 구성을 저장하기 위한 명확한 구조가 필요합니다. 적절한 조직을 사용하면 모든 팀 구성원이 현재 프로덕션 프롬프트를 빠르게 찾고, 이전 버전과 비교하고, 배포 프로세스를 이해할 수 있습니다.

여기서는 프롬프트에 대한 파일 형식을 선택하고, 공동 작업을 위해 리포지토리 폴더를 구성하고, 명명 규칙을 설정하고, Git 태그를 사용하여 에이전트 배포를 추적하는 방법을 알아봅니다.

프롬프트 스토리지에 대한 파일 형식 선택

파일 형식을 표준화하는 이유는 무엇인가요?

프롬프트 스토리지에 적합한 파일 형식을 선택하면 가독성, 도구 호환성, 버전 제어 효율성 및 팀 공동 작업에 영향을 줍니다. 이 형식은 기계 처리 기능과 인간의 가독성의 균형을 유지해야 합니다.

일반 텍스트(.txt) - 간단하고 효과적

일반 텍스트 파일은 간단한 프롬프트 스토리지를 제공합니다.

• 최대 단순성: 학습할 서식 복잡성 또는 특수 구문 없음
• 범용 호환성: 모든 텍스트 편집기 및 프로그래밍 언어로 작동
• 버전 제어 친화적: Git은 버전 간의 명확한 줄별 차이를 보여 줍니다.
• 직접 SDK 통합: Python 스크립트는 구문 분석 없이 파일을 직접 읽을 수 있습니다.
• 최소 종속성: 라이브러리 또는 특수 도구가 필요하지 않음

비고

Microsoft Foundry SDK 예제에서는 .txt 파일을 시스템 지침에 사용하므로, 이는 에이전트 프롬프트에 자연스럽게 선택됩니다.

Markdown (.md) - 향상된 설명서

Markdown은 더 풍부한 설명서가 필요한 경우 추가 서식 지정 기능을 제공합니다.

• 사람이 읽을 수 있는: 머리글, 목록 및 강조에 대한 간단한 서식이 있는 일반 텍스트
• 설명서 지원: 포괄적인 프롬프트 컨텍스트를 위한 테이블, 코드 블록 및 링크
• 유니버설 도구 지원: 모든 편집기, IDE 및 설명서 플랫폼에서 작동
• 균형 잡힌 접근 방식: 복잡성 없이 구조 추가

특정 요구 사항에 대한 대체 형식

• JSON(.json): 특히 프롬프트에 메타데이터 또는 여러 구성 요소가 포함된 경우 구조적 데이터 및 API 통합에 적합합니다.
• YAML(.yaml): 구성 관리 및 메타데이터 스토리지에 유용합니다.
• Python 파일(.py): 동적 콘텐츠가 있는 프로그래밍 방식 프롬프트 템플릿에 유용합니다.
• Jinja2 템플릿(.jinja2): 프롬프트에서 변수 대체를 위한 강력한 템플릿

Microsoft Foundry 호환성

Microsoft Foundry 에이전트는 주로 시스템 지침에 일반 텍스트 파일을 사용하며 에이전트를 만드는 동안 Python SDK에서 직접 읽습니다. 형식 선택은 워크플로에 따라 달라집니다.

사용 사례	권장 형식	목적
에이전트 시스템 지침	.txt 또는 .md	배포 스크립트에서 읽은 간단한 프롬프트
구성 파일	.yaml 또는 .json	환경 설정 및 메타데이터
동적 프롬프트 콘텐츠	.py 또는 .jinja2	변수 대체가 있는 템플릿
문서	.md	사람이 읽을 수 있는 프롬프트 가이드 및 표준

팁 (조언)

에이전트 프롬프트에 대한 일반 텍스트(.txt)와 설명서의 Markdown(.md)으로 시작합니다. 이 조합은 포괄적인 설명서를 유지하면서 배포 스크립트에 대한 단순성을 제공합니다. 특정 요구 사항이 요구되는 경우에만 다른 형식을 추가합니다.

리포지토리 구조에서 프롬프트 구성

버전 관리 에이전트 프롬프트의 일반적인 프로젝트 구조는 다음과 같습니다.

project-root/
├── src/
│   └── agents/
│       └── trail_guide_agent/
│           ├── trail_guide_agent.py      # Deployment script
│           └── prompts/
│               ├── v1_instructions.txt   # Version 1 prompt
│               ├── v2_instructions.txt   # Version 2 prompt
│               └── v3_instructions.txt   # Version 3 prompt
├── .env                                  # Environment configuration
└── requirements.txt                      # Python dependencies

이 구조는 다음과 같습니다.

• 배포 스크립트를 사용하여 관련 프롬프트 그룹화
• 파일 이름을 통해 버전 기록 유지 관리
• 프롬프트 진화를 나란히 비교할 수 있습니다.
• 버전 간 자동화된 테스트 지원

명명 규칙 설정

계층적 폴더 구조

잘 구성된 리포지토리를 사용하면 프롬프트 검색 및 유지 관리가 간단해집니다. Microsoft Foundry 에이전트 개발 워크플로에 따라 권장되는 구조는 다음과 같습니다.

project-root/
├── README.md                           # Project overview and setup guide
├── .env                                # Environment configuration (not committed)
├── .gitignore                          # Files to exclude from version control
├── requirements.txt                    # Python dependencies
├── src/
│   ├── agents/
│   │   ├── trail_guide_agent/
│   │   │   ├── trail_guide_agent.py    # Deployment script
│   │   │   └── prompts/
│   │   │       ├── v1_instructions.txt # Version 1 prompt
│   │   │       ├── v2_instructions.txt # Version 2 prompt
│   │   │       └── v3_instructions.txt # Version 3 prompt
│   │   ├── customer_support_agent/
│   │   │   ├── support_agent.py
│   │   │   └── prompts/
│   │   │       ├── v1_greeting.txt
│   │   │       └── v2_greeting.txt
│   │   └── content_generator/
│   │       ├── content_agent.py
│   │       └── prompts/
│   │           └── blog_post.txt
├── tests/
│   ├── test_trail_guide.py            # Automated agent tests
│   └── test_support_agent.py
├── docs/
│   ├── deployment-guide.md            # Deployment procedures
│   ├── testing-standards.md           # Quality assurance
│   └── prompt-guidelines.md           # Writing standards
├── infra/                             # Infrastructure as code
│   └── main.bicep                     # Azure resource definitions
└── .github/
    └── workflows/                     # CI/CD automation
        ├── test-agents.yml
        └── deploy-agents.yml

파일 명명 규칙:

• 설명이 포함된 소문자 이름을 사용합니다. trail_guide_agent.py
• Python 파일의 밑줄을 사용하여 단어를 구분합니다. customer_support_agent.py
• 프롬프트 파일에 v1_instructions.txt, v2_instructions.txt에 대한 버전 번호를 추가하십시오.
• 프롬프트 변형에 설명이 포함된 접미사를 사용합니다. greeting.txtescalation.txt
• 공백, 특수 문자 및 약어 방지
• 파일 형식당 일관된 파일 확장자 유지

폴더 조직 규칙:

• 에이전트 또는 함수별로 그룹화: trail_guide_agent/support_agent/
• 각 에이전트 폴더 내의 전용 prompts/ 하위 디렉터리에 프롬프트 배치
• 에이전트 루트 수준에서 배포 스크립트 유지
• 단순 계층 유지(최대 3개 수준 깊이)
• 에이전트 이름과 일치하는 명확한 설명이 포함된 폴더 이름 사용
• 별도의 소스 코드(src/), 테스트(tests/) 및 인프라(infra/)

버전 명명 패턴:

• 시맨틱 버전: v1_instructions.txt, v2_instructions.txtv3_instructions.txt
• 기능 기반: basic_greeting.txt, enhanced_greeting.txtproduction_greeting.txt
• 날짜 기반: instructions_2024_01.txt (의미 체계 버전 관리가 실용적이지 않은 경우)

비고

Microsoft Foundry는 에이전트(버전 1, 버전 2, 버전 3 등)에 증분 버전 번호를 자동으로 할당합니다. 프롬프트 파일(v1_instructions.txt, v2_instructions.txt)에 대해 유사한 증분 번호 매기기를 사용하여 파일 버전과 배포된 에이전트 버전 간에 명확한 맞춤을 만들어 추적 및 디버깅을 간소화합니다.

Git 태그를 사용하는 버전 에이전트 배포

Git 태그는 에이전트 배포에 대한 의미 체계 버전을 제공합니다. 각 에이전트 버전은 배포 중요 시점을 표시하는 Git 태그에 해당합니다.

Git 태그	프롬프트 파일	에이전트 버전	Description
v1	v1_instructions.txt	에이전트 버전 1	기본 트레일 가이드 기능
v2	v2_instructions.txt	에이전트 버전 2	개인 설정으로 향상됨
v3	v3_instructions.txt	에이전트 버전 3	고급 기능을 사용하여 프로덕션 준비

그러면 리포지토리 상태와 배포된 에이전트 간에 추적 가능한 관계가 만들어집니다.

# Deploy version 1
python trail_guide_agent.py
git add trail_guide_agent.py
git commit -m "Deploy trail guide agent V1"
git tag v1

# Deploy version 2 (after updating script to use v2_instructions.txt)
python trail_guide_agent.py
git add trail_guide_agent.py
git commit -m "Deploy trail guide agent V2"
git tag v2

팁 (조언)

Git 태그를 사용하면 배포된 에이전트에 해당하는 리포지토리 버전을 빠르게 식별하여 디버깅 및 롤백 시나리오를 간소화할 수 있습니다. 이 기본 구조는 프롬프트를 일류 코드 자산으로 처리하고 프로덕션 GenAI 시스템에 필수적인 안정적인 협업, 변경 내용 추적 및 배포 프로세스를 가능하게 하는 기초를 설정합니다.