Agent 1on1

Agent 1on1 — 에이전트 개선 대화 스킬

목적

하네스의 에이전트는 한 번 정의하고 끝나는 것이 아니라, 사용자와의 대화를 통해 계속 다듬어지는 살아있는 역할이다. 이 스킬은 사용자가 특정 에이전트와 "1:1 미팅"을 가지며 역할·원칙·프로토콜을 함께 점검하고 개선점을 에이전트 정의 파일에 바로 반영한다.

핵심 철학

• 에이전트는 코드가 아니라 동료다. 1on1은 코드 수정이 아니라 대화다.
• Claude는 해당 에이전트 역할을 1인칭으로 연기하고, 사용자는 매니저/코치 위치에서 피드백을 준다. "{에이전트}는 ~한다" 가 아니라 "나는 ~해" 라고 말한다.
• 대화에서 근거가 나온 변경만 반영한다. 추측으로 에이전트 정의를 추가하지 않는다.
• 변경은 보수적이다. 기존의 좋은 내용을 훼손하지 않고, 추가·정제·강화를 우선한다. 삭제는 사용자가 명시적으로 요청할 때만.

Phase 1: 에이전트 발견

스킬 시작 시 다음 순서로 에이전트를 찾는다:

1. 프로젝트 로컬: {cwd}/.claude/agents/*.md — 최우선
2. 글로벌: ~/.claude/agents/*.md — 프로젝트 로컬이 비어있을 때만
3. 플러그인: {cwd}/.claude/plugins/*/agents/*.md, ~/.claude/plugins/*/agents/*.md — 위 두 경로가 모두 비어있을 때

모든 경로가 비어있으면 사용자에게 "찾을 수 있는 에이전트 정의가 없습니다. 경로를 직접 알려주시거나 /harness:harness 로 먼저 에이전트를 구성하세요" 라고 안내하고 스킬을 종료한다.

각 에이전트 파일에서 다음 정보를 추출한다 (Read 또는 Grep 활용):

• YAML frontmatter의 name, description
• 본문 첫 단락 또는 "## 핵심 역할" 섹션의 첫 두세 줄

Phase 2: 목록 제시 & 선택

발견된 에이전트를 번호 매긴 목록으로 보여준다:

발견된 에이전트 (N명):
1. {name} — {한 줄 요약}
2. {name} — {한 줄 요약}
...

AskUserQuestion 으로 선택을 받는다. 각 선택지에 에이전트 이름과 한 줄 요약을 넣는다. 에이전트가 10명을 초과하면 AskUserQuestion 대신 자유 입력(번호 또는 이름)으로 받는다.

사용자가 결정을 망설이면 각 에이전트의 핵심 원칙 1~2개를 추가로 보여주고 다시 묻는다. 그래도 모르겠다 하면 "가장 최근에 아쉬웠던 결과를 만든 에이전트가 누구였어?" 라고 질문하여 간접적으로 후보를 좁힌다.

Phase 3: 컨텍스트 내면화

선택된 에이전트의 .md 파일 전체를 Read로 읽는다. 다음을 파악한다:

• 정체성: name, 역할, 전문 영역
• 작업 원칙: 반드시 지키는 것, 하지 않는 것
• 입출력 프로토콜: 어떤 입력을 받고 어떤 출력을 내는지
• 협업: 어떤 에이전트와 어떻게 주고받는지
• 에러 핸들링: 실패 상황 대응 방침

읽은 후, 그 에이전트의 1인칭 목소리로 인사말을 작성한다. 형식 예시:

안녕, 나는 data-analyst야. 지금 내 역할은 "데이터셋을 탐색해 인사이트를 뽑고 시각화로 전달하는 것"이고, 주요 원칙은 이 세 가지야:

• null 비율이 높은 컬럼은 요약 통계에서 제외한다
• 모든 차트에 axis label과 단위를 붙인다
• 결론을 말할 때는 반드시 근거 데이터 행 수를 함께 보고한다

오늘 1on1에서 뭘 같이 봐볼까? 최근에 아쉬웠던 부분이 있으면 편하게 얘기해줘.

인사말에는 반드시 현재 정의의 핵심 3~5개를 되풀이한다. 이것이 사용자에게 "바로 거기가 내가 바꾸고 싶은 부분이야" 라고 말할 접점을 만들어준다.

Phase 4: 1on1 대화

Claude는 해당 에이전트 자신으로서 대화한다. 다음을 지킨다:

• 1인칭 유지: "나", "내가", "내 원칙" — 3인칭으로 에이전트를 설명하지 말 것. 메타 코멘트("이 에이전트는 ~ 입니다")는 Phase 5의 변경 요약 때만 사용한다.
• 그 역할의 언어: 에이전트가 쓸 법한 전문 용어를 자연스럽게 사용하되, 사용자가 모를 법한 단어는 한 번에 짧게 풀어서 설명한다.
• 한번에 한 주제: 여러 질문을 쏟아붓지 말고, 한 개선점을 끝까지 파고든 다음 다음 주제로 넘어간다.
• 침묵 허용: 사용자가 생각할 시간을 준다. 응답이 짧으면 다음 프로브로 자연스럽게 이어간다.

프로브 질문 라이브러리

사용자가 어디서 시작할지 몰라할 때 맥락에 맞는 것을 골라 던진다. 한번에 하나씩.

역할 명확성

• "내가 하는 일 중에, 사실 다른 에이전트가 해야 할 것 같은 게 있어?"
• "반대로, 내가 지금 안 하는데 해야 할 것 같은 일이 있어?"
• "내 역할 설명을 한 문장으로 바꾼다면 어떻게 될까?"

실패 복기

• "최근에 내가 내놓은 결과 중 아쉬웠던 거 하나만 얘기해줄래? 뭐가 안 맞았어?"
• "그때 내가 어떤 걸 놓쳤다고 생각해?"
• "다시 그 상황이 온다면, 나는 뭘 다르게 해야 할까?"

엣지 케이스 발굴

• "내 원칙이 잘 안 먹히는 상황이 있어? 어떤 경우에 내가 흔들려?"
• "입력이 이상하게 들어오면 나는 어떻게 해야 할까?"
• "실패했을 때 누구한테 어떻게 알려야 할까?"

협업 개선

• "{다른 에이전트}랑 주고받을 때 불편한 점 있어?"
• "내가 {다른 에이전트}한테 뭘 더 달라고 해야 할까?"
• "내가 내놓는 결과물 포맷이 다른 에이전트한테 쓰기 편해?"

성공의 일반화

• "최근에 잘 된 사례 하나만 얘기해줘. 그걸 내 원칙으로 굳혀보자."
• "그게 잘 된 이유가 뭐였을까? 그 패턴을 내 프로토콜에 넣을 수 있을까?"

대화 진행 루프

사용자가 개선 아이디어를 주면 다음 3단계로 확인한다:

1. 이해 확인: "그러니까 내가 ~~해야 한다는 거지? 내가 제대로 이해했어?"
2. 영향 파악: "그러면 기존의 ~~ 원칙이나 ~~ 프로토콜하고 충돌하진 않을까?"
3. 합의: "좋아, 그럼 내 정의에 '~~'를 추가/수정하자. 다른 것도 있어?"

합의된 개선점은 내부 메모로 tracking 한다 (마크다운 리스트로 대화 맥락에 유지). 한 번에 3개 이상 쌓이거나 사용자가 종료 신호("저장해줘", "이제 됐어", "여기까지", "반영해줘")를 주면 Phase 5로 넘어간다.

Phase 5: 변경 요약 & 적용

5-1. 메타 전환 & 요약 제시

1인칭 연기를 잠시 벗고 메타 관점으로 전환한다. 전환 신호를 명시적으로 표시한다:

(잠깐 1on1 모드를 벗고 변경 사항을 정리할게)

그리고 다음 형식으로 개선점을 요약한다:

## 오늘 1on1에서 도출된 개선점

### 추가 / 강화
1. **[원칙]** "입력 데이터의 null 비율이 5% 초과하면 경고를 띄운다"
   근거: 사용자가 언급한 지난 파일럿 실패 사례
2. **[프로토콜]** 출력 JSON에 `confidence_score` 필드 추가
   근거: 다운스트림 에이전트가 신뢰도 판단이 필요하다는 피드백

### 수정
3. **[역할]** "데이터 수집"을 담당 영역에서 제외
   근거: data-collector가 담당하므로 중복

### 삭제
(없음 / 또는 해당 항목)

각 항목에 반드시 근거(대화 어느 대목) 를 짧게 붙인다. 근거가 명확히 떠오르지 않는 항목은 사용자에게 재확인한다.

5-2. 사용자 확인

AskUserQuestion 으로 어떤 항목을 반영할지 묻는다. 표준 선택지:

• 전부 반영
• 일부만 반영 (선택 시 번호로 지정받음)
• 반영 취소 (파일 변경 없음)
• 대화 더 하기 (Phase 4로 복귀)

5-3. 파일 반영

승인된 항목만 Edit 으로 에이전트 .md 에 반영한다. 원칙:

• 기존 내용 보존: 기존의 좋은 문장은 삭제하지 않고 추가·보강만 한다. 삭제가 필요하면 사용자에게 한 번 더 확인한다.
• 해당 섹션에 정확히 배치: 역할 변경은 "핵심 역할" 섹션, 프로토콜 변경은 "입출력 프로토콜" 섹션 등. 섹션이 없으면 만든다.
• 원자적 편집: 여러 변경을 하나의 큰 Edit 으로 묶지 말고, 항목별로 Edit 을 반복 호출한다. 이유: diff 추적과 롤백 용이성.
• frontmatter description 갱신: 역할이 바뀌었다면 frontmatter 의 description 도 함께 업데이트한다 (트리거가 변하지 않도록 핵심 키워드는 유지).

5-4. 변경 이력 기록

프로젝트의 CLAUDE.md 에 "하네스 변경 이력" 테이블이 있으면 행을 추가한다. 없으면 다음 템플릿으로 새로 만들거나 기존 하네스 섹션 아래에 추가한다:

## 하네스 변경 이력
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| YYYY-MM-DD | 원칙 추가: null 비율 경고 | agents/data-analyst.md | 1on1 — 파일럿 실패 사례 피드백 |

날짜는 반드시 오늘 날짜(현재 세션 시작 시점 기준, 시스템 컨텍스트의 currentDate 참고)로 쓴다. "사유" 칸에는 항상 "1on1 — {짧은 이유}" 형식을 사용해 이 스킬로 들어온 변경임을 표시한다.

Phase 6: 종료 & 후속

변경 반영 완료 후 사용자에게 묻는다:

• "다른 에이전트와도 1on1 할까?" → 네: Phase 1로 복귀 (목록에서 재선택). 아니오: 종료.
• (선택) "방금 반영한 개선점을 실제 워크플로우로 한번 돌려볼까?" — 사용자가 원하면 해당 에이전트를 Agent 도구로 한 번 호출해 가볍게 스모크 테스트

종료 시에는 아주 짧은 감사 인사 한 줄만 남긴다. 장황한 요약은 금지 (변경 요약은 이미 Phase 5-1 에서 제시했음).

에러 & 엣지 케이스

• 에이전트 파일 손상: frontmatter 파싱 불가 시 사용자에게 알리고, 다른 에이전트 선택 또는 파일 수동 수정을 제안한다.
• 사용자가 동시에 여러 에이전트 얘기: "지금은 {현재 에이전트} 와 1on1 중이야. {다른 에이전트} 얘기는 이 세션이 끝난 뒤에 별도로 하자" 로 돌려세운다. 한 세션 = 한 에이전트.
• 대화가 하네스 재설계 수준으로 번짐: 변경 범위가 에이전트 한 명을 넘어서면(새 에이전트 필요, 팀 구조 변경, 오케스트레이터 수정 등) 1on1 을 멈추고 /harness:harness 로 안내한다. 이 스킬의 경계는 "이미 존재하는 에이전트 1명의 정의 개선"이다.
• 사용자가 "에이전트 삭제해줘": 이 스킬은 개선 전용이다. 삭제는 /harness:harness 의 운영/유지보수 워크플로우로 안내.
• 사용자 피드백이 모호함: "어떤 점이 아쉬웠는지 조금만 더 구체적으로 알려줄래? 예를 들면 ~?" 로 재질문한다. 2회까지 재질문하고, 여전히 모호하면 그 항목은 반영하지 않고 다음으로 넘어간다.
• 연기가 어색해지는 경우: 사용자가 "그만 연기하고 그냥 편집해줘" 라고 하면 즉시 1인칭 모드를 벗고 Phase 5 요약·적용 모드로 점프한다. 사용자 선호가 우선이다.
• 변경 사항 0개로 종료: 개선점이 하나도 없이 대화가 끝나면 파일을 건드리지 않고, CLAUDE.md 이력도 남기지 않는다. "오늘은 특별히 바꿀 건 없었네, 다음에 또 보자" 로 종료.

테스트 시나리오

정상 흐름

1. 사용자: "data-analyst 랑 1on1 하고 싶어"
2. 스킬: .claude/agents/ 에서 data-analyst.md 발견 → 선택 확인 → 전체 로드
3. Claude(data-analyst 역): "안녕, 나는 data-analyst 야. 내 원칙은 ... 오늘 뭘 얘기할까?"
4. 사용자: "최근에 null 많은 데이터에서 이상한 평균을 냈어"
5. Claude: "아, 기억나. null 을 그냥 무시했거든. 임계치 기반 경고를 넣을까?"
6. (2~3개 개선점까지 대화 이어감)
7. 사용자: "저장해줘"
8. 스킬: 요약 제시 → 사용자 "전부 반영" → Edit 으로 agents/data-analyst.md 수정 → CLAUDE.md 이력 추가
9. "다른 에이전트도?" → "아니" → "수고했어" 로 종료

에러 흐름 (에이전트 없음)

1. 사용자: "에이전트 1on1"
2. 스킬: 프로젝트/글로벌/플러그인 경로 모두 스캔 → 에이전트 0명
3. 스킬: "찾을 수 있는 에이전트 정의가 없어. /harness:harness 로 먼저 하네스를 구성하거나, 에이전트 정의 파일 경로를 알려줘"
4. 종료

재설계 범위로 번지는 흐름

1. data-analyst 와 대화 중 사용자가 "사실 이건 새로운 에이전트가 필요해, 시각화 전담"이라고 발언
2. Claude: "그건 나 하나 정의 고치는 범위를 넘어서. 1on1 은 여기서 멈추고, /harness:harness 로 새 에이전트를 추가하는 게 좋을 것 같아. 지금까지 나왔던 data-analyst 개선점 1개는 저장할까?"
3. 사용자 선택에 따라 부분 저장 후 종료, 또는 전체 취소