# QC 검증 체크리스트 표준

> 작성일: 2026-03-03
> 작성자: 아테나 (개발1팀 UX/UI 설계자)
> 관련 문서: qc-runtime-verification.md, qc-report-template.md

---

## 1. 개요

### 이 표준의 목적

팀의 QC 체계는 두 가지 계층으로 운영된다.

- **자동화 계층**: `qc_verify.py`가 반복적이고 정량적인 검증을 자동 수행
- **수동 판정 계층**: 마아트가 자동화 결과를 바탕으로 최종 판단

이 문서는 두 계층이 어떻게 조합되는지, 작업 유형과 QC 레벨에 따라 어떤 항목을 수행해야 하는지를 정의한다.

### 기존 문서와의 관계

- `qc-runtime-verification.md`: 마아트가 수동으로 실행하는 4항목 검증의 방법론과 명령어를 정의
- `qc_verify.py`: `qc-runtime-verification.md`의 4항목을 자동화한 Python 스크립트
- **이 문서**: 두 문서/도구를 통합하여 언제, 무엇을, 어떤 순서로 수행할지 정의하는 운영 표준

### 적용 대상

모든 작업에 적용하되, QC 레벨(normal / critical / security)에 따라 수행 범위가 달라진다.

---

## 2. QC 3단 방어선 아키텍처

QC는 세 개의 독립적인 방어선으로 구성된다. 각 레이어는 다음 레이어를 보완하며, 어느 하나가 FAIL이면 다음 레이어로 넘어가지 않는다.

```
[Layer 1] 셀프 QC (팀장 직접)
    ↓ PASS 시
[Layer 2] 자동 검증 (qc_verify.py)
    ↓ PASS 시 (critical/security 레벨에서)
[Layer 3] 독립 검증 (마아트 / 로키)
```

---

### 2.1 Layer 1: 셀프 QC (팀장 직접)

작업 완료 직후 팀장이 즉시 수행하는 자기 검증이다.

**수행 시점**: 작업 완료 선언 전, 즉시

**System 2 Forcing 5항목**

- 작업이 요청 명세와 100% 일치하는가
- 파일 경로와 위치가 정확한가
- 의도치 않은 사이드이펙트가 없는가
- 이전 작업과의 일관성이 유지되는가
- 보고서에 작성한 내용이 실제 결과물과 일치하는가

**판정**: 5항목 모두 자체 확인 후 Layer 2로 진행

---

### 2.2 Layer 2: 자동 검증 (qc_verify.py)

반복적이고 정량적인 검증을 자동으로 수행하는 Python 스크립트.

**스크립트 경로**
- `/home/jay/workspace/teams/dev1/qc/qc_verify.py`

**4개 검증 모듈**

- `api_health`: 서버 엔드포인트 HTTP 응답 검증
- `file_check`: 파일 존재, 크기, 위치, 권한 검증
- `data_integrity`: JSON 파일 정합성 및 데이터 교차 검증
- `test_runner`: 지정 테스트 디렉토리 자동 실행

**특성**
- LLM 호출 없음 (순수 Python, 비용 0)
- JSON 형식 결과 출력 (마아트 검토 입력으로 사용)
- SKIP 가능 모듈 지정 지원

**기본 실행 명령**
```
python3 qc_verify.py --task-id {task_id}
```

**모듈 스킵 예시 (스크립트/유틸리티 작업)**
```
python3 qc_verify.py --task-id {task_id} --skip api_health
```

**출력 예시 구조**
```
{
  "task_id": "task-001",
  "overall": "PASS",
  "modules": {
    "api_health": "PASS",
    "file_check": "PASS",
    "data_integrity": "PASS",
    "test_runner": "PASS"
  },
  "timestamp": "2026-03-03T10:00:00Z"
}
```

---

### 2.3 Layer 3: 독립 검증 (마아트 / 로키)

개발팀과 완전히 격리된 시각으로 결과물을 검증하는 단계.

**활성화 조건**
- `critical` 레벨: 마아트 독립 검증 필수
- `security` 레벨: 마아트 독립 검증 + 로키 보안 감사 필수
- `normal` 레벨: 생략

**마아트의 독립 검증 원칙** (상세 내용은 섹션 5 참조)
- `qc_verify.py` JSON 결과를 주요 입력으로 사용
- 개발팀 보고서는 참고 자료이지 판단 근거가 아님
- 작업 명세(task file)와 결과물을 직접 대조

**로키의 보안 감사 원칙** (security 레벨 전용)
- 인증 / 권한 / 입력 검증 취약점 집중 검토
- 민감 정보 노출 여부 확인
- 감사 결과는 별도 보안 리포트로 제출

---

## 3. 작업 유형별 검증 항목 매트릭스

작업 유형에 따라 각 검증 모듈의 필수 여부가 다르다. 이 매트릭스를 기준으로 `qc_verify.py` 실행 옵션을 결정한다.

---

**유형 A: 서버 / API 작업**

