서론

이 스킬을 알게 된 계기는 실무에서 경험한 "재작업(手戻り)"의 고통 때문이었습니다.

구현 전에 어느 정도 설계는 세워두었다고 생각해도, 테스트 환경을 배포하여 QA 멤버에게 동작 확인을 요청하면 모달(Modal)의 동작을 어떻게 할 것인가와 같은 세부적인 사양 및 고려 누락이 차례차례 발견됩니다.

그것을 다른 개발과 병행하면서 그때마다 재작업으로 수정해 나가는 사이클이 쌓여가는 것이 업무적으로 상당히 힘들다고 느끼고 있었습니다.

"설계 단계에서 고려 누락을 없애고 싶다"라고 생각하던 중에 알게 된 것이 grill-me라는 스킬입니다.

실제로 사용해 보니, 그 제작자인 Matt Pocock 씨의 스킬 모음에는 설계뿐만 아니라 개발 플로우(Flow) 전체를 커버하는 스킬들이 갖춰져 있다는 것을 알 수 있었습니다.

아직 사용하기 시작한 지 얼마 되지 않아 완벽한 활용법을 확립하지 못했으므로 앞으로 업데이트해 나가겠습니다...!

이 스킬 모음의 전체상

mattpocock/skills 는 Matt Pocock 씨(Total TypeScript / AI Hero)가 공개하고 있는 Claude Code용 에이전트 스킬 모음입니다. 도입은 다음 한 줄이면 됩니다.

npx skills@latest add mattpocock/skills

README에 따르면, AI 코딩에서 자주 발생하는 실패는 다음 4가지 패턴으로 분류할 수 있으며, 각각에 대응하는 스킬이 준비되어 있습니다.

#	문제	원인 한 줄 요약	대응 스킬
1	생각했던 것과 다른 것이 만들어짐	인식의 차이	/grill-me , /grill-with-docs
2	출력이 장황함·설명이 과도함	유비쿼터스 언어(Ubiquitous Language)[1]의 부재	/grill-with-docs (CONTEXT.md)
3	코드가 동작하지 않음	피드백 루프(Feedback Loop)의 부족	/tdd , /diagnosing-bugs
4	볼 오브 머드(Ball of Mud)가 됨	설계에 대한 투자 부족	/improve-codebase-architecture , /codebase-design

이 기사에서는 제가 실무에서 실제로 도움을 받았던 #1(인식의 차이)과 #2(도메인 언어의 부재) 두 가지에 집중하여, "제작자가 해결하고 싶었던 것", "제가 실무에서 안고 있던 과제", "실제로 어떻게 사용하고 있는지" 순으로 소개하겠습니다.

과제 1: 설계·사양의 고려 누락을 없애기 ── grill-me / grilling

제작자가 해결하고 싶었던 것

README는 Pragmatic Programmer의 한 구절을 인용하고 있습니다.

"No-one knows exactly what they want"

개발자 자신도 자신이 정말로 원하는 것을 처음부터 명확하게 언어화할 수 있는 것은 아니다. 그렇기 때문에 AI 에이전트 사이에도 인식의 차이가 발생한다는 과제 설정입니다.

그 대책으로 제시된 것이, 착수 전에 AI로부터 끈질기게 질문 공세를 받는 "grilling 세션"입니다.

제가 실무에서 안고 있던 과제

"서론"에서 썼듯이, 저의 경우에는 이것이 "개발자와 AI 에이전트의 인식 차이"라기보다는, "제 머릿속에서 세운 설계"와 "QA 멤버가 실제로 움직여보며 깨닫는 사양" 사이의 차이였습니다.

모달의 동작과 같은 세부적인 고려 누락이 구현 후·테스트 후에 발견되어, 그때마다 재작업이 발생하고 있었습니다.

구현에 들어가기 전에, 저 혼자서는 깨닫지 못하는 고려 누락을 씻어낼 수 있는 메커니즘이 필요했던 것입니다.

grill-me / grill-with-docs / grilling의 메커니즘

실제로 ~/.claude/skills/ 하위의 SKILL.md를 읽어보면 관련 있는 3가지 스킬의 관계를 알 수 있습니다.

