diff --git a/.atp/work-session/20260617-174635/report.md b/.atp/work-session/20260617-174635/report.md index 5a22a09..0666937 100644 --- a/.atp/work-session/20260617-174635/report.md +++ b/.atp/work-session/20260617-174635/report.md @@ -130,7 +130,10 @@ Retrospective: docs_sync_target: null # 내부 작업 흐름(에이전트 출력 스타일) 교훈 → MEMORY 단독. 단 protocol_feedback 로 ATP 출력 규약 반영 제안 별도. protocol_feedback: - agent-team-protocol 의 출력 스타일/압축 규약에 "사용자 대면 의사결정 제시문은 압축 비적용(배경+선택지+권장 풀어쓰기)" 예외 규칙을 명문화 제안. caveman/토큰 다이어트 지침이 있다면 그 적용 범위를 "에이전트 간 내부 산출물·로그·요약"으로 한정하고, 사용자 질문/AskUserQuestion 옵션 라벨은 자기완결 서술을 요구하도록 가드 추가. (structural negative 신호에서 도출) - applied_changes: [] + applied_changes: + - orchestrator 결정(사용자 지시): memory_candidate `decision-prompt-no-compression-spell-out` 를 MEMORY 대신 docs 에 반영. + → docs/development/agent-output-conventions.md 신설 + development/index.md 링크. (사용자 "메모리에 말고 docs에 남기자") + - W3 골자 doc + index 동기화 + 세션 산출 커밋: 15b8bc3 (feat/v2). # ended_at 2026-06-18 diff --git a/docs/development/agent-output-conventions.md b/docs/development/agent-output-conventions.md new file mode 100644 index 0000000..7d6c801 --- /dev/null +++ b/docs/development/agent-output-conventions.md @@ -0,0 +1,38 @@ +--- +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 천장)과 같은 계열. diff --git a/docs/development/index.md b/docs/development/index.md index 91620b3..3c799bd 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -6,5 +6,6 @@ - [verification-strategies.md](./verification-strategies.md) — `verification-advisor` 가 읽는 검증 전략 레지스트리 (프로젝트별 `cmd` 를 채워 사용) - [document-category-classification.md](./document-category-classification.md) — 카테고리 분류 기준 (불필요한 카테고리는 프로젝트에 맞게 정리) +- [agent-output-conventions.md](./agent-output-conventions.md) — 에이전트 출력 규약. 사용자 대면 의사결정 제시문엔 압축 비적용(배경+선택지+권장 풀어쓰기), 압축은 내부 산출물 한정 > atp 플러그인 번들 레퍼런스(`agent-team-protocol.md`, `agent-catalog.md`, `documentation-guidelines.md`, `search-tool-matrix.md`)는 플러그인 캐시에 있으며 이 프로젝트로 복사되지 않는다. 에이전트가 `${CLAUDE_PLUGIN_ROOT}/docs/...` 로 직접 참조한다.