AI 에이전트에게 CI/CD 파이프라인 수정을 맡길 때 주의할 점

최근 프론트엔드 프로젝트의 CI/CD 파이프라인 수정을 AI 코딩 에이전트(AI Coding Agent)와 함께 진행할 기회가 있었습니다.

대상은 GitHub Actions 상에서 동작하는 일반적인 PR 체크입니다.

구체적으로는 포맷 체크(Format Check), 테스트, 커버리지 리포트(Coverage Report)와 같은 흔히 있는 품질 체크 주변의 수정이었습니다.

AI 에이전트는 로그 확인, 설정 파일 수정, 로컬에서의 재현 확인, 커밋 생성까지 상당히 매끄럽게 진행해 줍니다.

한편, CI/CD 주변은 개발 플로우(Development Flow) 전체에 영향을 미치기 때문에, 완전히 맡겨두기보다는 인간 측에서 확인해야 할 포인트도 많다고 느꼈습니다.

이 기사에서는 실제로 작업하며 유용했던 확인 관점을 정리합니다.

CI 로그를 보면 여러 단계(step)가 연속해서 실패하는 것처럼 보일 때가 있습니다.

하지만 후속 에러가 반드시 근본 원인인 것은 아닙니다.

예를 들어, 커버리지 리포트를 게시하는 step이 실패했더라도, 진짜 원인은 그 전 단계의 테스트나 커버리지 생성이 실행되지 않은 것일 수도 있습니다.

살펴봐야 할 포인트는 다음과 같습니다.

가장 먼저 실패한 step은 무엇인가
후속 step이 always()와 같은 조건으로 실행되고 있지는 않은가
후속 step이 참조하고 있는 결과물이 정말로 생성되었는가
에러가 '원인'인가 아니면 '원인의 결과'인가

AI 에이전트에게 로그를 읽게 할 때도 단순히 "이 에러를 고쳐줘"라고 하기보다, "가장 먼저 실패하고 있는 step과 후속 2차 에러를 구분해서 확인해줘"라고 지시하는 편이 안전합니다.

CI/CD 수정에서는 설정 파일만 바라보고 판단하는 것보다, CI와 동일한 명령어를 로컬에서 실행하는 것이 더 빠를 때가 있습니다.

예를 들어 다음과 같은 확인입니다.

pnpm exec prettier --check .
pnpm exec vitest run --coverage.enabled=true --coverage.reporter=json-summary
--coverage.reporter=json

이 확인을 통해 다음과 같은 것들을 알 수 있습니다.

포맷 체크가 로컬에서도 재현되는가
커버리지 출력 디렉토리가 자동 생성되는가
리포트용 JSON 파일이 실제로 생성되는가
CI 고유의 문제인가, 설정 자체의 문제인가

AI 에이전트는 명령어 실행과 결과 정리에 능숙하므로, 이 부분은 상당히 궁합이 좋은 작업이었습니다.

CI에서 실행하는 명령어와 로컬에서 사용하는 패키지 스크립트(package script)가 미묘하게 다르면 원인 조사가 어려워집니다.

예를 들어, workflow에서는 프로젝트 전체를 대상으로 하고 있는데, package script에서는 일부 확장자만을 대상으로 하는 경우입니다.

