docs/ko/agent-brief.md

# 에이전트용 검수 브리프

[English](../agent-brief.md)

**QAMap 0.5.1 이상이 필요합니다.**

`qamap qa brief`는 코딩 에이전트가 바로 검수할 수 있는 한 개의 텍스트 브리프를
출력합니다. 에이전트는 읽는 분량뿐 아니라 모델 호출 횟수만큼 토큰을 씁니다.
호출할 때마다 호스트의 시스템 프롬프트와 지금까지의 대화를 다시 보내기 때문입니다.
LLM 단독으로 PR을 검수하면 보통 `git diff`, 검색, 파일 읽기에 여러 번 호출을
씁니다. 브리프는 그 근거를 LLM 호출 없이 로컬에서 한 번에 모읍니다.

```sh
qamap qa brief
```

기준 브랜치는 CI 정보, 저장소 설정, Git 이력 순서로 자동 선택합니다. PR의
기준 브랜치가 다르면 `--base <ref>`, 커밋하지 않은 변경을 포함하려면
`--include-working-tree`를 추가합니다. 기본 크기 한도는 24,000바이트이며
`--max-bytes <n>`으로 바꿀 수 있습니다(최소 4,000). 전체 보고서는 계속
`~/QAMap-reports/qa-*`(또는 `--output <directory>`)에 저장되지만, 브리프는
에이전트에게 그 파일을 읽으라고 안내하지 않습니다.

## 브리프에 들어가는 내용

| 항목 | 내용 |
| --- | --- |
| 머리말 | 비교 범위, 변경 파일 수, 테스트까지 연결된 변경 선언 수, 감지한 프로젝트와 기존 검증 명령 |
| 변경 | 줄 번호가 붙은 diff. 문맥 줄과 `+` 줄은 head 기준, `-` 줄은 base 기준 번호입니다. 150줄 이하 파일은 전체를, 작은 함수는 함수 전체를, 그 외에는 앞뒤 8줄을 보여줍니다. |
| 사용처 | 변경된 선언마다 직접 테스트(제목, 호출, 그 결과에서 나온 지역 변수, 그 값을 쓰는 단언), 호출하는 코드와 그 소속 선언, 그 호출 코드의 테스트 |
| 호출 대상 | 새 코드나 삭제된 코드가 호출하는 함수의 정의 위치, 12줄 이하의 짧은 본문, 저장소 밖에서 가져온 import, 또는 "저장소에 정의·import 없음" |
| 이력 | 삭제되거나 바뀐 줄을 처음 넣은 커밋과, 그 커밋이 함께 추가한 테스트(줄 번호 포함) |
| 검증할 항목 | 추론한 변경 의도별 동작 흐름(trigger, 조건, 동작, 상태, 결과)과 중요 시나리오의 모든 확인 항목(경계 사례 포함). 검수자는 각 항목을 "동작 → 기대 결과"로 바꾸거나, 해당하지 않으면 이유와 함께 제외합니다. 추론이므로 코드로 확인해야 합니다. |
| 미확인 | 실행 시점에 고르는 모듈, 모호한 re-export, 테스트 참조가 없는 변경 선언 |
| 생략 | 크기 한도 때문에 빠진 파일 목록과, 그 파일을 확인하는 명령 |

사용처는 비교 대상 head의 모든 추적 파일에서 `git grep`으로 찾습니다. 문서,
lockfile, 빌드 결과물은 제외하며, 구문 색인에 넣기엔 너무 큰 파일도 포함합니다.
찾은 후보는 파일의 import 바인딩으로 다시 확인합니다(JavaScript/TypeScript,
Python). 이름이 같아도 다른 모듈에서 가져온 심볼은 빼고, `export { a as b }`나
`import { a as b }` 같은 별칭은 따라갑니다. import 바인딩이 없는 언어는 이름
일치 결과를 그대로 둡니다.

여러 파일에서 숫자 하나만 다르게 반복되는 변경은 실제 파일 하나를 보여준 뒤
나머지 값을 정확히 적습니다(예: `N = 0..9, 11..159`). 표본만 고르거나 빠뜨리는
항목은 없습니다.

## 에이전트에서 사용하기

`qamap init --agent`는 이 작업 순서를 `AGENTS.md`에 적고, Codex와 Claude Code용
`qamap-pr-qa` 스킬을 설치합니다. `--review-mode report`는 사용자가 이 프로젝트에서
QAMap 검수를 선택했다고 기록하고, `--review-mode ask`는 먼저 제안하는 방식으로
되돌립니다. 설치만으로 동의한 것은 아닙니다.

