docs(dev): AskUserQuestion 비ASCII 리터럴 작성 + 복수대상 스코프확인 규약 추가
세션 회고 반영. 두 교훈 모두 이번 세션에서 실제 재질의 왕복 비용을
발생시킨 구조적 결함:
1. 한글을 \u 코드포인트로 수동 타이핑하다 오타로 2회 깨짐 → 리터럴
UTF-8 작성 규칙 명문화.
2. "각 그래프"(복수) 지적을 미터바 단수로 임의 축소 해석 → 사용자
정정("내가 말한건 육각 그래프였어") 발생 → 복수 표현 시 전체
후보 나열 규칙 명문화.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011h6etRXJLx1xdfxmVcHjBg
This commit is contained in:
parent
7185b4a4ba
commit
f086b12142
|
|
@ -82,3 +82,106 @@ fork 하드룰(Agent 재귀 호출 금지)이 정면 충돌 — 248k 토큰 소
|
||||||
다음 구조적 변경(신규 함수/모듈/스키마 등) 배치 시 orchestrator 메인 스레드에서 직접
|
다음 구조적 변경(신규 함수/모듈/스키마 등) 배치 시 orchestrator 메인 스레드에서 직접
|
||||||
/graphify 실행(서브에이전트 다수 병렬 Agent 호출) 하거나 Workflow 툴(사용자 명시 opt-in)로
|
/graphify 실행(서브에이전트 다수 병렬 Agent 호출) 하거나 Workflow 툴(사용자 명시 opt-in)로
|
||||||
처리 — fork 위임은 Agent 재귀 금지 룰 때문에 불가함을 확인(교훈).
|
처리 — 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
|
||||||
|
|
|
||||||
|
|
@ -36,3 +36,22 @@ source_session: 20260617-174635
|
||||||
W3 골자 합의 세션(`20260617-174635`)에서 orchestrator 가 W3-1 마무리 질문을 ID 약어(`C3`/`C6`/`(가)`)와 표로 과압축해 제시 → 사용자: "너무 축약적이라 W3-1에 대한 질문이 뭔질 모르겠어". 배경+선택지+권장 풀어쓰기로 전환하니 즉시 매끄럽게 답변. 첫 제시부터 풀어쓰기를 기본값으로 삼았다면 1회 왕복 비용이 없었다.
|
W3 골자 합의 세션(`20260617-174635`)에서 orchestrator 가 W3-1 마무리 질문을 ID 약어(`C3`/`C6`/`(가)`)와 표로 과압축해 제시 → 사용자: "너무 축약적이라 W3-1에 대한 질문이 뭔질 모르겠어". 배경+선택지+권장 풀어쓰기로 전환하니 즉시 매끄럽게 답변. 첫 제시부터 풀어쓰기를 기본값으로 삼았다면 1회 왕복 비용이 없었다.
|
||||||
|
|
||||||
> 관련(다른 레포): ATP 번들의 출력 스타일/압축 규약에 동 예외를 명문화하자는 protocol_feedback 가 세션 회고에 기록됨. 적용 *대상* 축은 다르지만 "압축 적용 경계" 교훈은 `caveman-bundle-compression-roi-ceiling`(번들 정적 압축 ROI 천장)과 같은 계열.
|
> 관련(다른 레포): 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 가 스코프를 막대 미터바로 좁혀 시각전략 확인 질문을 구성·구현·커밋까지 마쳤으나, 사용자가 "미터바도 좋은데 내가말한건 육각 그래프였어"로 정정. 최초 확인 질문에 "미터바/레이더 둘 다 대상인지, 어느 쪽인지"를 먼저 물었다면 방향 전환 비용(재구현+재검증 사이클)을 피할 수 있었다.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue