제9장 Google Docs 스타일 코멘트로 에이전트 지휘하기

에이전트와 협업하다 보면 누구나 한 번은 같은 실수를 합니다. 계획을 보다가 마음에 안 드는 문장을 발견하고, 스크린샷에서 이상한 버튼을 보고, diff에서 과한 리팩터링 냄새를 맡는 순간 곧바로 채팅창으로 달려가 새 메시지를 씁니다. 그리고 길게 설명합니다. 방금 본 것이 왜 문제인지, 원래 의도는 무엇이었는지, 이제 어떻게 바꿔야 하는지 말이죠.

그런데 Antigravity가 진짜 잘 작동하는 방식은 조금 다릅니다. 이 도구는 피드백을 채팅창에만 몰아넣는 대신, 각 surface와 artifact 위에서 바로 남기고 실행 중인 작업에 반영하도록 설계돼 있습니다.¹ 다시 말해, 잘 지휘하는 사람은 대화를 처음부터 다시 시작하지 않습니다. 이미 만들어진 작업물 위에 짧고 정확한 코멘트를 남겨서 에이전트의 궤도를 바꿉니다.

이 차이는 생각보다 큽니다. 채팅은 설명의 공간이고, 코멘트는 조향의 공간입니다. 채팅으로는 에이전트와 토론하지만, 코멘트로는 에이전트를 운전합니다.

대화를 다시 시작하지 않는다는 것

Copilot류 도구에 익숙한 사람은 수정이 필요할 때 대개 다음 메시지를 보냅니다. 좀 다르게 해줘, 아까 건 잊고 이 방향으로 가자, 아니 그게 아니라 버튼만 바꾸자는 뜻이었어. 이 방식은 동기적입니다. 내가 말하고, 상대가 듣고, 잠깐 멈추고, 다시 움직입니다.

Agent-First에서는 작업 단위가 더 큽니다. 에이전트는 계획을 만들고, 파일을 바꾸고, 테스트하고, 브라우저를 열고, 증거를 남깁니다. 이때 사람의 역할은 프레임마다 핸들을 잡아채는 운전자가 아니라, 항로를 수정하는 관제사에 가깝습니다. 그래서 수정도 대화 전체를 흔드는 식보다, 특정 Artifact의 특정 지점에 붙는 방식이 더 효율적입니다.

Google Docs에서 문서 한 문단을 선택해 여기에 예시가 부족하다고 남기는 것과 비슷합니다. 문서 전체를 새로 쓰라고 소리치지 않아도 됩니다. 정확한 위치에 정확한 코멘트를 달면 됩니다. Antigravity의 Codelab도 Artifacts와 code diff에 Google Docs 스타일 코멘트를 남겨 에이전트가 그에 맞춰 반복할 수 있다고 설명합니다.²

코멘트는 왜 채팅보다 강한가

채팅 메시지는 쉽게 길어지고, 길어질수록 애매해집니다. 반면 인라인 코멘트는 위치가 곧 문맥입니다. 무슨 대상을 보고 말하는지 따로 길게 풀지 않아도 됩니다. 그 한 가지 차이만으로 피드백의 품질이 눈에 띄게 좋아집니다.

코멘트가 강한 이유는 세 가지입니다.

• 말이 아니라 위치에 묶여 있어서 해석 오차가 작습니다.

• 작업을 처음부터 다시 설명하지 않아도 돼서 재시작 비용이 낮습니다.

• 어떤 판단을 왜 내렸는지 흔적이 남아 나중에 검토와 감사가 쉬워집니다.

예를 들어 채팅창에 디자인을 좀 더 차분하게 바꿔줘라고 쓰면, 에이전트는 색을 바꿀 수도 있고 간격을 줄일 수도 있고 폰트를 바꿀 수도 있습니다. 하지만 스크린샷의 빨간 배지 위에 이 강조색은 경고처럼 보여서 부담스럽다. 기본 상태는 회색, 상승 지표만 초록으로 바꿔달라고 남기면, 수정 범위가 바로 좁아집니다.

좋은 코멘트는 설명을 줄이는 것이 아니라, 해석의 여지를 줄입니다.

어디에 어떤 코멘트를 남길까

코멘트는 아무 데나 다는 것이 아니라, 잘못된 방향이 생기는 지점에 맞춰 달아야 합니다. Antigravity에서는 계획서, Task List, code diff, walkthrough, 스크린샷과 녹화 같은 결과물 전반에 피드백을 남길 수 있습니다.²³

먼저 Implementation Plan에서는 방향을 바꿉니다. 여기서는 아직 코드가 많이 나오기 전이므로 가장 값싸게 개입할 수 있습니다. 예를 들어 계획서에 새 인증 라이브러리를 도입하겠다고 적혀 있다면 기존 세션 체계를 유지하고 UI만 수정해 달라고 남기는 것이 맞습니다. 계획에 API 키를 직접 쓰려는 흔적이 보이면 환경 변수로 바꾸고 클라이언트 노출은 피하라고 즉시 코멘트할 수 있습니다.⁴