grilling (Productivity / Model-invoked)

Interview me relentlessly about every aspect of this plan until we
reach a shared understanding. Walk down each branch of the design
tree, resolving dependencies between decisions one-by-one. For each
...

이것이 심문 로직 (Interrogation Logic)의 본체입니다. 설계의 분기를 하나씩 따라가며, 한 번에 한 질문씩 확인하며 없애 나가는 인터뷰의 형식 그 자체를 기술하고 있습니다.

** grill-me** (Productivity / User-invoked)

Run a `/grilling` session.

본문은 이 한 줄뿐입니다. grilling을 그대로 호출하는 얇은 래퍼 (Wrapper)입니다.

** grill-with-docs** (Engineering / User-invoked)

Run a `/grilling` session, using the `/domain-modeling` skill.

이것도 한 줄이지만, grilling에 더해 domain-modeling 스킬을 함께 호출합니다 (후술할 과제 2에서 자세히 다루겠습니다).

README의 Reference 섹션에는 이러한 구성의 배경이 되는 설계 원칙이 적혀 있습니다.

User-invoked skills는 사용자가 직접 입력했을 때만 도달할 수 있으며 (예: /grill-me), 이들의 역할은 오케스트레이션 (Orchestration)입니다. Model-invoked skills는 사용자가 호출하거나, 작업 내용에 따라 에이전트가 자동으로 호출할 수 있으며, 재사용 가능한 규율 (Discipline)을 담고 있습니다. User-invoked skill은 model-invoked skill을 호출할 수는 있지만, 다른 user-invoked skill을 호출할 수는 없습니다.

실제 SKILL.md의 frontmatter에도 이것이 반영되어 있습니다. grill-me / grill-with-docs에는 disable-model-invocation: true가 명시되어 있어, 명령어를 입력했을 때만 발화합니다.

반면 grilling에는 그러한 제한이 없으며, description에도 "'grill'이라는 트리거 문구를 사용했을 때" 사용한다고 적혀 있습니다.

즉, 사용자가 아무런 명령어를 입력하지 않아도, 대화 속에서 Claude가 자율적으로 발화할 수 있는 설계입니다.

세 가지 차이점을 정리하면 다음과 같습니다.

구분	grill-me	grill-with-docs	grilling
분류	Productivity / User-invoked	Engineering / User-invoked	Productivity / Model-invoked
기동 방법	/grill-me를 입력했을 때만	/grill-with-docs를 입력했을 때만	명령어 없이도 자율 발화 가능 ('grill' 트리거 문구 등)
역할	grilling을 호출하기만 하는 얇은 래퍼	grilling + domain-modeling을 호출하는 래퍼	심문 로직의 본체 (설계 분기를 하나씩, 한 질문씩 없애 나감)
CONTEXT.md/ADR 생성	하지 않음	함 (용어 확정·결정이 나오는 즉시 그 자리에서 반영)	하지 않음
SKILL.md 본문 길이	1줄	1줄	수 단락 (심문의 형식 그 자체를 기술)

"grilling이 grill-me의 최신 버전"인 것이 아니라, "grilling이라는 하나의 모델 기동 가능한 코어 로직을, grill-me(심문 전용)와 grill-with-docs(심문 + 문서 생성)라는 두 개의 사용자 기동 스킬이 공유하여 호출하고 있는" 구조인 것으로 보입니다.

실제 운용 방법

README에서는 "개발자와 AI 에이전트 사이의 인식 차이를 해소하기 위해"라는 위치를 점하고 있지만, 저 자신은 설계 단계에서의 벽치기 (Sparring/Brainstorming) 용도로 사용하고 있습니다.

구현에 들어가기 전, grilling 계열의 스킬과 일문일답을 반복함으로써 사양의 세부 사항을 파악하고 설계 누락을 방지하는 것이 목적입니다.

나아가, 거기서 확정된 설계를 QA 멤버에게 조기에 공유하여 테스트 케이스를 미리 작성하도록 합니다.

