V0.1은 어디에?는 마지막 및 후속 기사에서 설명됩니다

Claude Code나 Codex와 같은 코딩 에이전트(Coding Agent)를 사용하면 구현 속도는 크게 올라간다.

조사, 수정안 작성, 테스트 추가, 리팩터링 (Refactoring), 리뷰 관점 도출까지, 지금까지 인간이 순차적으로 진행하던 작업을 짧은 시간 안에 병렬로 진행할 수 있다.

한편, AI가 내놓는 코드가 항상 옳은 것은 아니다.

그럴듯한 구현, 그럴듯한 테스트, 그럴듯한 설명을 동일한 오해를 전제로 하여 한꺼번에 생성하기도 한다.

따라서 코딩 에이전트를 안전하게 사용할 때 중요한 것은,

AI가 올바른 코드를 쓸 수 있는가

만이 아니다.

보다 중요한 것은,

AI가 내놓은 변경 사항을 팀이 안전하게 받아들일 수 있는가

이다.

이 가이드에서는 코딩 에이전트를 실무에서 사용할 때의 기본 플로우 (Flow), 리뷰 관점, 권한 제어, 복잡한 변경 시 추가해야 할 확인 사항을 정리한다.

핵심이 되는 사고방식은 다음의 한 문장이다.

AI에게 증거를 구조화하게 하고, 기계로 검출할 수 있는 것은 자동화하며, 인간은 판단에 집중한다.

우선, 변경 종류에 따라 운용을 나눈다

모든 변경을 동일한 비중으로 다룰 필요는 없다.

여기서는 변경의

복잡성과 리스크를 별개의 축으로 다룬다.

복잡성은 여러 PR (Pull Request), 여러 서비스, 책임 경계, 변경 경로, 시간 경과 등을 아울러 기능 전체의 정합성을 유지해야 하는지를 나타낸다.

반면, 리스크는 변경을 잘못했을 때의 영향력이나 문제가 발생했을 때의 복구 난이도를 나타낸다.

따라서 단순하지만 고리스크인 변경이 있는가 하면, 복잡하지만 영향 범위를 한정하기 쉬운 변경도 있다.

문구 수정과 인가 로직 (Authorization Logic) 변경에 동일한 리뷰 공정을 요구하는 것은 비효율적이다.

일반적인 변경에서는 다음을 기본 플로우로 한다.

의뢰
↓
조사
...

한편, 다음과 같은 변경에서는 이 기본 플로우만으로는 부족하다.

• 여러 PR 또는 서비스에 걸쳐 있음
• 상태 전이, 권한, 책임 경계를 변경함
• DB, API, proto, 생성된 코드, 화면 간의 변환을 동반함
• 장기간 유지되는 브랜치 (Branch) 상에서 개발함
• 하나의 PR만으로는 기능 전체의 올바름을 확인할 수 없음

이러한 복잡한 변경에서는 다음과 같은 사항을 추가한다.

기본 플로우
+
불변 조건 (Invariant) 정리
...

나아가 인증·인가, 과금, 개인정보, DB migration, 운영 설정 등의 고리스크 변경에서는,

• 전문 리뷰
• 권한 제한
• dry-run / plan
• feature flag
• 단계적 릴리스 (Release)
• rollback 또는 보상 절차

까지 추가한다.

중요한 것은 AI 이용 여부만으로 공정을 결정하는 것이 아니라, 변경이 가진 리스크와 영향 면에 따라 검증 방법을 바꾸는 것이다.

1. 갑자기 구현하게 하지 마라. 먼저 조사만 시켜라

처음부터 코드를 쓰게 하지 마라.

먼저 관련 코드, 사양, 기존 테스트, 영향 범위를 조사하게 한다.

예를 들어 다음과 같이 의뢰한다.

아직 구현하지 마세요.
관련 코드, 사양, 기존 테스트, 영향 범위를 조사하여
다음 내용만 출력해 주세요.
...

이 단계에서 확인하는 것은 AI의 결론이 맞는지뿐만이 아니다.

살펴봐야 할 것은 다음과 같다.

• 관련 코드를 충분히 보고 있는가
• 기존 사양을 잘못 읽고 있지는 않은가
• 영향 범위를 과소평가하고 있지는 않은가
• 불명확한 점을 멋대로 보완하고 있지는 않은가
• 필요한 테스트를 인식하고 있는가

조사 결과가 부실하다면 그대로 구현으로 진행할 수 없다.

AI는 코드를 쓰기 전에도 사용할 수 있다.

