계획(Plan)에서는 자유롭게, 수정에서는 엄격하게 — AI 코딩을 안정화하는 커밋 경계

이 기사는 주로 **Antigravity 2.0 (Gemini 3.5 Flash (High))**를 사용하여 개발하는 과정에서 얻은 지견을 정리한 것입니다.

특정 도구에만 통용되는 이야기가 아니라, AI 코딩 에이전트(AI Coding Agent) 전반에도 응용할 수 있을 것이라고 생각합니다.

AI 코딩 에이전트에게 구현을 맡기면, 처음에는 놀라울 정도로 순조롭게 진행될 때가 있습니다.

관련 파일을 조사하고, 구성을 생각하며, 여러 파일을 한꺼번에 변경해 줍니다. 인간이 하나씩 쓰는 것보다 훨씬 빠르게 형태를 갖추기도 합니다.

하지만, 동일한 대화 속에서 세세한 수정을 몇 번이고 요청하다 보면 거동이 이상해질 때가 있습니다.

• 표시만 고쳐달라고 했는데, 다른 처리까지 변경됨
• 이전의 수정을 남겨두길 원하는데, 원래대로 되돌려짐
• 하나의 버그를 고친 결과, 또 다른 버그가 발생함

이것은 단순한 AI의 성능 부족이 아닙니다.

작업의 페이즈(Phase)가 바뀌었음에도 지시 방식(Instruction)을 바꾸지 않은 것도 원인 중 하나입니다.

저는 AI 코딩을 다음과 같은 흐름으로 진행하게 되었습니다.

• Plan(계획) 단계에서는 폭넓게 조사하게 하고 자유롭게 생각하게 한다
• Implementation Plan(구현 계획)은 인간이 면밀히 리뷰한다 - 승인한 계획에 따라 한 번에 모아서 구현하게 한다
• 동작하는 상태가 되면, 완전하지 않더라도 커밋(Commit)한다
• 이후의 수정에서는 대상과 제약을 엄격하게 지정한다
• 문맥(Context)이 혼란스러워지면 새로운 세션(Session)으로 옮긴다

중요한 것은 처음부터 끝까지 동일한 입도(Granularity)의 지시를 사용하지 않는 것입니다.

발산하는 단계에서는 자유를 주고, 수렴하는 단계에서는 제약을 강화합니다.

설계의 초기 단계에서는 인간 측에서도 정답이 보이지 않을 때가 있습니다.

이 단계에서 변경 방법을 너무 세세하게 지정하면, AI가 코드베이스(Codebase)를 조사하여 찾아냈을 더 자연스러운 구현안을 짓밟아 버리게 됩니다.

Plan 단계에서는 다음과 같이 의뢰합니다.

관련된 코드와 기존의 설계 패턴을 조사해 주세요.
아직 코드는 변경하지 마세요.
여러 구현안이 있는 경우, 장점과 단점을 제시해 주세요.
...

여기서는 AI를 작업자가 아니라, 조사 담당자나 설계 상담 상대로 사용합니다.

방향성이 결정되면 구체적인 구현 계획을 만들게 합니다.

확인하는 것은 주로 다음 내용입니다.

• 변경할 파일
• 파일별 변경 내용
• 기존 기능에 미치는 영향
• 테스트 방법
• 완료 조건
• 이번에 변경하지 않는 것

AI가 작성한 코드를 나중에 고치는 것보다, 계획 단계에서 고치는 것이 비용이 적게 듭니다.

건물을 지은 뒤에 기초를 움직이는 것보다, 도면에 빨간 선을 긋는 것이 더 용이합니다.

계획을 승인하면 한 번에 모아서 구현하게 합니다.

명명(Naming)이나 표시, 에러 처리(Error Handling)에 개선점이 남을 수도 있습니다. 하지만 전혀 사용할 수 없는 상태가 아니라면, 저는 일단 한 번 커밋합니다.

git add .
git commit -m "Add initial implementation"

여기서 말하는 커밋은 완성을 선언하는 것이 아닙니다.

여기까지는 하나의 도달점으로 저장한다는 의미입니다.

커밋을 하면 다음 수정을 독립된 차이(Diff)로서 확인할 수 있습니다.

git diff HEAD

