grill-with-docs

grill-with-docs 스킬 개요

grill-with-docs는 팀이 이미 저장소 안에 있는 언어와 결정 사항을 기준으로 설계를 검증하고 싶은 경우에 쓰는 기획·문서화 스킬입니다. CONTEXT.md와 ADR에 맞춰 용어를 유지해야 하는 Technical Writing, 제품 감각이 필요한 엔지니어링, AI 보조 아키텍처 작업에 특히 잘 맞습니다. “프롬프트만으로” 대충 맞추는 방식이 아니라, 실제 저장소의 문맥에 기대어 판단을 정렬해야 할 때 유용합니다.

핵심 역할은 단순합니다. 사용자를 한 번에 한 질문씩 인터뷰하고, 답변을 추천하며, 질문이 소스에서 해결 가능하면 코드베이스나 문서를 확인하는 것입니다. 그래서 실제 위험이 용어 불일치, 기록되지 않은 가정, 오래된 의사결정 문서라면 grill-with-docs 스킬은 일반적인 브레인스토밍 프롬프트보다 훨씬 쓸모가 큽니다.

grill-with-docs가 다른 점

이 스킬은 단순한 대화가 아니라 도메인 인식을 중심으로 설계돼 있습니다. 기존 컨텍스트 파일을 확인하고, ADR을 훑고, 결정이 분명해질수록 문서를 갱신하도록 유도합니다. 그래서 grill-with-docs for Technical Writing 같은 문서 중심 워크플로에서 특히 잘 작동합니다.

가장 잘 맞는 사용 사례

다음이 필요할 때 grill-with-docs를 사용하세요:

• 기존 도메인 모델을 기준으로 계획을 검증해야 할 때,
• 프로젝트 용어를 정확하게 골라야 할 때,
• 결정 사항을 만들어지는 즉시 기록해야 할 때,
• 또는 구현 전에 초안을 확립된 문서와 정합시키고 싶을 때.

맞지 않는 경우

빠른 요약, 다듬어진 명세, 저장소 맥락이 없는 자유로운 아이데이션만 원한다면 이 스킬은 일반 프롬프트보다 느리게 느껴질 수 있습니다. 이 스킬의 가치는 규율 있는 질문과 문서 인식 점검에서 나옵니다.

grill-with-docs 스킬 사용법

grill-with-docs 설치하기

저장소의 표준 스킬 매니저로 grill-with-docs 스킬을 skills 디렉터리에 설치한 다음, 대상 프로젝트 맥락에서 스킬 파일을 여세요. 기본 설치 패턴은 다음과 같습니다:

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

이 명령을 grill-with-docs install의 시작점으로 삼고, 실제로 사용하는 에이전트 환경에서 스킬이 उपलब्ध한지 확인하세요.

올바른 입력으로 시작하기

이 스킬은 첫 메시지에 다음 정보가 들어 있을 때 가장 잘 작동합니다:

• 기획 중인 목표,
• 시스템 또는 기능 이름,
• 중요하게 다뤄야 할 알려진 용어,
• 그리고 정리하고 싶은 결정의 경계.

약한 프롬프트 예: “이 기능 설계 좀 도와줘.”
더 강한 프롬프트 예: “현재 billing 도메인을 기준으로 이 기능 계획을 grill-with-docs로 검증해줘. ‘subscription period’에 맞는 용어, 데이터 형태, 문서에 남겨야 할 ADR급 결정을 문서 작성 전에 정리하고 싶어.”

먼저 읽어야 할 파일

grill-with-docs usage를 시작할 때는 다음부터 보세요:

• 인터뷰 동작과 워크플로를 담은 SKILL.md,
• 활성 도메인 모델을 보여주는 CONTEXT.md 또는 CONTEXT-MAP.md,
• 기존 결정을 확인할 수 있는 docs/adr/,
• 파일을 새로 만들거나 갱신해야 할 때 필요한 ADR-FORMAT.md와 CONTEXT-FORMAT.md.

이 파일들은 무엇을 저장소에서 추론할 수 있는지, 그리고 무엇을 명시적으로 적어야 하는지를 알려줍니다.

결과를 높이는 워크플로

