Command 문법

Command의 기본 개념은 이해했는데, 파일을 어떤 형식으로 작성해야 할까요? 단순히 Markdown을 쓰면 되는 걸까요, 아니면 특별한 규칙이 있을까요?

Command 파일은 YAML 프론트매터와 Markdown 본문으로 구성됩니다. 각 요소가 왜 필요한지를 이해하면 자신만의 Command를 설계할 때 더 나은 판단을 내릴 수 있습니다.

YAML 프론트매터

프론트매터는 Command 파일의 메타데이터를 정의합니다. 파일 최상단에 ---로 감싸서 작성하며, Claude Code가 이 정보를 읽어 자동완성 목록과 도움말을 표시합니다.

기본 형식

---
title: COMMAND-TITLE
description: 명령어에 대한 설명
argument-hint: "<arg> 인자에 대한 설명"
---

필드 상세

title (필수)

Command의 표시 이름입니다. 대문자와 하이픈 사용이 일반적입니다. 이 값은 Claude Code UI에서 Command를 식별하는 데 사용되므로, 명령어의 목적을 한눈에 알 수 있도록 작성합니다.

title: RELEASE-NOTES
title: CODE-REVIEW
title: GENERATE-TEST

description (필수)

Command가 수행하는 작업에 대한 간단한 설명입니다. / 입력 시 자동완성 목록에 표시되므로, 팀원이 어떤 Command를 선택할지 판단하는 기준이 됩니다.

description: 릴리스 노트를 자동으로 생성합니다
description: 코드를 분석하고 리뷰 의견을 제시합니다

argument-hint (선택)

인자에 대한 힌트 메시지입니다. <>로 필수 인자를, []로 선택적 인자를 표현합니다. 이 힌트가 있으면 사용자가 어떤 값을 전달해야 하는지 바로 알 수 있습니다.

# 단일 인자
argument-hint: "<version> 릴리스 버전 (예: v1.2.0)"

# 선택적 인자 표현
argument-hint: "[topic] 선택적 토픽 필터"

# 복수 인자 예시
argument-hint: "<source> <target> 소스와 타겟 경로"

Markdown 본문 구조

프론트매터 이후의 본문이 Claude에게 전달되는 실제 프롬프트입니다. 본문의 구조가 곧 Claude의 작업 흐름을 결정하므로, 논리적인 순서로 구성하는 것이 중요합니다.

권장 구조

---
(프론트매터)
---

# 명령어 제목

명령어 개요 설명

## 파라미터

파라미터 설명 및 검증 규칙

## 워크플로우/단계

수행할 작업 단계

## 규칙/가이드라인

따라야 할 규칙

## 출력 형식

결과물 형식 정의

개요로 시작하여 파라미터를 검증하고, 워크플로우를 실행하고, 규칙을 따르고, 출력 형식에 맞춰 결과를 생성하는 흐름입니다. Claude는 이 순서대로 작업을 수행하게 됩니다.

예시: 완전한 Command 파일

---
title: API-DOC
description: API 문서를 생성합니다
argument-hint: "<class> 문서화할 클래스명"
---

# API 문서 생성

$ARGUMENTS 클래스에 대한 API 문서를 생성합니다.

## 파라미터 검증

**클래스명:** $ARGUMENTS

클래스명이 지정되지 않은 경우 오류를 출력하고 중단합니다.

## 워크플로우

1. **클래스 검색**: 프로젝트에서 해당 클래스 찾기
2. **분석**: public 멤버 추출
3. **문서 생성**: Markdown 형식으로 작성

## 문서 규칙

- 모든 public 메서드 문서화
- 매개변수와 반환값 설명 포함
- 사용 예제 코드 포함

## 출력 형식

```markdown
# {ClassName}

## 개요
{클래스 설명}

## 메서드
### {MethodName}
{메서드 설명}

**매개변수:**
- `{param}`: {설명}

**반환값:** {설명}

**예제:**
```csharp
{코드}
```
```

효과적인 프롬프트 작성 기법

Command 본문은 결국 Claude에게 보내는 프롬프트입니다. 프롬프트를 어떻게 작성하느냐에 따라 결과 품질이 크게 달라집니다. 여기서는 실제로 효과가 검증된 다섯 가지 기법을 소개합니다.