QA 측의 리뷰를 통해 지적을 받음으로써, 혼자서는 깨닫지 못했을 누락을 한 단계 더 없애 나가는 흐름으로 운용하고 있습니다.

과제 2: 도메인 지식·용어의 차이를 없애기 ── grill-with-docs / CONTEXT.md

저자가 해결하고 싶었던 것

README는 DDD(도메인 주도 설계)의 유비쿼터스 언어(Ubiquitous Language)를 인용하고 있습니다.

With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.

유비쿼터스 언어(Ubiquitous Language)가 있다면, 개발자 사이의 대화도 코드상의 표현도 모두 동일한 도메인 모델(Domain Model)로부터 도출됩니다.

README는 이어서 다음과 같이 과제를 제시합니다.

The Problem: At the start of a project, devs and the people they're building the software for (the domain experts) are usually speaking different languages.

【문제점】 프로젝트 시작 시점에는 개발자와 소프트웨어를 의뢰한 사람(도메인 전문가, Domain Expert) 사이의 언어가 서로 맞지 않는 경우가 자주 발생합니다.

이는 AI 에이전트(AI Agent)에서도 마찬가지이며, 저자는 다음과 같이 언급합니다.

I felt the same tension with my agents. Agents are usually dropped into a project and asked to figure out the jargon as they go. So they use 20 words where 1 will do.

저 역시 자신의 에이전트(Agent)와 소통하며 비슷한 답답함을 느낀 적이 있습니다. 보통 에이전트는 프로젝트에 갑자기 투입되어, 진행하면서 전문 용어(Jargon)를 파악해야 하는 상황에 놓입니다. 그 결과, 단 한 단어로 충분할 것을 20단어를 사용하여 설명하곤 합니다.

The Fix for this is a shared language. It's a document that helps agents decode the jargon used in the project.

이 문제에 대한 해결책은 '공유 언어(Shared Language)'입니다. 이는 에이전트가 프로젝트에서 사용되는 전문 용어를 해독할 수 있도록 돕는 문서입니다.

가독성이 떨어질 뿐만 아니라 토큰(Token)도 불필요하게 소비된다는 것이 저자가 설정한 과제입니다.

README에 실린 실제 사례(course-video-manager 리포지토리)를 보면 이해가 쉽습니다.

BEFORE: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
AFTER: "There's a problem with the materialization cascade"

한번 "materialization cascade(실체화 카스케이드)"라는 용어를 정의해 두면, 이후 세션에서 매번 이 설명을 반복할 필요가 없어집니다.

실무에서 겪고 있던 과제

이는 AI 에이전트만의 문제가 아니라, 인간 팀원 사이에서도 동일한 일이 일어나고 있다고 느낍니다.

내가 특정 개념에 사용하는 단어를 다른 팀원들도 동일한 의미와 동일한 단어로 사용하고 있는지 묻는다면, 사실 그렇지 않은 경우가 많습니다.

용어가 팀 내에서 통일되지 않은 상태에서 AI 에이전트에게 개발을 도와달라고 하면, 멤버마다 서로 다른 언어로 AI에게 지시를 내리게 되고, 결과적으로 사람에 따라 AI의 이해도가 달라지는 문제로 이어집니다.

grill-with-docs / domain-modeling의 메커니즘

이 '공유 언어'를 육성하는 역할을 하는 것이 domain-modeling 스킬(Engineering / Model-invoked)입니다. README에서는 다음과 같이 설명합니다.

domain-modeling— Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update CONTEXT.md and ADRs inline.

프로젝트의 도메인 모델 (Domain Model)을 적극적으로 구축하고 정교화하세요. 용어가 용어집과 일치하는지 면밀히 검토하고, 에지 케이스 (Edge Case)를 사용하여 견고성을 검증한 후, CONTEXT.md나 ADR (Architecture Decision Records, 아키텍처 결정 기록)을 수시로 업데이트해 나갑니다.

SKILL.md에는 더욱 구체적인 지시 사항이 적혀 있습니다.

