58 lines
5.0 KiB
Markdown
58 lines
5.0 KiB
Markdown
---
|
|
kind: development
|
|
title: 에이전트 출력 규약 — 사용자 대면 의사결정 제시
|
|
description: AI 에이전트(특히 ATP orchestrator)가 사용자에게 결정/선택을 요청할 때의 제시문 규약. 출력 압축(약어·ID 참조·표 과밀)의 적용 경계를 정한다.
|
|
status: active
|
|
created_at: 2026-06-18
|
|
source_session: 20260617-174635
|
|
---
|
|
|
|
# 에이전트 출력 규약 — 사용자 대면 의사결정 제시
|
|
|
|
재사용 규칙. AI 에이전트가 작업 중 사용자와 주고받는 출력의 스타일 경계를 정한다.
|
|
|
|
## 규칙 1 — 의사결정 제시문에는 출력 압축을 적용하지 않는다
|
|
|
|
**사용자에게 결정/선택/판정을 요청하는 제시문**(질문, `AskUserQuestion` 옵션 포함)은 항상 풀어 쓴다:
|
|
|
|
1. **배경** — 왜 묻는지, 무엇에 걸린 결정인지
|
|
2. **선택지** — 각 옵션을 ID·약어가 아닌 문장으로
|
|
3. **권장** — 있으면 이유와 함께
|
|
|
|
약어·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 가 스코프를 막대 미터바로 좁혀 시각전략 확인 질문을 구성·구현·커밋까지 마쳤으나, 사용자가 "미터바도 좋은데 내가말한건 육각 그래프였어"로 정정. 최초 확인 질문에 "미터바/레이더 둘 다 대상인지, 어느 쪽인지"를 먼저 물었다면 방향 전환 비용(재구현+재검증 사이클)을 피할 수 있었다.
|