18. AI 개발 워크플로우 종합

0. 먼저 알고 가기 (30초 요약)

• AI 워크플로우는 요구사항 정리 -> 생성 -> 검증 -> 반영의 4단계 루프입니다.
• 중요한 입력은 문맥/제약/기술 결정이므로 정확히 전달하세요.
• 마지막 검증(테스트, 리뷰, 보안)은 반드시 사람의 승인 게이트로 처리하세요.

왜 중요한가: AI가 만든 코드를 검증 없이 머지하면 회귀 비용은 사람이 만든 코드보다 더 큽니다. 빠른 작성과 느슨한 검증의 비용 차이가 가장 큰 영역이 AI 협업입니다.

일상 비유: 패스트푸드 주방과 같습니다. 자동화 기기(AI)가 패티를 빠르게 익혀줘도, 손님에게 내기 전 한 명이 위생/온도/주문 일치를 직접 확인합니다.

초심자용 한눈에 보기

AI를 쓸 때 가장 중요한 건 "문맥을 관리하고, 결과를 검증"하는 체계입니다.

flowchart LR
  REQ[요구사항 정리] --> CTX[문맥 + 제약 전달]
  CTX --> GEN[AI 생성]
  GEN --> VERIFY[검증 게이트]
  VERIFY -->|통과| APPLY[반영]
  VERIFY -->|실패| REQ
  APPLY --> AUDIT[감사 기록]

핵심 용어 빠르게 정리

---

AI 개발 워크플로우 표준은 특정 코딩 에이전트 제품 사용법이 아니라 AI가 만든 결과를 안전하게 검증하고, 민감정보를 보호하며, 사람의 책임을 유지하는 개발 운영 체계입니다.

---

추천 항목 (실무 우선순위)

• 시작 추천: 작업 의도/제한사항/성공 기준을 3문장으로 정리한 뒤에만 AI 입력을 전달하세요.
• 안정 추천: 민감정보 redaction과 감사 로그를 고정 규칙으로 자동 검사합니다.
• 운영 추천: AI 출력은 사람이 최종 승인 후 반영하고, 반려 사유는 템플릿에 기록하세요.

추천 항목 고도화 체크

• 첫 적용 — AI 사용 범위, 컨텍스트, 검증 책임 중 하나를 실제 PR이나 운영 이슈에 붙이고, 변경 전 기준을 먼저 적는다.
• 증거 정리 — task boundary, prompt/output 기록, 검증 명령, 사람 승인를 같은 작업 기록에 남긴다.
• 재점검 — AI 제안 반려율, 재작업률, 검증 누락 수가 나아졌는지 30일 안에 확인하고 기준을 유지, 수정, 폐기 중 하나로 판정한다.

추천 항목 실행 기록 템플릿

• 작업 : AI 사용 범위, 컨텍스트, 검증 책임 적용 범위를 어느 화면, 패키지, 문서에 둘지 적는다.
• 증거 : task boundary, prompt/output 기록, 검증 명령, 사람 승인 중 실제로 남긴 항목만 링크한다.
• 판정 : 유지/수정/폐기 중 하나와 이유를 한 문장으로 남긴다.
• 다음 점검 : AI 제안 반려율, 재작업률, 검증 누락 수를 다시 볼 날짜와 담당자를 지정한다.

문서 책임 범위

---

0. 모든 프론트엔드 그룹 공통 Baseline

0.0 AI 워크플로우 운영 파이프라인

flowchart TD
  A[요청 접수] --> B{요청 유형 분류}
  B -->|허용 가능한 초안 작업| C[Prompt 템플릿 작성]
  B -->|금지 항목| D[수동 처리 또는 승인 보류]
  C --> E[민감정보 Redaction + 범위 명시]
  E --> F[AI 산출물 생성]
  F --> G[Type / Test / Security / Human Review 게이트]
  G --> H{게이트 통과?}
  H -->|Pass| I[PR 산출물 분리 등록]
  H -->|Fail| J[재요청/수동 보정]
  I --> K[감사 노트 기록 + 비용 집계]
  J --> C
  K --> L[배포 승인/운영 handoff]

0.1 교차 검증 매트릭스

0.2 운영 게이트

---

1. AI에 맡겨도 되는 작업

왜 중요한가: "어디까지 맡길 수 있나"가 사람마다 다르면, 같은 팀에서도 PR 품질의 분산이 매우 커집니다.

---

2. AI에 맡기면 안 되는 작업

2.1 AI 사용 결정 트리