Task List에서는 빠진 단계와 완료 기준을 보강합니다. 모바일 검증을 추가해 주세요, 실패 케이스도 브라우저에서 확인해 주세요, 테스트는 로그인 성공만이 아니라 잘못된 비밀번호 흐름까지 포함해 주세요 같은 코멘트가 여기에 어울립니다.

Code Diff에서는 실제 변경을 다듬습니다. 함수명은 괜찮지만 이 유틸은 기존 formatter를 재사용해 주세요, 이 예외 처리는 로깅이 빠졌습니다, 이 훅은 의존성 배열을 다시 봐 주세요처럼 줄 단위에 가까운 지적이 강합니다.

스크린샷, 브라우저 녹화, walkthrough에서는 경험을 조정합니다. 버튼 위치가 맞지 않는다, 로딩 후 스크롤이 튄다, 성공은 하지만 토스트가 너무 빨리 사라진다 같은 피드백은 채팅보다 화면 위 코멘트가 훨씬 정확합니다.

핵심은 단순합니다. 설계 문제는 계획에, 검증 문제는 Task List에, 코드 문제는 diff에, 경험 문제는 시각적 Artifact에 남기면 됩니다.

좋은 인라인 코멘트의 문법

좋은 코멘트는 짧지만, 모호하지 않습니다. 실무에서는 다음 네 요소를 함께 넣으면 대부분의 코멘트 품질이 좋아집니다.

• 무엇이 보였는가

• 왜 문제인가

• 어떤 제약이 있는가

• 다음에 어떻게 바꾸길 원하는가

예를 들어 이 버튼 이상해요는 너무 약합니다. 에이전트 입장에서는 크기인지, 색인지, 위치인지, 문구인지 알 수 없습니다. 반면 로그인 버튼의 파란색이 경고 배지와 충돌해 시선이 분산됩니다. 브랜드 메인 컬러는 헤더 CTA에만 쓰고, 이 버튼은 중립 회색 톤으로 낮춰 주세요. 모바일 360px에서도 한 줄 유지가 조건입니다는 바로 수정 가능한 지시입니다.

코드 쪽도 같습니다. 여기 보안 챙겨주세요는 사실상 기도문입니다. 대신 계획서의 API 키 직접 사용 부분은 제외하고, 서버 측 환경 변수와 프록시 경유 호출로 바꿔 주세요. 프런트 번들에는 비밀값이 포함되면 안 됩니다라고 쓰면 의도와 제약이 함께 전달됩니다.⁴

그리고 의외로 많이 놓치는 작은 규칙이 하나 있습니다. 코멘트는 남기는 것만으로 끝이 아닙니다. 제출해야 흐름이 바뀝니다. 실제 사용 가이드에서도 코멘트를 단 뒤 submit해야 Antigravity가 계획이나 작업을 업데이트하기 시작한다고 안내합니다.³

비동기 피드백 루프의 진짜 의미

비동기 피드백이라고 하면 많은 사람이 내가 댓글 달고, 에이전트가 나중에 읽는 구조 정도로 이해합니다. 물론 그것도 맞습니다. 하지만 더 중요한 뜻은 따로 있습니다. 사람과 에이전트가 같은 시계로 일하지 않아도 된다는 뜻입니다.

사람은 시간이 날 때 계획서를 읽고, 점심 직전에 스크린샷을 훑고, 회의 끝나고 diff를 확인할 수 있습니다. 에이전트는 그 사이에 코딩을 하고 테스트를 돌리고 브라우저 검증을 합니다. 둘이 계속 같은 템포를 맞추지 않아도 됩니다. 이게 생각보다 큰 해방감을 줍니다. 개발자는 계속 대기 상태로 붙잡혀 있지 않아도 되고, 에이전트도 사소한 질문마다 멈추지 않아도 됩니다.

실전에서는 이런 장면이 자주 나옵니다. 계획서와 Task List를 만든 뒤 에이전트가 당신의 최종 승인 없이 먼저 코딩으로 들어가는 경우가 있습니다. 그렇다고 늦은 것이 아닙니다. 그때도 해당 계획서나 Task List에 코멘트를 남기면 이후 코드와 walkthrough가 그 피드백을 반영해 갱신될 수 있습니다. 정말 급하면 작업을 멈추고 다시 조정할 수도 있습니다.³

중요한 것은 내가 언제 말했는가보다, 어디에 말했는가입니다. 좋은 비동기 피드백은 타이밍보다 앵커가 강합니다.

잘못된 방향으로 가는 에이전트를 멈추는 타이밍

물론 모든 수정이 코멘트만으로 충분한 것은 아닙니다. 어떤 경우에는 에이전트를 그냥 계속 가게 두면 나중에 되돌리는 비용이 너무 커집니다. 이럴 때는 과감하게 멈춰야 합니다.

다음 상황이라면 즉시 개입하는 편이 좋습니다.

• 새 외부 의존성이나 외부 서비스 도입이 계획에 갑자기 등장했을 때

• 데이터베이스 스키마, 인증 방식, API 계약처럼 파급 범위가 큰 축이 바뀔 때

• 보안 민감 정보, 권한 상승, 파일 삭제 같은 위험 동작이 보일 때

