커스텀 커맨드 프론트매터 설정

앞 편에서 만든 /meeting:summary는 본문만 있는 커맨드였습니다. 그것만으로도 동작하지만, 실무에서 쓰다 보면 세 가지가 아쉬워집니다. 목록에서 골라 쓸 때 이 커맨드가 뭘 하는지 한 줄 설명이 없고, 커맨드가 git 명령을 실행할 때마다 승인 창이 뜨고, 인수를 어떤 순서로 넣어야 하는지 매번 기억해야 합니다. 이 세 가지를 해결하는 것이 프론트매터입니다.

이 글에서는 커맨드 파일 첫머리에 ---로 감싸 적는 YAML 프론트매터의 생김새와 자주 쓰는 필드 네 가지(description, allowed-tools, argument-hint, model)를 공식 문서 기준으로 정리하고, 마지막에 이 설정을 조합한 "안전한 커밋 커맨드"를 만듭니다. 다음 편에서는 인수를 받는 $ARGUMENTS로 넘어갑니다.

핵심 요약

• 프론트매터는 파일 맨 위 --- 사이에 적는 YAML 메타데이터이며 모든 필드가 선택 사항입니다.
• description은 목록에 보이는 설명이자 Claude가 자동으로 커맨드를 고를 때 보는 기준입니다.
• allowed-tools는 지정한 도구를 승인 없이 쓰게 해 줍니다. 도구를 제한하는 기능이 아니라 사전 승인 기능입니다.
• argument-hint는 자동 완성 화면에 인수 형식을 보여 줍니다. 예: [file] [format].
• model은 그 커맨드를 실행하는 동안 쓸 모델을 지정하며 해당 턴이 끝나면 세션 모델로 돌아갑니다.

프론트매터는 어떻게 생겼나

프론트매터는 파일의 가장 첫 줄부터 시작해야 하며 --- 두 줄 사이에 키: 값 형태로 적습니다. 공식 문서는 .claude/commands/ 파일이 스킬과 같은 프론트매터를 지원한다고 명시하되, name과 paths 두 필드는 커맨드 파일에서 무시된다고 덧붙입니다. 나머지는 그대로 쓸 수 있습니다.

---
description: 녹음 전사 텍스트를 회의록(참석자/논의/결정/할 일)으로 정리
argument-hint: [전사파일] [형식]
allowed-tools: Read
---
전사 파일을 읽고 회의록으로 정리합니다.
...

프론트매터가 없어도 커맨드는 동작합니다. 다만 YAML이 깨진 경우가 문제입니다. 공식 문서에 따르면 프론트매터 형식이 잘못되면 본문은 빈 메타데이터로 로드되어 /이름 호출은 되지만 description이 사라집니다. 콜론 뒤에 공백을 빠뜨리거나 들여쓰기가 어긋나는 실수가 대부분이니, 수정 후 목록에 설명이 보이는지로 확인하면 됩니다.

공식 문서의 프론트매터 참조에는 이 글에서 다루는 네 필드 외에도 disable-model-invocation, user-invocable, disallowed-tools, effort, context, agent, hooks, shell, arguments, when_to_use 등이 있습니다. 이 중 disable-model-invocation: true는 "Claude가 알아서 이 커맨드를 실행하지 못하게, 사용자만 부르게" 만드는 필드라서 커밋·배포처럼 부작용이 있는 커맨드에 자주 씁니다. 마지막 예시에서 함께 씁니다.

함께 알아 둘 필드: model

model 필드는 커맨드가 활성화되었을 때 쓸 모델을 지정합니다. 공식 문서에 따르면 /model 명령과 같은 값을 받거나 inherit로 세션 모델을 유지할 수 있고, 재정의는 "현재 턴의 나머지 부분"에만 적용되며 설정에 저장되지 않습니다. 다음 프롬프트에서는 세션 모델로 돌아갑니다. 조직의 availableModels 허용 목록에 없는 값은 무시되고 현재 모델이 유지됩니다.

