code-qa 작업 규칙 (rules)

이 파일 = 규칙. 상태·진행·이력은 handoff.md, 파트별 감사 원본은 C:\dev\tools\code-qa\audit\, 에이전트가 읽는 실무 매뉴얼은 C:\dev\tools\code-qa\manual\. 새 규칙은 🆕 신규에 1줄 append → 안정화되면 확립 규칙 §로 원문 이관.

📑 인덱스

• 🆕 신규 (최근 확립, 미분류)
• §1 파이프라인 규칙
• §2 에이전트 설정
• §3 데이터·기록

🆕 신규

• 2026-07-30 서브에이전트가 같은 리포에서 도는 동안 브랜치를 바꾸지 마라. 운영배포(파일 단위 선별 포워드) 때 작업트리를 deploy-live 로 checkout 했는데 마침 리팩토링 에이전트가 같은 리포에서 돌고 있었다 → 그 에이전트가 커밋했다면 리팩토링이 운영 브랜치로 그대로 나갈 뻔했다. 즉시 master 로 복귀하고 git worktree add <임시경로> deploy-live 로 격리해 배포했다(끝나면 worktree remove). 배포는 워크트리에서가 이제 기본이다.

• 2026-07-30 선별 포워드는 "포워드 대상 파일에 한해 배포본 == 내 작업 시작점"을 먼저 증명한다. git diff origin/deploy-live <내 시작 커밋> -- <파일들> 이 비어 있으면 그 파일들의 포워드분은 곧 내 변경분뿐이다 (미배포 타 작업이 딸려갈 수 없다). 커밋 개수·patch-id 로 세는 것보다 확실하고 한 줄이다.

• 2026-07-30 리팩토링 에이전트가 디버깅의 누락분을 잡으면 그 자리에서 디버깅으로 되돌린다. templates-xss-cache 리팩토링이 PFS-D046(base 를 안 쓰는 독립 템플릿 5개의 캐시버스터 누락)을 찾아냈다 — 디버깅이 "base.html 상속군"만 보고 끝낸 탓. 에이전트는 고치지 않고 finding 으로 등록했고, 디버깅이 받아 처리했다. 파이프라인 2단계가 서로의 커버리지 구멍을 메운다 = 이 구조를 쓰는 이유.

• 2026-07-30 횡단 결함은 파일마다 고치지 말고 "모두가 지나는 한 지점"을 찾는다. DataTables 저장형 XSS 는 21개 템플릿 컬럼을 손대는 대신 defaults.column.mRender 한 곳(web/static/js/datatable.js)에서 끝냈다. 판단 기준 = 예외를 프레임워크가 이미 정의해 주는가(여기선 columns.render 가 기본을 덮고, data 가 함수면 건드리지 않는다). 예외 규칙을 내가 새로 만들어야 하면 그건 중앙화가 아니라 새 결합이다.

• 2026-07-30 수정이 사용자에게 "전달되는 경로"까지가 수정이다. XSS 수정 파일(datatable.js) 자체에 캐시버스터가 없어 12시간 캐시로 막힐 상황이었다 → 두 건을 같은 커밋에 묶었다. 정적 자산을 고치면 배포 경로(캐시·CDN·워커 재기동)를 함께 확인한다.

• 2026-07-29 검증 호출이 상태를 바꾸는지 먼저 본다. 인증 게이트 검증으로 운영 /api/sticker/sync-poll 을 불렀다가 8일째 대기 중이던 요청이 running 으로 claim 됐다(원복함). 엔드포인트 이름이 조회처럼 보여도 큐·락·카운터를 건드릴 수 있다 → 검증은 부작용 없는 경로로(여기선 sync-complete 빈 body = id 없으면 DB 미변경).

• 2026-07-29 "내 변경 탓인가"는 미배포 환경을 대조군으로 가른다. 테스트에서만 나던 화면 오류를 운영(아직 P0 미배포)에 같은 스크립트로 돌려 운영 PASS → 내 변경 무관을 먼저 확정하고 원인(테스트 DB 의 null 데이터)으로 갔다. 배포 전후 환경이 갈라져 있는 동안이 가장 싼 대조 실험 기회다.

