Quality Gate — AI 개발 품질 관리 프로세스

Quality Gate — AI Dev Quality Management

Autodebug + CI를 통합한 감사·자동패치·테스트·배포 검증 워크플로우 — AI 코딩 어시스턴트와 함께 실행
Integrated Autodebug + CI workflow — audit, auto-patch, test, deploy verification with your AI coding assistant
2026-04-20 품질 관리 Quality Gate CI/CD Python
개념 Concept 학습 원리 Theory 구축 프롬프트 Build Prompt 품질 게이트 Quality Gate
💡

사용법: 프롬프트 블록(주황 박스)을 AI 코딩 어시스턴트에 순서대로 붙여넣으세요. 각 단계는 독립적으로 실행할 수도 있고, Step 1→5 순서로 전체 파이프라인을 한 번에 돌릴 수도 있습니다.

How to use: Paste each prompt block (orange box) into your AI coding assistant in order. Steps can be run independently or as a full pipeline from Step 1 through 5.

전체 흐름 — Autodebug + CI:

Full Flow — Autodebug + CI:

Step 1
감사
Step 1
Audit
Step 2
자동 패치
Step 2
Auto-Patch
Step 3
테스트
Step 3
Test
Step 4
배포 검증
Step 4
Deploy Check
PASS ✓
PASS ✓

사전 준비

Prerequisites

필요 도구

Required Tools

도구Tool 용도Purpose 설치Install
pytest 단위·통합 테스트Unit & integration tests pip install pytest pytest-cov
GitHub CLI CI 워크플로우 트리거·모니터CI workflow trigger & monitor brew install gh
AI 코딩 어시스턴트AI Coding Assistant 감사·패치 프롬프트 실행Run audit & patch prompts Claude Code, Cursor 등Claude Code, Cursor, etc.

프로젝트 최소 구조

Minimum Project Structure

project/
├── core/           # 핵심 모듈
├── tests/          # pytest 테스트
│   ├── test_core.py
│   └── conftest.py
├── .github/
│   └── workflows/
│       └── ci.yml  # GitHub Actions CI
└── requirements.txt

tests/ 디렉터리와 최소 1개 이상의 테스트 파일이 없으면 Step 3이 동작하지 않습니다. 먼저 구축 프롬프트로 기본 봇을 만든 후 이 가이드를 실행하세요.

Without a tests/ directory and at least one test file, Step 3 will not run. Complete the Build Prompt guide first, then run this quality gate.

Step 1 코드 감사 (Audit) Code Audit

전체 코드베이스를 스캔하여 CRITICAL 버그와 구조 위반을 탐지합니다. 패치 전 반드시 선행합니다.

Scan the entire codebase for CRITICAL bugs and structural violations. Always run before patching.

감사 기준 (우선순위 순)

Audit Criteria (Priority Order)

등급Severity 항목Issue
CRITICAL 예외 조용히 삼키기 (except: pass) Silent exception swallow (except: pass)
CRITICAL 외부 호출 타임아웃 없음 Missing timeout on external calls
CRITICAL 타 모듈 내부 상태 직접 접근 (_private) Direct access to other module's private state
HIGH 순환 임포트 Circular imports
HIGH 스레드 풀 미경계 (max_workers 없음) Unbounded thread pool (no max_workers)
MEDIUM 하드코딩 매직 넘버 Hardcoded magic numbers
MEDIUM 레이어 방향 위반 (하위→상위 호출) Layer direction violation (low-level calls high-level)
다음 코드베이스를 전체 감사해 주세요.

[감사 대상 파일 또는 디렉터리 목록을 여기에 붙여넣거나, "현재 디렉터리 전체"라고 입력]

감사 기준 (우선순위 순):
1. CRITICAL: except/pass 또는 except Exception: pass — 에러를 조용히 삼키는 패턴
2. CRITICAL: 외부 API·DB 호출에 timeout 없음
3. CRITICAL: 타 모듈의 _private 속성에 직접 접근
4. HIGH: 순환 임포트 (A→B→A)
5. HIGH: ThreadPoolExecutor에 max_workers 미지정
6. MEDIUM: 하드코딩 매직 넘버·문자열
7. MEDIUM: 레이어 방향 위반 (service가 orchestrator를 직접 호출 등)

출력 형식:
- 파일명:줄번호 | 등급 | 문제 설명 | 권장 수정 방향
- CRITICAL 항목 수, HIGH 항목 수, MEDIUM 항목 수 합산 요약
- CRITICAL이 0이 될 때까지 Step 2를 반복합니다
Please audit the following codebase completely.

[Paste the list of files or directories to audit, or write "entire current directory"]

Audit criteria (priority order):
1. CRITICAL: except/pass or except Exception: pass — silent error swallowing
2. CRITICAL: External API/DB calls with no timeout
3. CRITICAL: Direct access to another module's _private attributes
4. HIGH: Circular imports (A→B→A)
5. HIGH: ThreadPoolExecutor without explicit max_workers
6. MEDIUM: Hardcoded magic numbers or strings
7. MEDIUM: Layer direction violation (e.g., service directly calling orchestrator)