우리는 이 필드를 "비용 조절 손잡이"로 가르칩니다. 회의록 정리처럼 형식만 맞추면 되는 커맨드는 Haiku 4.5로도 충분하고, PR 리뷰 준비처럼 판단이 필요한 커맨드는 세션 모델을 그대로 두는 식입니다. 모델명은 공식 문서의 모델 설정 페이지에서 현재 값을 확인해 적습니다. 모델 종속을 피하려는 우리 원칙과 같은 맥락입니다. 특정 모델명을 커맨드에 박아 두면 모델 세대가 바뀔 때 파일을 다시 열어야 하니, 꼭 필요한 커맨드에만 적습니다.

description: 후보 목록에 무엇이 보이나

description은 두 곳에서 쓰입니다. 첫째, /를 눌렀을 때 뜨는 목록에서 커맨드 옆에 표시됩니다. 둘째, Claude가 대화 흐름상 관련 있는 커맨드를 스스로 골라 쓸 때 판단 근거가 됩니다. 공식 문서는 이 필드를 "권장"으로 표시하고, 생략하면 본문 첫 단락이 대신 쓰인다고 안내합니다.

그래서 설명은 "무엇을 하는지"와 "언제 쓰는지"를 함께 적는 것이 좋습니다. 공식 문서는 description과 when_to_use를 합친 텍스트가 목록에서 1,536자에서 잘린다고 하니, 핵심 용도를 앞에 둡니다.

description: 회의 전사를 회의록 4항목으로 정리. 상담·미팅 녹음을 텍스트로 변환한 직후 사용

반대로 설명이 너무 넓으면 Claude가 엉뚱한 상황에서 커맨드를 끌어다 씁니다. 공식 문서의 문제 해결 절도 "너무 자주 트리거되면 설명을 더 구체적으로 만들거나 disable-model-invocation: true를 붙이라"고 안내합니다.

allowed-tools: 어떤 도구를 확인 없이 쓰게 할까

기본 작성법

allowed-tools에 적은 도구는 그 커맨드가 활성화된 동안 승인 창 없이 실행됩니다. 공백이나 쉼표로 구분한 문자열, 또는 YAML 목록 형태를 모두 받습니다.

allowed-tools: Read Grep

allowed-tools:
  - Read
  - Bash(git status *)

가장 중요한 점은 공식 문서의 이 문장입니다. "사용 가능한 도구를 제한하지 않습니다. 모든 도구는 호출 가능하게 유지되며, 권한 설정은 나열되지 않은 도구를 계속 관리합니다." 즉 allowed-tools는 허용 목록(화이트리스트)이 아니라 사전 승인 목록입니다. 목록에 없는 도구도 평소처럼 승인을 받으면 쓸 수 있습니다. 특정 도구를 아예 못 쓰게 하려면 disallowed-tools 필드나 권한 설정의 deny 규칙을 써야 합니다.

자주 쓰는 도구 지정 패턴

도구 이름만 적으면 그 도구 전체를, 괄호 안에 패턴을 적으면 해당 패턴에 맞는 호출만 사전 승인합니다. 공식 문서 예시와 우리 수업 예시를 함께 정리하면 다음과 같습니다.

Bash(git *)처럼 넓게 잡으면 편하지만 git push --force까지 사전 승인되는 셈이므로, 우리 수업에서는 "동사 단위로 좁게" 적기를 권합니다. 위 표처럼 add와 commit만 열어 두면 커맨드가 실수로 푸시하는 일은 승인 창에서 걸립니다.

사전 승인의 장점과 주의점

장점은 명확합니다. 매번 같은 git status, git diff에 승인을 누르는 일이 사라져 커맨드가 한 번에 끝까지 돕니다. 7주차에서 다루는 무인 자동화에 가까워지는 첫걸음입니다.

