# task-1061.1 보고서: 1056 도입 B — 기존 시스템 연동 및 업데이트

**작성자**: 비슈누 (개발4팀장)
**작성일**: 2026-03-26
**작업 레벨**: Lv.1 (단순 수정 + 분석)
**팀원**: 카르티케야(백엔드), 사라스바티(프론트엔드)

---

## SCQA

**S**: task-1056.1 비교분석에서 도출된 4개 도입 제안(코드 아키텍처 원칙, 공통 용어사전, 문서 갱신 트리거, 성능 지표) 중 기존 시스템 파일 수정이 필요한 항목들이 정의되었다. task-1060.1(신규 문서 3개)과 병렬 진행.

**C**: 기존 QC-RULES.md, anu-guide.md, work-level-system.md에 additive 수정이 필요하며, 3개 심층 분석 항목(Lv.0 QC 충돌, 문서 갱신 트리거, 성능 지표)은 도입 적절성 판단이 선행되어야 한다.

**Q**: 5개 항목 모두를 기존 시스템을 깨뜨리지 않는 additive 방식으로 반영할 수 있는가?

**A**: 5개 항목 중 3개(항목 1, 2, 3) 구현 완료, 2개(항목 4, 5) 분석 결과 추가 구현 불필요. QC-RULES.md에 체크리스트 7·8번 추가, anu-guide.md에 용어사전 갱신 규칙 추가, work-level-system.md에 Lv.0 경량 QC 규칙 추가. 기존 규칙 수정 없이 additive only 원칙 준수.

---

## 항목별 작업 결과

### 항목 1: QC-RULES.md 업데이트 — 완료

**변경 파일**: `/home/jay/workspace/teams/shared/QC-RULES.md`
**변경 내용**:
- 셀프 QC 체크리스트에 7번 항목 추가: "코드 아키텍처 원칙(`memory/specs/code-architecture-principles.md`)을 확인했는가? — SOLID/DRY 위반 없음 확인"
- 8번 항목 추가: "인터페이스(API/함수 시그니처) 변경 시 관련 문서를 갱신했는가?"
- 기존 1~6번 항목 미수정 확인
- 변경 이력에 v3.4 추가
- 요약 문구 "6항목" → "8항목" 갱신

### 항목 2: anu-guide.md 규칙 추가 — 완료

**변경 파일**: `/home/jay/workspace/memory/specs/anu-guide.md`
**변경 내용**:
- §2.4 "코딩 진행 방식" 섹션에 규칙 1줄 추가: "용어사전 동시 갱신: 새로운 개념/용어 도입 시 `memory/specs/glossary.md` 용어사전을 동시 갱신한다."
- 기존 규칙 미수정 확인
- 문서 버전 v1.1 → v1.2 갱신

### 항목 3: Lv.0 QC 충돌 해결 — 분석 완료 + 구현

**분석 결과**:

충돌 구조:
- 외부 항목 14: "변경이 작아도 매번 영향 확인"
- 우리 Lv.0: "상수/경로 1~2줄 → QC 스킵"

**판단**: 경량 QC 도입 적절. 근거:
1. Lv.0는 "로직 변경 없음, 판단 불필요"가 전제이므로 전체 QC 파이프라인은 과도
2. 그러나 상수/경로 변경도 import 참조, 설정 파일 체인 등에서 다른 파일에 영향을 줄 수 있음
3. "영향 파일 1줄 확인"은 Haiku 에이전트가 수정 후 즉시 수행 가능 (추가 시간 ~5초)
4. Yes면 Lv.1로 재분류하여 정식 QC를 거치므로 안전망 확보
5. 전체 QC(~2분) 대비 경량 QC(~5초)로 속도/효율성 유지

**구현 내용**:
- **변경 파일**: `/home/jay/workspace/memory/specs/work-level-system.md`
- Lv.0 프로세스 3번 수정: "전체 QC 파이프라인 스킵. 단, 경량 QC 수행"
- 3.5번 추가: "경량 QC — 영향 파일 1줄 확인, Yes면 Lv.1 재분류"
- 문서 버전 v2.0 → v2.1 갱신

### 항목 4: 문서 갱신 트리거 — 분석 완료, 추가 구현 불필요

**분석 결과**:

선택지 2가지:
- **A안**: PostToolUse 훅에 API 파일 변경 감지 추가 (자동 리마인드)
- **B안**: QC-RULES.md 셀프 체크리스트에 항목 추가 (수동 확인)

**판단**: B안 (QC 체크리스트 항목 추가)으로 충분. 근거:
1. 항목 1에서 이미 8번 항목("인터페이스 변경 시 관련 문서 갱신") 추가 완료
2. PostToolUse 훅은 **모든 파일 저장 시** 실행되므로 API 무관 파일에서도 트리거 → 노이즈 증가
3. 훅에 파일 패턴 필터링(routes.py, endpoints.py 등)을 추가하면 유지보수 부담 증가
4. QC 체크리스트는 Phase 완료 시점에 한 번 확인 → 적절한 빈도
5. 훅 수정은 `.claude/hooks/` 전역 설정이므로 모든 팀에 영향 → 별도 승인 필요