• 원래 요청하지 않은 대규모 리팩터링이 슬며시 끼어들 때

반대로 이런 경우는 굳이 흐름을 끊지 않고 Artifact 위 코멘트로 충분한 경우가 많습니다.

• 문구 톤, 색상, 여백, 정렬 같은 UI 다듬기

• 테스트 케이스 한두 개 추가 같은 검증 보강

• 함수명, 주석, 경미한 구조 정리 같은 코드 정제

• walkthrough에서 드러난 작은 상호작용 어색함 수정

원칙은 간단합니다. 뼈대가 틀리면 지금 멈추고, 표면이 거슬리면 흔적을 남기고 계속 가게 하세요. 좋은 관제사는 모든 비행기를 착륙시키지 않습니다. 충돌 위험이 있을 때만 적극 개입합니다.

실전 시나리오로 보는 코멘트 지휘법

가령 당신이 대시보드의 매출 카드 UI 개선을 맡겼다고 해봅시다. 에이전트가 계획서를 만들었는데, 거기에 차트 라이브러리 교체와 상태 관리 정리가 들어 있습니다. 이 순간 채팅창에 길게 쓸 필요는 없습니다. 계획서의 해당 문단에 이번 작업 범위는 카드 UI와 필터 상호작용 개선입니다. 차트 라이브러리 교체와 전역 상태 리팩터링은 제외해 주세요라고 남기면 됩니다.

이후 Task List를 보니 모바일 검증이 빠져 있습니다. 그 줄에 360px 뷰포트와 한글 숫자 포맷 확인 단계를 추가해 주세요라고 코멘트합니다.

코딩이 끝나고 스크린샷을 보니 상승률 배지가 지나치게 빨갛습니다. 배지 위에 경고처럼 보입니다. 기본은 중립 회색, 양수만 초록 강조로 바꿔 주세요라고 남깁니다.

브라우저 녹화를 보니 필터를 바꿀 때 카드가 두 번 깜빡입니다. 녹화 타임라인 근처에 필터 전환 시 skeleton이 이중으로 나타납니다. 재요청 중복 여부를 확인해 주세요라고 적습니다.

마지막으로 diff를 보니 날짜 포맷 유틸을 새로 만들었습니다. 그 줄에 기존 src/lib/format.ts의 formatter를 재사용해 주세요라고 남깁니다.

보세요. 대화는 한 번도 새로 열지 않았습니다. 하지만 에이전트의 항로는 다섯 번이나 바뀌었습니다. 이게 바로 잘 지휘하는 방식입니다.

코멘트를 남길 때 피해야 할 습관

코멘트가 강력하다고 해서 아무렇게나 달면 오히려 일이 꼬입니다. 특히 다음 습관은 빨리 버리는 편이 좋습니다.

• 하나의 코멘트에 새로운 요구사항 다섯 개를 한꺼번에 밀어 넣는 것

• 취향과 필수 요구사항을 섞어서 우선순위를 흐리는 것

• Artifact에 달아야 할 말을 채팅에 추상적으로 던지는 것

• 이미 끝난 작은 작업을 거대한 새 작업으로 슬그머니 확장하는 것

에이전트는 사람보다 눈치가 적고, 말은 잘 듣지만 맥락 싸움에는 약합니다. 그러니 친절함보다 구조가 중요합니다. 한 코멘트에는 한 가지 핵심 판단을 담고, 필요하면 여러 코멘트로 나누세요. 디자인 취향이면 선호라고 밝히고, 규정이나 요구사항이면 제약이라고 분명히 적으세요.

좋은 코멘트는 많이 쓰는 코멘트가 아니라, 나중에 읽어도 왜 그 수정을 요구했는지 남는 코멘트입니다.

결국, 좋은 지휘는 말을 많이 하는 것이 아니다

에이전트 시대에 개발자의 능력은 프롬프트를 그럴듯하게 길게 쓰는 데서 끝나지 않습니다. 더 중요한 능력은 이미 움직이기 시작한 작업을 멈추지 않고도 수정할 줄 아는 것입니다.

Antigravity의 Google Docs 스타일 코멘트는 바로 그 능력을 훈련시킵니다. 계획에는 방향을, Task List에는 완료 기준을, diff에는 정확도를, 스크린샷과 녹화에는 사용자 경험을 남깁니다. 그러면 에이전트는 매번 처음부터 설명을 다시 듣지 않아도 됩니다. 당신이 남긴 흔적을 따라 궤도를 수정합니다.

결국 잘 지휘하는 사람은 에이전트와 더 오래 대화하는 사람이 아닙니다. 올바른 표면에서, 올바른 순간에, 올바른 한마디를 남기는 사람입니다. 채팅을 다시 시작하지 않고도 방향을 바꿀 수 있을 때, 비로소 당신은 사용자가 아니라 감독자가 됩니다.

참고

¹Google Antigravity introduces agent-first architecture for asynchronous, verifiable coding workflows

²Google Antigravity 시작하기 | Google Codelabs

³Provide Feedback to Google Antigravity

⁴How to Use Google Antigravity: A Complete Guide.