주의점은 두 가지입니다. 첫째, 공식 문서는 프로젝트 .claude/ 안에 체크인된 파일의 allowed-tools가 "해당 폴더에 대한 작업 공간 신뢰 대화를 수락한 후" 적용된다고 안내하며, 신뢰하기 전에 내용을 검토하라고 경고합니다. 남이 만든 레포를 열 때 그 안의 커맨드가 스스로 넓은 도구 권한을 부여할 수 있기 때문입니다. 둘째, 사전 승인은 "이 커맨드가 활성화된 동안"만입니다. 세션 전체 권한을 바꾸려면 /permissions나 settings.json을 써야 합니다.

argument-hint: 인수 형식을 어떻게 알려 주나

argument-hint는 자동 완성 화면에서 커맨드 옆에 표시되는 힌트입니다. 공식 문서 예시는 [issue-number]와 [filename] [format]입니다. 기능을 바꾸지는 않고 순전히 안내용이지만, 인수를 두 개 이상 받는 커맨드에서는 순서를 잊지 않게 해 주므로 다음 두 편에서 만드는 커맨드에는 꼭 붙입니다.

argument-hint: [전사파일] [형식: md|notion]

우리 수업에서는 대괄호 안에 한국어로 적어도 된다고 안내합니다. 표시용 문자열이라 형식 제약이 없습니다. 다만 이 힌트가 있다고 해서 인수가 검증되는 것은 아니므로, 빠진 인수 처리는 본문 지시문으로 해결합니다(4편에서 다룹니다).

설정을 조합한 예: 안전한 커밋 커맨드

네 필드를 모두 써서 "검토 후 커밋" 커맨드를 만듭니다. 우리 초급 과정에서 매주 마무리마다 "커밋하고 푸시해줘"를 시키는데, 이 커맨드는 그중 커밋까지만 담당합니다. 푸시는 일부러 뺐습니다.

.claude/commands/git/commit-safe.md

---
description: 변경 내용을 검토하고 의미 단위로 커밋. 푸시는 하지 않음
argument-hint: [커밋 메시지 요지]
allowed-tools: Bash(git status *) Bash(git diff *) Bash(git add *) Bash(git commit *)
disable-model-invocation: true
---
다음 순서로 진행합니다.

1. git status와 git diff로 변경 내용을 확인합니다.
2. .env, 키 파일, 비밀번호가 포함된 줄이 diff에 있으면 즉시 멈추고 보고합니다.
3. 변경을 의미 단위로 나눠 각각 커밋합니다. 메시지 요지: $ARGUMENTS
4. 커밋 결과를 표(해시, 메시지, 파일 수)로 보여 줍니다.
5. 푸시는 하지 않습니다. 사용자가 따로 요청할 때만 진행합니다.

호출은 /git:commit-safe 회의록 커맨드 추가처럼 합니다. 이 커맨드가 안전한 이유를 필드별로 보면 이렇습니다.

1. allowed-tools에 git push가 없으므로 5번 규칙을 어기려 해도 승인 창이 뜹니다.
2. disable-model-invocation: true라서 Claude가 "코드가 준비된 것 같으니 커밋하자"고 스스로 실행하지 못합니다. 공식 문서도 /commit, /deploy류에 이 필드를 권합니다.
3. 2번 규칙은 3주차 "키는 절대 깃허브·문서에 원문으로 넣지 않는다"를 커맨드 안의 정지 규칙으로 옮긴 것입니다.
4. 4번 규칙은 정지 규칙이 증거여야 한다는 우리 관점입니다. 커밋했다는 말이 아니라 해시가 찍힌 표가 완료 증거입니다.

정리

• 프론트매터는 파일 첫 줄의 --- 블록이며 전부 선택 사항이지만 description은 붙이는 것이 좋습니다.
• allowed-tools는 제한이 아니라 사전 승인이며, Bash(git add *)처럼 동사 단위로 좁게 엽니다.
• 프로젝트 커맨드의 allowed-tools는 작업 공간 신뢰 수락 후 적용되므로 남의 레포는 먼저 읽고 신뢰합니다.
• argument-hint는 표시용, model은 해당 턴 동안만 적용되는 모델 재정의입니다.
• 부작용이 있는 커맨드에는 disable-model-invocation: true를 함께 붙입니다.

자주 묻는 질문