Agent UI
AI 에이전트가 실제로 읽거나, 제안하거나, 변경하는 화면의 임무는 단 하나입니다: 사람이 에이전트가 한 일을 확인하고, 다음에 무엇을 할지 결정하며, 둘 다 신뢰할 수 있게 하는 것입니다. 다음은 모든 프레임워크와 디자인 시스템에서 적용되는 규칙과 검사 항목입니다. 프로젝트가 Candor UI를 사용한다면 candor-ui 스킬이 각 작업에 해당하는 컴포넌트를 명명하고, 이 스킬은 화면이 무엇을 그리든 반드시 해야 할 일을 설명합니다.
작업 방법
화면을 만들기 전에 세 가지 질문에 답하고, 그 답변을 개발 중에도 계속 염두에 두세요:
- 여기서 에이전트가 무엇을 할 수 있나요: 읽기만, 사람이 적용할 수 있도록 제안만, 아니면 스스로 실행? 모든 컨트롤은 이에 따라 결정됩니다.
- 사람은 무엇을 결정하고, 어떤 증거를 바탕으로 결정하나요? 결정에는 설명이 아닌 실제 데이터(diff, 대상, 금액)가 필요합니다. 여기서 승인되는 것이 있다면
references/approvals.md를 읽으세요. - 무엇이 되돌릴 수 없나요? 그런 작업은 명시적으로 표시하고, 더 강력하게 확인하며, 기본값이나 단일 키 아래에 두지 마세요.
개발하는 동안 아래 9가지 규칙을 지키고, references/status-and-states.md의 상태 단어를 사용하며, references/progress.md에서 설명하는 방식으로 진행을 표시하세요. 모델 텍스트는 데이터입니다: 표시만 하고, 실행하거나 렌더링하지 마세요.
각 화면 이후 references/review-checklist.md를 실행 중인 화면에 대해 한 줄씩 검사하고, 통과하지 못한 항목을 다음으로 넘어가기 전에 수정하세요. 의도한 것만 체크하지 말고, 실제로 확인한 것만 체크 표시하세요.
9가지 규칙
각 규칙은 references/honesty-rules.md에 예제와 함께 확장되어 있습니다.
- 모델 출력은 텍스트이지, 마크업이 아닙니다. 모델이 작성한 내용을 텍스트(최대한 안전한 마크다운 하위 집합)로 표시하세요. 모델이 작성한 URL은 링크가 아닌 텍스트입니다. 모델이 작성한 어떤 것도
innerHTML에 도달하지 않습니다. - 알 수 없는 것은 알 수 없음으로 남깁니다. 측정되지 않은 기간, 비용, 수는 비워두거나 "측정되지 않음"이라고 표시합니다. 추정치는 "추정치"와 그 근거를 함께 표시합니다. 실행에서 침묵은 "실행 중"이 아닙니다.
- 사용할 수 없는 컨트롤은 이유를 표시합니다. 키보드와 스크린 리더 사용자가 접근할 수 있는 이유와 함께 잠그고,
disable만 하고 사람들이 추측하게 두지 마세요. - 결정에서 아무것도 미리 선택하지 않습니다. 승인과 거부, 유지와 폐기는 둘 다 선택되지 않은 상태로 시작합니다. Enter 키는 승인하지 않습니다. 에이전트의 추천은 표시되지만 선택되지는 않습니다.
- 정확한 변경 사항을 승인합니다. 결정은 사람이 본 변경 사항(해시 또는 버전)에 묶여 있습니다. 변경 사항이 이동하면 다시 물어보세요. 정책에 따라 자기 승인은 거부되며, 프로덕션에서는 두 번째 사람이 필요할 수 있습니다.
- 추론은 믿어지지 않고, 검증되지 않습니다. 모델의 이유 설명은 주장입니다. 그렇게 표시하고 증거(소스, 테스트 결과, diff)와 분리하여 유지하세요.
- 앱이 에이전트의 이름을 지정합니다. 모든 에이전트 메시지는 앱 자체 데이터에서 가져온 이름을 전달합니다. 시스템 메시지는 앱의 문자열입니다. 모델이 작성한 어떤 것도 이름이나 시스템 메시지가 되지 않습니다.
- 무엇을 되돌릴 수 있고, 무엇을 되돌릴 수 없는지 말합니다. 파괴적인 작업 전에: 무엇을 제거하는지, 되돌릴 수 있는지, 어떻게, 얼마나 오래 동안인지. 취소 또는 복원 후: 무엇을 되돌리지 못했는지.
- 움직임은 결과를 따릅니다. 애니메이션은 발생한 변경 사항을 보고합니다. 예측하거나 장식하지 않습니다. 성공 표시는 결과가 확정된 후에 그려지고, 진행률은 측정된 만큼만 채워지며, 화면이 그려질 때 이미 최종 상태였던 것은 애니메이션되지 않으며, OS의 동작 줄이기 설정이 우선합니다. 각 애니메이션에 변경 유형을 지정하고(Candor는 14개의 모션 패밀리를 명명하며,
references/honesty-rules.md에 나열됨), 테마가 애니메이션의 모양은 변경할 수 있지만, 실행 시점은 변경할 수 없습니다.
무엇을 읽을지
| 화면에 다음이 있을 때… | 읽을 문서 |
|---|---|
| 사람이 승인, 허용, 거부하는 모든 것 | references/approvals.md |
| 실행, 도구 호출, 단계, 상태, 점 | references/status-and-states.md |
| 잠시 이상 작업하는 에이전트, 또는 사람이 없는 동안 완료되는 경우 | references/progress.md |
| 사람과 대화하는 AI, 또는 AI가 만든 콘텐츠 | references/disclosure-and-accessibility.md |
| 무엇이든, 넘어가기 전에 | references/review-checklist.md |
단어 사용
평범하고 측정된 언어. 무슨 일이 발생했는지, 누구에게, 다음에 무엇을 해야 하는지 말합니다. 문장형 케이스, 느낌표는 사용하지 않음, 최상급 표현 사용 금지, 데이터가 담고 있지 않은 주장 금지. 상태는 그 옆에 색상이 있는 단어로만 표시하며, 색상만으로 표시하지 않습니다. 숫자는 측정된 경우에만 사용하고, 그 외에는 "추정치" 또는 "측정되지 않음"이라는 단어를 사용합니다.