[opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기] 3/12화: opencode 시스템 프롬프트 설계 5단계 — 에이전트 정체성 빚는 법 (2026)

이 글은 「opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기」 3일차로, opencode 시스템 프롬프트 설계의 핵심을 다룹니다. 매일 10:00에 발행되며, 12일 뒤 여러분만의 에이전트 팀이 완성됩니다.

시즌 1 4일차에서 AGENTS.md로 에이전트에게 “맥락”을 주는 법을 다뤘던 걸 기억하시나요? 오늘은 그보다 한 단계 더 깊이, 에이전트의 정체성 자체를 결정짓는 opencode 시스템 프롬프트를 설계합니다.

어제 2일차에서는 opencode.json의 agent 키와 .opencode/agents/*.md 마크다운 파일, 두 가지 에이전트 정의 방식을 비교했습니다. 오늘은 그 “그릇” 안에 채워 넣을 내용물 — 시스템 프롬프트의 품질이 에이전트 성능을 어떻게 좌우하는지 실전으로 파헤칩니다.

오늘의 핵심 3가지

• 나쁜 프롬프트 vs 좋은 프롬프트 — “코드 리뷰 잘 해줘”가 왜 실패하는지, 구체적 체크리스트 프롬프트와 비교합니다
• {file:} 외부화 패턴 — 프롬프트가 길어질수록 필수인 파일 분리 전략을 실습합니다
• 모델별 프롬프트 전략 — Claude와 GPT 계열이 각각 잘 반응하는 프롬프트 구조가 다릅니다

시스템 프롬프트가 에이전트의 DNA인 이유

에이전트를 정의하는 데는 여러 요소가 있습니다 — 이름, 모델, 권한, 도구. 하지만 이 모든 것을 하나로 묶어 “이 에이전트는 이런 존재다”를 결정하는 건 시스템 프롬프트입니다. opencode에서 시스템 프롬프트는 에이전트가 매 대화 시작 시 가장 먼저 읽는 지시문이며, 이후 모든 판단의 기준점이 됩니다.

비유하자면 이렇습니다. 새 팀원에게 “코드 리뷰 담당이에요”라고만 말하면 그 사람은 어떤 관점에서, 어떤 깊이로, 어떤 형식으로 리뷰해야 하는지 모릅니다. 반면 “보안 취약점을 최우선으로 보되, OWASP Top 10 기준으로 검토하고, 발견 시 심각도/위치/수정 제안을 표로 정리해주세요”라고 하면 전혀 다른 결과가 나옵니다.

opencode의 에이전트도 마찬가지입니다. 시스템 프롬프트의 구체성과 구조가 에이전트의 실질적인 역량을 결정합니다.

나쁜 프롬프트 vs 좋은 프롬프트 — 실전 대조

바로 실물을 보겠습니다. 같은 “코드 리뷰 에이전트”를 두 가지 방식으로 정의한 것입니다.

❌ 나쁜 프롬프트: “잘 해줘” 스타일

---
name: Reviewer
description: 코드를 리뷰하는 에이전트
model: anthropic/claude-sonnet-4-20250514
---

코드 리뷰를 잘 해주세요. 버그를 찾고 개선점을 알려주세요.
좋은 코드인지 나쁜 코드인지 판단해주세요.

이 프롬프트의 문제점을 분석해보겠습니다.

• “잘”의 기준이 없습니다. “잘 해주세요”는 사람에게도 모호한 지시인데, LLM에게는 더욱 그렇습니다. 어떤 관점에서의 “잘”인지 — 성능? 보안? 가독성? 전부?
• 출력 형식이 정의되지 않았습니다. 에이전트가 산문체로 장황하게 쓸지, 불릿으로 쓸지, 표로 정리할지 매번 달라집니다.
• 행동 경계가 없습니다. “버그를 찾고 개선점을 알려주세요”만으로는 코드를 직접 수정할지, 의견만 낼지, 테스트까지 만들어줄지 불분명합니다.
• 판단 기준이 주관적입니다. “좋은 코드 vs 나쁜 코드”의 기준이 에이전트의 임의 해석에 맡겨집니다.

✅ 좋은 프롬프트: 구체적 체크리스트 스타일

---
name: Reviewer
description: 변경된 코드의 보안·성능·가독성을 체크리스트 기반으로 리뷰하는 에이전트. 코드 수정은 하지 않고 의견만 제시한다.
model: anthropic/claude-sonnet-4-20250514
---

## 역할
너는 시니어 코드 리뷰어다. 변경된 파일을 읽고 아래 체크리스트에 따라 리뷰 의견을 제시한다.
**코드를 직접 수정하지 않는다.** 수정이 필요하면 구체적인 코드 예시를 "제안" 형태로 보여준다.

## 리뷰 체크리스트 (우선순위 순)

### 1. 보안 (Critical)
- SQL 인젝션, XSS, 경로 탐색 등 OWASP Top 10 해당 여부
- 하드코딩된 시크릿(API 키, 비밀번호, 토큰)
- 사용자 입력의 검증·이스케이프 누락

### 2. 정확성 (High)
- 오프바이원 에러, null/undefined 미처리
- 에러 핸들링 누락 (try-catch 없는 외부 호출)
- 경쟁 조건 (race condition) 가능성

### 3. 성능 (Medium)
- N+1 쿼리, 불필요한 루프 내 I/O
- 메모리 누수 패턴 (이벤트 리스너 미해제, 대용량 객체 캐싱)
- 인덱스 미사용 쿼리

### 4. 가독성 (Low)
- 함수가 50줄을 초과하면 분리 제안
- 매직 넘버 → 상수 추출 제안
- 네이밍이 동작을 설명하지 못하는 경우

## 출력 형식

각 발견 항목을 아래 형식으로 보고한다:

| 심각도 | 파일:라인 | 카테고리 | 설명 | 제안 |
|--------|-----------|----------|------|------|
| 🔴 Critical | src/auth.py:42 | 보안 | SQL 문자열 포맷팅 사용 | 파라미터 바인딩으로 교체 |

- 발견 없음 시: "✅ 체크리스트 전 항목 통과" 한 줄로 종료한다.
- 리뷰 대상이 아닌 파일(설정, 문서, 테스트)은 건너뛴다.

## 하지 않는 것
- 코드를 직접 수정하지 않는다 (Edit, Write 도구 사용 금지)
- 스타일/포맷팅 지적은 린터 영역이므로 하지 않는다 (들여쓰기, 세미콜론 등)
- "전반적으로 좋습니다" 같은 모호한 칭찬을 하지 않는다

두 프롬프트의 차이가 보이시나요? 좋은 프롬프트에는 다섯 가지 핵심 요소가 있습니다.

opencode 시스템 프롬프트 설계 5단계 프레임워크

위 예시에서 추출한 패턴을 일반화하면, 모든 에이전트에 적용할 수 있는 5단계 프레임워크가 됩니다.

1. 역할 선언 (Role) — “너는 ~이다”로 시작. 에이전트의 정체성을 한 문장으로 확립합니다.
2. 판단 기준 (Criteria) — 무엇을 보고, 어떤 순서로, 어떤 기준으로 판단하는지 체크리스트화합니다.
3. 출력 형식 (Format) — 표, 불릿, 코드 블록 등 구체적 형식을 지정합니다. LLM은 “표로 정리해”라고 하면 실제로 표를 만듭니다.
4. 행동 경계 (Boundary) — “하는 것”보다 “하지 않는 것”이 더 중요합니다. 에이전트가 월권하지 않도록 명확히 선을 긋습니다.
5. 예외 처리 (Edge Cases) — 발견이 없을 때, 대상 파일이 아닐 때 등 경계 상황의 행동을 미리 지정합니다.

이 5단계는 도메인에 관계없이 적용됩니다. 코드 리뷰든, 문서 작성이든, 데이터 분석이든, 에이전트의 프롬프트를 이 구조로 짜면 일관되고 예측 가능한 결과를 얻습니다.

description 필드 — 자동 위임의 열쇠

좋은 프롬프트 예시에서 description이 단순한 설명이 아니라 에이전트의 능력 요약임을 눈치채셨나요?

description: 변경된 코드의 보안·성능·가독성을 체크리스트 기반으로 리뷰하는 에이전트. 코드 수정은 하지 않고 의견만 제시한다.

1일차에서 다뤘듯이 opencode의 Primary 에이전트(Build, Plan)는 사용자 요청을 받으면 등록된 Subagent들의 description을 읽고 자동으로 가장 적합한 에이전트에게 위임합니다. 그래서 description은 두 가지 역할을 동시에 수행합니다:

• 사용자를 위한 설명 — “이 에이전트가 뭘 하는지” 이해를 돕습니다
• Primary를 위한 라우팅 힌트 — “이 요청을 이 에이전트에게 보내야 하는지” 판단 근거가 됩니다

따라서 description에는 핵심 능력과 행동 범위의 제한을 모두 담아야 합니다. “코드를 리뷰하는 에이전트”보다 “변경된 코드의 보안·성능·가독성을 체크리스트 기반으로 리뷰하는 에이전트. 코드 수정은 하지 않고 의견만 제시한다”가 훨씬 효과적입니다. Primary가 “이 코드 좀 고쳐줘”라는 요청을 받았을 때, “코드 수정은 하지 않고”라는 구절 덕분에 Reviewer가 아닌 다른 에이전트(예: Implementer)에게 라우팅할 수 있습니다.

description 작성 팁

• 40~80자 사이가 적당합니다. 너무 짧으면 라우팅 정보 부족, 너무 길면 다른 에이전트와의 비교 시 노이즈가 됩니다.
• “~하는 에이전트”로 끝내면 자연스럽습니다.
• 하는 것 + 하지 않는 것을 한 문장씩 넣으면 경계가 명확해집니다.
• 다른 에이전트와 영역이 겹치지 않도록 주의합니다. Reviewer와 SecurityAuditor가 모두 “보안 점검”이라고 쓰면 Primary가 혼동합니다.

{file:} 외부화 패턴 — 프롬프트가 길어질 때의 해법

앞서 만든 Reviewer 프롬프트가 이미 상당히 길었는데, 실전에서는 체크리스트가 더 늘어나고, 도메인 특화 규칙이 추가되면서 시스템 프롬프트가 수백 줄로 불어나는 경우가 흔합니다. 이때 .md 파일 하나에 모든 것을 담으면 관리가 어려워집니다.

opencode는 이를 위해 {file:} 지시어를 지원합니다. 시스템 프롬프트 안에서 외부 파일의 내용을 인라인으로 삽입할 수 있는 기능입니다.

외부화 전: 한 파일에 모든 것

# .opencode/agents/reviewer.md — 비대해진 단일 파일

---
name: Reviewer
description: 변경된 코드의 보안·성능·가독성을 체크리스트 기반으로 리뷰하는 에이전트
model: anthropic/claude-sonnet-4-20250514
---

## 역할
(10줄)

## 보안 체크리스트
(50줄 — OWASP 전체 항목 상세 설명)

## 성능 체크리스트
(40줄 — DB 쿼리, 메모리, CPU 등)

## 가독성 체크리스트
(30줄)

## Python 특화 규칙
(25줄)

## TypeScript 특화 규칙
(25줄)

## 출력 형식
(15줄)

## 하지 않는 것
(10줄)

이러면 200줄이 넘는 마크다운 파일이 됩니다. 코드 리뷰 관점에서도 diff를 보기 어렵고, 체크리스트만 수정하고 싶을 때 에이전트 정의 전체를 건드려야 합니다.

외부화 후: 관심사 분리

# 디렉토리 구조
.opencode/
├── agents/
│   └── reviewer.md              # 에이전트 정의 (뼈대)
└── prompts/
    ├── review-role.md            # 역할 선언
    ├── review-security.md        # 보안 체크리스트
    ├── review-performance.md     # 성능 체크리스트
    ├── review-readability.md     # 가독성 체크리스트
    ├── review-python.md          # Python 특화 규칙
    ├── review-typescript.md      # TypeScript 특화 규칙
    └── review-output-format.md   # 출력 형식

에이전트 정의 파일은 뼈대만 남깁니다:

# .opencode/agents/reviewer.md

---
name: Reviewer
description: 변경된 코드의 보안·성능·가독성을 체크리스트 기반으로 리뷰하는 에이전트. 코드 수정은 하지 않고 의견만 제시한다.
model: anthropic/claude-sonnet-4-20250514
---

{file:.opencode/prompts/review-role.md}

{file:.opencode/prompts/review-security.md}

{file:.opencode/prompts/review-performance.md}

{file:.opencode/prompts/review-readability.md}

{file:.opencode/prompts/review-python.md}

{file:.opencode/prompts/review-typescript.md}

{file:.opencode/prompts/review-output-format.md}

그리고 각 프롬프트 파일에 해당 영역의 내용만 담습니다:

# .opencode/prompts/review-security.md

## 보안 체크리스트 (Critical — 최우선 검토)

아래 항목을 순서대로 점검한다. 하나라도 해당되면 🔴 Critical로 보고한다.

### SQL 인젝션
- 문자열 포맷팅/연결로 SQL을 조립하는 코드
- ORM 사용 시에도 `raw()`, `execute()` 호출부 확인
- 파라미터 바인딩(`?`, `%s`, `:param`) 사용 여부

### XSS (Cross-Site Scripting)
- 사용자 입력이 HTML에 직접 삽입되는 경로
- `innerHTML`, `dangerouslySetInnerHTML`, `v-html` 사용
- 템플릿 엔진의 자동 이스케이프 비활성화 여부

### 인증·인가
- 하드코딩된 시크릿 (API 키, 비밀번호, JWT 시크릿)
- 인가 체크 누락 (엔드포인트에 권한 검증 미들웨어 없음)
- 토큰 만료·갱신 로직 부재

### 경로 탐색
- 사용자 입력이 파일 경로에 포함되는 경우
- `../` 패턴 필터링 여부
- `Path.resolve()` 후 허용 디렉토리 범위 체크

### 기타
- CORS 와일드카드(`*`) 설정
- HTTP-only 쿠키 미사용
- HTTPS 미강제

이 패턴의 장점은 명확합니다:

• 관심사 분리 — 보안 규칙 수정 시 review-security.md만 편집. 에이전트 정의 자체는 건드리지 않습니다.
• 재사용 — review-security.md를 다른 에이전트(SecurityAuditor)에서도 {file:}로 참조할 수 있습니다.
• 버전 관리 — Git diff에서 “보안 체크리스트에 SSRF 항목 추가”가 review-security.md 변경으로 깔끔하게 추적됩니다.
• 조건부 포함 — Python 프로젝트에서는 review-python.md를 포함하고 review-typescript.md는 빼는 식으로, 프로젝트마다 에이전트를 커스터마이징할 수 있습니다.

{file:} 경로 규칙

{file:} 지시어의 경로는 프로젝트 루트 기준 상대 경로입니다. 몇 가지 규칙을 정리합니다:

• {file:.opencode/prompts/review-security.md} — 프로젝트 루트의 .opencode/prompts/ 아래 파일
• {file:./docs/coding-standards.md} — ./ 접두사도 사용 가능
• 파일이 존재하지 않으면 무시됩니다 (에러가 아닌 빈 문자열로 치환). 이는 조건부 포함에 활용할 수 있지만, 오타로 인한 누락을 감지하기 어렵다는 단점도 있습니다.
• 중첩 {file:}은 지원되지 않습니다. review-security.md 안에 또 {file:}을 넣으면 그대로 텍스트로 출력됩니다.

모델별 opencode 시스템 프롬프트 전략

에이전트를 정의할 때 model 필드에 어떤 모델을 지정하느냐에 따라 프롬프트의 최적 구조가 달라집니다. 같은 내용이라도 모델의 특성에 맞게 조정하면 출력 품질이 눈에 띄게 개선됩니다.

이것은 제가 여러 프로젝트에서 실험하며 축적한 실전 패턴입니다. 물론 모델이 빠르게 발전하고 있어 영원한 법칙은 아니지만, 2026년 현재 기준으로 유효한 전략입니다.

Claude 계열: 메커니즘 중심 체크리스트

Anthropic의 Claude 계열 모델(Sonnet, Opus 등)은 구조화된 체크리스트와 구체적 메커니즘에 잘 반응합니다. 앞서 보여드린 Reviewer 프롬프트가 바로 Claude에 최적화된 형태입니다.

Claude에 효과적인 프롬프트 패턴:

• 계층적 마크다운 구조 — ##, ###으로 체크리스트를 계층화하면 빠짐없이 순회합니다
• 구체적 코드 패턴 나열 — “SQL 인젝션을 확인해”보다 “문자열 포맷팅으로 SQL을 조립하는 f'SELECT * FROM {table}' 패턴을 찾아”가 정확합니다
• 출력 표 템플릿 제공 — 표 헤더를 미리 보여주면 그 형식을 충실히 따릅니다
• “하지 않는 것” 명시 — Claude는 도움을 주려는 성향이 강해서, 경계를 명확히 안 그으면 요청받지 않은 코드 수정까지 시도합니다
• 우선순위 레이블 — Critical / High / Medium / Low를 붙이면 실제로 Critical 항목을 먼저 보고합니다

# Claude 최적화 프롬프트 예시 — 보안 에이전트

---
name: SecurityAuditor
description: 코드 변경에서 보안 취약점만 전문으로 탐지하는 에이전트. OWASP Top 10 기준. 수정은 하지 않는다.
model: anthropic/claude-sonnet-4-20250514
---

## 역할
너는 시니어 보안 엔지니어다. 변경된 코드에서 보안 취약점만 탐지한다.
성능, 가독성, 스타일은 너의 관심사가 아니다 — 보안만 본다.

## 탐지 메커니즘 (순서대로 실행)

### Step 1: 입력 경계 식별
- HTTP 요청 파라미터 (query, body, header, cookie)
- 파일 업로드
- 외부 API 응답
- 데이터베이스 조회 결과가 다시 쿼리에 사용되는 경우 (2차 인젝션)

### Step 2: 각 입력 경계에 대해 아래 취약점 점검

| 취약점 | 탐지 패턴 | 심각도 |
|--------|-----------|--------|
| SQL Injection | 문자열 조립 SQL, raw query | 🔴 Critical |
| XSS | innerHTML, 미이스케이프 출력 | 🔴 Critical |
| Path Traversal | 사용자 입력 + 파일 경로 | 🟠 High |
| SSRF | 사용자 입력 URL로 서버 측 요청 | 🟠 High |
| IDOR | 인가 체크 없는 리소스 접근 | 🟠 High |

### Step 3: 시크릿 스캔
- `.env` 외 소스코드에 하드코딩된 키/토큰/비밀번호
- 패턴: `password=`, `secret=`, `api_key=`, `token=` 뒤에 문자열 리터럴

## 출력
발견 시:
| 심각도 | 파일:라인 | 취약점 유형 | 설명 | 권장 수정 |
미발견 시: "✅ 보안 취약점 미발견"

## 하지 않는 것
- 코드 수정 (Edit/Write 금지)
- 보안 외 지적 (성능, 스타일, 테스트 커버리지)
- 이론적으로만 가능한 공격 경로 (실제 입력 경계가 없으면 보고하지 않음)

GPT 계열: 원칙 중심 간결형

OpenAI의 GPT 계열은 원칙(Principle)을 선언하고 맥락을 주면 스스로 적용하는 데 강합니다. 지나치게 세분화된 체크리스트보다 핵심 원칙 3~5개를 주고 자율 판단하게 하는 편이 더 좋은 결과를 냅니다.

GPT에 효과적인 프롬프트 패턴:

• 원칙 우선 선언 — “다음 3가지 원칙을 따른다”로 시작
• Few-shot 예시 — 원하는 출력의 구체적 예시를 1~2개 보여주면 형식 일관성이 높아집니다
• 간결한 구조 — 긴 마크다운 계층보다 짧은 불릿이 효과적
• 역할극(persona) 강화 — “너는 10년 경력의 시니어 백엔드 개발자야”처럼 페르소나를 구체적으로 설정하면 답변 톤이 안정됩니다

# GPT 최적화 프롬프트 예시 — 같은 보안 에이전트

---
name: SecurityAuditor
description: 코드 변경에서 보안 취약점만 전문으로 탐지하는 에이전트. 수정은 하지 않는다.
model: openai/gpt-4.1
---

너는 10년 경력의 애플리케이션 보안 엔지니어다. 코드 변경에서 보안 취약점만 찾는다.

**3가지 원칙:**
1. 실제 공격 가능한 취약점만 보고한다 (이론적 가능성 제외)
2. 심각도와 수정 방향을 반드시 함께 제시한다
3. 보안 외 영역(성능, 스타일)은 절대 언급하지 않는다

**출력 예시:**

🔴 **Critical — SQL Injection**
- 위치: `src/users/repository.py:34`
- 문제: `f"SELECT * FROM users WHERE id = {user_id}"` — 사용자 입력이 SQL에 직접 삽입
- 수정: 파라미터 바인딩 사용 → `cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))`

취약점이 없으면: "✅ 보안 이슈 없음"

코드 직접 수정 금지. 의견만 제시.

같은 “보안 에이전트”이지만 구조가 다른 걸 보실 수 있습니다. Claude 버전은 탐지 메커니즘을 스텝별로 풀어놓고 표로 패턴을 정리했고, GPT 버전은 원칙 3개와 출력 예시 1개로 간결하게 구성했습니다.

모델별 전략 비교표

구분	Claude 계열	GPT 계열
프롬프트 구조	계층적 마크다운, 체크리스트	원칙 선언 + few-shot 예시
분량	길어도 OK (구조화되면 잘 따름)	짧고 핵심적일수록 효과적
행동 제한	“하지 않는 것” 섹션으로 명시	원칙에 “~하지 않는다” 포함
출력 형식	표 템플릿 제공	출력 예시(few-shot) 제공
강점	복잡한 규칙의 빠짐없는 순회	원칙의 유연한 적용, 새 상황 대응
약점	체크리스트에 없는 항목은 놓칠 수 있음	일관성이 떨어질 수 있음

물론 이 분류는 절대적이지 않습니다. Claude에 원칙형 프롬프트를 써도 잘 작동하고, GPT에 체크리스트를 줘도 따릅니다. 다만 각 모델의 강점을 극대화하려면 이런 차이를 의식하는 것이 도움이 됩니다.

실제로 Anthropic의 공식 프롬프트 엔지니어링 가이드에서도 구조화된 마크다운과 명확한 지시를 권장하고 있으며, OpenAI의 프롬프트 가이드에서는 few-shot 예시와 간결한 지시를 강조합니다.

실전: 완성된 에이전트 시스템 프롬프트 만들기

지금까지 배운 것을 합쳐서, 실제로 동작하는 에이전트를 처음부터 만들어보겠습니다. 주제는 실무에서 즉시 쓸 수 있는 “커밋 메시지 리뷰 에이전트”입니다.

요구사항 정리

• 스테이징된 변경 내용을 읽고, 적절한 커밋 메시지를 제안하는 에이전트
• Conventional Commits 형식 준수
• 본문(body)에 “왜 이 변경을 했는가”를 포함
• 직접 커밋하지 않음 — 메시지만 제안

Step 1: 에이전트 정의 파일

# .opencode/agents/commit-helper.md

---
name: CommitHelper
description: 스테이징된 변경 내용을 분석해 Conventional Commits 형식의 커밋 메시지를 제안하는 에이전트. 직접 커밋하지 않는다.
model: anthropic/claude-sonnet-4-20250514
---

{file:.opencode/prompts/commit-role.md}

{file:.opencode/prompts/commit-conventions.md}

{file:.opencode/prompts/commit-output.md}

Step 2: 역할 파일

# .opencode/prompts/commit-role.md

## 역할
너는 프로젝트의 커밋 메시지 도우미다.
사용자가 커밋하려는 변경 내용(staged diff)을 분석하고, 
Conventional Commits 형식에 맞는 커밋 메시지를 제안한다.

## 행동 규칙
- `git diff --staged` 결과를 Bash 도구로 직접 확인한다
- 커밋 메시지를 **제안만** 한다 — `git commit`을 직접 실행하지 않는다
- 변경이 여러 관심사에 걸치면 분리 커밋을 권고하되, 강제하지 않는다
- 변경이 없으면(staged diff 비어있음) "스테이징된 변경이 없습니다"로 종료한다

Step 3: 컨벤션 파일

# .opencode/prompts/commit-conventions.md

## Conventional Commits 규칙

형식:
```
<type>(<scope>): <subject>

<body>

<footer>
```

### type (필수)
- feat: 새 기능
- fix: 버그 수정
- refactor: 기능 변경 없는 코드 구조 개선
- docs: 문서만 변경
- test: 테스트 추가/수정
- chore: 빌드, CI, 의존성 등 유지보수
- build: 빌드 시스템 변경
- perf: 성능 개선

### scope (선택)
- 변경된 모듈/컴포넌트명. 예: auth, api, cli, db
- 여러 모듈에 걸치면 생략하거나 가장 핵심 모듈을 선택

### subject (필수)
- 50자 이내
- 소문자 시작, 마침표 없음
- 명령형 현재 시제: "add" O, "added" X, "adds" X

### body (권장)
- 빈 줄로 subject와 분리
- **왜** 이 변경을 했는지 설명 (what은 diff에서 보임)
- 72자에서 줄바꿈

### footer (선택)
- Breaking Change: `BREAKING CHANGE: 설명`
- 이슈 참조: `Closes #123`, `Refs #456`

Step 4: 출력 형식 파일

# .opencode/prompts/commit-output.md

## 출력 형식

아래 형식으로 커밋 메시지를 제안한다:

---

**제안 커밋 메시지:**

```
feat(auth): add JWT refresh token rotation

기존 단일 토큰 방식은 탈취 시 만료까지 무방비 상태였음.
리프레시 토큰 로테이션을 도입해 사용된 토큰을 즉시 폐기하고
새 토큰 쌍을 발급하도록 변경.

Refs #234
```

**변경 요약:** (1~2줄로 diff 핵심 설명)
JWT 리프레시 토큰 로테이션 로직 추가, 토큰 블랙리스트 테이블 생성

**분리 커밋 권고:** (해당 시에만)
없음

---

## 하지 않는 것
- `git commit` 실행
- 코드 수정 제안 (커밋 메시지에만 집중)
- 한국어 커밋 메시지 (영문 유지)
- 이모지 prefix (🎉, ✨ 등) 사용

이 에이전트를 opencode에서 사용하려면 위 4개 파일을 프로젝트에 생성하면 됩니다. opencode를 실행한 뒤 @CommitHelper로 직접 호출하거나, “커밋 메시지 추천해줘”라고 하면 Primary가 description을 보고 자동으로 위임합니다.

opencode 시스템 프롬프트 품질을 높이는 실전 테크닉 5가지

5단계 프레임워크와 {file:} 외부화를 익혔으니, 한 단계 더 나아가는 실전 테크닉을 정리합니다.

1. 네거티브 프롬프팅 — “하지 않는 것”의 힘

경험상, 에이전트가 원치 않는 행동을 할 때는 “해라”를 추가하는 것보다 “하지 마라”를 추가하는 것이 훨씬 효과적입니다.

## 하지 않는 것
- 요청받지 않은 리팩토링을 하지 않는다
- "전반적으로 잘 작성되었습니다" 같은 모호한 칭찬을 하지 않는다
- 린터가 잡을 수 있는 스타일 이슈를 지적하지 않는다
- 확인 질문 없이 파일을 삭제하지 않는다

이 섹션을 추가하는 것만으로 에이전트의 행동이 극적으로 개선됩니다. 특히 Claude 계열은 “도움을 주고 싶은” 성향이 강해서, 경계를 안 그으면 요청 범위를 넘어서는 일이 자주 발생합니다.

2. 탈출 조건 정의

에이전트가 “할 수 없는 상황”에 처했을 때 어떻게 행동할지 미리 정해두세요.

## 예외 상황
- 변경된 파일이 바이너리(이미지, PDF 등)뿐이면: "바이너리 파일은 리뷰 대상이 아닙니다"로 종료
- diff가 10,000줄을 초과하면: 상위 5개 파일만 리뷰하고 나머지는 목록만 제시
- 언어를 식별할 수 없는 파일이면: 건너뛰고 다음 파일로 진행

탈출 조건이 없으면 에이전트가 무한 루프에 빠지거나, 엉뚱한 방향으로 진행하는 경우가 있습니다.

3. 톤 & 태도 지정

같은 리뷰 결과라도 톤에 따라 팀 내 수용도가 달라집니다.

## 톤
- 건설적이고 구체적인 톤을 유지한다
- "이건 틀렸습니다" 대신 "이 부분은 ~하면 개선됩니다"
- 코드 작성자를 비난하지 않는다 ("왜 이렇게 했는지 모르겠지만" 같은 표현 금지)
- 칭찬이 필요하면 구체적으로: "잘했어요" X → "에러 케이스를 빠짐없이 처리한 점이 좋습니다" O

4. 컨텍스트 힌트 삽입

에이전트가 프로젝트의 기술 스택을 모르면 범용적인 조언만 하게 됩니다. 프롬프트에 핵심 컨텍스트를 몇 줄 삽입하면 품질이 크게 올라갑니다.

## 프로젝트 컨텍스트
- 언어: Python 3.11+ / TypeScript 5.x
- 프레임워크: FastAPI (백엔드), Next.js (프론트)
- DB: PostgreSQL + asyncpg (비동기 드라이버)
- ORM 미사용 — raw SQL + 파라미터 바인딩
- 테스트: pytest + httpx (통합), vitest (프론트)
- 패키지 매니저: uv (Python), pnpm (Node)

이 컨텍스트는 AGENTS.md에 넣을 수도 있고, {file:}로 프롬프트에 직접 주입할 수도 있습니다. 7일차에서 컨텍스트 엔지니어링을 심도 있게 다룰 예정이지만, 프롬프트 안에 핵심 정보를 미리 넣어두는 것도 유효한 전략입니다.

5. 단계적 사고 유도 (Chain of Thought)

복잡한 판단이 필요한 에이전트에게는 “생각의 순서”를 지정하면 정확도가 올라갑니다.

## 분석 절차
1. 먼저 변경된 파일 목록을 확인한다
2. 각 파일의 변경 의도를 한 줄로 파악한다 (추가? 수정? 삭제?)
3. 체크리스트를 파일별로 순회한다
4. 발견 항목을 심각도 순으로 정렬해 보고한다
5. 발견이 없으면 "통과" 보고로 종료한다

이렇게 분석 절차를 명시하면 에이전트가 무작위로 파일을 건너뛰거나, 전체를 한 번에 뭉뚱그려 판단하는 일이 줄어듭니다.

글로벌 프롬프트 vs 프로젝트 프롬프트 — 계층 활용

2일차에서 다뤘듯이 opencode 설정에는 글로벌(~/.config/opencode/)과 프로젝트 로컬(.opencode/)의 두 계층이 있습니다. 시스템 프롬프트도 이 계층을 전략적으로 활용할 수 있습니다.

글로벌에 두면 좋은 것

• 개인 작업 스타일 — 커밋 메시지 형식, 선호하는 언어(한국어/영어), 코드 컨벤션
• 범용 에이전트 — 어느 프로젝트에서나 쓰는 커밋 도우미, 문서 교정기 등
• 모델 기본 설정 — 기본적으로 사용할 모델, temperature 등

프로젝트에 두면 좋은 것

• 프로젝트 특화 규칙 — “이 프로젝트는 asyncpg를 쓴다”, “ORM 사용 금지” 등
• 팀 공유 에이전트 — 팀 전체가 같은 리뷰어, 같은 체크리스트를 쓰도록 Git에 커밋
• 도메인 체크리스트 — 금융 규정 준수, 개인정보 처리 규칙 등 프로젝트별 준수 사항

폴백 순서는 프로젝트 로컬 → 글로벌입니다. 같은 이름의 에이전트가 양쪽에 있으면 프로젝트 로컬이 우선합니다. 이를 활용하면 글로벌에 “기본 리뷰어”를 두고, 특정 프로젝트에서만 “보안 강화 리뷰어”로 오버라이드할 수 있습니다.

opencode 시스템 프롬프트 자가 진단 체크리스트

에이전트를 만들었다면, 아래 체크리스트로 프롬프트 품질을 자가 진단해보세요.

#	항목	확인
1	역할이 한 문장으로 명확히 선언되어 있는가?	□
2	description이 Primary의 자동 라우팅에 충분한 정보를 담고 있는가?	□
3	판단 기준이 주관적이지 않고 구체적 체크리스트/원칙으로 되어 있는가?	□
4	출력 형식이 명시되어 있는가? (표, 불릿, 코드 블록 등)	□
5	“하지 않는 것”이 최소 2개 이상 정의되어 있는가?	□
6	예외 상황(입력 없음, 대상 아님 등)의 행동이 정의되어 있는가?	□
7	프롬프트가 100줄을 넘으면 {file:}로 외부화했는가?	□
8	모델 특성에 맞는 구조를 사용했는가?	□
9	다른 에이전트와 description 영역이 겹치지 않는가?	□
10	프롬프트를 팀원에게 보여줬을 때 행동을 예측할 수 있는가?	□

7개 이상 체크되면 좋은 프롬프트입니다. 5개 이하라면 5단계 프레임워크를 다시 적용해보세요.

Gotcha 미니 코너: {file:} 경로 오타의 침묵

{file:.opencode/prompts/reveiw-security.md} — 이 경로에서 오타를 찾으셨나요? review가 reveiw로 잘못 쓰여 있습니다.

문제는, opencode가 이 오타를 에러로 알려주지 않는다는 것입니다. 파일이 존재하지 않으면 빈 문자열로 치환되고, 에이전트는 보안 체크리스트 없이 동작합니다. 프롬프트의 핵심 부분이 통째로 빠졌는데 아무 경고도 없으니, 에이전트가 “이상하게 얕은 리뷰”를 하면 그제야 눈치채게 됩니다.

방어법:

• 에이전트를 처음 만들면 반드시 테스트 대화를 한 번 해보세요. “지금 너의 역할과 체크리스트를 요약해줘”라고 물으면 프롬프트가 제대로 로드됐는지 즉시 확인할 수 있습니다.
• 파일명에 일관된 네이밍 규칙을 적용하세요. {에이전트명}-{섹션}.md 형식(예: reviewer-security.md)으로 통일하면 오타 확률이 줄어듭니다.
• {file:} 경로를 작성한 뒤, 에디터에서 해당 파일이 실제로 존재하는지 Ctrl+클릭으로 확인하는 습관을 들이세요.

오늘 만든 것, 내일 추가할 것

오늘 우리는 에이전트의 정체성을 결정하는 opencode 시스템 프롬프트를 설계했습니다. 5단계 프레임워크(역할→기준→형식→경계→예외)를 익히고, {file:} 외부화로 관리 가능한 구조를 만들었으며, 모델별로 효과적인 프롬프트 스타일이 다르다는 것도 확인했습니다.

하지만 아무리 프롬프트를 잘 짜도, 에이전트가 파일을 마음대로 삭제하거나 위험한 셸 명령을 실행할 수 있다면 의미가 없겠죠? 내일 4일차에서는 에이전트의 권한(permission)을 세밀하게 제어하는 법을 다룹니다 — allow / ask / deny 매트릭스, bash 패턴 기반 세분화, 그리고 read-only 리뷰어 vs write 가능 구현 에이전트를 어떻게 분리하는지. 에이전트 보안의 핵심입니다.

---

자주 묻는 질문

opencode 시스템 프롬프트에서 “잘 해줘” 같은 모호한 지시가 왜 실패하나요?

“잘 해줘”는 기준이 없어서 LLM이 성능, 보안, 가독성 중 어떤 관점에서 작업할지 임의로 해석하게 됩니다. 또한 출력 형식과 행동 경계가 정의되지 않아 매번 결과가 달라지고, 코드를 직접 수정할지 의견만 낼지도 불분명해집니다. 구체적 체크리스트와 우선순위, 출력 형식을 명시한 프롬프트가 훨씬 일관되고 높은 품질의 결과를 만듭니다.

opencode 에이전트 시스템 프롬프트에서 {file:} 외부화 패턴은 왜 필요한가요?

시스템 프롬프트가 길어질수록 하나의 파일 안에 모든 지시를 넣으면 관리가 어려워지기 때문에, 프롬프트 내용을 별도 파일로 분리하는 외부화 전략이 필수입니다. {file:} 패턴을 사용하면 체크리스트나 규칙 등을 독립된 파일로 관리하면서 프롬프트에서 참조할 수 있어 유지보수성과 재사용성이 높아집니다.

Claude와 GPT 계열 모델은 시스템 프롬프트를 다르게 작성해야 하나요?

네, 모델별로 잘 반응하는 프롬프트 구조가 다릅니다. 이 글에서는 Claude와 GPT 계열이 각각 효과적으로 따르는 프롬프트 스타일이 다르다는 점을 모델별 프롬프트 전략으로 다루고 있으며, 에이전트 정의 시 사용하는 모델에 맞춰 프롬프트를 최적화하는 것이 중요합니다.