**결론**: 별도 훅 수정 불필요. 항목 1의 체크리스트 8번으로 요구사항 충족.

### 항목 5: 성능 지표 영향분석 — 분석 완료, 도입 부적합

**분석 결과**:

performance_check verifier 추가 적합성 평가:

**부적합 판단. 근거**:
1. **적용 범위 제한**: 서버/API 작업에만 해당 (~전체 작업의 10% 미만). 대부분의 작업(문서, 스크립트, 프론트엔드)에서 SKIP 처리
2. **기존 커버리지**: api_health verifier가 이미 HTTP 200 응답 여부 검증. 서버 기본 건전성은 확인됨
3. **기준값 설정 비현실적**: 응답시간은 로컬 환경, CI 환경, 프로덕션 환경에서 2~10배 편차 발생. 고정 기준값(예: 2000ms)은 환경별 false positive/negative 유발
4. **메모리 측정 복잡성**: 프로세스 메모리 측정은 `psutil` 의존성 추가 + PID 식별 로직 필요. qc_verify.py의 단순성 훼손
5. **대안 존재**: 성능 측정이 필요한 Lv.3+ 서버 작업은 k6, locust 등 전용 도구로 별도 검증이 적절

**현재 qc_verify.py 현황**: 12종 verifier (api_health, file_check, data_integrity, test_runner, tdd_check, schema_contract, pyright_check, style_check, scope_check, critical_gap, spec_compliance, duplicate_check). 범용 verifier만 포함하는 현행 원칙 유지 권장.

---

## 생성/수정 파일 목록

- **수정**: `/home/jay/workspace/teams/shared/QC-RULES.md` — 체크리스트 항목 7, 8 추가 (v3.4)
- **수정**: `/home/jay/workspace/memory/specs/anu-guide.md` — 용어사전 동시 갱신 규칙 추가 (v1.2)
- **수정**: `/home/jay/workspace/memory/specs/work-level-system.md` — Lv.0 경량 QC 추가 (v2.1)
- **생성**: `/home/jay/workspace/memory/reports/task-1061.1.md` — 본 보고서

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **QC-RULES.md 항목 개수 불일치** — 기존 "6항목"을 "8항목"으로 갱신하여 체크리스트 개수 정합성 확보
2. **항목 4와 항목 1의 중복** — 분석 결과, 체크리스트 8번이 항목 4의 요구사항을 이미 충족함을 확인. 중복 구현 방지.
3. **work-level-system.md 이전 버전 표기 불일치** — v2.0에서 v2.1로 갱신 시 이전 버전이 "v1.0"으로 표기되어 있으나, 이는 기존 상태 그대로 유지 (원본 문서의 의도적 표기로 판단)

### 범위 외 미해결 (0건)
없음.

---

## 셀프 QC 체크리스트

- [x] 1. 이 변경이 다른 파일에 영향을 미치는가? — 3개 파일 수정. QC-RULES.md는 모든 팀이 참조하므로 영향 범위 넓음 (additive only이므로 기존 동작 무변경)
- [x] 2. 이 로직의 엣지 케이스는 무엇인가? — 코드 아키텍처 원칙 문서(code-architecture-principles.md)가 아직 미생성일 수 있음. task-1060.1에서 생성 예정이므로 체크리스트 7번은 해당 문서 생성 후 활성화됨.
- [x] 3. 이 구현이 작업 지시와 정확히 일치하는가? — 5개 항목 전수 처리 (3개 구현 + 2개 분석 후 미구현 판정, 각각 근거 명시)
- [x] 4. 에러 처리와 보안은 확인했는가? — 문서 수정 작업이므로 해당 없음
- [x] 5. 테스트가 모든 경로를 커버하는가? — 문서 수정 작업이므로 해당 없음. 3개 파일 수정 내용 직접 검증 완료.
- [x] 6. 발견한 이슈를 모두 직접 해결했는가? — 3건 자체 해결, 미해결 0건
- [x] 7. 코드 아키텍처 원칙 확인 — 코드 변경 없음 (문서 수정만)
- [x] 8. 인터페이스 변경 시 관련 문서 갱신 — 인터페이스 변경 없음

---

## QC 자동 검증

- **전체 결과**: PASS (5 PASS, 7 SKIP)
- file_check: PASS (3개 파일 존재 + 크기 확인, 보고서 7877 bytes)
- data_integrity: PASS (task-timers.json 정합)
- test_runner: SKIP (관련 테스트 파일 0개, 문서 수정 작업이므로 정당)
- tdd_check: SKIP (코드 변경 없음)
- pyright_check: SKIP (Python 파일 변경 없음)
- style_check: SKIP (Python 파일 변경 없음)
- critical_gap: PASS (1건 CRITICAL 식별 → RESOLVED)
- spec_compliance: PASS (미체크 항목 없음)
- duplicate_check: PASS (최대 유사도 14.2% — task-1056.1, 참조 관계로 인한 정상 수준)
- .done 파일 자동 생성 완료