flowchart TD
  TASK([작업 요청]) --> Q1{민감 데이터<br/>secret/PII가<br/>입력에 필요?}
  Q1 -->|예| MASK{마스킹/익명화<br/>가능?}
  MASK -->|아니오| HUMAN[사람만 처리]
  MASK -->|예| Q2
  Q1 -->|아니오| Q2{되돌리기<br/>30분 이상 걸리는가}
  Q2 -->|예| Q3{테스트로<br/>회귀 감지 가능?}
  Q2 -->|아니오| AI_OK[AI 초안 OK]
  Q3 -->|아니오| HUMAN
  Q3 -->|예| Q4{법적/규제 판단인가}
  Q4 -->|예| HUMAN
  Q4 -->|아니오| AI_GUARD[AI + 검증 게이트]
  AI_OK --> VERIFY[type/test/review]
  AI_GUARD --> VERIFY
  VERIFY --> APPROVE[사람 최종 승인]

비유: 의약품 처방과 같습니다. 일반의약품(AI OK)은 약사 안내로 충분하지만, 전문의약품(HUMAN)은 의사 진료가 필요합니다. 잘못된 처방의 회수 비용 차이 때문입니다.

---

3. Prompt 표준

## Goal

무엇을 해결해야 하는가

## Context

- 관련 파일:
- 현재 동작:
- 원하는 동작:
- 제약:

## Quality Bar

- 타입:
- 테스트:
- 성능:
- 접근성:
- 보안:

## Verification

실행해야 할 명령과 기대 결과

## Output

원하는 산출물 형식

AI에게 "고쳐줘"라고만 요청하면 검증 기준이 빠집니다. 목표, 제약, 실패 조건, 검증 명령을 함께 전달합니다.

---

4. 컨텍스트 관리

왜 중요한가: 컨텍스트는 AI의 음식 재료입니다. 신선하지 않거나 잘못된 재료를 넣으면 결과물 맛도 무너집니다.

컨텍스트가 클수록 정확해지는 것이 아닙니다. 관련 없는 파일은 비용과 오류 가능성을 모두 늘립니다.

4.1 컨텍스트 단계별 사용 패턴

flowchart LR
  subgraph 미니["1. 미니 컨텍스트<br/>한 함수 수정"]
    M1[해당 파일 1개]
    M2[관련 테스트 1개]
    M3[목표 1문장]
  end
  subgraph 페어["2. 페어 컨텍스트<br/>모듈 단위 작업"]
    P1[모듈 인터페이스]
    P2[의존성 계약]
    P3[테스트 fixture]
  end
  subgraph 큰컨["3. 큰 컨텍스트<br/>아키텍처 설계"]
    L1[ADR/RFC 링크]
    L2[도메인 모델]
    L3[제약/SLA]
  end
  미니 -->|작업 확대| 페어
  페어 -->|구조 변경| 큰컨
  큰컨 -.실행은 미니로 쪼개기.-> 미니

비유: 요리사의 작업대와 같습니다. 한 요리당 필요한 재료만 올려야 동선이 짧아집니다. 모든 식자재를 올리면 오히려 잘못된 재료를 집을 위험이 큽니다.

4.2 검증 책임 매트릭스

flowchart TB
  subgraph AI역할["AI 책임"]
    AI1[초안 생성]
    AI2[테스트 후보 제안]
    AI3[근거 링크 표시]
  end
  subgraph Author역할["작성자 책임"]
    AU1[입력 데이터 등급 확인]
    AU2[로컬 검증 실행]
    AU3[AI output 1차 판단]
  end
  subgraph Reviewer역할["Reviewer 책임"]
    RV1[비즈니스 의도 확인]
    RV2[보안/접근성 게이트]
    RV3[최종 approval]
  end
  subgraph Owner역할["Code Owner 책임"]
    OW1[Merge 결정]
    OW2[배포 후 모니터링]
    OW3[회수/rollback 책임]
  end
  AI역할 --> Author역할
  Author역할 --> Reviewer역할
  Reviewer역할 --> Owner역할

---

5. AI 산출물 검증 게이트

일상 비유: 공장 라인의 QC와 같습니다. AI는 1차 조립, 사람과 자동 검사기는 출하 전 마지막 검수입니다. QC를 거치지 않은 제품은 같은 라인에서 나왔다고 해도 출하 대상이 아닙니다.

AI가 만든 코드는 "초안"입니다. merge 가능한 코드는 검증을 통과한 코드입니다.

5.1 안전 체크리스트 흐름

이 그림은 AI 산출물을 PR에 반영하기 전에 거쳐야 하는 안전 체크리스트의 순서를 보여줍니다. 각 단계는 앞 단계의 통과를 전제로 합니다.

