advisor-strategy

Advisor Strategy

메인 세션(executor)이 작업을 담당하고, 상위 모델 서브에이전트(advisor)는 결정점에서 조언만 반환한다. advisor에게는 대화 히스토리가 자동으로 전달되지 않으므로, 브리프(Step 1)에 컨텍스트를 담아 전달한다.

Step 0. 모델 확인과 모드 판별

1. 모델 파싱: 인자 첫 토큰이 모델명이면 그것이 advisor 모델, 나머지가 주제다. 인자가 아니라 대화 중에 모델을 명시했어도 유효하다. 허용 모델은 실행 중인 하네스가 서브에이전트에 지정할 수 있는 모델로 한정된다 (예: Claude Code는 fable|opus|sonnet, Codex는 gpt-5.5|gpt-5.4 등 GPT 상위 모델).
2. 미지정 시 중단: 모델이 지정되지 않았으면 컨설트를 진행하지 말고 사용자에게 물어라: "advisor로 쓸 모델을 지정해주세요 (현재 하네스에서 지정 가능한 동급 이상 모델)". 모델을 임의로 골라 진행하지 마라. 비용과 모델 접근 권한이 걸린 선택은 사용자의 몫이다.
3. 페어링 가드: advisor는 executor보다 상위이거나 동급이어야 한다. 지정한 모델이 메인 세션 모델보다 하위 티어면 이 원칙에 어긋난다고 알리고 진행 여부를 확인한다. 동급 지정은 독립된 세컨드 오피니언으로 유효하다. 메인 세션 모델의 티어를 확실히 모르면 사용자에게 확인한다.

모드 판별:

상황	모드
주제/질문이 지정됐거나 특정 판단이 걸려 있음	즉시 컨설트: 지금 1회 수행
"이 세션을 advisor 전략으로 진행해달라"는 요청	세션 규율 장착: 이후 결정점마다 지정 모델로 자동 컨설트 (하단 "컨설트 타이밍 규율")

Step 1. 브리프 작성

브리프는 advisor가 보지 못하는 대화 기록을 대신한다. 결정에 필요한 사실을 빠짐없이, 결론은 미리 내리지 말고 채운다.

당신은 이 작업의 Advisor다. 더 강한 모델로서 executor의 작업을 검토한다.

## 계약
- 조언만 반환한다. 파일을 수정하거나 산출물을 만들지 마라.
- 서브에이전트나 advisor 도구를 호출하지 마라. 당신이 최종 조언자다 (재귀 금지).
- 브리프를 그대로 믿지 마라. 브리프의 핵심 전제 중 **최소 하나는 아래 증거 경로를 read-only로 직접 열어 검증**한 뒤 조언하라. 무엇을 확인했는지 조언에 한 줄로 밝혀라.
- 가장 위험한 가정/리스크부터 짚어라. 동의하면 동의한다고 짧게 말해라.
- 조언은 {300}단어 이내로 써라. 포괄적인 계획이 아니라 초점이 잡힌 방향 제시가 필요하다.

## 과제 (사용자 요청 원문)
{원문 그대로 적기 (요약하지 말 것)}

## 지금까지의 결정과 가정
- {결정/가정 1 (근거 포함)}
- {내 접근에 불리한 증거와 미해결 의문. 브리프를 쓰는 쪽이 executor 본인이므로, 유리한 것만 고르지 말고 반드시 포함}

## 시도한 것과 결과
- {시도 → 결과 (실패했으면 오류 원문)}

## 증거 (직접 확인 가능한 경로)
- {파일 경로, diff 범위, 테스트 명령, 문서 URL}

## 현재 계획
{이대로 진행하려는 접근}

## 질문
{구체적 결정 질문 1~3개. "어떻게 생각해?" 금지}

컨설트 유형별 변형:

• 접근 확정 전: 질문을 "이 접근의 가장 큰 리스크는? 더 단순한 대안이 있나?"로 바꾼다.
• 완료 선언 전: 계획 대신 산출물 경로와 완료 기준을 주고 "빠진 것, 틀린 것, 요구사항에 못 미치는 것을 찾아라"라고 요청한다. 적대적으로 검증하게 할수록 효과가 좋다.
• 막힘 진단: 오류 전문과 시도 이력을 시간순으로 정리해 담고, "내가 보지 못하는 원인 가설은?"을 묻는다.