• 2026-07-29 서버 인증을 조이기 전에 "사람 세션 없는 호출자"를 전수 조사한다. pfs 는 poin-agent 데몬 2종이 이미 로그인 방식이라 무사했지만 door_sync_watch 하나가 무세션이었다 → 화이트리스트로 뚫어두지 말고 공유 토큰으로 인증시킨다(구멍을 남기지 않는다). 상주 데몬은 코드를 고쳐도 재기동해야 반영된다 — 실제로 구버전으로 돌고 있어 배포 직후 401 을 받기 시작했다.

• 2026-07-29 재검수는 감사 노트 재인용이 아니라 실측이다. 파트 착수 전 재검수에서 감사 원본 문장을 그대로 옮기면 재검수가 아니다 — 해당 파일·라인을 다시 열고, 필요하면 운영 EC2까지 읽기전용으로 확인한다(scripts/ssm_run.py). 실측이 우선순위를 바꾼 실례: 배차 업로드 경로 버그는 "운영 오작동 확정"이었지만 운영 uploads/dispatch에 .gitkeep뿐 = 축적 파일 0 → 데이터 마이그레이션 불필요·한 줄 수정으로 종결이라 가장 먼저 칠 파트가 됐다. ⚠EC2 python은 3.6.9 — 조사 스크립트에 subprocess.run(capture_output=) 같은 3.7+ 인자 쓰면 죽는다.

• 2026-07-29 "결정 대기"는 파트 status=blocked로 표기한다. P0 안에 페페 결정이 필요한 파트가 섞여 있으면 순차 진행이 통째로 막힌다. 결정 선행 파트는 qa.py part set --status blocked로 대시보드에 ⛔로 드러내고, 착수 가능한 파트를 로드맵 위쪽으로 재배치한다(같은 P 안에서는 표의 위에서부터가 순서다).

• 2026-07-29 "코드 버그"와 "계약 변경"을 한 파트에 두지 않는다. 무해한 국소 수정이 결정 대기에 묶여 같이 멈춘다. 실례: platform-core의 예외 __str__ 수정(국소·무해)과 fail() HTTP status 전환(프론트 error: 콜백 158곳이 한꺼번에 살아나는 전면 회귀)은 성격이 달라 후자를 platform-response-policy로 분리했다. 판단 기준 = 호출자의 기대 동작이 바뀌면 그건 버그 수정이 아니라 정책 결정이다.

