2편 — 에이전트 파일 작성하기

에이전트 파일의 역할은 단순히 프롬프트를 저장하는 것에 그치지 않는다. 특정 모델, 실행 권한, 온도, 그리고 출력 형식까지 하나의 패키지로 묶어 고정하는 것이 핵심이다. 이를 통해 에이전트를 어디서 호출하든 일관된 성격과 능력을 갖춘 전문가가 나오게 만들 수 있다. OpenCode에서 이 패키지는 마크다운 파일 형식을 빌려 구현된다.

파일은 크게 두 부분으로 나뉜다. 상단의 YAML frontmatter 영역은 에이전트의 물리적인 제약과 메타데이터를 정의하고, 하단의 본문 영역은 에이전트의 사고방식과 행동 지침을 담는 시스템 프롬프트 역할을 한다. 이 두 영역이 조화를 이뤄야 에이전트가 의도한 궤도를 벗어나지 않고 임무를 수행할 수 있다.

frontmatter: 에이전트의 뼈대 설계

frontmatter는 에이전트의 정체성을 결정하는 가장 중요한 영역이다. 여기서 model을 지정하면 에이전트의 지능 수준이 결정되고, permission을 설정하면 에이전트가 만질 수 있는 도구의 범위가 확정된다. 특히 description 필드는 단순히 사람이 읽기 위한 용도를 넘어, OMO와 같은 오케스트레이션 시스템이 적절한 에이전트를 선택하는 라우팅 기준으로 활용되기도 한다.

---
model: anthropic/claude-3-5-sonnet
description: "React 컴포넌트의 접근성 문제를 read-only로 검토하고 WCAG 기준 준수 여부를 보고하는 에이전트"
permission:
  read: allow
  edit: deny
  bash: ask
---

위 예시에서 볼 수 있듯이 description은 구체적일수록 좋다. 단순히 “코드 리뷰어”라고 적는 것은 나쁜 예다. “어떤 상황에서”, “무엇을 검토하고”, “어떤 형식으로 보고하는지”까지 적어야 오케스트레이터가 이 에이전트를 잘못 호출할 가능성이 줄어든다.

permission은 프롬프트보다 먼저 온다

초보자가 가장 자주 하는 실수는 본문에 “절대 수정하지 마세요”라고 쓰고 edit 권한은 열어두는 것이다. 모델은 지시를 따르려고 노력하지만, permission은 실행 가능성 자체를 결정한다. 리뷰어라면 edit: deny가 먼저고, 그 다음에 “수정하지 말고 보고만 하라”는 문장이 와야 한다. 순서가 바뀌면 안전장치가 아니라 부탁이 된다.

역할별 기본값은 이렇게 시작하는 편이 안전하다.

이 표는 정답이 아니라 출발점이다. 중요한 것은 “필요하면 나중에 열자”는 방향이다. 처음부터 모든 도구를 열어두면 빠르게 움직이는 것처럼 보이지만, 나중에는 어느 에이전트가 어떤 파일을 바꿨는지 추적하는 데 더 많은 시간을 쓴다. 자동화가 빨라진 게 아니라 사고 수습이 빨라진 것일 수도 있다.

시스템 프롬프트: 사고방식 주입

본문 영역은 에이전트의 사고방식을 정의한다. 여기에는 역할, 작업 절차, 금지 행동, 출력 형식, 검증 기준이 들어가야 한다. 좋은 시스템 프롬프트는 길기만 한 문서가 아니라, 실패할 지점을 미리 막아둔 운영 매뉴얼에 가깝다.

You are a read-only accessibility reviewer.

## Must do
- Inspect changed UI components and related tests.
- Report findings with severity and file path.
- Mention manual verification gaps separately.

## Must not do
- Do not edit files.
- Do not suppress type errors.
- Do not delete failing tests.

## Output
Return bullets grouped by P0/P1/P2.

이 정도 구조만 있어도 에이전트의 행동은 훨씬 예측 가능해진다. 특히 Must not do는 귀찮아 보여도 반드시 넣어야 한다. 모델은 보통 문제를 해결하려고 들기 때문에, 때로는 “해결하지 말고 보고만 하라”는 경계가 더 중요하다.

실제 에이전트 구성 예시

블로그 운영을 예로 들면 read-only 검토자와 writer는 별도의 에이전트가 되는 편이 좋다. 검토자는 현재 글을 읽고 누락된 내용을 찾지만 API를 호출하지 않는다. writer는 수정안을 만들 수 있지만 publish 권한은 갖지 않는다. 실제 PATCH나 publish는 command가 담당하고, command는 다시 토큰 출력 금지와 최소 payload 규칙을 강제한다.

---
model: openai/gpt-5.1
description: "블로그 글의 구조, 톤, 누락된 실전 예시를 검토하는 read-only 편집자"
permission:
  read: allow
  edit: deny
  bash: deny
---

You review Korean technical blog posts.
Do not rewrite the article directly.
Return: summary, missing sections, concrete insertion points, and risks.

반대로 writer 에이전트는 파일 수정이나 API payload 생성을 허용할 수 있다. 다만 이 경우에도 publish는 별도 단계로 분리하는 편이 낫다. 글을 쓰는 능력과 발행 버튼을 누르는 권한은 같은 능력이 아니다. 이 둘을 나누는 것만으로도 운영 사고의 절반은 줄어든다.

파일 하나에 모든 것을 넣지 않는다

에이전트 파일은 역할을 고정하는 곳이지, 프로젝트 전체의 모든 규칙을 복사해 넣는 곳이 아니다. 모든 에이전트가 공유해야 하는 규칙은 AGENTS.md에 두고, 특정 작업의 절차는 command로 빼고, 도메인 지식은 skill에 둔다. 에이전트 파일은 이 요소들을 어떤 역할로 묶어 호출할지 정의하는 마지막 조립 단계에 가깝다.

이렇게 나누면 에이전트 하나를 바꿀 때 전체 시스템이 흔들리지 않는다. 리뷰어의 출력 형식을 바꿔도 블로그 작성 skill은 그대로 남고, 블로그 API command를 바꿔도 보안 리뷰 에이전트는 영향을 받지 않는다. 작은 분리는 귀찮지만, 큰 자동화를 오래 굴리려면 결국 이 귀찮음이 보험이 된다.