먼저 답부터 말씀드리면: AI 코딩 에이전트가 만든 PR에서 기능 테스트가 통과했더라도 package manifest·lockfile·GitHub Actions action 참조가 함께 바뀌었다면, 기능 확인과는 별도로 새 실행 경로를 받아들일지 판단해야 합니다.
이 글은 그런 순간에 병합 / 추가 증거 요청 / 보류 중 하나를 고를 수 있도록, 여섯 칸의 Dependency Change 카드를 제안합니다.
핵심 요약
- 테스트 통과는 기능 경로의 증거입니다. 새 패키지·간접 의존성·workflow action 참조를 수용할 근거까지 자동으로 만들어 주지는 않습니다.
- manifest, lockfile, workflow의
uses참조, 설치 스크립트는 한 덩어리로 넘기지 말고 직접 변경과 간접 변경으로 나누어 기록하세요. - action 참조는 조직의 기준에 맞는 lockfile 또는 full-length commit SHA처럼 변하지 않는 실행 참조인지 확인하는 편이 좋습니다.
- 알려진 취약점·라이선스·새 간접 의존성·설치 시 실행되는 동작·권한 또는 네트워크 요구를 설명하기 어렵다면, 테스트가 초록색이어도 추가 증거 요청이 더 적절할 수 있습니다.
- 이 카드는 범용 PR 인수, workflow 권한 검토, 배포 artifact 출처 검증을 대체하지 않습니다. 의존성 변경이 섞였을 때만 꺼내는 좁은 보조 장치입니다.
목차
- 왜 의존성 변경을 따로 봐야 할까요?
- 무엇을 dependency change로 볼까요?
- 병합 전 6칸 Dependency Change 카드
- 병합·추가 확인·보류를 가르는 결정표
- 좁은 가상 PR로 카드 채워 보기
- 다른 검토 절차와 연결하는 순서
- 시작 전 체크리스트
- 자주 묻는 질문
- 참고 자료
왜 의존성 변경을 따로 봐야 할까요?
AI 코딩 에이전트는 기능 요청을 처리하는 과정에서 패키지 하나를 추가하거나 버전을 올리고, lockfile을 다시 만들고, CI workflow의 action 참조까지 조정할 수 있습니다. 리뷰 화면에서는 모두 한 PR 안에 보이지만, 팀이 내리는 결정은 하나가 아닙니다.
첫 번째 결정은 “요구한 기능이 동작하는가”입니다. 두 번째 결정은 “이 저장소가 앞으로 설치하거나 실행하게 될 새 경로를 받아들여도 되는가”입니다. 전자는 테스트·빌드·동작 확인으로 답할 수 있습니다. 후자는 왜 이 변경이 필요한지, 무엇이 직접 바뀌었는지, 무엇이 따라 들어왔는지, 되돌릴 수 있는지까지 살펴야 답할 수 있습니다.
GitHub는 workflow dependency lockfile이 action을 검증된 commit에 고정하고, lockfile 생성 과정에서 workflow의 참조도 바뀔 수 있으므로 전체 diff를 검토해야 한다고 안내합니다. lockfile을 사용하지 못하는 환경에서는 full-length commit SHA 고정을 대안으로 설명합니다. 이는 한 가지 설정으로 모든 위험이 사라진다는 뜻이 아니라, 실행 참조가 무엇인지 분명히 확인하자는 실무 기준입니다.
무엇을 dependency change로 볼까요?
의존성 변경은 package.json 한 줄만 뜻하지 않습니다. 아래 다섯 표면을 분리하면, 에이전트가 만든 작은 diff도 훨씬 읽기 쉬워집니다.
- manifest: 직접 추가·삭제·버전 변경이 필요한 이유입니다.
- lockfile: 직접 변경을 따라온 정확한 해석 결과와 간접 의존성 변화입니다.
- workflow action 참조: CI에서 어떤 외부 코드를 어떤 고정점으로 실행하는지입니다.
- install 또는 postinstall 동작: 설치 시점에 실행되는 명령, 생성 파일, 네트워크 접근이 있는지입니다.
- 생성 파일과 설정: 번들·코드 생성 결과가 실제로 의도한 범위를 넘지 않는지입니다.
GitHub의 dependency review는 manifest 또는 lockfile 변경 PR에서 간접 의존성 변화, 알려진 취약점, 라이선스 같은 검토 신호를 볼 수 있다고 설명합니다. 다만 어떤 도구의 결과도 완전한 판정문으로 취급하지 말고, 팀이 설명하고 기록해야 할 질문을 줄여 주는 입력으로 사용하는 편이 좋습니다.
병합 전 6칸 Dependency Change 카드
아래 카드는 리뷰어가 긴 보안 보고서를 새로 쓰기 위한 양식이 아닙니다. “이 변경을 지금 받아들일 근거가 있는가?”를 짧고 재현 가능하게 남기기 위한 카드입니다.
| 카드 칸 | 확인 질문 | 최소 증거 | 보류 신호 |
|---|---|---|---|
| 1. 업무 의도 | 기능 요청과 직접 필요한 패키지·action 변경이 연결되나요? | 요청 한 문장과 변경 파일의 연결 | “에이전트가 알아서 추가함” 외 설명이 없음 |
| 2. 변경 표면 | 직접 변경과 lockfile·생성 파일의 간접 변경을 나눴나요? | manifest, lockfile, workflow, 설치 동작 목록 | 대량 lockfile diff를 한 줄 요약으로 덮음 |
| 3. 고정 참조 | 실행되는 action·외부 참조가 팀 기준에 맞게 고정됐나요? | lockfile 또는 full-length commit SHA 확인 | 이동 가능한 tag·branch만 남아 있음 |
| 4. 위험 신호 | 간접 의존성·취약점·라이선스·설치 동작을 설명할 수 있나요? | 검토 결과와 예외 사유 | 새 권한·네트워크·postinstall 이유가 불명확함 |
| 5. 최소 검증·되돌림 | 설치·빌드·테스트와 이전 버전 복귀 경로가 있나요? | 실행 결과, 이전 잠금 상태 또는 revert 계획 | 실행 기록 또는 rollback 근거가 없음 |
| 6. 사람 수용 | 누가 어떤 위험을 알고 병합했는지 남겼나요? | 담당 reviewer와 결정 기록 | 소유자 없이 자동 병합만 제안됨 |
병합·추가 확인·보류를 가르는 결정표
카드를 채웠다고 해서 항상 같은 결론이 나오는 것은 아닙니다. 변경의 설명 가능성과 검증 가능성에 따라 다음처럼 갈라 보세요.
| 결정 | 이런 경우 | 남겨야 할 기록 |
|---|---|---|
| 병합 | 기능 요구와 직접 연결되고, 직접·간접 변경이 설명되며, 고정 참조·최소 검증·되돌림·reviewer가 모두 있음 | 카드 요약, 테스트 결과, 책임자 |
| 추가 증거 요청 | 변경 목적은 납득되지만 lockfile 규모, 간접 변경, 라이선스·취약점 신호, 설치 동작 중 일부가 불명확함 | 무엇을 확인하면 다시 판단할지 |
| 보류 | 이동 가능한 실행 참조, 설명 없는 대량 변경, 새 privileged trigger, 권한 경계 변화, 되돌림 불가 상태가 섞임 | 보류 이유와 별도 검토로 넘길 대상 |
중요한 구분: 새 privileged trigger나 신뢰 경계 변화가 함께 생겼다면, 이 카드만으로 병합을 판단하지 마세요. 그때는 workflow의 권한·입력·외부효과를 별도로 검토해야 합니다.
좁은 가상 PR로 카드 채워 보기
가상의 PR이 “CSV 내보내기 기능에 날짜 파서 패키지 하나를 추가해 달라”는 요청을 처리했다고 가정해 보겠습니다. 에이전트는 manifest에 패키지를 추가했고, lockfile이 변했으며, CI의 action 참조도 업데이트했습니다.
1) 업무 의도와 직접 변경
“특정 형식의 날짜를 안정적으로 해석해야 한다”가 요청입니다. manifest의 패키지 추가가 이 한 문장과 연결된다면 직접 변경의 이유는 기록할 수 있습니다. 반대로 기능 코드와 관계없는 formatter, 분석 도구, 배포 도구가 같이 추가됐다면 이유를 분리해 물어봐야 합니다.
2) lockfile에서 확인할 부분
lockfile에는 직접 패키지 하나보다 더 많은 변화가 나타날 수 있습니다. 여기서 목표는 모든 하위 패키지를 암기하는 것이 아니라, 새로 추가된 묶음의 범위와 설명 가능한 관계를 잡는 것입니다. 이전 잠금 상태로 돌아갈 방법이 있는지도 함께 남깁니다.
3) workflow 참조는 별도 줄로 기록
CI action 참조가 바뀌었다면, 그 변경은 날짜 파서 추가와 같은 이유로 설명되지 않을 수 있습니다. GitHub는 workflow dependency lockfile과 full-length commit SHA 고정 같은 방식을 안내합니다. 팀의 기존 기준과 맞는지, 왜 이 참조가 지금 바뀌었는지 확인한 뒤 별도의 카드 줄로 기록하세요.
4) 결론을 미루는 것이 실패는 아닙니다
패키지 자체의 목적은 분명하지만 action 참조가 이동 가능한 tag를 가리키고, 설치 시 실행되는 동작의 이유가 비어 있다면 결론은 “추가 증거 요청”이 될 수 있습니다. 이것은 에이전트의 작업을 버리는 일이 아니라, 다음 리뷰에서 무엇을 보완해야 하는지 명확히 하는 운영입니다.
다른 검토 절차와 연결하는 순서
Dependency Change 카드는 좁은 질문에 답합니다. 그래서 다른 절차와 이어 붙일 때 더 유용합니다.
- PR 전체의 완료 조건과 인수 근거는 AI 코딩 에이전트 PR을 범용 인수 패킷으로 검토하는 방법에서 먼저 정리합니다.
- manifest·lockfile·action 참조가 바뀌면, 이 글의 여섯 칸 카드를 추가합니다.
- 새 workflow가 권한·비밀값·외부 실행 경계를 바꾼다면 workflow 실행 경계 검토로 전환합니다.
- 배포 직전 결과물이 승인된 source와 workflow에서 나왔는지는 artifact provenance와 digest 확인 절차로 별도 검증합니다.
- AI가 보안 경고를 고친 PR이라면 경고 종료와 병합 수용을 분리하는 방법도 함께 확인합니다.
npm provenance는 패키지의 build/publish 출처를 확인하는 보조 근거가 될 수 있습니다. 다만 provenance가 없다는 사실만으로 악성이라고 단정하거나, 반대로 provenance가 있다는 이유만으로 검토를 생략하지는 않는 편이 좋습니다.
병합 버튼을 누르기 전 체크리스트
- 변경 요청 한 문장과 직접 필요한 패키지·action 변경을 연결했나요?
- manifest, lockfile, workflow
uses, 설치 스크립트, 생성 파일을 나누어 적었나요? - action 참조가 팀의 lockfile 또는 full-length commit SHA 기준에 맞나요?
- 알려진 취약점·라이선스·새 간접 의존성·postinstall·권한·네트워크 요구를 설명할 수 있나요?
- install/build/test의 최소 기록과 이전 버전으로 돌아갈 방법을 남겼나요?
- 새 privileged trigger 또는 신뢰 경계 변화가 있다면 별도 실행 경계 검토로 넘겼나요?
- 마지막으로, 사람이 병합 결정을 수용했다는 기록이 있나요?
자주 묻는 질문
lockfile이 없으면 무조건 병합하면 안 되나요?
그렇지는 않습니다. lockfile이 없다는 한 가지 사실만으로 결론을 내리기보다, 사용하는 생태계와 팀 기준에서 실행 참조를 어떻게 고정하고 검토할지 확인하세요. GitHub Actions의 경우 GitHub는 lockfile을 사용할 수 없을 때 full-length commit SHA 고정을 대안으로 안내합니다.
간접 의존성이 많으면 AI 코딩 에이전트를 쓰기 어려운가요?
아닙니다. 핵심은 간접 의존성이 있다는 사실보다, 직접 요청과의 관계·검토 가능한 신호·되돌림 경로를 남기는 것입니다. 작은 변경부터 같은 카드를 반복해 쓰면 팀의 기준도 더 빨리 안정됩니다.
dependency review 결과가 깨끗하면 바로 병합해도 되나요?
그 결과는 중요한 입력이지만, 변경 목적·실행 참조·설치 동작·복구 계획·책임자까지 대신해 주지는 않습니다. 결과를 카드의 위험 신호 칸에 넣고, 나머지 칸도 함께 채우는 편이 좋습니다.
누가 sign-off 해야 하나요?
패키지나 workflow가 실제로 영향을 주는 코드 경로와 운영 책임을 이해하는 사람이 맡는 것이 좋습니다. 역할 이름보다 중요한 것은, 문제가 생겼을 때 왜 받아들였는지와 무엇으로 되돌릴지 설명할 수 있는 소유자가 기록에 남는 일입니다.
이 카드가 artifact provenance 검증을 대신하나요?
대신하지 않습니다. 이 카드는 병합 전 dependency diff를 수용할지 결정하는 절차이고, provenance 검증은 배포할 결과물이 어떤 source와 build 흐름에서 나왔는지 확인하는 절차입니다. 두 질문을 분리하면 누락이 줄어듭니다.
참고 자료
- GitHub Docs — Locking action dependencies in a repository’s workflows: workflow action을 검증된 commit에 고정하는 lockfile과, lockfile 변경을 포함한 전체 diff 검토의 배경을 확인할 수 있습니다.
- GitHub Docs — Secure use reference: workflow dependency lockfile, full-length commit SHA 고정, 신뢰 경계와 관련한 공식 권고를 확인할 수 있습니다.
- GitHub Docs — Dependency review: manifest·lockfile 변경에서 간접 의존성, 알려진 취약점, 라이선스 등 검토 신호를 살펴보는 기능 범위를 확인할 수 있습니다.
- npm Docs — Generating provenance statements: 패키지 build/publish 출처를 확인하는 provenance statement의 개념과 검증 흐름을 확인할 수 있습니다.
마무리: AI 코딩 에이전트가 만든 PR을 빠르게 병합하는 팀일수록, 테스트 성공과 dependency change 수용을 같은 체크 표시로 합치지 않는 편이 좋습니다. 여섯 칸만 남겨도 다음 리뷰와 다음 복구가 훨씬 명확해집니다.
이 글이 마음에 드세요?
FLOWIT on YouTube
영상으로도 FLOWIT을 이어서 보세요
AI 자동화, Claude Code, n8n, 데이터 분석 흐름을 블로그와 영상으로 함께 정리하고 있습니다.
Related Notes
같이 읽으면 좋은 FLOWIT 글
AI 데이터 에이전트, 잘 쓰는 사람이 늘면 바로 확대해도 될까? 접근 범위를 여는 5지표 게이트AI 데이터 에이전트 파일럿의 사용자가 늘었을 때 사용자·데이터 범위를 확대할지 판단하는 5지표 운영표와 실패 조건을 정리합니다.
AI 코딩 에이전트가 만들기 전에 합의해야 할 것: 완료 정의를 고정하는 6칸 스프린트 계약AI 코딩 에이전트에게 기능을 맡기기 전, 범위·사용자 행동·실행 증거·실패 기준·권한·재작업 책임을 합의하는 6칸 스프린트 계약을 정리합니다.
AI 에이전트가 작업 흐름을 스스로 짜게 해도 될까? 동적 워크플로의 고정 경계 5칸AI 에이전트가 하위 작업과 순서를 스스로 만들 때, 목적·입력·권한·비용·완료 증거를 어떻게 고정할지 5칸 운영 경계표와 보류 기준으로 정리합니다.