Output format:
- filename:line | severity | problem description | recommended fix direction
- Summary: count of CRITICAL, HIGH, MEDIUM items
- Repeat Step 2 until CRITICAL count reaches 0
Step 1 완료 기준: 감사 결과 리스트 출력 완료. CRITICAL 항목이 존재하면 Step 2로 진행.
Step 1 done when: audit result list is generated. If CRITICAL items exist, proceed to Step 2.

Step 2 자동 패치 루프 (Autodebug) Auto-Patch Loop (Autodebug)

Step 1 감사 결과를 기반으로 CRITICAL → HIGH 순으로 자동 패치합니다. 패치 후 재감사하여 CRITICAL이 0이 될 때까지 반복합니다. 최대 5라운드.

Patch CRITICAL → HIGH issues found in Step 1, in priority order. Re-audit after each patch until CRITICAL count reaches 0. Maximum 5 rounds.

Step 1 감사 결과를 바탕으로 CRITICAL 항목부터 패치해 주세요.

패치 순서: CRITICAL → HIGH → MEDIUM
패치 규칙:
- 한 번에 하나의 파일씩, 변경 전/후 코드를 명시
- 기존 로직은 보존하고 최소한의 수정만 적용
- except/pass → except Exception as e: logger.warning(f"[모듈명] 실패: {e}")
- timeout 없음 → timeout=30 또는 timeout=60 명시 추가
- _private 직접 접근 → 공개 메서드(예: cache_age(), get_balance()) 를 통해 접근
- ThreadPoolExecutor → max_workers=N 명시 (N은 작업 수에 맞게)

각 패치 후:
1. 변경한 파일 목록 나열
2. 해당 파일의 남은 CRITICAL/HIGH 수 업데이트
3. CRITICAL이 남아있으면 계속 패치. 0이면 Step 3으로 이동.

[Step 1 감사 결과 리스트를 여기에 붙여넣기]
Based on the Step 1 audit results, patch CRITICAL items first.

Patch order: CRITICAL → HIGH → MEDIUM
Patch rules:
- One file at a time, show before/after code explicitly
- Preserve existing logic — apply minimum necessary changes
- except/pass → except Exception as e: logger.warning(f"[module] failed: {e}")
- Missing timeout → add timeout=30 or timeout=60 explicitly
- _private direct access → access via public method (e.g., cache_age(), get_balance())
- ThreadPoolExecutor → add explicit max_workers=N (N appropriate for task count)

After each patch:
1. List changed files
2. Update remaining CRITICAL/HIGH count for that file
3. If CRITICAL remains, keep patching. If 0, proceed to Step 3.

[Paste Step 1 audit result list here]

5라운드 후에도 CRITICAL이 남으면 해당 모듈을 격리(circuit breaker 추가 또는 임시 비활성화)하고 Step 3을 진행하세요. 무한 루프 금지.

If CRITICAL items remain after 5 rounds, isolate the affected module (add circuit breaker or temporarily disable) and proceed to Step 3. Never loop infinitely.

Step 2 완료 기준: CRITICAL 항목 0개. 또는 5라운드 소진 후 모듈 격리 완료.
Step 2 done when: CRITICAL count = 0. Or 5 rounds exhausted with affected modules isolated.

Step 3 테스트 실행 (CI) Test Execution (CI)

로컬 pytest 실행 후 GitHub Actions CI를 트리거하여 실제 실행 결과를 확인합니다.

Run pytest locally, then trigger GitHub Actions CI to verify results in a real environment.

로컬 테스트 명령

Local Test Commands

# 기본 실행
pytest tests/ -v

# 커버리지 포함
pytest tests/ -v --cov=core --cov-report=term-missing

# 특정 모듈만
pytest tests/test_finance_agent.py -v

CI 트리거 및 모니터

CI Trigger & Monitor

# 워크플로우 수동 트리거
gh workflow run ci.yml

# 실시간 로그 확인
gh run watch

# 마지막 실행 결과 확인
gh run list --limit 5
테스트가 실패했습니다. 아래 pytest 출력을 분석하고 수정해 주세요.

규칙:
- 테스트 코드가 아닌 실제 코드를 수정하세요 (테스트가 올바른 경우)
- 테스트 기대값이 잘못된 경우에만 테스트를 수정하고, 이유를 명시하세요
- 수정 후 동일한 pytest 명령으로 재실행 결과를 예상하여 보여주세요

[pytest 출력 전체를 여기에 붙여넣기]
Tests are failing. Analyze the pytest output below and fix the issues.

Rules:
- Modify the actual code, not the tests (if the tests are correct)
- Only modify tests if the expected values are wrong — state the reason explicitly
- After fixing, show the expected re-run result for the same pytest command

[Paste full pytest output here]
Step 3 완료 기준: pytest 전체 PASSED. GitHub Actions CI green.
Step 3 done when: pytest all PASSED. GitHub Actions CI green.

Step 4 배포 검증 Deploy Verification

배포 후 헬스체크 엔드포인트와 핵심 기능을 실제로 호출하여 동작을 확인합니다.

