amadeus-grilling은(는) 무엇을 하나요?

목적

계획이나 설계의 모호함을 질문을 통해 하나씩 해소합니다.

공유된 이해에 도달할 때까지 설계 트리의 가지를 순서대로 탐색합니다. 서로 의존하는 결정은 의존 관계를 풀어가며 하나씩 해결합니다.

기본 자세

질문은 엄격하게 수행합니다. 단, 질문을 늘리는 것 자체를 목적으로 하지 않습니다.

사용자가 판단하지 않으면 진행할 수 없는 사항만 묻습니다. 코드베이스, .amadeus/ 산출물, 기존 문서, 기존 대화에서 답을 얻을 수 있는 것은 질문하지 않고 스스로 확인합니다.

질문 방식

질문은 한 번에 하나씩 제시합니다. 여러 질문을 한 번에 나열하면 어떤 결정부터 풀어야 할지 파악하기 어렵기 때문입니다.

각 질문에는 다음을 포함합니다.

무엇을 결정할 것인가.
왜 지금 그 결정이 필요한가.
권장 답변.
권장하는 이유.

질문한 후에는 사용자의 답변을 기다립니다. 답변을 받기 전에 다음 질문으로 넘어가지 않습니다.

권장 답변

각 질문에는 반드시 권장 답변을 첨부합니다.

권장 답변은 현재 시점의 산출물, 설계 경계, 구현 리스크, 후속 작업에 미치는 영향을 고려하여 제시합니다. 권장할 수 없는 경우에는 그 이유와 판단에 필요한 부족 정보를 명시합니다.

조사 우선

질문이 코드베이스나 산출물을 조사하면 답할 수 있는 경우, 먼저 조사합니다.

조사 대상 예시:

.amadeus/
README.md
AGENTS.md
AMADEUS.md
기존 skill
기존 Intent 산출물
기존 domain, glossary, decision, traceability

조사 결과, 여전히 인간의 판단이 필요한 경우에만 질문합니다.

Grilling Decision Trail

guided 또는 refine에서 산출물의 의미나 후속 판단에 영향을 미치는 질문과 답변이 발생한 경우, 확정된 판단 과정을 Grilling Decision Trail로 기록합니다.

Grilling Decision Trail은 원시 로그가 아닙니다. 확정되지 않은 발언, 도중에 부정된 안, 단순한 실행 허가, 작업 순서에 대한 간단한 확인, 명령 실행 확인, 일시적인 작업 편의는 기록하지 않습니다.

기록 대상은 다음과 같은 판단입니다.

범위.
성공 조건.
대상 외.
의존성.
용어.
경계가 지정된 컨텍스트.
분할 방침.
상태 판단.
반영 대상.
supersede 판단.

amadeus-grilling은 기록 대상, 기록 구조, 상태, 채번 기준을 정의합니다. 실제 grillings.md와 grillings/Gxxx-*.md의 생성 또는 업데이트는 grill을 호출한 phase skill이 수행합니다.

질문한 턴에서는 산출물을 업데이트하지 않습니다. 사용자 답변을 받은 다음 턴에서 phase skill이 자신의 산출물 경계 내에서 답변을 해석하고, phase 산출물에 반영하는 것과 동일한 변경으로 Grilling Decision Trail을 업데이트합니다.

배치는 대상 산출물 세트의 root 바로 아래에 합니다.

<대상 root>/
  grillings.md
  grillings/
    G001-<topic>.md

대상 root는 다음과 같습니다.

.amadeus/discoveries/<discovery-id>/
.amadeus/event-storming/<event-storming-id>/
.amadeus/intents/<intent-id>-<slug>/
.amadeus/intents/<intent-id>-<slug>/event-storming/<event-storming-id>/

Steering layer는 현재 .amadeus/ 바로 아래 구조가 혼재되어 있으므로 이 기록 대상에서 제외합니다.

전체 도메인 또는 공유 용어에만 반영되는 판단은 현재 구조에서는 전용 Grilling Decision Trail을 새로 만들지 않습니다. 필요한 경우 .amadeus/domain-map.md, .amadeus/context-map.md, .amadeus/glossary.md의 근거 또는 대상 Intent의 decision에 남깁니다.

grillings.md는 색인만을 다룹니다. session 상세는 grillings/Gxxx-*.md에 둡니다.

