AI 드리븐

지도 위치 : 3일차 · 신뢰와 운영 · 강제 사다리의 꼭대기 | 이전: 18차시 버전 관리와 강제 장치 | 다음: 20차시 자동화 파이프라인 ② 키워드 : 클라우드 자동 검사(CI)의 개념, 통과 관문 설정

이 차시를 다 읽으면

1. CI 를 유와 종차로 정의하고, 18차시의 커밋 검사와 무엇이 다른지 표로 가를 수 있다.
2. CI가 매번 깨끗한 환경 에서 도는 것이 왜 중요한지 ④ 로컬 ↔ 원격 축으로 설명할 수 있다.
3. 통과 관문에 넣을 검사를 빠른 순서 로 나열하고, 앞쪽은 형식 · 뒤쪽은 뜻을 검사한다는 것을 말할 수 있다.
4. 워크플로 파일만으로는 관문이 되지 않는 이유와, 브랜치 보호 에서 무엇을 켜야 강제가 되는지 말할 수 있다.
5. CI 실패를 에이전트에게 맡길 때 꼭 넣을 문장과, 관문이 낮아지는 신호 를 댈 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 사람도 AI도 우회할 수 없는 검사는 어떻게 만드는가 입니다. 앞에서 배운 커밋 검사 (18차시)는 --no-verify로 건너뛸 수 있었습니다. 이 차시의 CI 관문은 README 6장 사다리의 가장 높은 칸 입니다.

약함 ◀──────────────────────────────────────────────▶ 강함
 프롬프트로 부탁  →  지침 파일(기억)  →  권한 제한  →  훅 · 커밋 검사  →  ⭐ 자동 검사 관문 (이 차시)

---

1. CI — 무엇에 속하는가

1.1 정의

CI (지속적 통합, Continuous Integration) — [자동 검사 방식]인데, [ 공유 저장소에 변경이 올라올 때마다 깨끗한 원격 환경에서 같은 검사를 자동으로 돌린다 ]는 점에서 내 컴퓨터에서 커밋 순간 도는 커밋 검사와 구별된다.

1.2 경계 — 커밋 검사 ↔ CI

⭐ 둘은 경쟁 관계가 아니라 겹 입니다. 커밋 검사는 빨리 알려 주는 첫 번째 겹이고, CI는 같은 검사를 다시 돌리며 느린 검사까지 더하는 마지막 겹입니다.

1.3 반례 — 이건 관문이 아닙니다

---

2. ⭐ CI의 흐름과 깨끗한 환경

개발자 / 에이전트가 브랜치에 푸시 → PR 생성
                  │
                  ▼
     클라우드에 새 가상 환경 생성 (매번 깨끗한 상태)
                  │
     코드 내려받기 → 의존성 설치 → 검사들 실행
                  │
          ┌───────┴───────┐
        전부 통과          하나라도 실패
          │                 │
     초록 체크 · 병합 가능    빨간 X · 병합 차단 + 실패 로그

🔍 읽는 포인트 : 두 번째 줄 "매번 깨끗한 상태" 와 마지막 갈림길만 보면 됩니다.

깨끗한 환경이 중요한 이유는 0절 축 2입니다. 로컬 환경은 사람마다, 에이전트 세션마다 조금씩 다릅니다.

"제 컴퓨터에선 되는데요"는 위 네 가지 중 하나입니다. CI는 그걸 매번 걸러 냅니다.

---

3. 통과 관문에 넣을 검사

3.1 정의와 순서

통과 관문 (Quality Gate) — [강제 장치]인데, [ 정해 둔 검사를 모두 통과해야만 다음 단계(병합 · 배포)로 넘어가게 한다 ]는 점에서 결과만 보여 주는 검사 보고와 구별된다.