After deployment, verify behavior by hitting the health-check endpoint and key functions with real calls.

Railway 배포 확인

Railway Deploy Check

# 배포 상태 확인
railway status

# 최근 배포 로그
railway logs --tail 50

# 헬스체크 엔드포인트 호출
curl -s https://your-app.railway.app/health | jq .

Vercel 배포 확인

Vercel Deploy Check

# 최신 배포 목록 (Age 비교)
vercel ls

# 프로덕션 배포
vercel --prod

# 헬스체크
curl -s https://your-app.vercel.app/api/health
배포 후 다음 체크리스트를 순서대로 검증해 주세요.

1. 헬스체크 엔드포인트 응답 확인 (아래 명령 실행)
   curl -s [헬스체크 URL] | 결과 분석

2. 핵심 기능 smoke test
   - [주요 API 엔드포인트 1] 실제 호출 → 응답 코드 + 응답 구조 확인
   - [주요 API 엔드포인트 2] 실제 호출 → 응답 코드 + 응답 구조 확인

3. 에러 경로 확인
   - 잘못된 입력값으로 호출 시 적절한 에러 반환 여부

4. 로그 이상 없는지 확인
   railway logs --tail 30 또는 vercel logs

각 항목에 대해 PASS / FAIL / SKIP (환경 없음) 으로 표시하세요.
After deployment, verify the following checklist in order.

1. Health-check endpoint response (run the command below)
   curl -s [health check URL] | analyze result

2. Core functionality smoke test
   - [Key API endpoint 1] — real call → verify response code + response structure
   - [Key API endpoint 2] — real call → verify response code + response structure

3. Error path check
   - Confirm that invalid input returns appropriate error response

4. Check logs for anomalies
   railway logs --tail 30 or vercel logs

Mark each item as PASS / FAIL / SKIP (no env).
Step 4 완료 기준: 헬스체크 PASS. 핵심 엔드포인트 응답 정상. 에러 경로 적절한 응답 반환.
Step 4 done when: health-check PASS, core endpoints respond normally, error paths return appropriate responses.

Step 5 품질 리포트 Quality Report

전체 파이프라인 결과를 요약하여 PASS / FAIL 판정과 변경 목록을 출력합니다.

Summarize the full pipeline result, output PASS / FAIL verdict and change list.

지금까지의 Quality Gate 실행 결과를 요약하여 최종 리포트를 작성해 주세요.

리포트 형식:
────────────────────────────────────────
Quality Gate Report — [날짜]
────────────────────────────────────────
Step 1 감사     : CRITICAL N개, HIGH N개, MEDIUM N개
Step 2 패치     : 수정 파일 N개, 남은 CRITICAL N개
Step 3 테스트   : pytest N passed / N failed, CI [green/red]
Step 4 배포     : health PASS/FAIL, smoke PASS/FAIL

최종 판정: [ PASS ✓ ] 또는 [ FAIL ✗ ]

변경된 파일 목록:
- 파일명 : 변경 내용 요약

다음 액션:
- PASS: 커밋 & 배포 진행 가능
- FAIL: 미해결 항목 목록 + 권장 대응
────────────────────────────────────────

위 형식에 맞게 이번 세션의 실제 결과로 채워주세요.
Summarize the Quality Gate execution results into a final report.

Report format:
────────────────────────────────────────
Quality Gate Report — [date]
────────────────────────────────────────
Step 1 Audit    : CRITICAL N, HIGH N, MEDIUM N
Step 2 Patch    : N files modified, N CRITICAL remaining
Step 3 Test     : pytest N passed / N failed, CI [green/red]
Step 4 Deploy   : health PASS/FAIL, smoke PASS/FAIL

Final Verdict: [ PASS ✓ ] or [ FAIL ✗ ]

Changed files:
- filename : summary of change

Next actions:
- PASS: commit & deploy when ready
- FAIL: list of unresolved items + recommended actions
────────────────────────────────────────

Fill in the format with the actual results from this session.
Step 5 완료 기준: 최종 판정 PASS ✓ — 커밋 & 배포 진행 가능.
Step 5 done when: final verdict PASS ✓ — ready to commit & deploy.

확장 아이디어

Extension Ideas

아이디어Idea 설명Description
자동 트리거Auto Trigger 파일 저장 시 Step 1→3 자동 실행 (PostToolUse hook) Run Steps 1→3 automatically on file save via PostToolUse hook
슬랙 알림Slack Notification FAIL 판정 시 Slack webhook으로 자동 알림 Auto-notify via Slack webhook on FAIL verdict
커버리지 게이트Coverage Gate 커버리지 80% 미만 시 FAIL 처리 Fail if coverage drops below 80%
히스토리 로그History Log 리포트를 quality-gate-log/YYYY-MM-DD.md에 누적 저장 Append each report to quality-gate-log/YYYY-MM-DD.md
멀티 모듈 병렬 감사Parallel Multi-module Audit 모듈별 감사를 병렬 subagent로 실행하여 속도 향상 Run per-module audits as parallel subagents for speed