Grill-with-docs란? AI 에이전트 작업 기준을 문서화하는 스킬 사용법

개발 테크

5일 전

조회수

114

개발자가 코드를 확인하며 작업 내역을 리뷰하고 있습니다.

AI 에이전트를 활용해 개발 작업을 진행할 때는 기능 구현 속도만큼이나 작업 기준을 명확하게 남기는 과정이 중요합니다. 구현에 큰 영향을 주는 용어, 데이터 구조, 권한 기준, 기술 결정이 문서로 남아 있지 않으면 AI가 일반적인 의미로 해석해 실제 프로젝트와 맞지 않는 결과를 만들 수 있습니다.

이러한 문제를 줄이기 위해 오픈소스로 공유된 스킬이 바로 Grill-with-docs입니다. Grill-with-docs는 AI 에이전트가 바로 구현을 시작하기 전에 사용자의 계획을 질문으로 검토하고, 그 과정에서 정리된 용어와 중요한 결정을 문서로 남기도록 돕는 스킬입니다.

이번 글에서는 Grill-with-docs의 특징과 사용법, 실무 활용 예시, 사용 시 주의사항까지 함께 정리했습니다.

Grill-with-docs란?

Grill-with-docs의 특징에 대해 정리했습니다. Grill-with-docs는 AI 에이전트가 작업을 시작하기 전에 사용자의 계획을 질문으로 검토하고, 그 과정에서 정리된 용어와 중요한 결정을 문서로 남기도록 만든 설계 검토 스킬입니다.

AI 에이전트에게 바로 구현을 맡기면 사용자의 의도, 도메인 용어, 기존 코드의 흐름을 AI가 임의로 해석할 수 있습니다. Grill-with-docs는 이런 문제를 줄이기 위해 한 번에 하나씩 질문을 던지고, 답변을 바탕으로 작업 기준을 구체화합니다.

특히 Grill-with-docs는 대화 중에 정리된 용어를 CONTEXT.md에 기록하고, 이후 되돌리기 어려운 기술적 판단은 ADR 형태로 남깁니다. 이를 통해 사용자와 AI 에이전트가 같은 용어와 기준을 공유할 수 있으며, 이후 spec 작성, ticket 분리, 구현 단계에서도 앞서 정리한 맥락을 이어갈 수 있습니다.

Grill-with-docs가 주목받는 이유

질문으로 정리한 내용을 문서로 남길 수 있습니다

AI 에이전트로 작업할 때 가장 큰 문제는 대화 중에 정리된 기준이 쉽게 흩어진다는 점입니다. 처음에는 기능의 목적, 용어, 예외 조건을 충분히 이야기했더라도 이후 구현 단계로 넘어가면 앞서 합의한 내용이 빠지거나 다르게 해석될 수 있습니다.

Grill-with-docs는 질문을 통해 사용자의 계획을 구체화하는 데서 끝나지 않고, 그 과정에서 정리된 내용을 문서로 남깁니다.

덕분에 AI 에이전트가 이후 작업을 진행할 때 같은 맥락을 다시 참고할 수 있고, 사용자는 작업 기준이 어디까지 정리되었는지 확인할 수 있습니다.

AI 에이전트가 도메인 용어와 작업 기준을 더 정확하게 이해할 수 있습니다

기준이 정리되지 않은 상태에서 AI 에이전트에게 구현을 맡기면, AI가 일반적인 의미로 해석해 실제 프로젝트와 맞지 않는 결과를 만들 수 있습니다.

Grill-with-docs는 이런 문제를 줄이기 위해 사용자의 답변과 코드베이스 맥락을 바탕으로 용어와 판단 기준을 정리합니다. 이를 통해 AI 에이전트는 단순히 명령을 수행하는 것이 아니라, 프로젝트 안에서 어떤 용어가 어떤 의미로 쓰이는지 이해한 상태로 작업을 이어갈 수 있습니다.

중요한 기술 결정을 기록해 이후 작업의 기준으로 사용할 수 있습니다

데이터 모델, API 구조, 권한 정책, 아키텍처 방향처럼 한 번 정하면 쉽게 바꾸기 어려운 결정은 작업 전에 충분히 검토되어야 합니다. 하지만 이런 결정이 대화 속에서만 오가면, 나중에 왜 그런 선택을 했는지 다시 확인하기 어렵습니다.

Grill-with-docs는 중요한 판단을 문서화해 이후 스펙 작성, 티켓 분리, 구현, 유지보수 과정에서 참고할 수 있는 기준으로 남깁니다. 덕분에 AI 에이전트가 작업을 반복하거나 확장할 때도 이전 결정과 충돌하지 않는 방향으로 진행할 수 있습니다.