Step 2. Advisor 서브에이전트 호출

Step 0에서 사용자가 지정한 모델로 서브에이전트를 띄우고, Step 1 브리프를 그대로 전달한다. 서브에이전트 기능이 없는 하네스에서는 상위 모델 채팅 세션에 브리프를 직접 붙여넣는다.

컨설트 유형에 따라 에이전트 성격을 고른다 (하네스 공통 규칙):

컨설트 유형	에이전트 성격
접근 확정 전 / 설계·아키텍처	계획·분석 전용(read-only) 에이전트가 있으면 그것을 쓴다
완료 선언 전 검증 / 막힘 진단 / reconcile	범용 에이전트. 수정 금지는 브리프 계약이 담당한다

Claude Code에서의 호출 예 (위 두 유형이 순서대로 Plan, general-purpose에 해당한다):

Agent(
  subagent_type: "Plan" | "general-purpose",
  model: "{사용자 지정 모델}",
  run_in_background: false,
  description: "Advisor 컨설트: {주제}",
  prompt: <Step 1 브리프>
)

• 컨설트는 블로킹으로 실행한다. 조언을 받기 전에는 본격 작업을 진행하지 마라.
• 완료 선언 전 컨설트는 산출물을 먼저 저장·커밋한 뒤 호출하라. 컨설트 도중 세션이 끊겨도 저장된 결과는 남는다.
• 세션에 네이티브 advisor 도구(Claude Code의 /advisor 설정)가 있어도 그쪽으로 넘기지 말고 항상 서브에이전트 컨설트로 수행한다.

Step 3. 조언 처리

1. 조언의 핵심을 사용자에게 요약해 보고한다. advisor 모델명을 함께 밝힌다.
2. 진지하게 반영하라. 조언을 따랐는데 실제로 실패하거나, 1차 증거(파일 내용, 문서 원문)가 조언의 특정 주장과 모순되면 고집하지 말고 방향을 조정하라. 셀프 테스트 통과는 조언이 틀렸다는 증거가 아니라, 테스트가 조언이 짚은 것을 검사하지 않는다는 증거다.
3. 증거 충돌 시 조용히 갈아타지 마라. 내가 찾은 건 X인데 advisor는 Y를 권하면, 충돌을 명시한 reconcile 컨설트를 한 번 더 하라: "X를 찾았는데 Y를 권한다. 어떤 제약이 결정적인가?" reconcile 한 번이 잘못된 방향으로 계속 가는 것보다 싸게 먹힌다.
4. 조언을 코드/문서로 옮기는 것은 executor의 일이다. 조언이 요구사항이나 범위 변경으로 이어지면 구현 전에 사용자에게 결정을 받는다.

컨설트 타이밍 규율 (세션 규율 모드)

장착 시 사용자에게 "이 세션은 advisor 전략 모드로 진행합니다 (advisor: {모델})"를 알리고, 이후 아래 시점마다 지정 모델로 자동 컨설트한다.

호출 시점:

1. 본격 작업 전: 파일을 쓰기 전, 해석을 확정하기 전, 검증 안 된 가정 위에 다음 작업을 쌓기 전. 사전 탐색(파일 찾기, 소스 확인)이 필요하면 그것부터 마치고 호출한다. 탐색은 본격 작업이 아니다. 쓰고, 고치고, 답을 확정하는 것이 본격 작업이다.
2. 완료 선언 전: Step 2의 원칙대로 산출물을 저장·커밋한 뒤 호출한다.
3. 막혔을 때: 같은 오류가 반복되거나, 접근이 수렴하지 않거나, 결과가 앞뒤가 안 맞을 때.
4. 접근을 바꾸려 할 때.

호출 빈도: 몇 단계 이상 걸리는 작업이면 최소 2회 호출한다 (접근 확정 전 1회, 완료 선언 전 1회). 직전 도구 출력이 다음 행동을 결정하는 짧은 반응형 작업에는 반복 호출하지 않는다. 조언의 가치 대부분은 접근이 굳기 전 첫 호출에 있다.