Agent Usability Loop

---
name: agent-usability-loop
description: 'Use to improve how coding agents use a CLI, MCP server, or harness ("에이전트 사용성 개선", "agent QA 돌려줘", "autoresearch"): measures model-facing output, runs host agents in sandboxes, keeps or reverts one change per run.'
---

# Agent Usability Loop

이 스킬은 **에이전트가 실제로 쓰는 도구를 측정하고, 한 번에 하나씩 고치고, 측정 결과로
유지 여부를 정하는 반복 루프**를 운영한다. 대상은 에이전트가 호출하는 CLI, MCP 서버,
하네스, 스킬이다. 사람이 쓰기 편한지가 아니라 에이전트가 적은 출력으로 실수 없이
끝까지 가는지를 본다.

- 저장소 전체를 자율적으로 개선하는 95점 게이트 루프는 [`self-augment`](../self-augment/SKILL.md)가 맡는다.
- 한 목표를 증거와 함께 끝내는 일은 [`verified-execution`](../verified-execution/SKILL.md)가 맡는다.
- 호스트별 실행 명령과 sandbox 구성은 [`references/host-qa-recipes.md`](references/host-qa-recipes.md)에 있다.
- 사용자 보고는 [`fluent-korean`](../fluent-korean/SKILL.md)의 `references/report-ste100.md`를 따른다.

## 1. 측정 기준 정하기

루프를 시작하기 전에 고정된 측정 스크립트 하나를 만든다. 스크립트는 한 번 실행에
한 사이클을 처음부터 끝까지 돌리고 `METRIC name=value` 줄을 출력한다.

| 지표 | 무엇을 재는가 | 방향 |
|---|---|---|
| 모델 대상 출력(KB) | 에이전트가 한 사이클에서 읽는 명령 출력, 도구 목록, 스킬 설명, hook 주입문의 합 | 낮을수록 좋다 |
| 사용성 결함 수 | 고정 probe가 찾은 결함 수 | 0이어야 한다 |
| 명령 지연(ms) | 자주 쓰는 명령의 중앙값. 첫 실행은 버린다 | 낮을수록 좋다 |

사용성 결함 probe의 예는 다음과 같다.

- `--json` 오류가 `2>&1`로 합쳐도 JSON 문서 하나인가.
- 알 수 없는 명령이 전체 usage를 쏟아내지 않는가.
- 하위 명령 `--help`가 stdout으로 나오는가.
- 판정이 "준비 안 됨"일 뿐인 조회 명령이 0이 아닌 종료 코드를 내지 않는가.
- 내부 telemetry가 stderr로 새지 않는가.

호스트가 실제로 모델에 넘기는 부분만 측정한다. 호스트가 버리는 필드를 줄여서 숫자를
낮추는 것은 지표 조작이다. 측정 스크립트를 바꾸면 기준선을 새로 잡는다.

## 2. 한 번의 실험

실험 하나에는 변경 하나만 넣는다. 아래 순서를 지키고 단계를 병렬로 실행하지 않는다.

1. 수정한다.
2. 포맷, 정적 분석, 전체 테스트, 변경한 패키지의 race 테스트를 통과시킨다.
3. 바이너리를 다시 빌드한다. 오래된 바이너리로 잰 숫자는 버린다.
4. 커밋한다. 메시지는 파일로 넘기고 따옴표 heredoc으로 작성한다.
5. 측정 스크립트를 실행한다.
6. 결과를 기록하고 유지하거나 되돌린다.

다음 상황에서는 측정하지 않는다. 숫자가 오염되거나 커밋과 경쟁한다.

- 백그라운드 테스트나 커밋이 실행 중이다.
- 다른 QA 에이전트가 같은 바이너리를 쓰고 있다.

유지 여부는 다음 기준으로 정한다.

- 주 지표가 좋아지면 유지한다.
- 주 지표가 같거나 나빠지면 되돌린다. 이미 커밋한 변경은 `git revert`로 되돌린다.
- 정확성 수정은 지표가 그대로여도 유지한다. 기록에 "CORRECTNESS"라고 적는다.
- 사용자가 요청한 기능이 지표를 올리면 유지하고, 요청 사실을 기록에 남긴다.

출력을 줄이는 변경은 숫자만으로 유지하지 않는다. 다른 모델 두 개가 줄인 출력을
보고 다음 행동을 정할 수 있는지 평가하게 한다. 평가가 나빠지면 되돌린다. 경로를
상대 경로로 바꿨다가 "읽을 파일" 출력이 덜 쓸모 있어진 사례가 있다.