{
"scripts": {
"fmt": "prettier --write .",
...

어떤 범위를 체크 대상으로 할지는 팀의 방침에 따릅니다.

다만, CI에서 사용하는 명령어와 개발자가 로컬에서 사용하는 명령어는 가급적 일치시켜 두는 것이 좋습니다.

AI 에이전트에게 수정을 맡길 때도 workflow만 보는 것이 아니라, package.json 측의 script와의 정합성까지 확인하게 하면 놓치는 부분을 줄일 수 있습니다.

prettier --check .는 이해하기 쉬운 반면, 대상 범위가 넓어집니다.

JavaScript나 TypeScript뿐만 아니라 Markdown, YAML, JSON 등도 대상이 됩니다.

이는 규약(Convention)으로서 다루기 쉽지만, 생성물이나 의존 패키지(Dependency Package)를 포함하지 않도록 주의해야 합니다.

예를 들어 다음과 같은 파일이나 디렉토리는 제외 후보가 됩니다.

node_modules/
dist/
build/
...

여기서 주의할 점은 .gitignore와 .prettierignore는 별개라는 점입니다.

Git 관리 대상이 아니라고 해서 반드시 Prettier의 대상에서 제외되는 것은 아닙니다.

prettier --check .를 채택한다면 .prettierignore도 명시적으로 정비하는 편이 안전합니다.

커버리지 리포트용 action은 대부분 사전에 생성된 리포트 파일을 읽어 들입니다.

즉, 전 단계의 테스트나 커버리지 생성이 실패한 경우 리포트 파일이 존재하지 않습니다.

그 상태에서 리포트 게시 step만 동작하면, 근본 원인과는 다른 에러가 표시됩니다.

이러한 구성에서는 다음 사항들을 확인해야 합니다.

커버리지 생성 (Coverage generation) step이 정말로 성공했는가
리포트 (Report) action이 읽는 파일명과 출력 파일명이 일치하는가
앞 단계가 실패했을 경우에도 리포트 step을 실행할 필요가 있는가
always()와 같은 조건이 2차 에러를 늘리고 있지는 않은가

always()는 편리하지만, 결과물을 읽는 step에 무조건적으로 사용하면 오히려 로그를 파악하기 어렵게 만들 수 있습니다.

CI/CD 수정은 변경 자체는 작더라도 브랜치 생성이나 PR(Pull Request) 생성까지 포함될 수 있습니다.

AI 에이전트에게 그 정도까지 맡기는 경우라도, 다음 사항들은 인간 측에서 확인하는 것이 좋습니다.

git remote -v

git status --short --branch

git diff --cached --stat

git show --stat --oneline HEAD

확인하고 싶은 내용은 주로 다음과 같습니다.

작업 대상 리포지토리 (Repository)가 올바른가
의도하지 않은 미커밋 (Uncommitted) 차분이 섞여 있지 않은가
커밋에 포함할 파일이 한정되어 있는가
PR의 base branch가 올바른가
fork나 upstream의 방향이 틀리지 않았는가

특히 여러 개의 remote나 fork를 다루는 환경에서는 PR의 방향을 반드시 확인해야 합니다.

GitHub CLI를 사용하는 경우, 리포지토리나 base branch를 명시하면 사고를 줄일 수 있습니다.

gh pr create \
  --repo / \
  --base \
  --head

생성 후에도 PR의 방향을 확인해 두면 안심할 수 있습니다.

gh pr view --json baseRefName,headRefName,isCrossRepository

이번과 같은 CI/CD 수정에서는 AI 에이전트에게 맡기기 쉬운 작업과 인간이 확인해야 할 작업이 나뉩니다.

AI에게 맡기기 쉬운 작업:

CI 로그 요약
관련 설정 파일 탐색
로컬에서의 재현 명령 실행
작은 설정 변경
차분 (Diff) 정리
PR 본문 초안 작성

인간이 확인해야 할 작업:

팀 규약과의 정합성
CI에서 정말로 확인해야 할 대상 범위
ignore 해도 되는 생성물에 대한 판단
PR의 방향
push나 PR 생성 타이밍
다른 미커밋 작업과의 혼입 여부

AI 에이전트는 작업을 빠르게 진행해 주지만, CI/CD 방침이나 리포지토리 운영에 대한 판단은 아직 인간이 책임지고 확인하는 것이 좋다고 느꼈습니다.

AI 에이전트에게 CI/CD 파이프라인 수정을 맡기면 조사, 수정, 검증, PR 생성까지의 흐름을 상당히 효율화할 수 있습니다.

반면, CI/CD는 개발 팀 전체에 영향을 미치는 부분입니다.

따라서 로그를 읽는 법, 결과물의 유무, 체크 대상 범위, ignore 설정, PR의 방향 등은 인간 측에서 명시적으로 확인해야 합니다.

특히 의식해야 할 점은 다음과 같습니다.

CI 로그에서는 주원인과 2차 에러를 구분한다
CI와 동일한 명령을 로컬에서 재현한다
workflow와 package script 간의 불일치를 없앤다
prettier --check .를 사용한다면 .prettierignore를 정비한다
AI에게 Git 조작을 맡기는 경우에도 push 대상과 PR 대상은 반드시 확인한다

AI 에이전트는 CI/CD 수정의 강력한 보조 도구입니다.

단, 마지막에 무엇을 정답으로 삼을지를 결정하는 것은 역시 개발자 측의 판단입니다.

AI 에이전트에게 CI/CD 파이프라인 수정을 맡길 때 주의할 점

요약

핵심 포인트

댓글