docs/ko/agent-integration.md

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

[한국어 문서 홈](README.md) | [English agent guide](../agent-skill.md)

Codex, ChatGPT 또는 다른 코딩 에이전트에서 사용해도 QAMap은 같은 로컬
CLI를 실행합니다. 특정 에이전트에서만 동작하는 별도 분석 엔진을 두지
않으며, 결과는 버전이 지정된 `qamap.qa` 형식으로 전달합니다.

0.5.1부터 패키지의 검수 지침은 [검수 브리프](agent-brief.md)를 사용합니다. 사용자의
동의 후 `qamap qa brief`를 한 번 실행하고, 줄 번호가 붙은 diff와 사용처, 이력,
미확인 항목으로 검수합니다. 소스는 특정 미확인 항목을 확인할 때만 읽습니다.
[Claude Code 실측](../release-validation.md)에 토큰과 품질 결과를 기록했지만,
모든 저장소에서 같은 절감을 보장하지는 않습니다. 0.5.0의 JSON
[한 번의 호출로 요약과 코드 근거를 받는 방식](agent-handoff.md)도 계속 사용할 수 있습니다.

## 프로젝트의 검수 방식 저장하기

**QAMap 0.5.0 이상에서 지원합니다. 0.4.17에서는 사용할 수 없습니다.**
매번 동의를 묻지 않고 QAMap 보고서로 먼저 검수하려면 사용자가 직접 다음
명령으로 해당 프로젝트의 기본 방식을 선택할 수 있습니다.

```sh
qamap init --agent . --review-mode report
```

`AGENTS.md`의 QAMap 전용 구간만 갱신하고, 사용자가 작성한 나머지 내용은
유지합니다. 이후 일반 설정 명령을 다시 실행해도 선택한 방식은 보존됩니다.
매번 선택하도록 되돌리려면 `--review-mode ask`를 사용하세요.

0.5.1부터는 설정만 바꾸는 `qamap consent` 명령도 제공합니다.

```sh
qamap consent grant            # 이 프로젝트: AGENTS.md의 QAMap 구간만 수정
qamap consent grant --global   # 모든 저장소: Claude Code와 Codex 사용자 지침
qamap consent revoke [--global]
qamap consent status
```

`--global`은 `~/.claude/CLAUDE.md`와 `~/.codex/AGENTS.md`(또는
`CLAUDE_CONFIG_DIR`, `CODEX_HOME`)에 표시된 구간을 추가합니다. 설정 디렉터리가
있는 호스트에만 쓰고, 저장소는 건드리지 않습니다. `revoke --global`은 그
구간만 지우고 나머지 내용은 그대로 둡니다. 프로젝트에서 `revoke`하면 "매번
묻기"가 기록되어, 그 프로젝트에서는 사용자 전역 동의보다 우선합니다.
에이전트는 사용자가 대화에서 QAMap을 직접 요청하지 않은 한
`qamap qa brief --require-consent`를 실행하며, 동의가 없으면 분석 없이 먼저
물어보라는 안내만 받습니다.

설치만으로 이 설정이 켜지지는 않습니다. 독립적인 코드 검수를 명시적으로
요청하면 그 요청을 우선하며, 테스트 실행이나 코드 수정 권한이 추가되는
것도 아닙니다. 호스트가 스킬 읽기를 요구하면 해당 과정의 토큰은 여전히
발생합니다. 설정 이후의 사용량과 처음 발견하고 동의를 받는 과정의 사용량은
구분해서 비교해야 합니다.

## OpenAI 플러그인으로 설치하기

ChatGPT 또는 Codex의 **Plugins**에서 **QAMap**을 검색하고 **+**를 누른 뒤
새 작업을 시작합니다.