## 3. 실제 에이전트 QA

숫자만으로는 에이전트가 막히는 지점을 찾을 수 없다. 실제 호스트 에이전트에게 사이클
하나를 맡기고 결과 보고서를 읽는다.

1. 격리된 sandbox를 만든다. 저장소, 로컬 bare origin, 상태 디렉터리, 원격 provider
   stand-in을 sandbox 안에 둔다. 실제 GitHub나 사용자 상태를 건드리지 않는다.
2. 시나리오 하나를 정한다. 예: 신규 기능, 버그 수정, 세션 인계, 리뷰 반영, CI 실패,
   기준 브랜치 변경, 하위 이슈 분할, 사용자 작업 중인 소스.
3. 프롬프트에 사용자 요청 한 문장, 모든 명령 앞에 붙일 환경 접두사, 보고서 경로를
   넣는다. 정답이나 우회 방법은 넣지 않는다.
4. 호스트를 바꿔 가며 실행한다. 같은 결함이 한 호스트에서만 나오면 호스트 차이부터 의심한다.
5. 보고서와 전사를 읽고 실패한 명령마다 원인을 하나로 분류한다.

| 분류 | 판단 기준 | 조치 |
|---|---|---|
| 도구 결함 | 도구가 틀린 값, 모호한 거부, 막다른 안내를 냈다 | 고친다 |
| 설계상 동작 | 기록된 결정대로 동작했다 | 고치지 않는다. 반복되면 문서를 보강한다 |
| 에이전트 실수 | 안내가 맞았는데 에이전트가 잘못 입력했다 | 같은 실수가 두 번 나오면 안내 문구를 바꾼다 |
| stand-in 한계 | 가짜 provider가 실제와 다르게 동작했다 | stand-in을 고친다. 도구는 그대로 둔다 |

실패한 명령이 0개인 전체 사이클을 호스트마다 한 번 이상 확인한다.

## 4. 장애 주입

외부 쓰기가 있는 도구는 응답이 사라지거나 호출한 프로세스가 죽어도 중복 없이 복구해야 한다.
stand-in에 한 번만 동작하는 장애 플래그를 둔다.

- 쓰기는 반영하고 응답만 잃는다. 이슈 생성, PR 생성, 병합, 브랜치 삭제에 각각 둔다.
- 쓰기 도중 호출한 부모 프로세스를 종료한다.
- 첫 head에서만 CI를 실패시킨다.

각 장애마다 에이전트 QA를 한 번 돌린다. 복구가 끝났을 때 중복 산출물이 0개인지 stand-in 상태 파일로 확인한다.

## 5. 입력 검증 probe

도구가 받는 이름, 제목, 본문, 경로를 경계값으로 찔러 본다. 판정 기준은 추측하지 않고
권위 있는 쪽과 대조한다. 예: 브랜치 이름은 `git check-ref-format --branch`, 제목·본문
길이는 provider 한도와 대조한다. 외부 provider가 거부할 입력은 되돌릴 수 없는 기록을
남기기 전에 로컬에서 거부한다. 거부 메시지에는 어긴 규칙과 고칠 방법을 넣는다.

## 6. 안전 규칙

- 정책이나 안전 검사를 완화하는 변경은 보안 리뷰를 받은 뒤에만 유지한다.
- sandbox 명령은 하위 셸 `( … )` 안에서 실행하고 그 안에서 `hash -r`을 실행한다.
  stand-in `PATH`와 가짜 provider 환경 변수를 작업 셸에 export하지 않는다.
- 모든 probe에 sandbox 상태 디렉터리를 지정한다. 지정하지 않으면 실제 사용자 상태에 기록이 남는다.
- 실제 저장소에 파일을 쓰는 명령(문서 bootstrap, 설치)을 sweep에 넣지 않는다.
- 스킬 설명을 바꾸면 라우팅 평가를 모델 세 개 이상으로 다시 돌린다. 기존 정답률보다 낮으면 되돌린다.

## 7. 기록과 보고

실험마다 설명, 지표, 확인한 근거, 다음 후보를 남긴다. 같은 함정을 두 번 밟으면 교훈을
기록에 추가한다. 주기적으로 전체 자기 검증과 호스트 적합성 검사를 다시 돌린다.

사용자에게는 STE100 형식으로 보고한다. 순서는 결과, 변경한 것, 확인한 것, 경고·주의,
사용자가 할 일이다. 기준선 대비 지표 변화를 표 하나로 보여 준다.