빠른 검사를 앞에 둡니다. 앞에서 실패하면 뒤를 기다릴 필요가 없습니다. 그리고 빠른 검사는 대체로 형식 검사입니다. 앞에서 배운 대로 (13차시) 형식 검사만으로는 뜻을 보장하지 못하므로, 4단계의 통합 테스트가 관문의 실질적인 몸통입니다. 17차시 5절의 클래스온 규칙 다섯 개가 여기서 매번 돕니다.

3.2 GitHub Actions 예시

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:                       # 통합 테스트용 DB
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready --health-interval 5s --health-retries 10
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test
        env:
          DATABASE_URL: postgres://postgres:test@localhost:5432/postgres
      - run: npm run build
      - run: npm audit --audit-level=high

  secrets-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

(버전 번호와 세부 옵션은 작성 시점의 공식 문서를 확인하세요.)

🔍 읽는 포인트 : run: 뒤의 다섯 줄 — lint · typecheck · test · build · audit — 이 3.1절 표의 검사 목록입니다. 그리고 jobs: 아래의 이름 두 개(check, secrets-scan)는 4절에서 필수 검사로 지정할 이름 입니다.

POSTGRES_PASSWORD: test처럼 CI에 들어가는 값은 테스트용 값만 씁니다. 실제 운영 키가 필요해 보이는 단계가 있다면 설계가 잘못된 것입니다. 꼭 비밀값이 필요하면 GitHub Secrets(저장소 설정에 숨겨 두고 워크플로에서 이름으로만 부르는 기능)에 테스트 키 를 넣습니다.

---

4. ⭐ 관문을 "강제"로 만드는 설정 — 브랜치 보호

브랜치 보호 (branch protection) — [저장소 설정]인데, [ 특정 브랜치에 들어가는 조건(PR 필수 · 검사 통과 · 승인)을 GitHub가 직접 강제한다 ]는 점에서 지침 파일의 "main에 직접 넣지 마"라는 부탁과 구별된다.

⚠️ 워크플로 파일만 있으면 실패해도 병합 버튼이 눌립니다. CI는 결과를 보여 줄 뿐이고, 그 결과를 병합 조건으로 묶는 것 은 저장소 설정입니다. 0절 축 1이 정확히 여기서 갈립니다.

GitHub 저장소 → Settings → Branches(또는 Rules) → main 보호 규칙:

• 병합 전 PR 필수
• 병합 전 상태 검사 통과 필수 → check, secrets-scan 지정
• 관리자에게도 적용 (화면 문구는 "관리자 포함", "우회 허용 안 함" 등 버전마다 다름 — 공식 문서 확인)

마지막 항목이 없으면 저장소 주인(나)은 빨간 X가 떠도 병합할 수 있습니다. 그리고 에이전트가 내 계정 권한으로 일하고 있다면, 에이전트도 그렇게 할 수 있습니다. 급할 때 한 번 우회하기 시작하면 관문은 다시 부탁으로 내려갑니다.

💡 비유는 마지막에 — 워크플로만 있는 CI는 공항의 엑스레이 화면 입니다. 위험물이 보여도 아무도 막지 않으면 통과합니다. 브랜치 보호는 그 화면에 연결된 게이트 입니다.

---

5. 관문을 낮추지 않게

5.1 CI 실패를 에이전트에게 맡기기

CI가 실패하면 로그를 에이전트에게 주고 고치게 할 수 있습니다. 로그는 읽지 않아도 됩니다. 대신 지시에 이 문장을 반드시 넣습니다.

CI의 npm test가 실패했다. 로그는 아래와 같다.
원인을 먼저 설명하고, 코드를 고쳐서 통과시켜라.
테스트 파일이나 CI 설정을 바꿔서 통과시키지 마라. 그래야 한다고 판단되면 이유를 보고해라.

🔍 읽는 포인트 : 마지막 줄입니다. 17차시의 "테스트를 고쳐서 통과" 문제가 CI에서는 "관문을 고쳐서 통과" 로 똑같이 일어납니다.

5.2 관문이 낮아지는 신호