1. 명확한 지시어 사용

Claude에게 작업 순서를 지시할 때는 “순서대로”라고 명시하고 번호를 매기는 것이 중요합니다. “A, B, C를 해주세요”라고 뭉뚱그려 말하면 Claude가 순서를 임의로 정하거나 일부를 건너뛸 수 있습니다.

# 좋은 예
다음 단계를 **순서대로** 실행하세요:
1. 먼저 A를 수행
2. 그 다음 B를 수행
3. 마지막으로 C를 수행

# 피해야 할 예
A, B, C를 해주세요.

2. 조건문 활용

실행 시점에 따라 상황이 달라질 수 있으므로, 조건별 동작을 명시하면 Claude가 상황에 맞게 대응할 수 있습니다. 특히 인자 유무에 따른 분기는 거의 모든 Command에 필요합니다.

## 버전 파라미터 ($ARGUMENTS)

**버전이 지정된 경우:** $ARGUMENTS

버전 파라미터는 필수입니다.

**버전이 지정되지 않은 경우:**
다음 오류 메시지를 출력하고 중단합니다:
> 버전을 지정해주세요. 예: /release-note v1.2.0

3. 체크리스트 형식

검증 단계에서 체크리스트를 사용하면 Claude가 각 항목을 하나씩 확인하도록 유도할 수 있습니다. 누락 방지에 효과적입니다.

## 검증 체크리스트

다음 항목을 모두 확인하세요:

- [ ] 프론트매터가 포함되어 있는가?
- [ ] 모든 필수 섹션이 있는가?
- [ ] 코드 예제이 검증되었는가?
- [ ] Breaking Changes가 문서화되었는가?

4. 표 활용

여러 단계의 목표와 출력을 한눈에 보여주려면 표가 효과적입니다. Claude도 표 형식의 정보를 잘 해석합니다.

## Phase별 목표