• 사용자의 용어가 기존의 CONTEXT.md와 모순되면 즉시 지적할 것
• 모호한 단어에는 정확한 대체어를 제안할 것 (예: "account"는 Customer인가 User인가?)
• 도메인 관계를 논의할 때는 에지 케이스를 찌르는 구체적인 시나리오로 스트레스 테스트 (Stress-test)를 수행할 것
• 코드와 발언이 일치하는지 대조할 것
• 용어가 확정되는 즉시 배치 처리하지 말고 그 자리에서 CONTEXT.md를 업데이트할 것

CONTEXT.md에는 "용어의 정의"만 작성해야 하며, 구현 상세 내용이나 스크래치패드 (Scratchpad)로 사용해서는 안 된다고 엄격히 제한하고 있습니다.

실제 포맷은 심플한 텍스트 형태의 용어집입니다.

## Language
**Order**:
{용어에 대한 설명을 1~2문장으로 작성}
...

ADR (아키텍처 결정 기록)은 별도로 관리하며, 다음의 3가지 조건이 모두 충족될 때만 제안됩니다.

• 비가역성이 높음 (나중에 뒤집는 데 비용이 많이 듦)
• 문맥이 없으면 의아함 (미래의 독자가 "왜 이렇게 했지?"라고 의문을 가질 만함)
• 진정한 트레이드오프 (Trade-off)의 결과임 (여러 선택지가 있었고, 이유를 가지고 하나를 선택함))

grill-with-docs는 grilling에 domain-modeling을 결합함으로써, "인식 맞추기를 위한 심문"과 "도메인 언어 및 ADR 기록"을 하나의 세션에서 동시에 수행하도록 설계되었습니다. 과제 1과 과제 2가 여기서 연결되는 것입니다.

실제 운용 방법

/grill-with-docs를 통해 설계에 대한 아이디어를 주고받는(Wall-hitting) 과정에서, 그 자리에서 확정된 용어를 CONTEXT.md에 축적해 나가는 방식으로 사용하고 있습니다. 이를 통해 AI 에이전트에 대한 지시가 장황해지는 것을 방지할 수 있을 뿐만 아니라, CONTEXT.md 자체가 팀원 간의 용어집으로서도 기능하게 됩니다. 제품의 도메인 지식을 한 사람의 머릿속에만 두지 않고 파일로서 키워나감으로써, 다른 멤버들이 AI 에이전트와 개발할 때도 동일한 언어로 대화할 수 있는 상태를 목표로 합니다.

요약

• 실무에서의 과제는 두 가지: ① 구현 후 또는 테스트 후에야 발견되는 사양(Specification) 고려 누락, ② 팀 및 AI 에이전트 간의 도메인 용어 불일치.
• ①에는 grill-me (내부적으로는 grilling이라는 공통 심문 엔진 이용)로 대응. 구현 전에 문답을 통해 설계를 다듬고, QA에 조기 공유 및 리뷰를 통해 누락을 더욱 줄이는 운용을 하고 있음.
• ②에는 grill-with-docs (grilling + domain-modeling)로 대응. 아이디어를 주고받는 과정에서 확정된 용어를 그 자리에서 CONTEXT.md에 축적하여, AI 에이전트의 장황한 출력을 방지하면서 팀의 용어집으로 키워나감.
• 다음에는 실제로 npx skills@latest add mattpocock/skills를 실행하여 /grill-with-docs를 테스트해 보고, CONTEXT.md가 어떻게 성장하는지 이 스터디 모임에서 시연하도록 하겠습니다.

관련 기사

참고

• 유비쿼터스 언어 (Ubiquitous Language): Eric Evans가 Domain-Driven Design (DDD)에서 제창한 개념. 개발자, 도메인 전문가, 그리고 코드 자체가 동일한 도메인 모델에 기반한 동일한 언어를 공통 언어로 사용하는 것. 이것이 없으면 사람마다, 상황마다 동일한 개념을 다른 단어로 설명하게 되어 번역 비용과 오해가 발생함. 이 글의 문맥에서는 그 공통 언어를 AI 에이전트와도 공유하기 위한 메커니즘이 CONTEXT.md에 해당함. ↩︎

Discussion