grillings.md는 다음과 같은 최소 구조를 가집니다.

# Grillings

## 목록

| ID | 주제 | 대상 | 상태 | 주요 확정 판단 | 반영 대상 | 상세 |
|---|---|---|---|---|---|---|
| G001 | Ideation Scope | Intent | completed | 대상 범위를 관리 화면으로 한정 | [scope.md](scope.md) | [G001](grillings/G001-ideation-scope.md) |

session 파일명은 G001-<topic>.md로 합니다. <topic>은 영문 소문자, 숫자, 하이픈만으로 작성합니다.

session 상태는 다음 중 하나로 합니다.

active
completed
superseded

개별 판단의 상태는 다음 중 하나로 합니다.

active
superseded

session 파일에는 개요, 확정 판단, 질문 기록을 둡니다. 개요에는 session 전체의 반영 대상을 반드시 씁니다. 개요와 개별 판단의 반영 대상은 대상 root 내의 산출물을 가리킵니다. Discovery와 Event Storming에서는 <id>/grillings에서 동일한 ID의 부모 Markdown을 가리키는 ../<id>.md를 허용합니다. 단, 전체 도메인 하위의 Grilling Decision Trail에서 .amadeus/glossary.md를 가리키는 경우에만 공유 용어로의 반영으로서 ../glossary.md를 허용합니다. 각 질문 기록에는 확인하고 싶은 것, 확인이 필요한 이유, 권장 답변, 권장 이유, 사용자 답변을 반드시 씁니다. 각 질문 기록에서 확정 판단 ID를 반드시 참조합니다. 개별 판단에는 반영 대상을 반드시 씁니다. superseded인 개별 판단에는 대체 대상을 반드시 씁니다.

scaffold-only에서는 질문하지 않으므로 Grilling Decision Trail을 만들지 않습니다. repair에서는 원칙적으로 Grilling Decision Trail을 업데이트하지 않습니다. 단, 기존 grillings.md나 grillings/Gxxx-*.md 자체가 손상된 경우에는 구조 수리로서 수정해도 좋습니다.

장기화된 논의의 인계

grilling이 장기화되어 별도의 대화 단위로 계속하는 것이 더 안전한 경우, handoff를 운영 보조 수단으로 사용합니다.

handoff는 Amadeus DLC의 산출물이 아닙니다. 작성된 인계 문서는 OS의 임시 디렉토리에 두고 .amadeus/ 하위에는 두지 않습니다.

확정된 판단은 Grilling Decision Trail에 남깁니다. handoff에는 다음 대화 단위에서 재개하는 데 필요한 참조 대상만을 씁니다.

handoff에는 적어도 다음을 포함합니다.

대상 workspace와 대상 산출물 세트.
참조해야 할 grillings.md와 grillings/Gxxx-*.md.
이미 확정된 판단의 요약.
미응답 질문과 다음에 확인해야 할 한 가지 질문.
다음 대화 단위에서 사용할 권장 skill.

기존 산출물에 쓰여 있는 내용을 handoff에 중복해서 옮기지 않습니다. 산출물, PR, Issue, 차이점, 검증 결과가 존재하는 경우에는 path 또는 URL로 참조합니다.

Amadeus에서의 사용처

다음과 같은 상황에서 사용합니다.

steering layer의 목적, 행위자, 제약, 도메인 영역을 확인합니다.
Intent의 목적, 의존성, 성공 조건, 범위를 확인합니다.
Ideation의 대상, 대상 외, 실현 가능성, 체제, 초기 목업, Inception으로의 인계를 확인합니다.
용어, 개념, 경계가 지정된 컨텍스트, DDD 모델, 계약의 의미를 확인합니다.
Unit, Bolt, Spec의 세분화 수준이나 예외 이유를 확인합니다.

금지 사항

여러 질문을 한 번에 나열하지 않습니다.
기존 산출물을 읽으면 알 수 있는 것을 질문하지 않습니다.
권장 답변 없이 질문하지 않습니다.
질문한 턴에서 답변을 기다리지 않고 산출물을 업데이트하지 않습니다.
사용자의 답변을 기존 산출물과 모순되는 형태로 확정하지 않습니다. 모순이 있는 경우에는 모순을 먼저 설명하고 확인합니다.

amadeus-grilling