flowchart TD
  S0([AI 산출물 수신]) --> S1{입력 데이터 등급\nsecret/PII?}
  S1 -->|발견| BL[전송 차단 + 입력 재작성]
  BL --> S0
  S1 -->|안전| S2{타입/린트 통과?}
  S2 -->|아니오| F2[수정 또는 재요청]
  F2 --> S0
  S2 -->|예| S3{관련 테스트 통과?}
  S3 -->|아니오| F3[테스트 보강 + 재요청]
  F3 --> S0
  S3 -->|예| S4{보안/접근성 변경 동반?}
  S4 -->|예| RV[보안/접근성 리뷰어 지정]
  S4 -->|아니오| S5
  RV --> S5{사람 reviewer 승인?}
  S5 -->|반려| RC[change request + Draft]
  RC --> S0
  S5 -->|승인| MERGE[Merge + audit note]
  MERGE --> MON[배포 모니터링]

5.2 AI 협업 검증 시퀀스

이 그림은 작성자, AI, CI, 리뷰어, 코드 오너 사이에서 메시지가 어떻게 오가며 한 PR이 머지되는지를 시간 순서로 보여줍니다.

sequenceDiagram
  participant Dev as 작성자
  participant AI as AI 도구
  participant CI as CI Gates
  participant Rev as Reviewer
  participant Own as Code Owner
  Dev->>AI: prompt + 컨텍스트(redacted)
  AI-->>Dev: 초안 + 근거 링크
  Dev->>Dev: 로컬 검증(type/test)
  Dev->>CI: PR 오픈
  CI-->>Dev: 자동 게이트 결과
  alt CI 실패
    CI-->>Dev: 실패 로그
    Dev->>AI: 수정 prompt 또는 수동 보정
  else CI 통과
    Dev->>Rev: 리뷰 요청 + AI 사용 표기
    Rev-->>Dev: 의도/보안/접근성 코멘트
    Dev->>Rev: 반영
    Rev->>Own: approve
    Own->>Own: merge 결정 + 모니터링 owner 지정
  end

---

6. AI 코드리뷰 흐름

왜 중요한가: 같은 AI를 쓰더라도 흐름의 순서가 다르면 검증 깊이가 완전히 달라집니다. "AI 먼저 → 사람 마지막"이라는 순서를 외부화해야 일관됩니다.

developer draft
  -> AI self-check
  -> local verification
  -> PR
  -> automated gates
  -> human review
  -> deploy monitoring

AI 리뷰는 사람 리뷰 전에 noise를 줄이는 데 유용합니다. 하지만 최종 승인과 책임은 사람에게 있습니다.

6.1 AI 산출물 상태 다이어그램

stateDiagram-v2
  [*] --> Draft: AI 초안 생성
  Draft --> SelfCheck: 작성자 1차 검토
  SelfCheck --> Reject: 의도 불일치
  SelfCheck --> LocalVerify: 의도 일치
  Reject --> [*]: AI 재요청 또는 폐기
  LocalVerify --> Failed: 테스트/타입 실패
  Failed --> Draft: 수정
  LocalVerify --> PROpen: 검증 통과
  PROpen --> CIGates: 자동 게이트
  CIGates --> CIFailed: 실패
  CIFailed --> Draft
  CIGates --> HumanReview: 통과
  HumanReview --> ChangesRequested: 사람 blocking
  ChangesRequested --> Draft
  HumanReview --> Approved: 사람 승인
  Approved --> Merged
  Merged --> Monitored
  Monitored --> [*]: 안정
  Monitored --> Reverted: 회귀
  Reverted --> Draft

---

7. 보안과 데이터 보호

왜 중요한가: 한 번 외부 모델에 전송된 데이터는 회수하기 어렵습니다. "보낸 후의 정책"보다 "보내기 전의 차단"이 항상 저렴합니다.

AI 도구 도입 전 데이터 보존, 학습 사용 여부, 접근 권한, 감사 로그, 삭제 요청 절차를 확인합니다.

7.1 입력 데이터 게이트 흐름

flowchart LR
  INPUT[입력 후보] --> SCAN[secret/PII 스캔]
  SCAN -->|발견| BLOCK[전송 차단<br/>경고]
  SCAN -->|미발견| CLASS{데이터 등급}
  CLASS -->|공개| SEND[AI로 전송]
  CLASS -->|내부| MASK[마스킹/익명화]
  MASK --> SEND
  CLASS -->|기밀| BLOCK
  SEND --> AUDIT[감사 로그 기록]
  BLOCK --> REWRITE[입력 재작성]
  REWRITE --> SCAN

---

8. 비용 운영

AI 비용은 개인 생산성 비용이 아니라 엔지니어링 운영 비용입니다. 팀 단위 예산과 사용량 리포트를 둡니다.

---

9. 체크리스트