의도하지 않은 파일까지 변경된 경우에도 즉시 알아차릴 수 있습니다.

나아가 AI에게 명확한 기준을 제시할 수 있습니다.

현재의 HEAD를 기준으로 합니다.
이번 수정 대상 이외에는 변경하지 마세요.

커밋은 코드를 저장하기만 하는 조작이 아닙니다.

유지할 부분과 앞으로 변경할 부분을 나누는 경계가 됩니다.

첫 구현에서는 AI가 여러 파일을 횡단하여 변경하는 능력이 도움이 됩니다.

하지만 마무리 단계에서는 그 능력이 위험 요소가 될 수 있습니다.

수정 시에는 다음 내용을 명시합니다.

• 무엇을 고칠 것인가
• 무엇을 유지할 것인가
• 변경해도 좋은 파일
• 리팩터링(Refactoring) 가능 여부
• 완료 조건
• 실행할 테스트

예를 들어, 다음과 같이 지시합니다.

목록 화면의 날짜 표시만 수정해 주세요.
제약 사항:
- API 응답은 변경하지 말 것
...

"적당히 잘 고쳐주세요"가 아니라, 변경 계약(Change Contract)을 전달하는 이미지입니다.

이것은 AI의 능력을 낮게 평가하여 일을 잘게 쪼개기 위한 수법이 아닙니다.

Plan에서는 탐색 능력을 살리고, 수정에서는 변경 범위를 좁힙니다.

페이즈에 따라 역할을 전환함으로써 AI의 강점을 살리면서도 의도하지 않은 변경을 방지하기 위한 수법입니다.

주의할 점도 있습니다.

Git에 커밋하더라도, 동일한 AI 세션을 계속 유지하는 한 과거의 지시나 실패한 수정은 대화의 문맥에 남아 있습니다.

동일한 부분을 몇 번이고 수정하게 한 뒤 동작이 불안정해진 경우에는 새로운 세션으로 이동합니다.

그럴 때는 현재의 HEAD, 변경 대상, 금지 사항, 완료 조건을 다시 한번 전달합니다.

즉,

• 커밋(Commit)으로 코드의 상태를 정리한다
• 새로운 세션으로 AI의 문맥(Context)을 정리한다

이 두 가지는 별개의 작업입니다.

AI 코딩을 안정화하기 위해 필요한 것은 완벽한 프롬프트(Prompt)를 한 번에 작성하는 것이 아닙니다.

작업 상태에 따라 AI에 대한 지시를 바꾸는 것입니다.

Plan(계획) 단계에서는 자유롭게 생각하게 한다.

Implementation Plan(구현 계획) 단계에서는 인간이 엄격하게 확인한다.

형태가 갖춰지면 완벽하지 않더라도 커밋한다.

수정 단계에서는 대상과 제약을 좁힌다.

문맥이 혼란스러워지면 새로운 세션으로 이동한다.

AI에게 항상 세세하게 명령하는 것이 제어(Control)는 아닙니다.

자유롭게 달리게 할 곳과 멈출 곳을 설계하는 것이야말로, 현재의 AI 코딩에 있어 유효한 제어라고 생각합니다.

물론, 이 글에서 계속 설명해 온 것과 같은 세밀한 제어를 하지 않더라도, 상황을 읽고 필요한 변경만을 선택하며 불필요한 변경을 피하는 AI는 이미 나타나기 시작했습니다.

인간이 Plan과 Implementation Plan을 나누고, 커밋을 경계로 삼으며, 변경해도 좋은 파일을 하나씩 지정하는.

그런 작업을 오래된 개발 관습으로 되돌아보는 날은 그리 멀지 않았을지도 모릅니다.

그때, 이 글은 무엇이었을까요.

아마도 AI가 충분히 똑똑해지기 전까지, 아주 짧은 시대에만 필요했던 운전 기술의 기록일 것입니다.

Implementation Plan이란, 태스크를 달성하기 위해 코드베이스(Codebase)에 필요한 변경 사항을 설계하고 구체적인 기술적 수정 내용을 나타내는, 사용자의 리뷰를 전제로 한 Artifact입니다. https://codelabs.developers.google.com/getting-started-google-antigravity?hl=ja#6 ↩