Grill Me — 체계적인 질문을 통한 공유 이해 구축
철학
질문(Grilling)의 목적은 에이전트와 사용자 간의 공유 이해(shared understanding) 를 구축하는 것입니다. 모든 계획에는 함축된 가정, 명시되지 않은 제약 조건, 모호한 결정이 포함됩니다. 질문은 의사 결정 트리의 모든 분기를 하나씩 살펴보며 양측이 완전히 일치할 때까지 진행합니다.
목표는 구현을 시작하기 전에 검토되지 않은 가정이 하나도 없도록 하는 것입니다.
핵심 지침
- 모든 질문에 AskUserQuestion을 사용하십시오. 모든 질문은
AskUserQuestion도구를 통해 전달되어야 합니다. 절대 평문으로 질문을 출력하지 마십시오. - 도메인 내에서 배치하십시오. 동일한 질문 도메인 내에서 최대 4개의 관련 질문을 하나의
AskUserQuestion호출로 그룹화하십시오. 서로 다른 도메인의 질문을 하나의 호출에 혼합하지 마십시오. - 권장 사항을 먼저 제시하십시오. 권장 답변은 항상 첫 번째 옵션이며 레이블에
(Recommended)를 추가합니다. - 묻기 전에 탐색하십시오. 코드베이스, 문서를 읽거나 기존 패턴을 확인하여 답을 알 수 있는 질문은 묻는 대신 그렇게 하십시오. 사용자의 판단이 필요한 결정에 대해서만 질문하십시오.
- 의존성을 순서대로 해결하십시오. 일부 결정은 다른 결정에 의존합니다. 의존성 체인을 식별하고 상위 결정을 먼저 해결하십시오.
- 모든 것을 구조화된 기록으로 추적하십시오. 결정 로그를 구조화된 테이블로 유지 관리하십시오. 해결된 각 질문에 대해 도메인, 주제(헤더), 선택된 옵션 레이블, '기타'가 선택된 경우 사용자 정의 텍스트를 기록하십시오. 로그는 대화 컨텍스트 내에서 제시하십시오. 파일 I/O는 사용하지 마십시오.
- 어떤 가정도 남지 않습니다. 함축되었지만 명시되지 않은 것이 있으면 표면화하십시오. 명백해 보이는 것이 있으면 확인하십시오. 공유 이해는 편안한 침묵이 아닌 명시적인 동의를 의미합니다.
- 구체적으로 유지하십시오. 추상적인 개념이 아닌 구체적인 동작, 데이터 흐름, 사용자가 볼 수 있는 결과를 중심으로 질문을 구성하십시오.
질문 전 설정
질문을 시작하기 전에 조용히 컨텍스트를 구축하십시오:
- 사용자가 검토를 원하는 계획 또는 설계 문서를 읽습니다.
- 기존 패턴, 제약 조건 및 관련 코드를 위해 코드베이스를 탐색합니다.
- 현재 작업에 대한 컨텍스트를 위해 최근 git 기록을 확인합니다.
- 프로젝트 규칙을 위해 project.md 및 CLAUDE.md를 읽습니다.
그런 다음 질문 도메인별로 정리하여 현재까지 이해한 내용을 간략히 요약하여 제시합니다. 이를 통해 사용자는 분기별 질문에 들어가기 전에 주요 오해를 수정할 수 있습니다.
질문 도메인
references/interrogation-domains.md에 정의된 도메인을 통해 작업합니다. 계획에 맞게 순서를 조정하십시오 — 구축 중인 것에 가장 중심이 되는 도메인부터 시작하여 바깥쪽으로 진행합니다. 명백히 관련 없는 도메인은 건너뜁니다.
질문 프로세스
1. 계획에 대한 이해를 읽고 요약합니다.
2. 사용자가 요약을 확인하거나 수정합니다.
3. 각 질문 도메인에 대해 (관련성 순서로):
a. 이 도메인의 모든 결정 지점과 가정을 식별합니다.
b. 관련 결정 지점을 최대 4개의 질문으로 구성된 배치로 그룹화합니다.
c. 각 배치에 대해 단일 AskUserQuestion 호출을 실행합니다.
(각 질문에 대해 권장 사항을 먼저 제시). 모든 선택된 옵션을 기록합니다.
d. 도메인의 모든 지점을 해결한 후, 결정 사항을 요약하여 제시합니다.
도메인의 결정 사항을 구조화된 테이블 형식의 행으로 제시합니다.
4. 모든 도메인이 다루어진 후:
- 완전한 결정 로그를 구조화된 테이블로 제시합니다:
| # | 도메인 | 주제 | 결정 | 비고 |
|---|--------|------|------|------|
| 1 | 의도 | 목표 | 기타 | 고객 대상이 아닌 운영팀용 내부 대시보드 |
- 해결되지 않았거나 연기된 항목을 표시합니다.
- 다시 검토해야 할 도메인이 있는지 질문합니다.
질문 형식
모든 질문은 반드시 AskUserQuestion 도구를 통해 질문해야 합니다. 각 호출을 다음과 같이 구성하십시오:
{
"question": "Oura API가 429를 반환할 때 속도 제한을 어떻게 처리해야 합니까?",
"header": "Rate Limits",
"options": [
{
"label": "지수 백오프 (Recommended)",
"description": "지수 백오프(1초, 2초, 4초)로 재시도합니다. 일시적인 제한을 적절히 처리하며 src/api_client.py에 이미 사용된 재시도 패턴과 일치합니다."
},
{
"label": "다음 실행을 위해 대기",
"description": "요청을 건너뛰고 다음 예약 실행에 추가합니다. 더 간단하지만 데이터를 한 주기 지연시킵니다."
}
],
"multiSelect": false
}
의존성: question 텍스트에 이 질문이 기반이 되는 이전 결정 사항을 명시하거나, 독립적인 경우 "의존성 없음"이라고 기재합니다.
배치된 질문 예시
{
"questions": [
{
"question": "주요 배포 대상은 무엇입니까?",
"header": "Deploy",
"options": [
{
"label": "Docker + ECS (Recommended)",
"description": "기존 인프라와 일치합니다. 배포 파이프라인이 이미 존재합니다."
},
{
"label": "Kubernetes",
"description": "더 유연하지만 새로운 인프라 설정이 필요합니다."
},
{
"label": "서버리스",
"description": "운영 부담은 적지만 콜드 스타트 지연 문제가 있습니다."
}
],
"multiSelect": false
},
{
"question": "어떤 모니터링 접근 방식을 포함해야 합니까?",
"header": "Monitoring",
"options": [
{
"label": "구조화된 로깅 (Recommended)",
"description": "CloudWatch에 JSON 로그를 기록합니다. 검색 및 알림 설정이 가능합니다."
},
{
"label": "APM 트레이스",
"description": "요청 흐름 가시성을 위한 분산 추적입니다."
},
{
"label": "사용자 정의 메트릭",
"description": "Datadog의 비즈니스 특정 카운터 및 게이지입니다."
}
],
"multiSelect": true
}
]
}
미리보기 사용
사용자가 코드 조각, 아키텍처 다이어그램, 스키마 형태 또는 구성 예제와 같은 구체적인 결과물을 시각적으로 비교해야 할 때 옵션에 preview 필드를 사용하십시오. 미리보기 콘텐츠는 고정폭 상자에 마크다운으로 렌더링되며 나란히 비교할 수 있습니다.
미리보기를 사용하는 경우:
- 두 코드 패턴 또는 구현 비교
- 다른 스키마 형태 또는 데이터 구조 표시
- ASCII 다이어그램이 포함된 아키텍처 대안 제시
제약 조건: 미리보기는 단일 선택 전용입니다(multiSelect: false). 다중 선택이 필요한 경우 미리보기를 생략하고 설명을 대신 사용하십시오.
미리보기 예시:
{
"question": "데이터 파이프라인에 어떤 패턴을 사용해야 합니까?",
"header": "Pipeline",
"options": [
{
"label": "제너레이터 파이프라인 (Recommended)",
"description": "지연 평가, 대용량 데이터 세트에 메모리 효율적입니다.",
"preview": "def pipeline(source):\n for record in source:\n cleaned = clean(record)\n validated = validate(cleaned)\n yield validated"
},
{
"label": "배치 파이프라인",
"description": "모든 레코드를 한 번에 처리합니다. 더 간단하지만 메모리 사용량이 더 높습니다.",
"preview": "def pipeline(source):\n records = list(source)\n cleaned = [clean(r) for r in records]\n validated = [validate(r) for r in cleaned]\n return validated"
}
],
"multiSelect": false
}
질문 규칙
- 모든 질문에 AskUserQuestion을 사용하십시오. 절대 예외 없습니다.
- 첫 번째 옵션 = 권장 사항. 첫 번째 옵션은 항상 레이블에
(Recommended)가 있습니다. - 관련 질문을 배치하십시오. 동일한 도메인의 최대 4개의 관련 질문을 하나의 AskUserQuestion 호출로 그룹화하십시오. 도메인 간 질문은 별도의 호출이어야 합니다.
- 도구 제약 조건을 준수하십시오. 질문당 2-4개의 옵션. 헤더는 최대 12자. 옵션이 상호 배타적이지 않을 때
multiSelect: true를 사용하십시오(예: '어떤 테스트 접근 방식을 사용해야 합니까?' 또는 '어떤 도메인이 범위에 포함되어야 합니까?'). - 옵션을 필터링하십시오. 유효한 선택지가 4개 이상인 경우 코드베이스 컨텍스트를 기반으로 가장 관련성 높은 3개를 제시하십시오. 사용자는 나열되지 않은 항목에 대해 '기타'를 선택합니다.
- 구체적으로 작성하십시오. "오류를 어떻게 처리해야 합니까?"는 너무 모호합니다. "Oura API가 429를 반환할 때 백오프로 재시도해야 합니까, 아니면 다음 실행을 위해 대기해야 합니까?"는 구체적입니다.
- 근거를 제시하십시오. 권장 사항이 코드베이스에서 발견한 내용에 기반한 경우 파일과 줄을 참조하십시오.
- 답변을 수락하십시오. 사용자가 결정하면 기록하고 넘어가십시오. 이후 결정이 이전 결정과 충돌을 일으키지 않는 한 재론하지 마십시오.
대체 형식 (AskUserQuestion을 사용할 수 없는 경우)
런타임 환경에서 AskUserQuestion을 사용할 수 없는 경우 다음 텍스트 형식으로 대체하십시오:
[헤더] — [주제]
[질문의 명확한 진술]
권장: [권장 사항 및 이유]
대안:
- (A) [옵션] — [장단점]
- (B) [옵션] — [장단점]
중단 시점
다음 조건이 충족되면 질문이 완료된 것입니다:
- 모든 관련 질문 도메인이 다루어졌습니다.
- 모든 결정 분기가 해결되었거나 명시적으로 연기되었습니다.
- 사용자가 공유 이해를 확인했습니다.