오히려, 무엇을 이해하고 있고 무엇을 이해하지 못하고 있는지를 가시화하는 것에 큰 가치가 있다.

2. 구현 전에 계획을 내놓게 하라

조사 다음에는 구현 계획을 만들게 한다.

여기서도 아직 코드를 변경하게 하지 않는다.

아직 코드를 변경하지 마세요.
다음 형식으로 구현 계획을 내놓으세요.
- 변경 목적
...

특히 유효한 것은, 변경하지 않을 범위를 쓰게 하는 것이다.

AI는 구현 도중에,

"이 부분도 정리해 두는 것이 좋겠다"

"이 이름도 바꾸는 것이 자연스럽다"

"하는 김에 공통화할 수 있다"

라며 변경 범위를 넓히는 경우가 있다.

그 자체로 항상 나쁜 것은 아니다.

하지만 변경 목적과 관계없는 수정이 섞일수록,

• 리뷰 범위
• 테스트 범위
• rollback 범위
• 문제 발생 시 원인 특정

은 어려워진다.

따라서 처음에 경계를 만든다.

3. 복잡한 변경에서는 「무엇을 바꿀 것인가」뿐만 아니라 「무엇을 지킬 것인가」를 결정한다

여러 PR, 여러 서비스, 상태 전이, API 경계 등을 아우르는 경우에는 파일 단위의 계획만으로는 부족하다.

그런 경우에는 기능 전체에서 지켜야 할 **불변 조건 (Invariant)**도 정리한다.

예를 들어 다음과 같이 의뢰한다.

이 변경은 여러 처리나 레이어에 영향을 미칠 가능성이 있습니다.
아직 코드를 변경하지 말고, 통상적인 구현 계획에 더해 다음 내용을 출력해 주세요.
- 기능 전체에서 지켜야 할 불변 조건
...

예를 들어,

• 특정 조건에서는 중복 등록되지 않는다
• 권한이 없는 이용자는 업데이트할 수 없다
• 취소 후에도 유효한 관련 상태가 남지 않는다
• 동일한 조작을 재전송해도 동일한 결과로 수렴한다
• API를 통과해도 값의 의미가 상실되지 않는다

등이 불변 조건이 된다.

「어떤 파일을 변경할 것인가」는 구현 계획이다.

「변경 후에도 무엇이 성립되어 있어야 하는가」는 품질 조건이다.

두 가지는 나누어 생각하는 것이 좋다.

4. 차분은 작게 유지한다

AI는 짧은 시간 안에 대량의 코드를 작성할 수 있다.

그렇기 때문에 AI의 위험은 잘못된 코드를 작성하는 것뿐만이 아니다.

인간이 다 확인할 수 없는 양의 변경을 짧은 시간 안에 만들어낼 수 있다는 점도 리스크가 된다.

기본적으로는 다음과 같이 한다.

• 1 PR = 1 목적
• 무관한 리팩터링 (Refactoring)을 섞지 않는다
• 포맷 변경을 부주의하게 섞지 않는다
• 로직 변경과 무관한 정리를 분리한다
• 테스트와 변경 대상을 대응시킨다
• 의존 패키지를 마음대로 추가하게 하지 않는다
• 공개 API나 DB 구조의 변경을 「덤」으로 처리하지 않는다

여기서 말하는 「작은 PR」은 단순히 줄 수의 문제가 아니다.

예를 들어, 하나의 기능 추가를 위해,

• backend
• API
• generated client
• frontend

를 모두 변경해야 한다면, 그것들을 동일한 목적의 변경으로 취급하는 것 자체는 자연스럽다.

문제는 그 PR에,

• unrelated한 리팩터링 (Refactoring)
• 의존성 (Dependency) 업데이트
• 명명 정리
• 다른 기능의 수정

까지 섞이는 것이다.

기준은,

「하나의 목적으로서 리뷰할 수 있는가」

로 생각한다.

5. 단, PR을 작게 나눈다고 해서 안전해지는 것은 아니다

이 부분은 중요하다.

하나의 기능을 여러 PR로 나누면 개별 리뷰는 쉬워진다.

하지만,

개별 PR이 모두 올바른 것과 통합된 기능 전체가 올바른 것은 같지 않다.

예를 들어,

PR A ─┐
PR B ─┼─ 통합 브랜치 ─ main 반영 ─ 코드 생성 ─ UI
PR C ─┘

와 같은 변경에서는 각 PR이 단독으로 CI와 리뷰를 통과하더라도,

• main 측의 변경
• merge
• rebase
• conflict 해결
• 코드 생성
• 다른 레이어의 변경

에 의해 이전에 확인했던 전제가 깨질 수 있다.