- `api_health`: 필수
- `file_check`: 필수
- `data_integrity`: 필수
- `test_runner`: 필수
- 마아트 curl 직접 검증: critical 레벨 이상에서 추가 수행

해당 작업 예시: 대시보드 서버 기동, API 엔드포인트 추가, 서버 설정 변경

---

**유형 B: 스크립트 / 유틸리티 작업**

- `api_health`: SKIP (서버 없음)
- `file_check`: 필수
- `data_integrity`: 필수
- `test_runner`: 필수
- 마아트 curl 직접 검증: 해당 없음

해당 작업 예시: qc_verify.py 작성, 데이터 변환 스크립트, 자동화 도구

---

**유형 C: 문서 / 설정 작업**

- `api_health`: SKIP
- `file_check`: 필수
- `data_integrity`: 선택 (JSON 설정 파일 포함 시 필수)
- `test_runner`: SKIP
- 마아트 curl 직접 검증: 해당 없음

해당 작업 예시: 명세 문서 작성, .env 설정, 마크다운 가이드 작성

---

**유형 D: 시스템 코드 작업 (dispatch, prompts 등)**

- `api_health`: SKIP
- `file_check`: 필수
- `data_integrity`: 필수
- `test_runner`: 필수 (회귀 테스트 특히 중요)
- 마아트 curl 직접 검증: 해당 없음

해당 작업 예시: 팀 에이전트 프롬프트 수정, dispatch 로직 변경, 파이프라인 hooks 수정

특이사항: 시스템 코드는 다른 기능에 파급 영향을 미치므로, `test_runner`는 해당 모듈 단위 테스트뿐 아니라 전체 회귀 테스트 스위트를 포함해야 한다.

---

## 4. QC 레벨별 프로세스

### normal 레벨

```
1단계: Layer 1 셀프 QC (5항목) → 확인 완료
2단계: Layer 2 qc_verify.py 실행 → overall PASS 확인
3단계: QC 보고서 작성 및 제출
```

- 마아트 독립 검증: 생략
- 보고서 양식: qc-report-template.md 기준

---

### critical 레벨

```
1단계: Layer 1 셀프 QC (5항목) → 확인 완료
2단계: Layer 2 qc_verify.py 실행 → overall PASS 확인
3단계: Layer 3 마아트 독립 검증 → 최종 판정
4단계: QC 보고서 작성 및 제출
```

- 2단계에서 FAIL이면 3단계로 진행하지 않고 재작업 요청
- 마아트는 3단계에서 qc_verify.py JSON 결과를 입력으로 받아 검증

---

### security 레벨

```
1단계: Layer 1 셀프 QC (5항목) → 확인 완료
2단계: Layer 2 qc_verify.py 실행 → overall PASS 확인
3단계: Layer 3 마아트 독립 검증 → 기능/정합성 판정
4단계: Layer 3 로키 보안 감사 → 보안 판정
5단계: QC 보고서 + 보안 감사 리포트 제출
```

- 3단계와 4단계는 병렬 수행 가능하나, 둘 다 PASS여야 5단계 진행
- 로키 보안 감사 결과는 별도 리포트로 발행

---

## 5. 마아트 독립 검증 원칙

이 섹션은 QC 개편의 핵심이다. 마아트의 독립성이 보장되어야 Layer 3의 의미가 있다.

### 컨텍스트 격리 원칙

마아트는 검증 시 다음 입력만을 사용한다.

- `qc_verify.py`가 생성한 JSON 결과 파일
- 원본 작업 명세 (task file)
- 실제 결과물 파일 (직접 접근)

다음은 판단 근거로 사용하지 않는다.

- 개발팀의 진행 보고서
- 팀장의 구두 설명
- 이전 작업과의 비교 ("지난번엔 이렇게 했다")

이유: 개발 컨텍스트에 오염되면 검증자가 의도치 않게 합리화에 동참하게 된다.

### 직접 대조 원칙

마아트가 수행하는 검증의 핵심은 명세와 결과물의 직접 대조다.

- task file에 명시된 요구사항 목록 추출
- 각 요구사항에 대응하는 실제 결과물 확인
- qc_verify.py PASS 항목이라도 명세 대조에서 불일치 발견 시 FAIL 가능

### FAIL 처리 원칙

마아트가 FAIL을 발견한 경우 다음을 기록해야 한다.

- FAIL 항목의 식별자 (모듈명 또는 명세 항목 번호)
- 명세에서 기대한 값 또는 상태
- 실제로 확인된 값 또는 상태
- 불일치의 구체적 내용 (모호한 서술 금지)
- 재작업 요청 내용 (무엇을 어떻게 수정해야 하는지)

---

## 6. 판정 기준

### 자동 검증 (qc_verify.py) 판정

- `overall: "PASS"`: 모든 필수 모듈이 PASS
- `overall: "FAIL"`: 필수 모듈 중 하나라도 FAIL
- SKIP으로 지정된 모듈은 overall 판정에서 제외
- SKIP 지정은 섹션 3의 유형별 매트릭스를 근거로 해야 함 (임의 SKIP 금지)

