AGENT.md와 Skills로 Antigravity CLI 개발 흐름을 정립하여, 대략적인 입력만으로 웹 애플리케이션 개발하기

얼마 전 Antigravity CLI가 발표되어 바로 사용해 보고자 합니다.

비즈니스 환경에서도 사용할 수 있도록 Google Cloud의 Gemini Enterprise Agent Platform을 사용하여 Antigravity CLI를 이용했습니다.

Google Cloud의 엔터프라이즈용 데이터 프라이버시 규약(Data Privacy Terms)에 따라, 주고받은 내용이 모델 학습에 이용되지 않으므로 비즈니스 환경에서도 안심하고 사용할 수 있습니다.

Google Cloud를 사용하는 방법은 간단합니다.

로그인하지 않은 상태에서 Antigravity CLI를 실행하면 다음과 같이 로그인 방법을 묻습니다.

2를 선택하면 로그인용 URL이 표시되므로, 해당 URL에 접속하여 Google Cloud에 로그인하면 준비 완료입니다.

Google Cloud를 이용하여 로그인한 경우에는 다음과 같이 (Antigravity Business)라고 표시됩니다.

비즈니스 환경에서 이용할 경우에는 프롬프트(Prompt)를 입력하기 전에 이 표시를 확인하는 것이 좋을 것 같습니다.

모호한 요구사항을 전달하면 열심히 제품으로 완성해 주는 Skills 등을 준비합니다.

Antigravity CLI에 다음과 같은 프롬프트로 만들어 달라고 요청했습니다.