또한, merge conflict가 발생하지 않았다는 것이 의미상의 충돌이 존재하지 않음을 보장하지는 않는다.

텍스트 상으로는 자동으로 통합할 수 있더라도, 다른 변경으로 인해 처리의 책임 범위나 전제 조건이 바뀌어 이전에 확인했던 불변 조건이 성립하지 않게 되는 경우가 있다.

따라서 여러 PR로 하나의 기능을 만들 경우에는 부모가 되는 Issue나 계획에 다음과 같은 내용을 남긴다.

• 각 PR의 역할
• 전제 관계
• 아직 대응하지 않은 범위
• 마지막에 기능 전체를 확인하는 방법

각 PR에서는 국소적인 올바름을 확인하고, 마지막에는 통합된 현재 상태를 확인한다.

6. AI가 작성한 코드를, 동일한 이해를 바탕으로 만든 테스트만으로 보증하지 않는다

AI에게 테스트도 작성하게 한다.

단, AI가 작성한 테스트라고 해서 자동으로 신뢰할 수 있는 것은 아니다.

AI가 사양을 오해하고 있는 경우,

잘못된 이해
↓
구현
...

라는 상태가 될 가능성이 있다.

코드, 테스트, 리뷰가 모두 일치하더라도 요구사항 그 자체와는 어긋나 있을 수 있다.

따라서 구현을 담당한 AI에게는,

• 구현 차분
• 예외 처리
• 경계값
• 의존 관계

등으로부터 화이트박스 (White-box) 방식으로 테스트를 생각하게 한다.

필요에 따라 별도의 세션이나 별도의 에이전트에게는,

• 요건
• 인수 조건 (Acceptance Criteria)
• 금지 조건
• 외부 인터페이스
• 과거 결함

등으로부터 블랙박스 (Black-box) 방식으로 확인하게 한다.

중요한 것은 AI의 수를 늘리는 것이 아니라,

「서로 다른 관측면에서 평가하는 것」

이다.

7. 고위험 변경은 동일한 운용 방식을 적용하지 않는다

다음과 같은 변경은 고위험으로 취급한다.

• 인증·인가 (Authentication/Authorization)
• 권한 관리 (Permission Management)
• 과금·청구 (Billing/Invoicing)
• 개인정보 (Personal Information)
• 계약 및 법무 관련 처리
• DB migration
• 데이터 삭제
• CI/CD
• 운영 환경 설정 (Production Settings)
• secret / token / credential
• 감사 로그 (Audit Log)
• 암호·서명 (Encryption/Signature)
• 외부 API에 대한 쓰기 (Write)
• 의존성 패키지 추가·업데이트

이러한 항목들에 대해서는 AI에게 자유롭게 변경하도록 하는 것이 아니라,

• 조사
• 설계안
• 테스트안
• 작은 차분(diff) 안

까지를 주요 역할로 한다.

구현에 사용할 경우에도,

• 실행 전에 계획을 확인한다
• dry-run이 가능한 것은 dry-run을 수행한다
• migration이나 인프라(infra) 변경은 plan을 확인한다
• 코드 오너(Code Owner)나 전문 리뷰를 필수화한다
• 롤백(rollback) 방법을 명시한다
• 피처 플래그(feature flag)나 단계적 출시를 검토한다

와 같은 제어를 추가한다.

AI가 할 수 있는 것과, AI에게 맡겨도 되는 것은 다르다.

8. 권한은 필요 최소한으로 한다

AI에게 넓은 권한을 주지 않는다.

이상적인 것은,

AI가 절대로 틀리지 않는 것

이 아니라,

AI가 틀려도 사고로 이어지기 어렵게 만드는 것

이다.

예를 들어,

• 운영 환경 자격 증명(production credential)을 읽게 하지 않는다
• secret을 포함하는 파일을 부주의하게 참조하게 하지 않는다
• 배포(deploy)를 직접 실행하게 하지 않는다
• migration 실행을 승인제로 만든다
• 패키지 설치(package install)를 승인제로 만든다
• 외부 통신을 동반하는 조작을 제한한다
• 위험한 shell command를 제한한다
• 리포지토리 쓰기(repository write) 권한을 상시 부여하지 않는다

와 같은 대책이 있다.

모델 성능이 향상되어도 이 원칙은 변하지 않는다.

9. 프롬프트만으로 안전을 지키려 하지 마라

CLAUDE.md, rules, skills, 프롬프트 등에,

"이 조작은 금지해 주세요"

라고 쓰는 것은 유효하다.

하지만 그것은 안전장치의 최종 단계가 아니다.

