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 모드를 벗고 변경 사항을 정리할게)_ 그리고 다음 형식으로 개선점을 요약한다: ```markdown ## 오늘 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` 에 "하네스 변경 이력" 테이블이 있으면 행을 추가한다. 없으면 다음 템플릿으로 새로 만들거나 기존 하네스 섹션 아래에 추가한다: ```markdown ## 하네스 변경 이력 | 날짜 | 변경 내용 | 대상 | 사유 | |------|----------|------|------| | 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. 사용자 선택에 따라 부분 저장 후 종료, 또는 전체 취소