Grill-with-docs,

Grill Me와 무엇이 다를까?

Grill Me와 Grill-with-docs는 모두 AI 에이전트가 바로 구현을 시작하지 않도록 돕는 계획 검토 스킬입니다. 사용자의 아이디어나 작업 요청을 그대로 실행하지 않고, 먼저 질문을 던져 부족한 조건과 모호한 결정을 확인한다는 점에서는 비슷합니다. 차이는 검토한 내용을 어디까지 남기느냐에 있습니다.

Grill Me, 사용자의 계획을 검토하는 스킬

Grill Me는 사용자의 계획을 질문으로 점검하고, AI 에이전트가 실행할 수 있는 형태로 정리하는 데 집중합니다. 기능 범위, 예외 조건, 데이터 구조, API 방향처럼 구현 전에 확인해야 할 내용을 하나씩 좁혀가며 작업 계획을 구체화합니다.

따라서 아이디어가 아직 정리되지 않았거나, AI 에이전트에게 바로 구현을 맡기기 전 빠르게 계획을 점검하고 싶을 때 사용하기 좋습니다.

Grill-with-docs, 계획 검토+프로젝트 문맥까지 문서화하는 스킬

Grill-with-docs는 여기에서 한 단계 더 나아가, 질문 과정에서 정리된 내용을 문서로 남기는 데 초점을 둡니다.

단순히 대화 안에서 계획을 정리하는 것이 아니라, 프로젝트에서 사용하는 용어와 작업 기준, 중요한 기술 결정을 문서화해 이후 작업에서도 다시 참고할 수 있도록 만듭니다.

이 차이는 AI 에이전트를 반복적으로 활용할 때 더 크게 드러납니다. Grill Me는 현재 작업의 방향을 정리하는 데 유용하지만, 대화가 끝나면 그 맥락이 사라질 수 있습니다.

반면 Grill-with-docs는 정리된 기준을 문서로 남기기 때문에 다음 작업, 다른 에이전트, 이후 구현 단계에서도 같은 기준을 이어갈 수 있습니다.

Grill-with-docs 사용법

Grill-with-docs 설치

npx skills add mattpocock/skills --skill=grill-with-docs

Grill-with-docs를 설치하기 위해 위의 명령어를 실행합니다.

Grill-with-docs를 설치하는 설치 화면입니다. Mattpocock의 스킬 선택화면이 나옵니다. Grill-with-docs로 이동해 스페이스바를 눌러 스킬을 선택합니다.

Grill-with-docs의 ai 에이전트 설치 화면입니다. Grill-with-docs를 어떤 AI 에이전트에 설치할지 선택하는 화면이 나타납니다.

Grill-with-docs는 Codex, Claude Code, Cursor, Antigravity, Warp 등 여러 AI 개발 도구에서 사용할 수 있기 때문에, 사용하려는 에이전트를 직접 선택해야 합니다. 사용을 원하는 AI 에이전트를 스페이스바로 눌러 선택한 뒤 Enter를 누릅니다.

Grill-with-docs의 설치 범위 선택 화면입니다. 설치 범위를 선택하는 화면이 나옵니다. 원하는 범위를 선택한 뒤 Enter를 누룹니다.

Project: 현재 프로젝트 폴더에만 스킬을 설치하는 방식입니다. 해당 프로젝트에서만 Grill-with-docs 사용을 원하면 선택합니다.
Global: 내 컴퓨터 전체 환경에 스킬을 설치하는 방식입니다. 여러 프로젝트에서 Grill-with-docs를 반복해서 사용할 계획이라면 선택합니다.

Grill-with-docs의 설치 방식 선택 화면입니다. 설치 방식 선택 화면이 나옵니다.

Symlink: 스킬 파일 원본을 한 곳에 두고, 선택한 에이전트들이 그 파일을 연결해서 사용하는 방식입니다. 업데이트가 쉽고 같은 스킬을 여러 도구에서 일관되게 쓸 수 있어 기본 추천 옵션입니다.
Copy to all agents: 선택한 에이전트 폴더마다 스킬 파일을 각각 복사하는 방식입니다. 각 도구에 독립적으로 파일이 들어가지만, 나중에 스킬을 업데이트할 때 여러 위치를 다시 관리해야 할 수 있습니다.

특별한 이유가 없으면 Symlink 선택 상태 그대로 Enter를 누르면 됩니다.

