커스텀 시스템 프롬프트

May 17, 2026 · View on GitHub

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Русский | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

이 가이드는 GAC가 커밋 메시지를 생성하는 데 사용하는 시스템 프롬프트를 커스터마이징하는 방법을 설명하며, 자체 커밋 메시지 스타일과 규칙을 정의할 수 있게 해줍니다.

목차

시스템 프롬프트란?

GAC는 커밋 메시지를 생성할 때 두 개의 프롬프트를 사용합니다:

  1. 시스템 프롬프트 (커스터마이징 가능): 커밋 메시지의 역할, 스타일 및 규칙을 정의하는 지시
  2. 사용자 프롬프트 (자동): 변경된 내용을 보여주는 git diff 데이터

시스템 프롬프트는 AI에게 커밋 메시지를 어떻게 작성할지 알려주고, 사용자 프롬프트는 무엇을 (실제 코드 변경 사항) 제공합니다.

커스텀 시스템 프롬프트를 사용하는 이유

다음 경우 커스텀 시스템 프롬프트를 원할 수 있습니다:

  • 팀이 컨벤셔널 커밋과 다른 커밋 메시지 스타일을 사용하는 경우
  • 이모지, 접두사 또는 다른 커스텀 형식을 선호하는 경우
  • 커밋 메시지에 더 많거나 적은 상세 정보를 원하는 경우
  • 회사별 가이드라인이나 템플릿이 있는 경우
  • 팀의 목소리와 톤을 일치시키고 싶은 경우
  • 다른 언어로 커밋 메시지를 원하는 경우 (아래 언어 구성 참조)

빠른 시작

  1. 커스텀 시스템 프롬프트 파일 생성:

    # 예제를 시작점으로 복사
cp custom_system_prompt.example.txt ~/.config/gac/my_system_prompt.txt

# 또는 처음부터 직접 생성
vim ~/.config/gac/my_system_prompt.txt

  2. .gac.env 파일에 추가:

    # ~/.gac.env 또는 프로젝트 레벨 .gac.env에서
GAC_SYSTEM_PROMPT_PATH=/path/to/your/custom_system_prompt.txt

  3. 테스트:

    uvx gac --dry-run

이게 전부입니다! GAC는 이제 기본값 대신 커스텀 지시를 사용합니다.

커스텀 시스템 프롬프트 작성

커스텀 시스템 프롬프트는 일반 텍스트일 수 있습니다 --- 특별한 형식이나 XML 태그가 필요 없습니다. AI가 커밋 메시지를 생성하는 방법에 대한 명확한 지시만 작성하세요.

포함할 핵심 사항:

  1. 역할 정의 - AI가 어떤 역할을 해야 하는지
  2. 형식 요구사항 - 구조, 길이, 스타일
  3. 예제 - 좋은 커밋 메시지의 모습 보여주기
  4. 제약 조건 - 피해야 할 것 또는 충족해야 할 요구사항

예제 구조:

[당신의 프로젝트/팀]을 위한 커밋 메시지 작성자입니다.

코드 변경 사항을 분석할 때 다음 커밋 메시지를 생성하세요:

1. [첫 번째 요구사항]
2. [두 번째 요구사항]
3. [세 번째 요구사항]

예제 형식:
[커밋 메시지 예제 보여주기]

전체 응답이 바로 커밋 메시지로 사용됩니다.

예제

이모지 기반 커밋 스타일

custom_system_prompt.example.txt에서 완전한 이모지 기반 예제를 확인하세요.

빠른 코드 조각:

이모지와 친근한 톤을 사용하는 커밋 메시지 작성자입니다.

각 메시지를 이모지로 시작하세요:
- 🎉 새로운 기능용
- 🐛 버그 수정용
- 📝 문서화용
- ♻️ 리팩토링용

첫 줄을 72자 이하로 유지하고 변경이 중요한 이유를 설명하세요.

팀별 규칙

엔터프라이즈 뱅킹 애플리케이션을 위한 커밋 메시지를 작성합니다.