이 스킬은 반복 루프로 사용할 때 가장 효과적입니다:

1. 구체적인 계획이나 거친 초안을 넣는다.
2. 스킬이 한 번에 한 질문씩 묻게 둔다.
3. 저장소 근거가 가장 분명한 구체적 답변을 한다.
4. 질문이 파일에서 답할 수 있으면 코드베이스 탐색을 허용한다.
5. 용어와 핵심 결정을 컨텍스트나 ADR 노트에 남긴다.

가장 중요한 실무 팁은 “이름이 필요한 것”과 “결정이 필요한 것”을 분리하는 것입니다. 이렇게 해야 grill의 초점이 흐트러지지 않고, 불필요한 ADR도 막을 수 있습니다.

grill-with-docs 스킬 FAQ

grill-with-docs는 문서 팀만 쓰는 건가요?

아닙니다. 기존 도메인 어휘와 계획이 맞아야 할 때라면 언제든 유용합니다. 특히 제품 엔지니어링, 플랫폼 작업, 또는 표현과 구조가 이후 이해도에 영향을 주는 grill-with-docs for Technical Writing 워크플로에서 효과가 큽니다.

일반 프롬프트와 뭐가 다른가요?

일반 프롬프트도 아이디어를 만들 수는 있지만, grill-with-docs는 가정을 캐묻고, 저장소를 확인하고, 기존 컨텍스트에 맞게 용어를 조여 가도록 설계돼 있습니다. 그 덕분에 이름 충돌과 코드베이스와 충돌하는 문서를 만들 가능성이 줄어듭니다.

제대로 쓰려면 문서 체계가 성숙해야 하나요?

아닙니다. 다만 CONTEXT.md와 ADR이 이미 있으면 가장 잘 작동합니다. 없더라도, 결정이 드러나는 대로 스킬이 그것들을 느슨하게 정의하도록 도와줄 수 있습니다.

언제는 쓰지 않는 게 좋나요?

순수 탐색 작업이거나, 저장소에 의미 있는 도메인 컨텍스트가 없거나, 구조화된 인터뷰보다 빠른 한 번짜리 답변이 더 중요한 경우에는 피하세요.

grill-with-docs 스킬 개선하기

더 좋은 결정 재료를 넣으세요

품질을 가장 크게 올리는 방법은 스킬에 좁고 결정 중심적인 프롬프트를 주는 것입니다. 기능 이름, 시스템에서 닿는 부분, 그리고 정확히 해소하고 싶은 모호성을 함께 넣으세요. 예: “회계 컨텍스트에서는 이걸 invoice, billing record, charge 중 무엇이라고 부르는 게 맞고, 그 결정은 어디에 남겨야 할까?”

저장소 근거를 초반에 주세요

이미 관련 파일을 알고 있다면 처음부터 언급하세요. CONTEXT.md, 특정 ADR, 또는 src/billing/ 같은 폴더를 지정하면 스킬이 덜 일반적인 질문을 하고, 더 쓸모 있는 질문을 하게 됩니다. 특히 grill-with-docs usage에서 중요합니다. 이 스킬은 기존 용어와 구조에 계획을 대조할 수 있을 때 가장 강하기 때문입니다.

자주 생기는 실패 지점을 주의하세요

가장 흔한 실패는 도메인을 너무 느슨하게 적어 인터뷰가 추상적으로 끝나는 경우입니다. 또 하나는 언어 모델이 정확한 용어를 갖기도 전에 구현을 요구하는 것입니다. 첫 출력이 너무 넓게 느껴진다면, 결정을 더 좁은 표현으로 다시 말하고 마지막으로 해결된 분기부터 계속 진행하라고 요청하세요.

첫 번째 결과를 바탕으로 반복하세요

첫 라운드가 끝나면 답변을 다음 셋 중 하나로 정리하세요: 정리된 용어집 항목, 짧은 ADR, 또는 수정된 구현 브리프. 그다음 남은 미해결 질문에 대해 grill-with-docs를 다시 실행하세요. 보통 두 번째 패스에서 가장 큰 효과가 납니다. 용어와 경계가 이미 더 명확해져 있기 때문입니다.