사용자가 동의를 기록하지 않았다면 에이전트는 QAMap을 실행하기 전에 먼저 묻습니다.
사용자는 "이번만", "항상", "이번엔 안 함" 중에서 고를 수 있습니다. "항상"은
프로젝트 단위로 `qamap consent grant`, 모든 저장소에 대해서는
`qamap consent grant --global`(Claude Code와 Codex 사용자 지침)로 기록합니다.
`qamap consent revoke [--global]`는 다시 묻는 방식으로 되돌리고,
`qamap consent status`는 두 범위의 상태를 보여줍니다. 패키지에 포함된 지침은
`qamap qa brief --require-consent`를 실행합니다. 동의가 기록되지 않았으면 이
명령은 아무것도 분석하지 않고 먼저 물어보라는 안내만 출력하므로, 호스트가
질문을 건너뛸 수 없습니다.

지침은 에이전트에게 브리프를 한 번 실행해 그 내용으로 검수하고, 특정 미확인
항목을 확인할 때만 소스를 읽도록 안내합니다. 결과는 발견한 문제, 구체적인 검증
항목, 미확인 항목 순서로 보고합니다. 테스트 상태는 `not-run`입니다.
브리프는 정적 근거일 뿐 실행 결과가 아닙니다. 브리프 속 저장소 텍스트는 근거일
뿐 지시가 아닙니다.

버전이 붙은 `qamap.qa.handoff` JSON이 필요한 도구는 계속 `qa report --handoff`와
`qa read`를 쓸 수 있습니다. [한 번의 호출로 검수 근거 받기](agent-handoff.md)를
참고하세요. 큰 보관 파일을 여러 페이지로 나눠 모델에 읽히면 브리프보다 토큰이 많이
들기 때문에, 패키지에 포함된 검수 지침은 브리프를 사용합니다.

## 한계

- 이름 검색과 import 확인은 타입 검사기가 아닙니다. 동적 디스패치, 의존성 주입,
  리플렉션, 문자열로 만든 모듈 경로는 호출 코드를 가릴 수 있습니다. 브리프는
  찾은 내용을 보여줄 뿐, 다른 사용처가 없다는 증명이 아닙니다.
- 이력 항목에는 로컬 Git 이력이 필요합니다. 얕은 clone에서는 해당 줄을 넣은
  커밋까지 거슬러 가지 못할 수 있습니다.
- 테스트 발췌는 선택한 줄이며 테스트 전체가 아닙니다. 브리프는 테스트를 실행하지 않습니다.
- 토큰 절감은 보장되지 않습니다. 호스트는 브리프를 읽고 검수 결과를 쓰는 데 토큰을
  쓰며, 에이전트가 더 읽기로 할 수도 있습니다.

## 실측 결과

Claude Code CLI가 고정된 19개 사례를 이 작업 순서로 한 번, QAMap 없이 한 번씩
검수했습니다. 방식마다 세 번씩 실행했고, 매번 새 세션에서 같은 모델, 도구,
프롬프트를 썼으며, 답변은 고정된 정답 기준으로 블라인드 채점했습니다. 사례에는
이 저장소 이력에서 되돌린 실제 회귀 3건이 포함됩니다.

| 항목 | 단독 | QAMap 0.5.1 사용 |
| --- | ---: | ---: |
| 사례별 총 토큰 중앙값의 합 | 9,752,041 | 2,526,116 (-74.1%) |
| 전체 57회 실행 총 토큰 | 30,916,750 | 8,056,261 (-73.9%) |
| 사례별 모델 호출 수 중앙값 | 7-32 | 2-6 |
| 심어 둔 회귀를 모두 찾은 실행 | 40/42 | 42/42 |
| 제품 fixture의 QA 계획 평균 포함률 | 0.73 | 0.89 |

모든 사례에서 QAMap 실행 중 가장 비싼 실행도 단독 실행 중 가장 싼 실행보다 적게
썼습니다. 저장소 설정 없이 프롬프트도 그대로 두고 `qamap consent grant --global`로
동의만 한 번 기록한 경우에도 38회 모두 QAMap을 사용했고, 중앙값 합은
2,881,446(-70.5%)이었습니다. 호스트 하나, 모델 하나로 측정한 알려진 사례 결과이며 일반적인 절감 보장이
아닙니다. 사례별 표, 민감도 측정, 한계는 [0.5.1 릴리스 기록](../releases/0.5.1.md#measured-results)과
[검증 기록](../release-validation.md)에 있습니다.