Antigravity CLI용 skills를 만들어 주세요.
Antigravity CLI의 skills에 관해서는 [공식 문서](https://antigravity.google/docs/cli-overview)를 참고해 주세요.
모두 글로벌(Global)이 아니라, 프로젝트 스코프(Project Scope)로 작성해 주세요.
...

완성된 skills와 AGENTS.md는 다음과 같습니다.

### 📂 생성된 파일 구성
/workspace/
├── .agent/
...

각 skills는 양이 많으므로 생략하지만, AGENTS.md는 생성된 내용을 그대로 공유하겠습니다.

여기서부터 생성된 AGENTS.md입니다.

이 문서는 프로젝트 전체의 개발 흐름(Development Flow), 에이전트의 각 역할(Role, 스킬)의 책무, 그리고 단계별 연계를 정의한 공통 가이드라인입니다. 모든 에이전트(서브 에이전트) 및 스킬은 이 정책을 최우선으로 준수하여 동작합니다.

본 프로젝트는 요구사항 정의부터 인프라 프로비저닝(Infrastructure Provisioning), E2E 테스트를 통한 통신 확인, 장애 조사까지 14개의 단계로 구성된 완전한 협업 흐름(Cooperative Flow)을 채택합니다.

역할 (Skill 명)	책무 개요	주요 산출물 및 배치 경로
product-owner	무리한 요구사항을 구체화하고 방침 결정권을 가짐.	docs/requirements/ (개요, 스토리, 기능 목록 등)
frontend-designer	디지털청 디자인 시스템 (DADS) 준수 화면 설계.	docs/designs/frontend/ (화면 전환도, 레이아웃, 항목 정의)
backend-designer	데이터 중심 설계 (Data-Centric Design) 기반 DB 및 서버 사이드 기능 설계.	docs/designs/backend/ (ER 다이어그램, 테이블 목록, DDL, 체크리스트)
infrastructure-designer	Cloud Run / SQL을 구축하는 보안이 강화된 Terraform 개발.	terraform/ (main.tf, variables.tf 등)
security-reviewer	OWASP Top 10 / IPA 가이드라인을 준수한 감사.	docs/reviews/security_issues.md (미결 사항 관리)
maintainability-reviewer	SOLID 원칙 / 클린 아키텍처 (Clean Architecture) 규약을 준수한 감사.	docs/reviews/maintainability_issues.md (미결 사항 관리)
performance-reviewer	데이터베이스 인덱스 / Next.js의 표시 레이턴시 (Latency) 감사.	docs/reviews/performance_issues.md (미결 사항 관리)
test-planner	설계에 준거한 논리적 그룹화 기반의 Vitest 코드 작성.	src/**/*.test.ts (테스트 코드)
developer	Next.js/PostgreSQL 구현. ESLint, Prettier, Vitest 필수 실행.	src/ (애플리케이션 본체 코드)
deployer	Cloud Build를 통한 빌드 및 Terraform을 통한 배포.	배포 로그, Cloud Run URL
validator	Playwright를 이용한 배포된 실제 환경에 대한 E2E 통신 확인.	tests/e2e/ (Playwright 테스트 코드, 테스트 결과)
inspector	validator 실패 시 GCP 로그를 통한 원인 규명.	docs/reviews/inspection_report.md

설계 또는 코드 리뷰 시, security, maintainability, performance의 3가지 리뷰어로부터 때로는 상충하는(동시에 만족할 수 없는) 지적이 올라올 수 있습니다.

[!IMPORTANT]

상충하는 지적이 있거나, 개발 비용 또는 인프라 비용이 현저히 높은 경우, 디자이너나 개발자는 PO의 결정에 엄격히 따라야 합니다. product-owner는 우선순위가 낮은 지적을 "대응 불필요"로 처리하여 클로즈(Close)할 권한을 가집니다.

모든 리뷰어(security, maintainability, performance)는 지적 사항을 개별 채팅으로 전달하는 것이 아니라, 지정된 마크다운 (Markdown) 형식의 관리표 파일(docs/reviews/ 하위)에 기술합니다.

• 지적을 받은 담당자(developer나 backend-designer 등)는 수정 시 해당 상태를 [ ] 미착수에서 [x] 완료 (또는 PO 판단에 따라 대응 불필요)로 업데이트하고, 수정 결과나 PO의 결정을 상세 섹션에 기술합니다. 모든 지적 사항이 완료 또는 대응 불필요가 될 때까지 다음 단계(배포 또는 릴리스)로 진행할 수 없습니다.

developer가 코드를 작성하거나 지적에 기반하여 수정했을 때는, 수동 배포나 머지 (Merge)를 수행하기 전에 반드시 로컬에서 다음의 검증 (Validation)을 실행하여 모두 성공했음을 입증해야 합니다.

포매터 (Prettier)
정적 분석 (ESLint)
테스트 (Vitest)

validator가 Playwright E2E 테스트에서 실패를 감지할 경우, 즉시 프로세스를 중단하고 inspector에게 의뢰합니다.

inspector는 Cloud Logging 정보를 추출하여 docs/reviews/inspection_report.md를 작성하고, 현 상태를 Blocked(장애 중)로 설정한 뒤 전체 개발 사이클을 일단 일시 종료합니다.

[!TIP]

이 프로젝트는 최고 수준의 자동화, 견고한 보안, 그리고 높은 유지보수성(Maintainability)을 양립한 프리미엄 개발 환경을 목표로 합니다. 각 에이전트는 자신의 전문 스킬(.agent/skills/ 이하)을 최대한 활용하여, 팀이 하나가 되어 이 고품질 개발 플로우를 자율적으로 유지해 주세요.

여기까지가 AGENTS.md입니다.

'프리미엄한 개발 환경'이라는 표현은 제가 평소에 잘 쓰지 않는 말이라 살짝 미소가 지어졌습니다.

플로우가 제가 의도한 내용과 약간 다르긴 하지만, 이번에는 수정하지 않고 그대로 개발을 진행해 보았습니다.

참고로, 저는 백엔드 설계를 바탕으로 프론트엔드 설계를 하게 할 계획이었습니다.

"첫 아이를 육아하는 부모들을 위해, 추천 육아용품을 서로 소개하는 리뷰 사이트를 만들어줘"라고 대충 요청해 보았습니다.

※ 저는 현재 한창 육아 중이라, 마침 떠오른 내용이 위와 같았습니다.

저의 대충 던진 요청을 바탕으로 project-owner 스킬을 사용하여 다음과 같은 문서를 작성해 주었습니다.

./
├── docs/
└── requierments/
...

생성된 제품 개요(Product Overview)와 유저 스토리(User Story)의 일부를 공유합니다.

# 제품 개요 (Product Overview)
첫 아이 육아에 직면한 초보 부모를 위한, 리얼하고 신뢰성 높은 "추천 육아용품" 리뷰 및 공유 플랫폼.
## 배경 (Background)
...

# 유저 스토리 (User Stories)
각 액터(Actor)의 관점에서 제품이 제공하는 가치와 수락 기준(Acceptance Criteria)을 정의합니다.
## 1. 육아용품 검색 및 열람 (게스트·일반 사용자 공통)
...

저의 대충 던진 요청을 바탕으로 구체화해 주고 있네요.

처음에 수락 기준이 되는 유저 스토리가 생성됨으로써, 후속 설계 및 구현이 안정적으로 진행될 것 같습니다.

PRD 작성 단계에서 일단 Antigravity CLI의 동작이 멈췄기에, "계속해 주세요"라고만 지시하여 설계를 진행하도록 했습니다.

그러자 프론트엔드와 백엔드 양쪽의 설계부터 리뷰 지적 사항 대응까지 한꺼번에 완료되었습니다.

작성된 설계서는 다음과 같습니다.

./
└── docs/
└── designs/
...

화면 레이아웃도 만들어 주길 바랐는데, 만들어지지는 않았네요...

생성된 ER 다이어그램(ER Diagram)은 이런 느낌입니다.

꽤 그럴싸하네요.

화면遷移도(Screen Transition Diagram)는 이런 느낌입니다.

선이 겹쳐서 보기 어렵긴 하지만, 이 또한 꽤 그럴싸합니다.

리뷰 결과는 다음과 같이 관점별 Markdown 파일로 출력되었습니다.

./
└── docs/
└── reviews/
...

성능 리뷰 지적 사항의 생성 결과는 다음과 같습니다.

# 성능 리뷰 지적 사항 관리표
이 파일은 시스템의 성능, 응답 속도, 리소스 효율 관점에서 검출된 설계·코드·설정의 과제와 대응 상황을 관리합니다.
## 📊 지적 사항 목록
...

흔히 발생하는 성능 문제를 설계 단계에서 고려해야 할 사항으로 꼽아주고 있네요.

PO(Project Owner)에 의해 대응 가능 여부 판단이 이루어지고, 지적 사항 대응으로서 설계서 수정이 이루어졌다는 점이 기재되어 있는 부분이 매우 좋다고 생각합니다.

설계 완료 후, 다시 한번 Antigravity CLI의 동작이 종료되었기에 이번에도 "계속해 주세요."라고만 전달하여 구현을 진행하도록 했습니다.

완성된 파일은 다음과 같습니다.

./
└── src/
├── app/ # Next.js 애플리케이션 라우팅·프레젠테이션 계층
...

테스트 코드는 lib 하위의 백엔드 로직만 만들어 주었습니다.

또한, 사전에 테스트 코드를 먼저 작성하도록 지시했기 때문인지, 중간에 추가된 파일에 대해서는 테스트가 없습니다.

소스 코드를 살펴보니 .tsx 파일은 뷰(View)에 전념하고 있었고, 로직은 actions.ts로 분리되어 있었습니다.

이 점은 소스 코드가 매우 읽기 쉬워서 좋다고 생각합니다.

스타일에 관해서는, 글로벌하게 정의된 CSS 클래스와 style 요소에 직접 작성(hard-coded)되어 있었습니다.

style 요소에 직접 CSS를 기술하면 코드가 장황해지기 때문에, tsx 파일이 불필요하게 길어진 점은 아쉽습니다.

CSS Modules를 사용하여 작은 스코프(scope)의 CSS 클래스를 만들어 주었다면 제 취향에 더 맞았을 것 같습니다.

여기서도 AGENT.md의 정의에 따라 각종 리뷰가 수행되었습니다.

각 관련 리뷰 기록표에는 지적 사항이 없다는 내용이 추가되었습니다.

또한, 구현 시에는 lint나 build, test를 수시로 실행하여 문제가 있으면 즉시 수정해 주었습니다.

이러한 작업은 시간이 걸리기 때문인지, Antigravity CLI가 백그라운드 태스크(background task)로 실행하고 있었으며, /tasks 명령어를 실행함으로써 각 태스크의 상태를 확인할 수 있었습니다.

구현이 완료되면 다시 일시 종료되었기 때문에, 여기서도 "계속해 주세요."라고만 전달하여 진행하도록 했습니다.

그러자 deployer 스킬을 사용하여 로컬 PC 상에서 Next.js의 프로덕션 빌드(production build)를 수행하고, 애플리케이션을 구동하기 시작했습니다.

(어라, deployer는 Google Cloud에 배포하는 스킬일 텐데...)

구동이 완료되자 validator 스킬로 Playwright의 E2E 테스트 코드가 생성되었고, 일련의 대표 조작이 가능해질 때까지 버그를 수정해 주었습니다.

작성된 테스트 코드는 다음과 같습니다.

import { test, expect } from "@playwright/test";
test.describe("いっぽめベビー 프로덕트 통신 확인 (E2E Smoke Test)", () => {
const baseUrl = process.env.BASE_URL || "http://localhost:3001";
...

대체로 주요 동선이 확인된 것 같네요.

애플리케이션 측의 HTML 태그에 id가 부여되어 있는 덕분에, 심플하고 읽기 쉬운 테스트 코드가 완성되었습니다.

테스트가 통과하게 되자, 다음과 같이 개발 흐름에서의 현재 상황을 보고해 주었습니다.

(최고 수준이라고 하기엔 좀 과하네요 ㅎㅎ)

톱 화면은 이런 느낌입니다.

검색도 가능했습니다.

신규 등록부터 사용자 등록을 해보겠습니다.

비밀번호가 짧으면 유효성 검사 에러(validation error)가 발생합니다.

에러가 발생했을 때 입력 항목이 비워지는 점은 조금 아쉽네요.

이미 등록된 이메일 주소를 입력해 보니 제대로 중복 에러가 발생했습니다.

사용자 등록이 완료되면 헤더에 사용자 이름이 표시되어 로그인 상태가 되었음을 알 수 있습니다.

용품 상세 화면으로 이동하면, 리뷰가 표시되는 부분은 이런 식입니다.

리뷰를 작성해 보겠습니다.

제대로 반영되었습니다.

자신이 작성한 리뷰는 편집이나 삭제가 가능하도록 되어 있습니다.

이 유모차를 즐겨찾기에 등록해 보았습니다.

마이페이지로 가니 즐겨찾기에 등록한 상품이 표시되었습니다.

꽤 괜찮은 느낌이네요!

사실 이 다음에 Google Cloud에 배포하는 단계도 있지만, 꽤 많이 구동해서 과금도 걱정되고 기사 분량도 길어질 것 같아 여기까지만 하겠습니다.

Antigravity CLI를 사용하여 개발 흐름의 정비부터 실제 개발까지 진행해 보았습니다.

개발 흐름을 정비했기 때문에, 거친 입력(input)임에도 불구하고 성공적으로 개발할 수 있었던 것 같습니다.

개발에 소요된 시간과 비용은 다음과 같습니다.

시간: 1h 17m

비용: 3,472엔

이 속도와 결과물이라면 파격적으로 저렴한 수준입니다.

Antigravity CLI + Gemini 3.5 Flash는 상당히 빨랐습니다.

잠시 지켜보는 사이에 착착 진행되었습니다.

이번처럼 대충 진행했음에도 생각보다 훨씬 원활하게 개발이 진행되었습니다.

더 개선하기 위해서는 다음과 같은 조치를 취하는 것이 효과적일 것으로 느껴졌습니다.

• AGENT.md 재검토 (흐름이 의도대로 되지 않는 부분을 수정하거나, 인간의 리뷰 타이밍을 명시하는 등...)
• Skills 재검토 (designer에 의한 설계 방법을 더 구체적으로 정하거나, reviewer의 관점을 구체화하거나, test-planner의 관점을 구체화하는 등...)
• 적절히 생성물을 인간이 리뷰하고 피드백을 전달 (PRD나 설계서를 작성하는 방식으로 단계를 밟게 하고 있으므로, 피드백을 줌으로써 더 좋은 결과물을 만들 수 있을 것 같음)

Antigravity CLI는 상당히 쓸만하다고 생각되므로, 앞으로도 계속 이용해 나가고 싶습니다.