- [QAMap 플러그인 페이지](https://chatgpt.com/plugins/plugins_6a752ca134a481919b90c45c09ab1629)
- [OpenAI 공식 설치 안내](https://learn.chatgpt.com/docs/plugins#install-and-use-a-plugin)

플러그인을 실행하는 앱이 현재 저장소와 로컬 터미널을 읽을 수 있어야
합니다. 일반 웹 채팅처럼 로컬 파일에 접근할 수 없는 환경에서는 분석할
코드를 읽을 수 없습니다.

## 에이전트용 JSON 출력

다른 에이전트는 다음 명령으로 간결한 JSON 결과를 받을 수 있습니다.

```sh
npx --yes @ivorycanvas/qamap@latest qa --format agent
```

결과는 다음 순서로 읽으면 됩니다.

1. `execution`: 테스트 명령을 실제로 실행했는지와 그 결과
2. `route`: 현재 권하는 다음 단계 하나
3. `action`: 명령 실행, 파일 변경, 네트워크 사용, 승인에 관한 조건
4. `intents`와 `flows`: 변경 의도, 확인할 시나리오, 영향받는 흐름
5. `requiredEvidence`: 판단을 신뢰하기 전에 더 필요한 근거

`route.command`는 `qamap qa run`이 실행할 명령 하나입니다. 이번 변경에서
다른 테스트나 벤치마크 명령도 꼭 확인해야 한다면
`route.additionalCommands`에 따로 들어갑니다. 이 명령들은 자동으로
실행되지 않으며 각각 별도의 승인과 실행 결과가 필요합니다.

`testContracts`는 지정한 PR 비교 범위에서 추가되거나 바뀐 테스트 선언입니다.
기준 브랜치를 병합하면서 들어온 테스트나 원래 내용으로 되돌린 선언은
이번 PR의 새 계약으로 세지 않습니다. 최신 커밋은 범위 안의 테스트를 먼저
보여주는 데만 사용하고, 위치는 현재 head를 기준으로 표시합니다.
`--include-working-tree`로 요청한 미커밋 변경은 `currentDelta`에서 구분합니다.

## 결과를 읽지 않고 파일로만 저장하기

**QAMap 0.5.0 이상에서 지원합니다. 0.4.17에는 없습니다.**

```sh
qamap qa report . --base origin/main --head HEAD --format agent
```

전체 보고서와 요약은 `~/QAMap-reports/qa-*`에 저장합니다. 에이전트에는
분석 완료 여부와 경로만 반환합니다. 사람용 터미널에서는 `--format agent`를
빼면 완료 안내와 보고서 링크가 표시됩니다. 파일은 매번 새 폴더에 저장하며,
`--output <디렉터리>`로 저장 위치를 정할 수 있습니다.

- `report.md`: 사람이 읽을 보고서
- `summary.json`: 나중에 해석을 요청할 때 먼저 전달할 짧은 요약
- `report.json`: 분석 범위 안에서 수집한 전체 근거

에이전트에는 **“보고서만 저장하고, 내용을 읽지 말고 경로만 알려줘”**라고
요청하세요. 해석이 필요해지면 요약 파일 경로를 전달하면 됩니다. 명령 호출과
완료 안내에도 에이전트 토큰은 들지만, 보고서 전체를 자동으로 읽는 과정은
생략할 수 있습니다. 별도의 터미널 앱을 열거나 실행 스크립트를 만들 필요는
없습니다.

이 모드는 테스트를 실행하지 않으므로 분석이 끝나도 테스트는 `not-run`입니다.
일반 웹 채팅에서는 로컬 경로만으로 파일을 읽을 수 없을 수 있습니다. 보고서에
비공개 코드가 포함될 수 있으니 공유 전에 확인하고, 불필요한 보고서는 직접
삭제하세요. 자세한 출력 형식은 [명령어 안내](../commands.md#save-a-report-without-reading-it)를
참고하세요.

## 모노레포에서 명령을 실행할 위치

먼저 `analysisScope.commandCwd`를 확인합니다.

- `workspace-root`: 저장소 최상위 디렉터리에서 실행합니다. QAMap이 고른
  패키지 명령에는 `--dir`, `--cwd`, `--prefix` 또는 `cd`와 함께 필요한
  하위 경로가 이미 들어 있습니다.
- `selected-package`: `analysisScope.selectedPath`에서 실행합니다. 사용자가
  `--workspace-root`와 함께 패키지를 직접 지정한 경우에 사용됩니다.

이 필드가 없는 이전 v1 출력은 저장소 최상위 디렉터리를 기본값으로
사용합니다. 경로를 추측해서 `selectedPath`를 한 번 더 붙이지 마세요.

## 토큰과 데이터 사용 범위

- QAMap의 정적 분석은 별도의 LLM을 호출하지 않습니다.
- 분석을 위해 소스 코드를 외부로 업로드하지 않습니다.
- QAMap을 호출하고 결과를 해석하는 에이전트는 자체 모델 토큰을 사용합니다.
- `npx`로 처음 실행할 때는 npm에서 패키지를 내려받기 위해 네트워크를
  사용할 수 있습니다.

따라서 “추가 LLM 호출 없음”은 전체 에이전트 작업에서 토큰을 전혀 쓰지
않는다는 뜻이 아닙니다. 저장소를 반복해서 읽고 변경 근거를 정리하는
단계를 QAMap이 로컬에서 맡는다는 뜻입니다.

## 안전하게 사용하는 순서

결과 전용 검수에서는 반환된 근거만 해석하고, 나머지는 확인하지 못한 범위로
남깁니다. 아래 단계는 사용자가 추가 검수나 실행을 요청한 경우에 적용합니다.

1. 먼저 `qa --format agent`로 변경 없이 분석 결과만 받아봅니다.
2. 가장 중요한 판단이 실제 변경 코드와 연결되는지 확인합니다.
3. `route.nextAction`에 적힌 다음 단계 하나를 검토합니다.
4. 저장소 명령을 실행하거나 파일을 만들기 전에는 `action`의 허용 범위와
   사용자 승인을 확인합니다.
5. 만들어진 초안과 실제로 실행한 결과를 구분해서 보고합니다.

문서, 패키지 문서 목록, 이슈 양식, PR 템플릿만 바뀌었다면 QAMap은 이를
제품 기능 변경으로 보지 않습니다. 링크, 명령, YAML 필드, 라벨, 할당자,
필수 PR 항목을 확인하는 저장소 검증으로 분류하고, 실행할 기존 명령을
찾았을 때만 준비 상태를 `ready`로 표시합니다.

QAMap 결과가 일반 코드 검토와 다르면 실제 코드와 실행 결과를 우선하세요.
의미 있는 차이는 잘못 짚은 항목, 놓친 항목, 근거 부족, 실행 안내 부족으로
분류해 다음 회귀 테스트를 만드는 데 사용할 수 있습니다.