### 마아트 최종 판정

**PASS**
- 자동 검증 overall PASS
- 마아트 수동 확인에서 이상 없음
- 명세와 결과물 완전 일치

**CONDITIONAL PASS**
- 자동 검증 overall PASS
- 마아트가 경미한 이슈 발견
- 이슈가 현재 작업 범위에 영향 없음
- 다음 작업에서 수정 조건 명시 필요

**FAIL**
- 자동 검증 overall FAIL
- 또는 마아트가 명세 불일치 / 중대 이슈 발견
- 재작업 완료 후 해당 항목 재검증 필요

### CONDITIONAL PASS 사용 기준

CONDITIONAL PASS는 남용을 방지하기 위해 다음 조건을 모두 만족해야 한다.

- 이슈가 현재 task의 주요 목적에 영향을 주지 않을 것
- 다음 스프린트 또는 다음 관련 작업에서 반드시 수정될 것
- 헤르메스 팀장이 조건을 인지하고 동의할 것

---

## 7. 대시보드 프로젝트 예시 체크리스트

대시보드 서버(기본 포트: localhost:8000) 작업 시 사용하는 구체적인 검증 항목이다.

**api_health 대상 엔드포인트**
- `/api/status` - 서버 상태 확인
- `/api/stats` - 통계 데이터 응답 확인
- `/api/teams` - 팀 목록 응답 확인
- `/api/tasks` - 태스크 목록 응답 확인

**file_check 대상 파일**
- `dashboard/server.py` - 서버 메인 파일 존재 및 크기 확인
- `dashboard/index.html` - 프론트엔드 파일 존재 확인

**data_integrity 교차 검증**
- `task-timers.json` (`/home/jay/workspace/memory/task-timers.json`)과 API 응답 태스크 목록 일치 여부
- `member-status.json`과 API 응답 팀원 상태 일치 여부
- completed 태스크에 대응하는 `.done` 파일 존재 여부

**test_runner 대상**
- `/home/jay/workspace/tests/` 전체 테스트 스위트

---

## 8. 체크리스트 커스터마이징 가이드

신규 프로젝트 또는 신규 작업 유형이 추가될 때 이 가이드를 따른다.

### 신규 프로젝트 추가 시

1. 섹션 3의 유형별 매트릭스에서 가장 유사한 유형 선택
2. 해당 유형의 SKIP/필수 기준을 기본값으로 설정
3. 프로젝트 고유 엔드포인트, 파일 경로, 데이터 파일을 섹션 7 형식으로 문서화
4. 이 문서에 추가 섹션으로 기록 (섹션 7의 예시 구조를 따름)

### qc_verify.py 옵션 선택 기준

- 서버/API 작업: 옵션 없음 (4개 모듈 전체 실행)
- 스크립트/유틸리티 작업: `--skip api_health`
- 문서/설정 작업: `--skip api_health --skip test_runner`
- 시스템 코드 작업: `--skip api_health` + `--regression-full` 옵션 권장

### 유형 분류 판단 기준

어떤 유형인지 불분명한 경우 다음 질문으로 판단한다.

- 서버가 기동되는 작업인가? → 서버/API 작업 (유형 A)
- 독립 실행 Python 또는 Shell 스크립트인가? → 스크립트/유틸리티 작업 (유형 B)
- 파일만 생성/수정되는가 (실행 없음)? → 문서/설정 작업 (유형 C)
- 팀 에이전트가 읽는 프롬프트나 dispatch 로직인가? → 시스템 코드 작업 (유형 D)

---

## 9. 자주 발생하는 FAIL 패턴

실제 검증에서 반복적으로 발견되는 패턴을 기록한다. 팀장은 셀프 QC(Layer 1)에서 이 항목들을 우선 확인한다.

**파일 관련**
- 파일은 생성되었으나 크기가 0 (내용 없음)
- 지정 경로가 아닌 `/tmp`나 작업 루트에 생성된 파일
- 다른 팀 디렉토리에 의도치 않게 생성된 파일

**데이터 정합성 관련**
- `task-timers.json`에 completed 상태이나 `.done` 파일 없음
- API 응답 데이터와 JSON 파일 내용 불일치
- JSON 파싱 오류 (파일 손상 또는 불완전한 쓰기)

**API 관련**
- HTTP 200이지만 응답 바디가 빈 객체 `{}`
- `Content-Type`이 `application/json`이 아닌 `text/html`
- 필수 필드가 응답에서 누락됨

**테스트 관련**
- 신규 코드에 대한 테스트가 없음 (test_runner PASS이지만 커버리지 0)
- 회귀 테스트를 실행하지 않고 단위 테스트만 실행

---

*이 문서는 헤르메스 팀장의 지시로 아테나(개발1팀 UX/UI 설계자)가 작성하였습니다.*
*`qc-runtime-verification.md`와 함께 QC 이중 레이어 운영의 완전한 표준을 구성합니다.*