요구사항:
1. 괄호 안에 JIRA 티켓 번호로 시작 (예: [BANK-1234])
2. 정중하고 전문적인 톤 사용
3. 관련 있는 경우 보안 영향 포함
4. 규정 준수 요구사항 참조 (PCI-DSS, SOC2 등)
5. 메시지를 간결하지만 완전하게 유지

형식:
[TICKET-123] 변경 요약

변경된 내용과 이유에 대한 상세한 설명. 포함:
- 비즈니스 근거
- 기술적 접근법
- 위험 평가 (해당하는 경우)

예제:
[BANK-1234] 로그인 엔드포인트에 속도 제한 구현

무차별 대입 공격을 방지하기 위해 Redis 기반 속도 제한 추가.
IP당 15분 동안 5회 로그인 시도로 제한.
액세스 제어를 위한 SOC2 보안 요구사항 준수.

상세한 기술 스타일

포괄적인 문서화를 생성하는 기술 커밋 메시지 작성자입니다.

각 커밋에 대해 다음을 제공하세요:

1. 명확하고 설명적인 제목 (72자 이하)
2. 빈 줄
3. WHAT: 변경된 내용 (2-3문장)
4. WHY: 변경이 필요한 이유 (2-3문장)
5. HOW: 기술적 접근법 또는 주요 구현 세부사항
6. IMPACT: 영향받는 파일/구성 요소 및 잠재적 부작용

기술적 정밀성 사용. 특정 함수, 클래스 및 모듈 참조.
현재 시제와 능동태 사용.

예제:
의존성 주입을 사용하도록 인증 미들웨어 리팩토링

WHAT: 전역 인증 상태를 주입 가능한 AuthService로 교체. 모든
라우트 핸들러를 업데이트하여 생성자 주입을 통해 AuthService를 수신하도록 함.

WHY: 전역 상태는 테스트를 어렵게 만들고 숨겨진 의존성을 생성했습니다.
의존성 주입은 테스트 용이성을 개선하고 의존성을 명시적으로 만듭니다.

HOW: AuthService 인터페이스 생성, JWTAuthService 및
MockAuthService 구현. 의존성 주입을 요구하도록 라우트 핸들러 생성자 수정.
의존성 주입 컨테이너 구성 업데이트.

IMPACT: 모든 인증된 라우트에 영향. 사용자를 위한 동작 변경 없음.
이제 MockAuthService로 테스트가 3배 빨리 실행됨.
routes/auth.ts, routes/api.ts 및 routes/admin.ts 마이그레이션 필요.

모범 사례

권장 사항

  • ✅ 구체적으로 - 명확한 지시가 더 나은 결과를 생성합니다
  • ✅ 예제 포함 - AI에게 좋은 것이 어떤 모습인지 보여주세요
  • ✅ 반복적으로 테스트 - 프롬프트를 시도하고 결과를 기반으로 개선
  • ✅ 집중적으로 유지 - 너무 많은 규칙은 AI를 혼란스럽게 할 수 있습니다
  • ✅ 일관된 용어 사용 - 전체에서 동일한 용어 사용
  • ✅ 마지막에 상기 문구 추가 - 응답이 그대로 사용될 것이라는 점을 강조

비권장 사항

  • ❌ XML 태그 사용 - 특별한 구조가 필요하지 않다면 일반 텍스트가 가장 잘 작동합니다
  • ❌ 너무 길게 만들기 - 지시는 200-500단어를 목표로 하세요
  • ❌ 자기 자신과 모순되기 - 요구사항에서 일관성 유지
  • ❌ 마지막 문구를 빼먹기 - 항상 상기: "전체 응답이 바로 커밋 메시지로 사용됩니다"

팁

  • 예제로 시작 - ../../examples/custom_system_prompt.example.txt를 복사하여 수정
  • --dry-run으로 테스트 - 커밋 없이 결과 확인
  • --show-prompt 사용 - AI에 보내진 내용 확인
  • 결과를 기반으로 개선 - 메시지가 완벽하지 않으면 지시 조정
  • 프롬프트 버전 관리 - 커스텀 프롬프트를 팀의 저장소에 보관
  • 프로젝트별 프롬프트 - 프로젝트별 스타일을 위해 프로젝트 레벨 .gac.env 사용

문제 해결

메시지에 여전히 "chore:" 접두사가 있음