CI의 가장 큰 위험은 AI가 통과시키려고 검사를 줄이는 것 입니다. YAML을 읽지 못해도, .github/workflows/ 파일이 바뀐 PR에서 아래 단어가 새로 생겼는지 는 찾을 수 있습니다.

⚠️ 이 가운데 하나라도 새로 생겼다면 검사를 무력화했을 수 있습니다. README 9.4의 위험 신호("자동 검사 설정을 바꿨다", "skip, disable")와 같은 이야기입니다.

5.3 불안정한 테스트

불안정한 테스트 (flaky test) — [자동 테스트]인데, [ 같은 코드에서 돌릴 때마다 결과가 달라진다 ]는 점에서 코드가 틀릴 때만 실패하는 믿을 수 있는 테스트와 구별된다.

앞에서 배운 "결정적이다" 조건 (17차시)을 어긴 테스트입니다. 이런 테스트가 있으면 빨간 X가 떠도 "재실행하면 돼"가 일상이 되고, 곧 진짜 실패도 재실행으로 넘기게 됩니다. 관문이 사람의 습관 때문에 낮아지는 경우입니다. 재실행이 아니라 원인을 고치게 합니다.

앞으로 다시 만납니다 — .github/workflows/ 자체가 바뀌는 것을 사람의 승인 없이는 병합할 수 없게 하는 장치가 20차시의 CODEOWNERS 입니다. 관문을 지키는 관문입니다.

---

6. 클래스온에 적용하면

---

7. 실습 — 맡기고 검수하기

지시

[1단계 — CI 설정]
클래스온 저장소에 GitHub Actions CI를 만들어줘.
- 검사: 린트, 타입 검사, 단위·통합 테스트(테스트용 Postgres를 띄움), 빌드, 의존성 감사, gitleaks.
- 비밀값이 필요한 단계에는 테스트용 값만. 운영 키는 어떤 경우에도 쓰지 마.
보고 형식: | 잡 이름 | 검사 단계 | 걸린 시간 | 결과 |
PR을 하나 열어 CI를 실제로 돌리고, Actions 실행 화면 주소와 각 단계 결과 원문을 붙여.

[2단계 — 관문 시험]
일부러 실패하는 테스트 하나를 넣은 시험용 PR을 따로 만들어줘. 병합은 절대 하지 마.
그 PR에서 CI가 실패한 로그의 마지막 부분 원문과 PR 주소를 보고해.
시험이 끝나면 시험용 PR은 닫고 브랜치는 지워. 닫기 전에 내 확인을 기다려.

브랜치 보호 설정은 내가 직접 할 테니, 필수 검사로 지정할 잡 이름만 알려줘.

🔍 읽는 포인트 : 2단계의 "병합은 절대 하지 마"와 "닫기 전에 내 확인"이 핵심입니다. 관문이 막는지는 내 눈으로 봐야 하기 때문입니다. 브랜치 보호는 관문 자체를 정하는 설정이라 사람이 직접 겁니다.

받을 증거

• 1단계 PR의 Actions 실행 주소와 단계별 결과 원문 (전부 초록)
• 2단계 시험용 PR 주소와 실패 로그 원문 (어느 테스트가 실패했는지 이름이 보여야 함)
• 필수 검사로 지정할 잡 이름 목록

내가 직접 확인할 것

💡 PR 화면의 초록 체크와 빨간 X가 당신의 계기판 입니다. CI는 코드를 읽지 못하는 사람 대신 매번 같은 검사를 빠짐없이 수행합니다. 그래서 이 방식에서 CI는 "있으면 좋은 자동화"가 아니라 가장 믿을 수 있는 팀원 이고, README 9.1의 신뢰 근거 ① 강제 장치의 대표입니다.

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 19차시 노트만 근거로 5문제를 내줘. 비전공자 기준으로.
"커밋 검사와 CI의 차이", "워크플로만으로는 관문이 되지 않는 이유", "관문이 낮아지는 신호"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.