정말로 지켜야 하는 조건은 AI의 외부에서 강제한다.

즉,

프롬프트
↓
바람직한 행동을 전달
...

이라는 역할 분담이 된다.

AI에게 "하지 마"라고 의뢰할 뿐만 아니라, 해버려도 통과되지 않는 메커니즘을 만든다.

10. AI에게는 "문제없습니까"보다 "증거를 제시해 주세요"라고 요청하라

AI 리뷰는 유효하다.

하지만,

"이 PR은 머지(merge)해도 괜찮습니까?"

라는 질문만 던지면, 최종 판단까지 AI에게 위임하기 쉽다.

대신,

"판단에 필요한 사실과 미확인 사항을 제시해 주세요"

라고 의뢰한다.

예를 들어,

이 diff를 리뷰해 주세요.
관점:
- 요구사항과의 대응
...

AI의 역할을,

판정자

가 아니라,

증거를 수집·구조화하는 보조자

로 설정한다.

최종적인 채택 여부 판단은 인간과 CI가 담당한다.

11. 구성이 바뀌었다면, 이전의 증거를 그대로 신뢰하지 마라

조사와 리뷰는 처음에 한 번만 수행하면 되는 것이 아니다.

다음과 같은 이벤트가 발생하면, 이전의 조사 결과나 테스트 결과가 현재도 유효한지 재확인한다.

• main이나 다른 브랜치(branch)를 머지(merge)했다
• 리베이스(rebase)했다
• 머지 충돌(merge conflict)을 해결했다
• 관련 코드가 이름 변경(rename), 이동, 통합, 분할되었다
• 대상 기능에 새로운 업데이트 경로가 추가되었다
• API, proto, OpenAPI, DB schema를 변경했다
• 코드 생성을 재실행했다
• 전제가 되는 PR의 내용이나 순서가 바뀌었다
• 장기간 브랜치를 유지했고, 그 사이에 주변 구현이 바뀌었다
• CI를 통과하기 위해 테스트를 삭제·무효화·대폭 변경했다

이것들은,

이전에 수집한 증거가 오래될 가능성이 있는 이벤트

로 취급한다.

기계적으로 탐지할 수 있는 것은 가능하다면 CI나 hook을 통해 알림을 보낸다.

인간이 기억하고 있다는 것을 전제로 하지 않는다.

12. 복잡한 변경에서는 통합 후 리뷰를 수행한다

복잡한 변경에서는 과거의 PR 설명이나 계획이 옳다고 가정하지 않고, 현재의 브랜치 전체를 기준으로 다시 한번 확인한다.

가능하다면 구현 시와는 다른 세션 또는 다른 에이전트를 사용한다.

현재 브랜치 전체를,
과거의 설명이나 계획을 옳은 것으로 가정하지 말고,
현재의 코드와 테스트를 기준으로 조사해 주세요.
...

여기서 얻고자 하는 것은 "합격"이라는 한마디가 아니다.

예를 들어,

인간은 이 정보를 사용하여 최종 판단을 내린다.

13. AI를 사용한 범위를 기록하기

나중에 변경 판단 과정을 추적할 수 있도록, AI에게 의뢰한 범위와 인간이 확인한 내용을 PR(Pull Request)에 남긴다.

단, 모든 변경에 대해 긴 기록을 요구할 필요는 없다.

저위험(Low-risk) 변경이라면 한 줄이라도 좋다.

중위험(Medium-risk) 이상, 복수의 PR, 고위험(High-risk) 영역에서는 예를 들어 다음 내용을 남긴다.

• AI에게 의뢰한 범위
• AI가 변경한 주요 부분
• 실행한 테스트와 CI (Continuous Integration)
• AI가 인식하고 있는 미확인 사항
• 인간이 확인·수정한 점
• 잔존 리스크
• 최종 판단
• rollback(롤백) 방법

AI 스스로 초안을 작성하게 해도 좋다.

이번 작업 이력과 diff(차이)를 바탕으로,
PR에 기재할 AI 이용 기록의 초안을 작성해 주세요.
AI가 기입할 항목:
...

포인트는 AI에게 "인간이 확인했다"라고 쓰게 하지 않는 것이다.

AI가 만든 증거와 인간이 수행한 판단을 분리한다.

14. 팀에서 정해두어야 할 것

개인이 주의하는 것만으로는 한계가 있다.

팀으로서 최소한 다음 사항을 정해둔다.

AI가 내놓은 변경을 안전하게 받아들일 수 있는 메커니즘을 가진 팀

이다.

15. 최소한의 체크리스트