문제: 커스텀 이모지 메시지에 "chore:"가 추가됩니다.

해결책: 이런 일이 일어나지 말아야 합니다 --- GAC는 커스텀 시스템 프롬프트를 사용할 때 컨벤셔널 커밋 강제를 자동으로 비활성화합니다. 이런 현상이 보이면 이슈를 제출해주세요.

AI가 내 지시를 무시함

문제: 생성된 메시지가 커스텀 형식을 따르지 않습니다.

해결책:

  1. 지시를 더 명시적이고 구체적으로 만드세요
  2. 원하는 형식의 명확한 예제 추가
  3. 다음으로 끝내기: "전체 응답이 바로 커밋 메시지로 사용됩니다"
  4. 요구사항 수 줄이기 --- 너무 많으면 AI를 혼란스럽게 할 수 있습니다
  5. 다른 모델 시도 (일부가 지시를 더 잘 따름)

메시지가 너무 길거나 짧음

문제: 생성된 메시지가 길이 요구사항과 일치하지 않습니다.

해결책:

  • 길이를 명시적으로 지정 (예: "메시지를 50자 이하로 유지")
  • 원하는 정확한 길이의 예제 보여주기
  • 짧은 메시지를 위해 --one-liner 플래그도 사용 고려

커스텀 프롬프트가 사용되지 않음

문제: GAC가 여전히 기본 커밋 형식을 사용합니다.

해결책:

  1. GAC_SYSTEM_PROMPT_PATH가 올바르게 설정되었는지 확인:

    uvx gac config get GAC_SYSTEM_PROMPT_PATH

  2. 파일 경로가 존재하고 읽기 가능한지 확인:

    cat "$GAC_SYSTEM_PROMPT_PATH"

  3. 이 순서로 .gac.env 파일 확인:

    • 프로젝트 레벨: ./.gac.env
    • 사용자 레벨: ~/.gac.env

  4. 상대 경로 대신 절대 경로 시도

언어 구성

참고: 커밋 메시지 언어를 변경하기 위해 커스텀 시스템 프롬프트가 필요하지 않습니다!

표준 컨벤셔널 커밋 형식은 유지하면서 커밋 메시지 언어만 변경하려면 대화형 언어 선택기를 사용하세요:

uvx gac language

이것은 25개 이상의 언어를 원본 스크립트 (Español, Français, 日本語 등)로 표시하는 대화형 메뉴를 제시합니다. 선호하는 언어를 선택하면 ~/.gac.env 파일에 GAC_LANGUAGE를 자동으로 설정합니다.

또는 수동으로 언어를 설정할 수 있습니다:

# ~/.gac.env 또는 프로젝트 레벨 .gac.env에서
GAC_LANGUAGE=Spanish

기본적으로 컨벤셔널 커밋 접두사 (feat:, fix: 등)는 changelog 도구 및 CI/CD 파이프라인과의 호환성을 위해 영어로 유지되며, 다른 모든 텍스트는 지정된 언어로 됩니다.

접두사도 번역하고 싶으신가요? .gac.env에서 GAC_TRANSLATE_PREFIXES=true를 설정하여 전체 현지화:

GAC_LANGUAGE=Spanish
GAC_TRANSLATE_PREFIXES=true

이것은 접두사 (예: fix: 대신 corrección:)를 포함한 모든 것을 번역합니다.

언어 변경이 유일한 커스터마이징 요구라면 커스텀 시스템 프롬프트를 만드는 것보다 더 간단합니다.

기본값으로 다시 전환하고 싶음

문제: 일시적으로 기본 프롬프트를 사용하고 싶습니다.

해결책:

# 옵션 1: 환경 변수 설정 해제
uvx gac config unset GAC_SYSTEM_PROMPT_PATH

# 옵션 2: .gac.env에서 주석 처리
# GAC_SYSTEM_PROMPT_PATH=/path/to/custom_prompt.txt

# 옵션 3: 특정 프로젝트를 위해 다른 .gac.env 사용

관련 문서

도움이 필요하신가요?

  • 이슈 보고: GitHub Issues
  • 커스텀 프롬프트 공유: 기여 환영!