• [ ] AI 사용 정책에 허용/금지 데이터가 명시되어 있는가
• [ ] prompt에 목표, 제약, 검증 명령이 포함되는가
• [ ] AI 산출물이 type/test/build/review 중 하나 이상으로 검증되는가
• [ ] AI가 만든 PR에 사람이 책임 reviewer로 기록되는가
• [ ] secret/고객 데이터/내부 URL이 AI 입력에 들어가지 않는가
• [ ] 자동화 호출량과 비용이 추적되는가
• [ ] 중요한 AI 기반 결정이 RFC/ADR/PR에 기록되는가

---

10. 제외한 벤더 종속 항목

공통 개발 가이드에는 특정 AI 코딩 도구, 특정 모델명, 특정 가격표, 특정 IDE 확장, 특정 MCP 서버 목록, 특정 SaaS 자동화 절차를 표준으로 포함하지 않습니다. 이 문서에는 어떤 AI 도구를 쓰더라도 유지되어야 하는 사용 정책, 보안, 검증, 책임, 비용 기준만 남깁니다.

---

실무 적용 가이드

언제 이 문서를 펼칠까

• AI에게 어떤 작업을 맡겨도 되는지 팀 기준이 없을 때
• AI가 만든 코드가 오래된 API나 보안 위험을 포함할 때
• 컨텍스트에 민감정보가 섞일 가능성이 있을 때

적용 순서

1. 작업을 초안 작성, 리팩터 후보, 테스트 보강, 위험 분석으로 분류한다.
2. 민감정보, 고객 데이터, secret, 내부 URL은 입력에서 제거한다.
3. AI 출력은 공식 문서, 테스트, 타입 검사, 사람 리뷰로 검증한다.
4. AI가 변경한 파일과 사람이 판단한 결정을 PR에 분리해 적는다.
5. 반복 오류는 prompt가 아니라 체크리스트와 자동화로 보완한다.

함께 두는 파일

• AI 작업 기록은 PR/issue에 남긴다.
• AI가 만든 테스트와 fixture는 기능 폴더에 둔다.
• 공통 AI 정책은 이 문서에 두고 도메인별 예외는 각 가이드에 둔다.

흔한 실수

• AI가 만든 코드를 검증 없이 merge한다.
• 최신 API 여부를 공식 문서로 확인하지 않는다.
• 민감 로그나 고객 데이터를 그대로 입력한다.
• 프롬프트만 고치고 코드 구조 문제를 방치한다.

PR 완료 기준

• [ ] AI 입력 데이터 등급이 안전하다.
• [ ] 검증 명령 결과가 있다.
• [ ] 사람 reviewer가 위험 항목을 승인했다.
• [ ] AI output과 최종 결정이 구분되어 있다.

추천 항목 실행 우선순위 매핑

• P1(7일 내) — AI 사용 범위, 컨텍스트, 검증 책임 중 하나를 작은 변경 1건에 적용하고 증거(task boundary)를 남긴다.
• P2(30일 내) — AI 협업 기준을 팀 템플릿, 체크리스트, CI 중 한 곳에 고정한다.
• P3(90일 내) — AI 제안 반려율, 재작업률, 검증 누락 수 추이를 보고 기준을 유지할지 조정할지 결정한다.
• 완료 기준 — AI 워크플로우 오너가 증거와 철회 조건을 확인했다는 기록을 남긴다.

추천 항목 실행 체크리스트

• [ ] 1단계(7일) : AI 사용 범위, 컨텍스트, 검증 책임 적용 대상을 1개로 좁힌다.
• [ ] 2단계(30일) : 증거(task boundary, prompt/output 기록, 검증 명령, 사람 승인)를 PR, ADR, 회고 중 한 곳에 연결한다.
• [ ] 3단계(60일) : AI 제안 반려율, 재작업률, 검증 누락 수가 기준 안에 들어왔는지 확인한다.
• [ ] 문제 대응 : 미달성 사유와 다음 조치, 중단 여부를 같은 기록에 남긴다.

추천 항목 실행 운영 규칙

• 실행 게이트 : AI가 맡은 일과 사람이 확인한 일을 PR에 분리해 남긴다.
• 승인 체계 : AI 워크플로우 오너가 영향 범위와 rollback 담당자를 적용 전에 확인한다.
• 재개 조건 : 검증 가능한 산출물과 사람 승인 근거가 있으면 다음 작업에 적용한다.
• 정지 조건 : 민감정보나 미검증 코드를 AI 출력 그대로 반영하면 중단한다.
• 리스크 점수 : 자동 생성 비율, 민감 데이터, 검증 난이도로 산정한다.
• 리더 승인자 : 기술 리드가 최종 승인 책임을 맡는다.
• 승인 역할 : AI 협업 작성자, 검토자, 운영 확인자를 분리해 기록한다.
• 재평가 주기 : 월 1회 AI 사용 사례와 실패 사례를 정리한다.