• 2026-07-29 규칙·작업단계는 devplan 페이지에도 공유한다 (페페 지시). 에이전트가 따르는 기본 규칙(파이프라인· 위험도 분기·단계 P0/P1/P2 정의·금지·검증 기준·재검수 루프)을 code-qa.html의 📋 작업 규칙 섹션에 요약해 둔다. 페페는 대시보드만 보고도 "이 시스템이 무슨 규칙으로 도는지"를 알 수 있어야 한다. → 규칙이 바뀌면 manual/*.md·이 파일과 함께 그 섹션도 같은 작업에서 갱신한다(원본은 manual, 페이지는 요약본). 단계 카드에는 그 라운드에서 P0으로 뽑은 파트와 선정 이유를 적어 둔다(다음 라운드에 바뀌면 같이 갱신).

• 2026-07-29 매 답변마다 시드 갱신 여부를 보고에 명시 (페페 지시 — 전역 규칙이라 rules/workflow.md "작업 원칙"에 원문 등록). 보고 끝에 시드: 갱신함(무엇을·커밋) 또는 시드: 갱신 없음(사유) 한 줄. 안 한 답변에서도 생략하지 않는다.

• 2026-07-29 에이전트 권한 = 위험도 분기 (페페 확정, 그릴링 1문항). 명백한 단순버그(오타·널가드 누락· args["key"] 같은 규약 위반·중복 쿼리)는 즉시 수정 + # BUG/FIX 주석. 도메인 판단 필요·다중 호출자 영향· DB 스키마 관련·금액 계산 규칙·권한 인증 로직은 # BUG: 주석만 달고 보류 → 페페 확인. 애매하면 보류가 기본. 커밋은 master까지(테스트 8001 자동배포로 검증), 운영배포는 페페가 채팅에 직접 입력했을 때만.

• 2026-07-29 노력도(effort) = 디버깅 xhigh / 리팩토링 high (코디 추천, 페페 위임). 근거 = 디버깅은 근본원인 추적·가설 검증·회귀 예측에 추론 깊이가 곧 정확도이고 틀린 수정이 실업무 사고가 된다. 리팩토링은 기법이 정형화돼 있어 판단 폭이 좁고, 중요한 건 추론 깊이가 아니라 절차 준수(안전망·범위 통제)라 high면 충분하다. max는 비용·시간 대비 이득이 체감되지 않아 제외. → 서브에이전트 frontmatter effort 필드는 실재한다(값 low/medium/high/xhigh/max, Opus 5는 전 단계 지원). model:은 별칭 opus 대신 claude-opus-5 핀 고정(별칭은 버전이 올라가면 같이 이동).

• 2026-07-29 로드맵은 살아있는 문서다 (페페 지시). 오늘 만든 로드맵을 따라만 가지 않는다 — 매 파트 착수 전 재검수(감사 후보가 지금도 그 자리에 있는지·범위가 여전한지·더 위험한 게 생겼는지·선행 파트 수정이 전제를 바꿨는지) 하고, 어긋나면 작업 전에 로드맵부터 고친다. qa.py roadmap set은 기존 진행상태를 보존하므로 범위만 갈아끼울 수 있다.

• 2026-07-29 전수검사 파트는 1,000~2,000 LOC가 적정. 그보다 크면 한 세션에 라인별 정독이 안 끝난다 (실측: 4,000줄 넘는 JS 2개는 grep 패턴 검사까지만 되고 정독 미완 → 로드맵에서 재검사 파트로 되돌림). 감사 에이전트에게는 커버리지를 정직하게 표기하게 시킬 것 — "다 봤다"는 보고가 사실이 아니면 로드맵이 거짓이 된다.

• 2026-07-29 감사 에이전트에 "읽기 전용 + 산출 md 1개만 Write"를 명시할 것. 안 그러면 검사 도중 코드를 고치려 든다. 또 파일 규모는 git ls-files 기준으로 세게 할 것 — find로 세면 미추적 임시파일이 섞여 3배 부풀려진다 (실측: 템플릿 207개/51.6k로 알려줬는데 실제는 62개/30.0k).

§1 파이프라인 규칙

1. 디버깅이 항상 먼저. 리팩토링은 그 파트의 debug=done이 아니면 착수하지 않는다.
2. 디버깅은 파트를 끝내면 작업 종료 전에 리팩토링 에이전트를 호출한다. 직접 호출이 안 되면 최종 응답 첫 줄에 [REFACTOR-REQUEST] part=... commits=... deferred=...를 적어 코디가 대신 부르게 한다.
3. 리팩토링은 착수 전 디버깅이 뭘 했는지 확인한다(수정·보류 목록, # BUG 주석 전량 grep). 보류된 항목의 코드는 건드리지 않는다 — 사람 판단 대기 중인 코드를 옮기면 판단 자체가 무효가 된다.
4. "리팩토링 안 함"도 정당한 결론. 근거를 적고 --refactor skipped로 기록하면 임무 완료다.
5. 리팩토링 중 버그를 발견하면 고치지 말고 기록만 하고 디버깅으로 넘긴다(두 개의 모자 원칙).
6. 기존 # BUG / # REFACTOR / 버그ID 주석은 누구도 지우지 않는다.

§2 에이전트 설정

• 정의 = 전역 ~/.claude/agents/{code-debugger,code-refactorer}.md(프로젝트 무관하게 재사용).
• 프로젝트별 지식은 에이전트 정의가 아니라 manual/<project>.md에 둔다 — 에이전트는 그대로 두고 프로젝트만 늘리는 구조. 새 프로젝트를 추가하면 manual/<p>.md + audit/<p>/ + qa.py --project <p>.
• 에이전트는 반복 이슈를 발견하면 그 자리에서 manual/<project>.md의 🆕 신규에 append한다. 쓰기가 막히면 응답에 [MANUAL-UPDATE] 블록으로 원문을 적어 코디에게 요청한다(그냥 넘어가지 않는다).

§3 데이터·기록

• 단일 데이터 = C:\dev\devplan\code-qa-data.json. 쓰기는 qa.py로만(직접 편집하면 대시보드가 깨진다).
• 발견 ID = PFS-D001(디버깅) / PFS-R001(리팩토링), qa.py가 자동 채번. 코드 주석의 ID와 일치시킨다.
• 코드 주석 날짜는 26.7.29(수) 형식(사람이 읽는 값). JSON ts는 YYYY-MM-DD HH:MM 유지.
• 파트 종료 시 part set + history add 둘 다 필수. 하나만 하면 미완료로 본다.