Gemini 3 Pro High 이녀석 똑똑하다
2025년 11월 말, 안티그래비티라는 AI 코딩 에이전트를 처음 접하고, 제대로 사용한지 일주일 정도가 지났다.
Cursor 구독이 끝나간다는게 첫번째 이유였는데, .cursorrules 에 가볍게 작성해둔 가이드를 쪼개서 Rules 로 만들수 있다는게 매력적이었다.
프론트엔드 프로젝트라는 건 코드만 보면 알 수 있는 게 아니다.
GraphQL을 어떻게 쓰고 있는지, 상태 관리 패턴이 뭔지, 어떤 폴더는 건드리면 안 되는지.
이런 "암묵적 규칙"들과 “우리끼리의 약속”이 항상 문제였다.
새로 온 팀원에게 설명하는 데 시간이 들고, 그렇기에 AI에게는 더더욱 전달이 안 됐던게 아닐까.
안티그래비티를 쓰면서 이런점들이 얼마나 해소가 됐는지 간단히 정리해보려 한다.
간단한 사이드 프로젝트를 Solid.js 로 만들어봤다.
이때 설정한 룰은 딱 두가지.
UI/UX 전달 Rule과 프로젝트 코드 컨벤션 가이드였다.
project.md
# 🎨 UI/UX Protocol: Mobile-First & Tailwind CSS
> **Context:** Solid.js MVP Development
> **Priority:** Mobile Experience First
> **Toolchain:** Tailwind CSS (v4)
This document defines how we maintain visual consistency while allowing for creative UI implementations.
## 1. The "Mobile-First" Standard 📱
## 2. Theming: Consistent Creativity 🎭
## 3. Mood: Quality to sound like "What's this app? It's pretty!" when shared on Instagram Story, Feedsolid-js.md
## 1. Core Philosophy: No VDOM, Just Reactivity
### 🚫 The "React Thinking" (Do NOT do this)
- **Do not** expect the component function to re-run on state changes.
- **Do not** destructure props. Destructuring breaks reactivity.
- _Bad:_ `const { title } = props;`
- _Good:_ `props.title` or using `mergeProps`.
### ✅ The "Solid Way" (ALWAYS do this)
- **Components run once:** The function body executes only once during initialization.
- **Signals are functions:** To access the value of a signal, you must call it as a function.
- `count()` ✅ vs `count` ❌
- **Tracking:** Reactivity only happens where a signal is accessed (read) inside a tracking scope (like JSX or `createEffect`).
---
## 2. Control Flow Components (Mandatory)
In Solid.js, we use dedicated components for logic instead of JavaScript array methods (`.map`) or ternary operators inside JSX. This ensures that only the changing part of the DOM is updated, not the entire block.
### Conditionals: `<Show>` & `<Switch>`
### Iteration: `<For>` & `<Index>`
### Dynamic Components: `<Dynamic>`사실 Solid.js 전용 Rule 은 정말 말그대로 한번씩 AI가 고장나서 ‘React 처럼 코드를 짤까봐’ 작성한 문서에 가깝다. 사실상 쓴 룰은 위의 project.md 한개뿐.
가 전부였다.
그래서 이렇게 뚝딱 만들어본 사이드 프로젝트는 문서 작성과 배포까지 거의 하루만에 완성됐는데, 꽤나 만족스러운? 그럴듯한 사이트가 나와서 주변 지인에게 요긴하게 써먹었다.
그리고 Rule 이라는건 활성화 모드가 4가지(Manual, Always On, Model Decision, Glob) 가 있는데, 이중 Manual로 적재적소에 읽히면 토큰도 많이 아끼고, 필요할때만 문서를 읽힐 수 있는 장점도 있다.
닥팔 클라이언트 레포에 .agent 폴더가 생겨도 상관없다는 팀원들의 허락을 받고, 가장 먼저 기본적인 Rule 하나를 추가해뒀다.
가장 먼저 만든 project-context.md라는 파일
---
trigger: always_on
---
# Project Context
This project is a **Monorepo** utilizing **Module Federation** based on **React**.
The codebase is structured to support micro-frontend architecture.
# Architectural Standards
## 1. Data Fetching (GraphQL)
- **Core Library:** Apollo Client v4.
- **New Development Pattern:**
- Adopt the **Relay Colocation + Data Masking** pattern.
- Do **NOT** reuse or depend on massive, pre-defined top-level queries
for new UI components.
- Instead, define **Fragments** colocated with their respective components.
# Constraints & Restrictions
- **Protected Directories:** Do **NOT** modify files inside the `lib` folder
unless explicitly instructed or absolutely necessary for a bug fix.28줄짜리 파일이었다. 내용은 심플하다.
lib 폴더는 건드리지 마라.이걸 넣고 나서 달라진 게 있었을까?
있다. 에이전트에게 "이 컴포넌트에 데이터 페칭 추가해줘" 하고 주루룩 아폴로스튜디오 스키마를 보여주면, 예전에는 쿼리에 필드를 추가하고, props drilling 하는 방식으로 코드를 생성했다. (우리 프로젝트의 레거시 패턴을 많이 읽다보니 나오는 현상같다)
하지만 Rule을 넣은 뒤로는 Fragment를 찾아서 컴포넌트한테 만들어서 쿼리에 조합하는 방식으로 생성하려고 한다.
물론 좀 느리긴 하다. 임포트 경로가 이상할때도 있고, 고장날때도 있긴하지만, 너무 복잡한 컨텍스트가 아니라면 어느정도 따라와주는게 솔직히 ‘어쭈, 이놈봐라..?’ 싶었다.
그 다음으로 만든건 Jotai 컨벤션 룰이었다.
Jotai 에 대한 닥터팔레트 컨벤션 내용은 이 글을 참고하시라.
아무튼 룰을 추가하고, local state로 UI만 만들어둔 필터링 화면에 도입했는데, 정말 순식간에 만들어줬다.
룰 작성이 훨씬 오래걸리는 시대에 살고있다.
물론 Rule은 한 번 쓰고 끝이 아니라, 에이전트의 출력을 보면서 계속 다듬어야 한다.
사람에게 설명할 때와 비슷하다. 처음에 대충 설명했다가 "아 그게 아니고..."하면서 점점 정교해지는 과정이다.
Antigravity 의 cmd + E 를 눌렀을때 나오는 Agent Manager 의 좌측 하단에 Playground 라는 탭이 있다.
여기서 만든 md 파일을 보여주고, 이걸 토대로 코드를 작성해보라는 식으로 아웃풋을 확인해보고, 첨삭을 요청해도 된다.
Rule 은 “이렇게 해” 라면, Workflow 는 “이 순서대로 해” 라는 지침서다.
행동강령을 넣어 둘 수 있다.
예를들면 코드리뷰 Workflow 를 들 수 있겠다.
## description: Code Change Review and Analysis (Korean Response Mode)
## rules:
1. **Response Language**: All analysis results must be written in **Korean**.
2. **Auto-Execution**: Execute read-only commands (e.g., `git diff`) automatically.
## workflow:
1. Run `git diff main...HEAD` to identify all changes from the main branch.
2. Analyze the code for bugs, design inconsistencies, and accessibility issues.
3. Provide specific improvement suggestions in **Korean**.
4. Run `git branch --show-current` to identify the current working branch.
5. Present a summary of the analysis and branch information.
## reference:
- @/.gemini/styleguide.mdPR을 올리기 전에 매번 "내가 놓친 게 없나" 확인하는 과정이 귀찮고, 깃헙 코드리뷰와 비슷한 품질이 나올 수 있게끔 GCP styleguide.md 를 연결해놨다.
git diff를 직접 보면서 리뷰하는 것도 방법이지만, 파일이 10개 넘어가면 집중력이 떨어진다.
에이전트한테 "이 변경사항 보고 이상한 거 없는지 체크해줘" 라고 시키면, 내가 놓친 import 누락이나 타입 불일치를 잡아준다.
물론 이 과정에서 잘 짜여진 Rule 과 가이드 문서가 보강된다면 더욱 꼼꼼해 질 것이다.
Rule을 만들어보고, 실제 아웃풋이 달라지는걸 보면서 느낀건, 이 작업이 결국 팀 내부의 컨벤션을 문서화 하는것과 다를게 없다는 점이다.
팀 노션에 FE Wiki 라는 페이지가 있다. 내가 입사하고 한두달 정도 붙잡아서 최신화 한 후로 아무도 업데이트를 하고 있지 않는 페이지다.
여기 있는 내용을 우리 프로젝트의 Rules 로, 순서가 중요한 규칙은 Workflows로 편입하면 더이상 노션은 볼 필요가 없다.
에이전트에게 바라는 문서가, 추후 새로 합류할 팀원에게 온보딩 문서로, 말로, 코드 리뷰로 말하던 그 내용과 동일하다.
즉, 생산성 측면을 제외하고서도 작업자의 지식을 코드와 가장 가까운 곳에 문서화하는 측면에서 사람에게도 도움이 된다. 이게 에이전트 문서를 잘 작성해야하는 가장 큰 이유가 아닐까.