5.0 KiB
| kind | title | description | status | created_at | source_session |
|---|---|---|---|---|---|
| development | 에이전트 출력 규약 — 사용자 대면 의사결정 제시 | AI 에이전트(특히 ATP orchestrator)가 사용자에게 결정/선택을 요청할 때의 제시문 규약. 출력 압축(약어·ID 참조·표 과밀)의 적용 경계를 정한다. | active | 2026-06-18 | 20260617-174635 |
에이전트 출력 규약 — 사용자 대면 의사결정 제시
재사용 규칙. AI 에이전트가 작업 중 사용자와 주고받는 출력의 스타일 경계를 정한다.
규칙 1 — 의사결정 제시문에는 출력 압축을 적용하지 않는다
사용자에게 결정/선택/판정을 요청하는 제시문(질문, AskUserQuestion 옵션 포함)은 항상 풀어 쓴다:
- 배경 — 왜 묻는지, 무엇에 걸린 결정인지
- 선택지 — 각 옵션을 ID·약어가 아닌 문장으로
- 권장 — 있으면 이유와 함께
약어·ID 교차참조·과밀 표는 보조로만 병기한다. AskUserQuestion 팝업을 쓰더라도 옵션 라벨·설명은 자기완결적이어야 한다(외부 표를 봐야 이해되는 라벨 금지).
압축형(요약·약어 위주)은 사용자가 명시 요청("요약만", "짧게")했을 때만 쓴다.
압축이 허용되는 범위
출력 압축(caveman 류 토큰 다이어트 포함)은 에이전트 간 내부 산출물·로그·요약에 한정한다. 거기선 ROI 양수다. 사용자 대면 결정 제시에서는 파악 실패 → 재질의 왕복 비용이 압축 절감을 초과한다.
Why
토큰을 줄이려는 압축 경향이 사용자가 답을 줘야 하는 의사결정 제시문으로 번지면, ID 참조·표는 작성자에겐 자명해도 사용자에겐 "무엇을 묻는지" 자체가 불투명해진다. 압축의 적용 대상 경계가 잘못 그어진 것이다.
발원 사례
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 가 스코프를 막대 미터바로 좁혀 시각전략 확인 질문을 구성·구현·커밋까지 마쳤으나, 사용자가 "미터바도 좋은데 내가말한건 육각 그래프였어"로 정정. 최초 확인 질문에 "미터바/레이더 둘 다 대상인지, 어느 쪽인지"를 먼저 물었다면 방향 전환 비용(재구현+재검증 사이클)을 피할 수 있었다.