Grill-with-docs의 설치 전 내역 요약 화면입니다. 마지막으로 설치 요약 화면에서 선택한 스킬과 설치 대상, 보안 점검 결과를 확인합니다. 설치하려는 스킬이 맞고 보안 경고가 없다면 Yes를 선택한 뒤 Enter를 눌러 설치를 완료합니다.

Grill-with-docs 실행하기

설치가 완료되었다면 Grill-with-docs 명령어를 입력해 스킬을 사용할 수 있습니다. 예시를 들기 위해 서비스에 결제, 정산, 흐름을 새로 설계하는 테스트를 진행해 보았습니다.

Grill-with-docs에서 초기 요청화면입니다. Grill-with-docs를 실행하면 먼저 프로젝트 문맥을 확인하고, 필요한 용어와 결정 항목을 CONTEXT.md에 정리합니다.

이후 결제 서비스, 결제 완료 기준, 중복 결제 처리, 웹훅 요청 방식, 부분 환불, 정산 기준처럼 이후 설계에 영향을 주는 질문을 제시합니다.

이 답변을 바탕으로 프로젝트 기준을 확정하고, 되돌리기 어려운 결정은 ADR로 남길 수 있습니다.

Grill-with-docs는 정리된 기준을 CONTEXT.md에 반영한 화면입니다. 질문에 맞춰 답변을 입력하면 Grill-with-docs는 정리된 기준을 CONTEXT.md에 반영합니다.

결제 상태 모델이나 웹훅 검증 방식처럼 이후 변경이 어려운 항목은 ADR 후보로 분류해, 별도 의사결정 문서로 남길 수 있도록 정리합니다.

Grill-with-docs가 기준을 ADR 파일로 작성한 화면입니다. 기술 결정을 프로젝트 기준으로 남기기 위해, 결제 완료 기준과 웹훅 검증 방식을 ADR 파일로 작성해 달라고 요청했습니다.

Grill-with-docs는 먼저 CONTEXT.md에 정리된 기준을 확인한 뒤, 각 ADR 문서에 결정 배경, 선택한 방식, 대안, 결정 이유, 이후 구현에 미치는 영향까지 포함해 정리했습니다.

특히 웹훅 검증 방식은 토스페이먼츠 공식 문서를 참고해 정리되었습니다. 이를 통해 단순히 대화로 정리된 기준을 넘어서, 실제 구현 단계에서 참고할 수 있는 의사결정 문서가 만들어진 것을 확인할 수 있습니다.

AI 에이전트에게 바로 구현을 맡기기 전 프로젝트의 맥락과 의사결정 기준을 정리하는 데 활용하기 좋은 스킬입니다.

Grill-with-docs,

실무에서는 이렇게 활용해 보세요.

프로젝트 용어와 기준이 모호할 때

Grill-with-docs는 질문을 통해 사용자가 쓰는 용어와 판단 기준을 구체화하고, 정리된 내용을 문서로 남겨 이후 작업에서도 같은 맥락을 유지할 수 있도록 돕습니다.

프로젝트마다 사용하는 용어와 기준은 다릅니다. 같은 ‘회원’, ‘고객’, ‘관리자’, ‘주문’이라는 단어도 서비스 구조에 따라 의미가 달라질 수 있습니다.

이 기준이 정리되지 않은 상태에서 AI 에이전트에게 작업을 맡기면, AI가 일반적인 의미로 해석해 실제 프로젝트와 맞지 않는 결과를 만들 수 있습니다.

이럴 때 Grill-with-docs를 사용하면 프로젝트에서 사용하는 용어의 의미와 판단 기준을 먼저 정리할 수 있어, 매번 같은 설명을 반복하지 않아도 되고, 프로젝트 맥락과 맞지 않는 결과가 나올 가능성도 줄일 수 있습니다.

기존 코드베이스를 수정하기 전에 맥락을 확인해야 할 때

기존 프로젝트를 수정할 때는 사용자의 설명만으로 판단하면 위험합니다. 사용자는 “주문 취소 기능을 수정하고 싶다”고 말하지만, 실제 코드에서는 전체 취소만 가능하거나 특정 상태에서만 취소가 가능할 수 있습니다. 이 차이를 확인하지 않으면 AI 에이전트가 현재 코드 구조와 맞지 않는 방향으로 작업할 수 있습니다.

Grill-with-docs는 코드에서 확인할 수 있는 내용은 사용자에게 다시 묻지 않고, 기존 코드와 문서를 먼저 살펴보는 흐름을 가집니다.

사용자의 설명과 코드의 실제 동작이 다르면 그 차이를 드러내고, 어떤 기준을 따를지 다시 확인합니다. 그래서 레거시 코드 수정이나 기존 기능 확장처럼 현재 구조와 충돌하면 안 되는 작업에 활용하기 좋습니다.

여러 단계의 AI 작업을 하나의 기준으로 이어가야 할 때

AI 에이전트 작업은 한 번에 끝나지 않는 경우가 많습니다. 먼저 요구사항을 정리하고, 그다음 spec을 만들고, ticket을 나누고, 구현하고, 마지막으로 코드 리뷰까지 이어질 수 있습니다.

이때 앞 단계에서 정리한 기준이 다음 단계로 이어지지 않으면 작업 결과가 흔들립니다.

Grill-with-docs는 정리된 용어와 중요한 결정을 문서로 남겨 여러 단계의 AI 작업이 같은 기준을 공유하도록 만듭니다. 그래서 단순한 아이디어 검토보다, 하나의 프로젝트를 여러 작업 단계로 이어가야 할 때 더 적합합니다.

정리하면 Grill Me는 지금 하려는 작업을 더 명확하게 만드는 스킬이고, Grill-with-docs는 앞으로 반복해서 사용할 프로젝트 기준을 남기는 스킬로 보는 게 가장 자연스럽습니다.

Grill-with-docs 사용 시 주의사항 4가지

1. 문서가 생성되어도 되는 프로젝트에서 사용해야 합니다

Grill-with-docs는 단순히 대화로 계획을 정리하는 스킬이 아니라, 정리된 내용을 CONTEXT.md나 ADR 파일로 남기는 방식으로 작동합니다. 따라서 테스트용 채팅이나 임시 폴더에서 사용하기보다, 실제로 문서가 추가되어도 되는 프로젝트 폴더에서 사용하는 것이 좋습니다.

특히 기존 프로젝트에 적용할 때는 새로 생성되거나 수정되는 파일을 확인해야 합니다. AI 에이전트가 정리한 문서가 프로젝트 기준으로 적절한지 검토한 뒤 반영해야 합니다.

2. AI가 정리한 기준을 그대로 확정하면 안 됩니다

Grill-with-docs는 사용자의 답변과 코드베이스를 바탕으로 용어와 기술 결정을 정리합니다. 하지만 이 내용이 항상 최종 기준이 되는 것은 아닙니다.

결제 완료 기준, 권한 정책, 데이터 모델, 웹훅 검증 방식처럼 서비스 운영에 영향을 주는 내용은 반드시 개발자나 담당자가 다시 확인해야 합니다.

AI가 문서로 정리해 주더라도 실제 비즈니스 정책, 보안 기준, 운영 흐름과 맞는지는 사람이 최종 검토해야 합니다.

3. 모든 내용을 ADR로 남기려고 하면 문서가 과해질 수 있습니다

Grill-with-docs는 중요한 기술 결정을 ADR로 남길 수 있지만, 모든 선택을 ADR로 기록할 필요는 없습니다. 작은 화면 문구 변경이나 단순 필드명 정리까지 ADR로 남기면 문서가 많아지고, 오히려 중요한 결정을 찾기 어려워질 수 있습니다.

ADR은 되돌리기 어렵거나, 나중에 선택 이유를 다시 확인해야 하거나, 여러 대안 중 하나를 선택한 기술 결정에 사용하는 것이 좋습니다.

예를 들어 결제 상태 모델, 웹훅 검증 방식, 권한 정책, API 응답 구조처럼 이후 구현에 큰 영향을 주는 항목이 ADR로 남기기 적합합니다.

4. 기존 코드와 문서를 먼저 확인하도록 지시해야 합니다

Grill-with-docs를 사용할 때는 AI 에이전트가 사용자에게만 질문하지 않고, 프로젝트 안에 있는 코드와 문서를 먼저 확인하도록 지시하는 것이 좋습니다. 코드에서 확인할 수 있는 내용을 다시 질문하면 작업 흐름이 길어지고, 기존 코드와 맞지 않는 기준이 문서화될 수 있습니다.

따라서 처음 실행할 때는 “코드와 문서에서 확인할 수 있는 내용은 먼저 확인하고, 부족한 기준만 질문해 달라”고 입력하는 것이 좋습니다. 이렇게 해야 Grill-with-docs가 단순 질문 도구가 아니라, 실제 프로젝트 맥락을 반영한 문서화 도구로 작동할 수 있습니다.