다중 평가자 디자인 개선 루프
제품이 사람이 사용할 준비가 될 때까지 독립적인 리뷰를 반복합니다: 모든 여정이 모든 리뷰어로부터 9점 이상을 받고, 심각도 높은 수정 사항이 없으며, 리뷰어 간 점수 차이가 1점 이내이고, 이 상태가 2라운드 연속 유지되어야 합니다. 만장일치 10점은 목표가 아니라 작업 설명을 다시 확인해야 하는 신호입니다. AI 점수는 강력한 신호일 뿐 증명이 아닙니다: 루프가 준비되었다고 말하면 실제 처음 사용하는 사람들이 테스트하고, 그들이 AI와 다른 의견을 제시하면 사람의 의견이 우선합니다.
모든 작업은 하나의 명령줄 도구인 scripts/eval_loop.py(이 파일과 같은 위치)를 통해 실행되므로, 사람, 이 에이전트, 또는 다른 에이전트 모두 동일한 결과를 얻습니다. 모든 명령은 --dir <리뷰 폴더>를 사용하며, status --json은 항상 루프의 현재 상태와 다음에 수행할 작업을 알려줍니다. Python 3.9 이상, Node.js 18 이상 및 Google Chrome 또는 Chromium이 필요합니다. 다른 설치는 필요하지 않습니다.
아래에서 LOOP는 python3 <이 스킬의 폴더>/scripts/eval_loop.py를 의미합니다.
시작하기 전에 (모든 mStack 스킬 공통)
~/.mstack/config.json의"disabled"아래에multi-evaluator가 있거나, 사람이 이 작업에 이 스킬을 사용하지 말라고 했다면 일반적인 방식으로 작업합니다.~/.mstack/learned/multi-evaluator.md파일이 있으면 읽습니다: 이 파일에는 이 사람이 수락한 개선 사항이 저장되어 있으며, 이 파일의 내용이 원본 설정보다 우선합니다.- 루프가 종료(또는 중단)되면, 비공개로 진행 상황을 기록합니다:
python3 <mstack skill folder>/scripts/mstack.py log multi-evaluator --outcome reached|partial|not-reached --needed-user "..." --stalled "..."(mstack 스킬은 이 스킬 옆에 있습니다).
1. 여정 및 기준 먼저 정의
리뷰 전에, 실제 사용자가 처음부터 끝까지 수행할 수 있어야 하는 작업에 대해 사람과 합의합니다.
LOOP init --dir design-review --name "<제품명>" --start "<제품을 시작하는 명령어, {port} 포함>" --cwd <제품 폴더>(또는 이미 실행 중인 경우--url <주소>사용, 예: 스테이징 사이트).- 사람과 함께
design-review/mstack-eval.json을 작성합니다. 모든 필드는references/config.md를 참조하세요:about및persona: 제품이 무엇이고 누가 평가하는지. 디자인 방향과 제약 조건은about이 아닌rules에 넣으세요: 리뷰어에게 "점수에 반영되지 않음"으로 표시되므로, 작업 설명이 듣고 싶은 답을 미리 알려주지 않습니다.journeys: 3~6개의 실제 작업, 각각 처음부터 끝까지 ("책을 추가하고 목록에서 확인").views: 매 라운드마다 캡처할 고정 화면 (데스크톱, 휴대폰, 다크 테마). 라이트 테마 우선.criteria: 기본 기준은 명확함, 깔끔함, 빠름, 신뢰감, 익숙함, 차분함, 모든 곳에서 작동.stages는 제품이 성숙해짐에 따라 추가 기준을 더함 (가치 실현 시간, 오류 복구, 카피, 에이전트 경험, 측정된 접근성, 속도, 5초 테스트, 감정적 톤, 일관성, 데이터 안전, 만족감). 점수가 기본 기준을 충족하면"active": true또는"from_round": <n>으로 단계를 활성화합니다.reviewers: 서로 다른 AI 제조사의 리뷰어 최소 두 명. 기본값은 Claude (당신, 에이전트가 실행)와 Codex (codex exec로 도구가 실행).control: 노이즈 검사 (권장). 첫 번째 캡처는 해당 라운드의 스크린샷을control/에 저장하고, 모든 리뷰어가 매 라운드마다 여정control로 점수를 매기며, 보고서는 점수가 얼마나 이동했는지 보여줍니다. 그 이동보다 작은 변화는 노이즈일 뿐 진행이 아닙니다.
- 라운드 1 전에 사람에게 여정과 기준을 보여주고 승인을 받습니다.
2. 각 라운드
LOOP start-round --dir design-review # rounds/r<N>/ 폴더를 열고, 이번 라운드의 기준 스냅샷 생성
# rounds/r<N>/changes.md 작성: 변경 사항을 한 줄에 하나씩
LOOP capture --dir design-review # 매 라운드 동일한 화면을 동일한 방식으로 캡처
LOOP brief --dir design-review # rounds/r<N>/briefs/ 에 블라인드 채점 브리프 생성, 라운드 2부터 -compare 브리프 추가
LOOP review --dir design-review # 명령줄 리뷰어(Codex)를 병렬로 실행; 백그라운드에서 실행
동시에 kind가 agent인 모든 리뷰어를 새로운 컨텍스트에서 직접 실행하세요:
- Claude Code:
rounds/r<N>/briefs/claude.md의 전체 텍스트를 프롬프트로 하는 서브에이전트(Agent 도구, 범용)를 시작합니다. 자신의 의견, 예상 답변 또는 이전 점수를 추가하지 마세요. - 다른 에이전트: 브리프를 유일한 지침으로 하여 새 세션이나 스레드를 엽니다.
kind: "chat"리뷰어 (선택 사항, 옵트인: 사람의 로그인된 브라우저에서 Grok, ChatGPT 또는 Gemini, API 키 불필요): 공유해도 되는 항목에 대해 사람의 동의를 얻은 후에만, 새 비공개 채팅을 열고rounds/r<N>/briefs/<id>.md를 붙여넣고, 제품이 공개되지 않은 경우 이번 라운드의 고정 스크린샷을 업로드하고, 답변을 저장한 후 탭을 닫은 다음verdict를 실행합니다. 채팅 리뷰어는 스크린샷만 보고 실제 제품을 보지 못하므로 동점자 역할을 합니다: "사람이 사용할 준비가 됨" 상태에 절대 포함되지 않으며 유일한 리뷰어가 될 수 없습니다.
답변이 오면 JSON을 저장합니다 (도구가 형식에 맞는지 확인하고 형식에 맞지 않으면 거부합니다):
LOOP verdict --dir design-review --reviewer claude reply.json # 또는 파이프로 답변을 -로 전달
블라인드 우선, 비교는 그 다음. 채점 브리프는 이번 라운드만 보여줍니다: 이전 라운드의 스크린샷, 이전 점수, 디자인 방향이 없으므로 1라운드와 9라운드에서 점수가 동일한 의미를 가집니다. 라운드 2부터는 rounds/r<N>/briefs/<reviewer>-compare.md도 있습니다. 평결이 저장된 후에 동일한 리뷰어에게 제공하고 (동일한 세션 가능, 더 이상 블라인드가 아님), 답변을 점수와 별도로 저장합니다:
LOOP verdict --dir design-review --reviewer claude --compare compare-reply.json
LOOP report --dir design-review # design-review/report.html 작성
비교는 절대 점수를 변경하지 않습니다; 보고서는 "변경된 사항" 아래에 표시됩니다.
그런 다음 사람에게 보고서와 라이트 테마 스크린샷(rounds/r<N>/shots/)을 보여줍니다. 에이전트가 가능하다면 (Claude Code의 PushNotification) 라운드 보고서가 준비되었거나 루프에 결정이 필요할 때 알림을 보냅니다; 설정의 notify 명령도 알림을 보낼 수 있습니다 (references/config.md 참조).
3. 수정 후 반복
- 보고서의 다음에 수행할 작업 목록부터 시작합니다 (모든 리뷰어가 먼저 표시한 여정의 수정 사항, 그 다음 심각도 높음, 그 다음 가장 큰 "수정 시" 격차). 여정 테이블에서 리뷰어 간 점수 차이가 2 이상이면, 어느 점수에 따라 행동하기 전에 직접 해당 여정을 살펴보세요.
- 제품에서 수정 사항을 적용하고, 자체 테스트를 실행한 후 다음 라운드의
changes.md를 작성합니다. LOOP start-round를 실행하고,LOOP status가 사람이 사용할 준비가 됨 (위 중지 규칙, 2라운드 유지)이라고 말할 때까지 반복합니다. 라운드가 통과하면 큰 변경을 하지 말고 한 라운드를 더 실행하여 유지되는지 확인합니다.max_rounds(기본값 6)에 도달할 때까지 준비 상태에 도달하지 못하면status는 중지하고 사람과 상의하라고 말합니다: 여정이나 기준이 제품이 해서는 안 되는 것을 요구하고 있을 수 있습니다.- 그런 다음 실제 사람: 처음 사용하는 다섯 명의 사용자가 여정을 도움 없이 시도합니다. 시간, 어려움, 한 마디를
rounds/r<N>/people.md에 기록합니다 (항목당 한 줄; 보고서에 표시됨). AI 리뷰어와 의견이 다른 경우 사람의 의견이 우선합니다: 발견한 내용을 다음 라운드의 여정이나 기준으로 전환합니다.
규칙
- 리뷰어는 채점 중에 서로의 평결, 이전 라운드, 이전 점수 또는 보고서를 볼 수 없습니다; 브리프가 그렇게 알려줍니다. 지난 라운드와의 비교는 평결 후 별도 패스입니다.
- 동일한 화면, 동일한 방식으로 매 라운드 캡처하여 전후 비교가 동등하게 이루어집니다.
- 리뷰어가 실제 결제, 메시지 또는 개인 데이터를 제출하지 못하게 합니다. 데모 데이터와 새 복사본을 사용하세요.
- 샌드박스 리뷰어(Codex)는 Chrome을 시작할 수 없습니다:
review는 공유 헤드리스 Chrome을 시작하고 브리프는 드라이버 명령 앞에MSTACK_CDP_PORT=<port>를 붙이라고 알려줍니다. - 리뷰어의 답변이 형식에 맞지 않으면
rounds/r<N>/work/<reviewer>/raw-reply.txt를 읽고 다시 실행합니다. 도구는 수정 사항을 여전히 제안하는 10점과 점수보다 낮은 "수정 시" 점수를 거부합니다. - 리뷰 폴더를 제품의 저장소(또는 그 옆)에 보관하여 모든 라운드가 보존되도록 합니다.
파일
scripts/eval_loop.py: 명령줄 도구 (init, status, start-round, capture, brief, serve, review, verdict, validate, report, notify).scripts/drive.mjs: 여정 드라이버, 실제 헤드리스 Chrome; 리뷰어가 직접 사용합니다.scripts/report.py: 보고서 빌더.scripts/readiness.py: 중지 규칙 및 노이즈 검사.templates/mstack-eval.json: 시작 설정.references/config.md: 모든 설정 필드.references/verdict-format.md: 답변 형식.references/method.md: 루프가 이렇게 작동하는 이유와 기준이 성장하는 방법.