diff --git a/.atp/work-session/20260701-102212/report.md b/.atp/work-session/20260701-102212/report.md index 236812a..6d9023c 100644 --- a/.atp/work-session/20260701-102212/report.md +++ b/.atp/work-session/20260701-102212/report.md @@ -82,3 +82,106 @@ fork 하드룰(Agent 재귀 호출 금지)이 정면 충돌 — 248k 토큰 소 다음 구조적 변경(신규 함수/모듈/스키마 등) 배치 시 orchestrator 메인 스레드에서 직접 /graphify 실행(서브에이전트 다수 병렬 Agent 호출) 하거나 Workflow 툴(사용자 명시 opt-in)로 처리 — fork 위임은 Agent 재귀 금지 룰 때문에 불가함을 확인(교훈). + +## Retrospective + +```yaml +Retrospective: + signals: + positive: + - quote_or_paraphrase: "눈금선 추가 방식이 좋다" + about: 미터바 시각전략 AskUserQuestion(4안, 추천 표시 + preview mockup) 1라운드 즉시 선택 + - quote_or_paraphrase: "축 이름 + 점수 둘 다 표시해줘" + about: 레이더 라벨 전략 AskUserQuestion 1라운드 즉시 선택 (한글 인코딩 재질문 이후) + - quote_or_paraphrase: (암묵) 재호출 없이 완료 승인 + about: JSP 즉시반영 known-pitfall 을 curl 대조 → stale 확인 → docker restart → 재대조로 스스로 재현·검증 + negative: + - quote_or_paraphrase: "한글이 죄다깨져서 뭐라하는지 모르겟어 다시 질문해봐" + about: AskUserQuestion 호출 시 한글 텍스트를 \u 유니코드 이스케이프로 수동 작성하다 오타로 2회 깨짐 + structural: true + - quote_or_paraphrase: "미터바도 좋은데 내가말한건 육각 그래프였어" + about: 최초 요청의 "각 그래프"(복수)를 미터바 단수로 좁혀 해석 → AskUserQuestion 옵션도 좁은 스코프로만 구성 + structural: true + - quote_or_paraphrase: (사용자 확인 후 보류 승인, 그 이전 248k 토큰 무산) + about: fork 에이전트에게 graphify 서브에이전트 병렬 디스패치(Agent 재귀 필요) 위임 시도 — fork 하드룰과 충돌 + structural: true + what_went_well: + - AskUserQuestion 옵션 설계(추천 표시 + preview mockup)가 시각전략 결정에서 1라운드 즉시 수락으로 이어짐 (미터바·레이더 양쪽 모두) + - JSP 즉시반영 안 되는 known-pitfall 을 false pass 없이 curl 대조 → stale 확인 → docker restart → 재대조 순서로 자가 재현·검증 + - 영향 파일 1개·결정축 단일 이산 스코프를 정확히 판정해 advisor 전량 skip 후 orchestrator 직접 처리 — 오버엔지니어링 없이 마이크로 스코프 유지 + what_to_improve: + - AskUserQuestion 등 도구 호출에 한글/비ASCII 텍스트를 넣을 때 \u 유니코드 이스케이프를 손으로 타이핑해 2회 깨짐 — 리터럴 UTF-8 문자로 작성해야 함 + - 이미지+텍스트 요청에서 "각 그래프"(복수)라는 표현을 단수(미터바)로 좁혀 해석 후 AskUserQuestion 옵션도 그 좁은 스코프로만 구성 — 최초 스코프 확인 단계에서 대상 전체 목록을 먼저 명시해야 했음 + - fork 서브에이전트에게 Agent 재귀가 필요한 작업(graphify 서브에이전트 병렬 디스패치)을 위임 시도 → fork 하드룰과 충돌해 248k 토큰 소모 후 무산. 위임 전 대상 작업의 툴 제약(Agent 재귀 요구 여부)을 먼저 확인해야 함 + memory_candidates: + - name: askuserquestion-non-ascii-literal-not-escape + type: feedback + description: AskUserQuestion 등 도구 호출에 한글/비ASCII 텍스트를 넣을 때 \u 유니코드 이스케이프 수동 타이핑 금지 — 리터럴 UTF-8 문자로 작성 + body_draft: | + Why: AskUserQuestion 호출 파라미터에 한글을 \u 이스케이프 시퀀스로 손으로 타이핑하면 + 오타(자릿수 누락/오기) 로 렌더링이 깨져 사용자가 옵션을 읽을 수 없게 된다. 같은 세션에서 + 2회 발생 — "한글이 죄다깨져서 뭐라하는지 모르겟어" 로 재질문 유발, 왕복 비용 발생. + How to apply: 도구 호출 파라미터에 비ASCII 텍스트가 필요하면 항상 리터럴 UTF-8 문자로 + 직접 작성한다. \u 이스케이프를 수동으로 조립하지 않는다 (인코딩은 도구/런타임이 처리할 + 영역이지 수기 작성 대상이 아님). + rationale_for_saving: 재현 가능한 도구 사용 패턴 결함 — 코드나 git log 로 유도 불가, 관찰로만 드러남. 프로젝트 특정이 아니라 도구 사용 습관이라 프로젝트 문서(agent-output-conventions.md, AskUserQuestion 제시문 규약 문서)와 사용자 전역 설정 양쪽에 적용 가치. + signal_source: negative + docs_sync_target: /Users/wemadeplay/workspace/stz/bibimbap/docs/development/agent-output-conventions.md + memory_optional: true + - name: fork-agent-recursion-precheck-before-delegation + type: feedback + description: fork 서브에이전트에게 위임 전, 대상 작업이 Agent 툴(서브에이전트 재귀 디스패치) 을 요구하는지 먼저 확인 — fork 는 Agent 재귀 금지 하드룰 적용 + body_draft: | + Why: graphify 전체 파이프라인(Step 3B: 서브에이전트 필수 병렬 디스패치) 을 fork 에이전트에게 + 위임했으나, fork 는 Agent 재귀 호출이 금지된 하드룰 적용 대상이라 정면 충돌 — 248k 토큰을 + 소모한 뒤에야 무산이 확인됨. 위임 전 확인했다면 즉시 회피 가능했던 낭비. + How to apply: 어떤 작업(스킬/파이프라인)을 fork 서브에이전트에게 위임하기 전에, 그 작업이 + 내부적으로 Agent 툴 호출(서브에이전트 추가 디스패치)을 필수로 요구하는지 먼저 확인한다. + 요구한다면 fork 위임이 불가하므로 orchestrator 메인 스레드에서 직접 실행하거나 사용자 + 명시 opt-in 경로(예: Workflow 툴)로 전환한다. + rationale_for_saving: 재발 가능(구조적) — fork 의 툴 제약은 프로토콜 레벨 규약이라 매 위임 시점에 재확인해야 함. 유사 위임 판단이 반복될 것으로 예상. + signal_source: negative + docs_sync_target: null + memory_optional: true + conflicts_with: null + - name: plural-target-phrase-scope-confirm-before-narrowing + type: feedback + description: 이미지+텍스트 사용자 요청에서 "각 그래프" 등 복수 대상 표현이 있으면 임의로 단수 스코프로 좁히지 말고, 확인 질문에 대상 전체 목록을 먼저 명시 + body_draft: | + Why: 사용자 최초 요청("리뷰 종합 항목 그래프(막대 미터 + 육각 레이더)에서 각 그래프 끝이...") + 에 두 그래프 유형이 병기돼 있었는데도, orchestrator 가 "각 그래프"를 미터바 단수로 + 좁혀 해석하고 AskUserQuestion 옵션도 그 좁은 스코프로만 구성함. 미터바 수정 완료 후 + "미터바도 좋은데 내가말한건 육각 그래프였어" 로 정정 발생 — 작업을 두 배로 나눠 처리하게 됨. + How to apply: 사용자 요청(특히 이미지 첨부)에 복수형 대상 표현("각 ~", "그래프들", "여기저기") + 이 있으면, 대상이 하나로 좁혀지는지 확신이 없는 한 확인 질문(AskUserQuestion 등)에 발견된 + 대상 전체 목록을 먼저 명시하고 스코프를 선택하게 한다. 임의로 대표 사례 하나만 골라 + 진행하지 않는다. + rationale_for_saving: 재발 가능 — 이미지+텍스트 혼합 요청에서 복수 대상 지시어는 반복될 패턴. 사용자 원 발화 재검토로만 드러나는 교훈이라 코드/커밋으로 유도 불가. + signal_source: negative + docs_sync_target: /Users/wemadeplay/workspace/stz/bibimbap/docs/development/agent-output-conventions.md + memory_optional: true + - name: askuserquestion-recommended-preview-mockup-effective + type: feedback + description: 시각전략 등 이산 선택 AskUserQuestion 에서 "추천 표시 + preview mockup" 병기 옵션 설계가 1라운드 즉시 수락으로 이어짐 + body_draft: | + Why: 미터바·레이더 시각전략 두 차례 모두 AskUserQuestion 에 추천 옵션 표시 + 각 옵션의 + 시각 결과 preview(mockup) 를 병기하자 사용자가 재질문 없이 1라운드에 선택. 비자명한 + 선택이었으나(4안 중 택1, 시각 결과를 텍스트만으론 가늠하기 어려움) 검증된 패턴. + How to apply: UI/시각 관련 이산 선택을 사용자에게 물을 때는 옵션 설명 텍스트만으로 + 끝내지 않고, 가능하면 추천 표시 + 결과 미리보기(mockup/스케치) 를 함께 제시한다. + rationale_for_saving: 비자명한 판단(일반적으로 텍스트 설명만으로 충분하다 여길 수 있는 상황에서 preview 를 추가 투자)이 검증된 성공 사례 — 재현 가치 있음. + signal_source: positive + docs_sync_target: /Users/wemadeplay/workspace/stz/bibimbap/docs/development/agent-output-conventions.md + memory_optional: true + protocol_feedback: + - fork 에게 위임 가능한 작업의 범위를 판별할 때, "대상 스킬/파이프라인이 Agent 툴(서브에이전트 재귀 디스패치)을 필수로 요구하는가" 를 위임 전 체크리스트 항목으로 명문화할 것을 제안 (예: platform-adapters.md 또는 fork 위임 경로 문서에 "위임 전 툴 제약 프리체크" 항목 추가). 이번 세션은 사후 확인(248k 토큰 소모 후)이라 손실이 컸음. + - AskUserQuestion 등 도구 호출 파라미터에 비ASCII 텍스트를 다뤄야 하는 경우의 작성 규칙(리터럴 UTF-8, \u escape 수동 조립 금지)을 agent-output-conventions.md 류 문서에 명문화할 것을 제안 — 현재는 "제시문 풀어쓰기" 규칙만 있고 인코딩 안전성 규칙은 부재. + applied_changes: [] +``` + +## memory_candidates 처리 +docs 반영 완료(같은 커밋): docs/development/agent-output-conventions.md 에 규칙 2(비ASCII 리터럴 작성, \u 수동 이스케이프 금지), 규칙 3(복수 대상 지적 시 스코프 임의 축소 금지) 추가. +protocol_feedback(fork 위임 전 Agent 재귀 요구 여부 프리체크 명문화) 는 atp 번들 직접 수정 권한 밖 — open_items 에 이미 기록된 교훈으로 충분, 별도 반영처 없음. +memory(전역) 갱신: 보류 — 사용자 memory 활성 설정 미확인, docs 단독 마감. + +ended_at: 2026-07-01T11:26:20+09:00 diff --git a/docs/development/agent-output-conventions.md b/docs/development/agent-output-conventions.md index 7d6c801..8e121ec 100644 --- a/docs/development/agent-output-conventions.md +++ b/docs/development/agent-output-conventions.md @@ -36,3 +36,22 @@ source_session: 20260617-174635 W3 골자 합의 세션(`20260617-174635`)에서 orchestrator 가 W3-1 마무리 질문을 ID 약어(`C3`/`C6`/`(가)`)와 표로 과압축해 제시 → 사용자: "너무 축약적이라 W3-1에 대한 질문이 뭔질 모르겠어". 배경+선택지+권장 풀어쓰기로 전환하니 즉시 매끄럽게 답변. 첫 제시부터 풀어쓰기를 기본값으로 삼았다면 1회 왕복 비용이 없었다. > 관련(다른 레포): ATP 번들의 출력 스타일/압축 규약에 동 예외를 명문화하자는 protocol_feedback 가 세션 회고에 기록됨. 적용 *대상* 축은 다르지만 "압축 적용 경계" 교훈은 `caveman-bundle-compression-roi-ceiling`(번들 정적 압축 ROI 천장)과 같은 계열. + +## 규칙 2 — 도구 호출에 넣는 비ASCII(한글 등) 텍스트는 리터럴로 작성, `\u` 수동 이스케이프 금지 + +`AskUserQuestion` 등 JSON 파라미터에 한글을 넣을 때 `\uXXXX` 코드포인트를 손으로 타이핑하지 않는다. 코드포인트 하나라도 오타 나면 렌더링 시 깨진 문자로 나타나고, 에이전트 자신은 도구 호출 스키마상 오류를 감지하지 못한 채 그대로 사용자에게 전달된다. 사용자에게는 "질문 자체가 뭔지 모르겠다"로 나타나 재질의 왕복이 발생한다. + +- 항상 실제 UTF-8 문자를 그대로 입력한다(복붙 아님, 정상 타이핑). +- 결과물이 의심되면 보내기 전에 스스로 읽어 자연스러운 한글인지 확인한다. + +### 발원 사례 + +세션 `20260701-102212` — `AskUserQuestion` 옵션 라벨/설명에 한글을 `\u` 이스케이프로 수동 작성하다 코드포인트 오타 2회 발생. 사용자: "육각 마범롘 다이었 끝점(궁벀 불망 지겁)..." 같은 깨진 텍스트를 받고 "한글이 죄다깨져서 뭐라하는지 모르겟어 다시 질문해봐"로 지적. 리터럴 문자로 재작성하자 즉시 정상 렌더링. + +## 규칙 3 — 사용자 지적에 복수 대상 표현이 있으면 스코프를 임의로 좁히지 말고 대상 목록을 먼저 확인 + +이미지·스크린샷을 동반한 지적에 "각 그래프", "이것들" 처럼 복수/포괄 표현이 쓰이면, 그 중 하나(가장 먼저 눈에 띄는 요소)로 스코프를 임의 축소해 확인 질문(`AskUserQuestion` 등)을 구성하지 않는다. 확인 질문 자체에 "지적 대상이 A/B/C 중 무엇인지"를 먼저 명시하거나, 최소한 확인 질문의 배경 문장에 전체 후보를 나열해 사용자가 스코프 오판을 즉시 정정할 수 있게 한다. + +### 발원 사례 + +세션 `20260701-102212` — 사용자가 스크린샷과 함께 "각 그래프의 끝이 어떤 점수인지 알 수 없다"고 지적(화면엔 막대 미터바 6개 + 육각 레이더 1개, 즉 "그래프"가 최소 2종류 혼재). orchestrator 가 스코프를 막대 미터바로 좁혀 시각전략 확인 질문을 구성·구현·커밋까지 마쳤으나, 사용자가 "미터바도 좋은데 내가말한건 육각 그래프였어"로 정정. 최초 확인 질문에 "미터바/레이더 둘 다 대상인지, 어느 쪽인지"를 먼저 물었다면 방향 전환 비용(재구현+재검증 사이클)을 피할 수 있었다.