마지막으로, 실무에서 사용하기 쉽도록 확인 시점별로 정리한다.

구현 시작 전

• 목적이 하나로 좁혀져 있는가
• 조사 결과와 불명확한 점을 확인했는가
• 구현 계획을 확인했는가
• 변경하지 않을 범위가 명확한가
• 리스크 구분을 확인했는가
• 고위험 변경에 필요한 리뷰나 권한 제한을 확인했는가

PR 작성 전

• 차이(diff)가 목적에 대해 필요 최소한인가
• 무관한 리팩터링 (Refactoring)이 섞여 있지 않은가
• 테스트가 추가·업데이트되었는가
• 테스트가 구현이 아닌 요구사항을 확인하고 있는가
• 권한, 개인정보, secret(비밀 정보)에 대한 의도치 않은 영향이 없는가
• dependency(의존성)나 설정을 마음대로 변경하지 않았는가
• 필요한 CI가 통과되었는가
• rollback(롤백) 또는 취소 방법을 알고 있는가
• 필요하다면 AI 이용 범위를 기록했는가

통합·머지(Merge) 판단 전

• 티켓의 목적과 차이(diff)가 대응하는가
• AI가 근거 없이 사양을 보완하지 않았는가
• 기존 동작이나 책임 경계를 깨뜨리지 않았는가
• CI만으로는 확인할 수 없는 사항이 남아 있지 않은가
• 미확인 사항이나 잔존 리스크를 허용할 수 있는가

복잡한 변경에서는 더욱 확인한다.

• 지켜야 할 불변 조건(Invariant)을 확인했는가
• 주요 변경 경로를 확인했는가
• 복수 PR의 역할과 의존 관계를 알고 있는가
• merge(머지), rebase(리베이스), 충돌 해결, 코드 생성 후에 재확인했는가
• DB, API, 생성된 코드, 화면 등의 경계에서 의미가 유지되고 있는가
• 통합된 상태를 리뷰했는가
• AI가 제시한 근거와 미확인 사항을 인간이 확인했는가

요약

코딩 에이전트는 구현 속도를 크게 높여준다.

안전하게 사용하기 위한 기본은,

조사
↓
계획
...

과정을 거치는 것이다.

하지만 실제 개발에서는 그것만으로 끝나지 않는다.

복수의 PR, main 브랜치 반영, 충돌 해결, 코드 생성, API나 DB 경계, 타 서비스와의 연결이 있으면, 개별 PR에서 확인한 정당성이 그 이후에도 유지된다고 보장할 수 없다.

따라서 복잡한 변경에서는 다음과 같은 추가 확인이 필요하다.

• 불변 조건을 명확히 한다
• 상태나 데이터를 변경할 수 있는 경로를 조사한다
• PR 간의 의존 관계를 관리한다
• 구성이 바뀌면 이전의 증거를 재확인한다
• 통합된 현재 상태를 다시 한번 리뷰한다

AI에게는 조사, 열거, 비교, 테스트, 증거 정리를 돕게 한다.

기계적으로 판정할 수 있는 것은 CI나 권한 제어로 넘긴다.

그리고,

• 사양으로서 올바른가
• 잔존 리스크를 수용해도 되는가
• 운영 환경(Production)에 배포해도 되는가

라는 판단은 인간과 팀의 책임으로 남긴다.

AI에게 코드를 쓰게 하는 것 자체가 위험한 것이 아니다.

위험한 것은,

한 번 확인한 변경의 정당성이 시간의 경과나 다른 변경과의 통합 후에도 그대로 유지될 것이라고 가정하는 것

이다.

AI가 구현을 빠르게 할수록, 팀에는 변경을 안전하게 받아들일 수 있는 메커니즘이 필요하다.

그리고 이 가이드도 완성본이 아니다.

실제로 운용하며 실패와 재작업을 관측하고, 필요에 따라 변경해 나가야 한다.

이 v0.2도 처음부터 이런 형태였던 것은 아니다.

v0.1을 실제 개발에 사용하면서, 개별 PR (Pull Request)이 아닌 「통합 후」에 문제가 나타나기 시작했고, 현재의 형태로 바뀌었다.

다음 기사에서는,

PR은 각각 CI (Continuous Integration)와 리뷰를 통과했는데, 왜 기능 전체는 망가졌는가

라는 실제 운용 결과로부터, v0.1을 v0.2로 변경한 이유를 정리한다.

다음 회차: PR은 전부 통과했다. 그럼에도 망가졌다 —— 코딩 에이전트 실운용에서 발견한 「통합 후」의 문제

Discussion