| Phase | 목표 | 출력 |
|-------|------|------|
| 1 | 환경 검증 | Base/Target 결정 |
| 2 | 데이터 수집 | .analysis-output/*.md |
| 3 | 커밋 분석 | phase3-*.md |
| 4 | 문서 작성 | RELEASE-*.md |
| 5 | 검증 | 검증 보고서 |

5. 코드 블록 지정

Claude가 실행해야 할 명령어나 생성해야 할 결과물은 코드 블록으로 감싸면 정확도가 높아집니다. 언어 태그(bash, markdown 등)를 붙이면 Claude가 맥락을 더 잘 파악합니다.

## 실행할 명령어

```bash
dotnet AnalyzeAllComponents.cs --base origin/release/1.0 --target HEAD
```

## 출력 예시

```markdown
# Analysis for Src/Functorium

## Change Summary
37 files changed
```

문서 참조 방식

Command가 복잡해지면 모든 지침을 하나의 파일에 담기 어렵습니다. 이때 다른 문서를 참조하여 상세 정보를 분리할 수 있으며, Claude는 참조된 문서를 필요에 따라 읽고 지침을 따릅니다.

상대 경로 참조

## Phase 1: 환경 검증

**상세**: [phase1-setup.md](.release-notes/scripts/docs/phase1-setup.md)

위 문서의 지침을 따라 환경을 검증하세요.

참조 테이블

## 참고 문서

| Phase | 문서 | 설명 |
|-------|------|------|
| 1 | [phase1-setup.md](...) | 환경 검증 |
| 2 | [phase2-collection.md](...) | 데이터 수집 |
| 3 | [phase3-analysis.md](...) | 커밋 분석 |

출력 형식 정의

Command의 결과물 형식을 명확히 정의하면 일관된 출력을 얻을 수 있습니다. 형식을 정의하지 않으면 Claude가 매번 다른 형태로 결과를 생성할 수 있으므로, 특히 파일 출력이 있는 Command에서는 형식 정의가 필수적입니다.

파일 출력

## 출력 파일

**파일명:** `.release-notes/RELEASE-$ARGUMENTS.md`

**형식:**
```markdown
---
title: Functorium $ARGUMENTS 새로운 기능
date: {오늘 날짜}
---

# Functorium Release $ARGUMENTS

## 개요
...
```

콘솔 출력

## 완료 메시지

작업 완료 시 다음 형식으로 출력하세요:

```txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
릴리스 노트 생성 완료
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

버전: $ARGUMENTS
파일: .release-notes/RELEASE-$ARGUMENTS.md

통계:
| 항목 | 값 |
|------|-----|
| 새로운 기능 | N개 |
| 버그 수정 | N개 |
| Breaking Changes | N개 |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

고급 기법

지금까지 살펴본 기본 문법만으로도 대부분의 Command를 작성할 수 있습니다. 하지만 릴리스 노트 자동화처럼 여러 단계로 구성된 복잡한 워크플로우에서는 몇 가지 추가 기법이 필요합니다.

1. 단계별 중간 결과 저장

복잡한 워크플로우에서는 각 단계의 중간 결과를 파일로 저장하면 디버깅이 쉬워지고, 다음 단계의 입력으로 재사용할 수 있습니다.

## 중간 결과 저장 (필수)

각 Phase 완료 후 중간 결과를 저장하세요:

- `.analysis-output/work/phase3-commit-analysis.md`
- `.analysis-output/work/phase3-feature-groups.md`

이 파일들은 다음 Phase의 입력으로 사용됩니다.

2. 오류 처리

예상 가능한 오류 상황을 미리 정의해두면 Claude가 적절하게 대응할 수 있습니다.

## 오류 처리

다음 상황에서는 작업을 중단하고 사용자에게 알리세요:

1. **Base Branch 없음**:
   > origin/release/1.0 브랜치가 없습니다.
   > 첫 배포인 경우 초기 커밋부터 분석합니다.

2. **.NET SDK 없음**:
   > .NET 10 SDK가 설치되어 있지 않습니다.
   > 설치 후 다시 시도하세요.

3. 성공 기준 명시

성공 기준을 명확하게 정의하면 Claude가 작업 완료 여부를 스스로 판단할 수 있습니다.

## 성공 기준

다음 조건을 모두 만족해야 Phase가 완료된 것입니다:

- [ ] 프론트매터 포함됨
- [ ] 모든 필수 섹션 포함됨
- [ ] 모든 주요 기능에 "Why this matters" 섹션 포함됨
- [ ] Uber 파일에 없는 API 사용: 0개

FAQ

Q1: 프론트매터의 argument-hint에서 <>와 []의 차이는 무엇인가요?

A: <>는 필수 인자를, []는 선택적 인자를 나타냅니다. 예를 들어 <version>은 반드시 전달해야 하는 인자이고, [topic]은 생략할 수 있는 인자입니다. 이 표기는 CLI 도구의 관례를 따른 것으로, Claude Code의 자동완성 목록에서 사용자에게 안내됩니다.

Q2: Command 본문에서 “순서대로 실행하세요”라고 명시하는 것이 왜 중요한가요?

A: Claude는 약한 지시(“A, B, C를 해주세요”)를 받으면 순서를 임의로 정하거나 일부를 건너뛸 수 있습니다. 번호를 매기고 “순서대로”라고 명시하면 Claude가 각 단계를 빠짐없이 지정된 순서로 수행합니다. 특히 Phase 간 데이터 의존성이 있는 워크플로우에서 순서 보장은 필수적입니다.

Q3: 출력 형식을 정의하지 않으면 어떤 문제가 생기나요?

A: Claude가 매번 다른 형태로 결과를 생성합니다. 릴리스 노트처럼 파일 출력이 있는 Command에서는 프론트매터 구조, 섹션 순서, 코드 블록 형식이 달라져 일관성이 깨집니다. 콘솔 출력과 파일 출력 모두 형식을 명시적으로 정의하는 것이 권장됩니다.

Q4: 다음 절에서는 무엇을 다루나요?

A: 이 문법을 실제로 적용한 release-note.md Command를 분석합니다. 모듈화 패턴, 체크리스트 패턴, 입출력 명시 패턴, 조건부 처리 패턴 등 복잡한 워크플로우를 설계하는 데 사용된 설계 패턴들을 살펴봅니다.

Command 문법의 기본과 고급 기법까지 살펴보았습니다. 다음 절에서는 이 문법을 실제로 적용한 release-note.md Command의 내부 구조를 분석해보겠습니다.