Antigravity의 AI 에이전트는 대화창이 아니라 프로젝트 안의 Markdown 파일을 읽고 일합니다. 오늘은 규칙 MD(AGENTS.md · Rules), 명세 MD(기획·데이터·API·검증), 기록 MD(작업 로그·결정 로그)를 설계하고, 필요한 MD를 스스로 추가하면서 요구사항 ID 하나씩 동작하는 서비스로 구현합니다.
프롬프트는 대화가 끝나면 사라지지만, MD 파일은 남아서 다음 작업의 AI에게 같은 기준을 전달합니다. 그래서 “잘 묻는 법”보다 “잘 남기는 법”이 먼저입니다.
화살표 버튼이나 키보드 방향키(←/→)로 이동합니다. 버튼(또는 N 키)을 누르면 슬라이드별 강의 노트가 열립니다.
ACE AI SW Startup Training · Day 4
Markdown is the Interface to AI.
Antigravity에게 좋은 코드를 받는 가장 확실한 방법은 더 긴 프롬프트가 아니라, AI가 매번 다시 읽을 수 있는 MD 문서를 프로젝트 안에 만드는 것입니다.
01 · RulesAGENTS.md · .agents/rules — 항상 지킬 규칙
02 · Specs기획·데이터·API·검증 — 무엇을 만들지
03 · Build/plan → 검토 → 구현 — 요구사항 하나씩
04 · TraceAI_WORK_LOG · DECISION_LOG — 남기고 연결
Opening question
“Antigravity야, 주문 키오스크 만들어 줘.” 어제와 오늘, 같은 앱이 나올까요?
대화로만 개발할 때
요청할 때마다 구조·이름·색이 바뀐다
새 대화를 열면 앞에서 정한 결정을 잊는다
요구하지 않은 기능을 “알아서” 추가한다
무엇이 맞는지 판단할 기준이 없다
MD 문서로 개발할 때
AGENTS.md가 매 대화에 같은 규칙을 주입한다
명세 MD의 ID로 범위를 정확히 잠근다
결정은 DECISION_LOG에 남아 다음 AI가 읽는다
수용 기준으로 “완료”를 판정한다
AI의 기억은 대화창이 아니라 파일 시스템에 있습니다. 남기지 않은 결정은, 다음 대화의 AI에게 존재하지 않는 결정입니다.
Analogy · 교대 근무
AI는 매번 새로 출근하는 직원, MD는 인수인계 노트
Why Markdown?
MD는 사람과 AI가 함께 읽는 유일한 계약서
둘 다 읽는다제목·표·체크리스트 구조를 사람도 AI도 똑같이 이해
버전이 남는다Git으로 누가, 언제, 왜 바꿨는지 추적하고 되돌림
콕 집어 준다채팅에서 @order-flow.md처럼 정확한 문서를 지정
도구를 넘나든다Antigravity · Codex · Claude Code가 같은 AGENTS.md를 읽음
The 3-layer MD stack
프로젝트 MD는 3계층 + 1로 나눕니다
새 MD를 만들기 전에 먼저 묻습니다. “이 내용은 규칙인가, 명세인가, 기록인가, 절차인가?” 층을 잘못 고르면 AI가 엉뚱한 때에 읽거나 아예 읽지 않습니다.
Analogy · 학교
MD 3계층 + 1을 학교로 이해하기
1층 · 규칙교칙언제나 지켜요
AGENTS.md.agents/rules/
“문서와 다르면 먼저 물어본다”
2층 · 명세과제 안내문이번에 무엇을 만들까
service-planning/service-analysis/
“REQ-004 장바구니 수량 1~10”
3층 · 기록학습 일지 · 출석부무엇을 했고 왜 그랬나
DECISION_LOGAI_WORK_LOG
“DEC-003 결제는 MVP 제외”
+1 · 절차실험 순서표반복 작업 레시피
.agents/skills/
“/build-req REQ-004”
HANDS-ON 0110분팀 · 분류 게임
이 내용은 몇 층 문서일까?
목표새 MD를 만들기 전에 규칙 · 명세 · 기록 · 절차 중 어디에 둘지 고를 수 있다
규칙Rules · 교칙항상 지킬 것
명세Specs · 과제 안내문이번에 만들 것
기록Logs · 학습 일지한 일 · 결정
절차Skills · 실험 순서표반복 레시피
질문“항상 지키나?” → 규칙 · “이번에 만드나?” → 명세 · “이미 했나?” → 기록 · “매번 같은 순서인가?” → 절차
문서와 다르면 코드 말고 문서 먼저 수정을 제안한다
정답: 규칙
REQ-004 장바구니 수량은 1~10, 0이면 삭제 확인
정답: 명세
AI-002 색상 임의 변경 → 반려 후 재요청
정답: 기록
구현 → 테스트 → 로그 → 추적표 갱신 순서로 진행
정답: 절차
항상 한국어로 답하고 코드 주석은 영어로
정답: 규칙
DEC-003 결제는 MVP에서 제외 (담당 PM)
정답: 기록
0 / 6 분류함
체크하면서 스스로 확인해 보세요
취창업 연결정보를 알맞은 곳에 정리하는 능력은 어느 회사에서나 신입에게 기대하는 기본 업무 역량입니다.
Where Antigravity reads MD
AI가 자동으로 읽는 곳과 불러야 읽는 곳
워크스페이스 구조 예시
kiosk-pbl/
├── AGENTS.md ← 자동 · 항상 적용 (프로젝트 헌법)
├── .agents/
│ ├── rules/ ← 자동 · trigger에 따라 적용
│ │ ├── doc-contract.md
│ │ ├── frontend-style.md
│ │ └── safety.md
│ └── skills/ ← /이름 또는 의도에 맞으면 로드
│ ├── build-req/SKILL.md
│ └── doc-audit/SKILL.md
├── service-planning/ ← 수동 · @멘션 / 문서 지도
├── service-analysis/
├── service-implementation/
└── service-validation/
전역 규칙 (모든 프로젝트)
~/.gemini/GEMINI.md 또는 ~/.gemini/AGENTS.md
~/.gemini/config/rules/*.md
예: “항상 한국어로 답하고, 코드 주석은 영어로”
크기 한도
규칙 파일 1개가 너무 길면 잘림
항상 켜진 규칙 합계에 토큰 예산이 있음
→ 규칙은 짧게, 긴 내용은 명세 MD로 링크
Rule activation · trigger
규칙은 언제 읽힐지까지 설계합니다
모든 규칙을 always_on으로 두면 중요한 규칙이 묻힙니다. “항상 필요한가?”를 기준으로 trigger를 고르세요.
always_on항상 적용매 대화마다 전체 내용이 주입됩니다. 문서 우선 원칙, 금지 사항처럼 짧고 절대적인 규칙만.예: doc-contract.md
glob파일 패턴globs: **/*.css, **/styles/** 처럼 특정 파일을 다룰 때만 자동 적용됩니다.예: frontend-style.md
model_decisionAI가 판단설명(description)만 먼저 보이고, 작업이 맞으면 AI가 스스로 전체를 읽습니다.예: safety.md (개인정보·결제)
manual@멘션할 때만채팅에서 @release-check처럼 직접 부를 때만 들어갑니다.예: release-check.md
Analogy · 전등 스위치
규칙이 언제 켜지는지 전등으로 이해하기
HANDS-ON 0210분짝 · 퀴즈
이 규칙은 어떤 스위치로 켤까?
목표규칙마다 언제 읽혀야 하는지 골라 토큰 낭비와 규칙 묻힘을 막는다
always_on항상 켜진 전등짧고 절대적인 규칙
glob센서등특정 파일을 만질 때
model_decision스마트등AI가 필요할 때 판단
manual벽 스위치@멘션할 때만
1규칙 읽기무엇을 지키는 규칙인가
2언제 필요한가항상? 특정 파일? 가끔?
3스위치 고르기버튼으로 확인
4이유 말하기짝에게 설명
문서 우선 원칙 · 금지 사항 (doc-contract.md)
✓ always_on — 짧고 매번 지켜야 하는 핵심 규칙
*.css 파일에서는 디자인 토큰만 사용
✓ glob — CSS 파일을 만질 때만 필요
개인정보 · 결제를 다룰 때 주의 규칙 (safety.md)
✓ model_decision — 관련 작업일 때 AI가 판단해 읽음
배포 전 최종 체크리스트 (release-check.md)
✓ manual — 배포할 때만 직접 부름
**/*.test.js 테스트 작성 규칙
✓ glob — 테스트 파일을 만질 때만 필요
정답 0 / 5
체크하면서 스스로 확인해 보세요
취창업 연결“무엇을 항상 하고, 무엇을 필요할 때만 하나”를 정하는 것은 업무 자동화 설계의 핵심입니다.
AGENTS.md = project constitution
AGENTS.md에는 6개 블록만 씁니다
AGENTS.md (요약)
# 샌드위치 주문 키오스크
고객은 모바일로 주문, 관리자는 PC에서 주문·품절 관리
## 문서 지도
- 화면·흐름 → service-planning/customer-order/*.md
- 관리자 → service-planning/admin/*.md
- 공통 정책·상태값 → service-planning/common/service-policies.md
- 지표·이벤트 → service-analysis/*.md
- 검증 → service-validation/*.md
## 작업 방식
- 요구사항 ID 하나씩, 코드 전에 계획부터
- 문서와 다르면 코드 말고 문서 먼저 제안
AGENTS.md 해부도
명세 MD는 자동으로 읽히지 않습니다. 문서 지도가 AI의 길잡이입니다.
HANDS-ON 0315분혼자 · 작성
내 프로젝트의 AGENTS.md 만들기
목표AI가 매 대화마다 읽을 프로젝트 헌법(6블록)을 직접 쓴다
16칸 채우기짧게 · 구체적으로
2자동 완성실시간 미리보기
3복사 · 저장프로젝트 루트에
4AI에게 확인“AGENTS.md 요약해 줘”
핵심② 문서 지도가 없으면 AI는 명세 MD가 어디 있는지 모릅니다. 질문별로 읽을 경로를 적어 주세요.
0 / 6
AGENTS.md · 실시간
체크하면서 스스로 확인해 보세요
취창업 연결AGENTS.md는 팀 온보딩 문서와 같습니다. 새 팀원(사람이든 AI든)이 첫날 읽는 문서를 쓸 줄 아는 사람은 리더가 됩니다.
사슬이 끊긴 곳에서 AI는 추측을 시작합니다. 추측된 코드는 다음 요구사항에서 반드시 충돌합니다.
Good spec vs vague spec
AI가 구현할 수 있는 명세 = ID + 규칙 + 상태 + 수용 기준
모호한 명세
## 장바구니
- 편리하게 수량을 바꿀 수 있다
- 합계가 보인다
- 오류가 나면 알려 준다
“편리하게”를 AI가 마음대로 해석
최대 수량·빈 상태·실패 상태 없음
완료를 판정할 기준이 없음
구현 가능한 명세
## REQ-004 장바구니 수량·합계 (UI-C04)
- 수량: 1~10, 0이 되면 삭제 확인
- 합계 = Σ(기본가 + 옵션 추가금) × 수량
- 상태: 정상 / 빈 장바구니 / 품절 포함 / 저장 실패
- AC-1 Given 빈 장바구니 When 진입
Then 주문 버튼 비활성 + 사유 문구
- AC-2 Given 품절 상품 포함 Then 해당 행 경고
- 검증: TEST-006, TEST-007
HANDS-ON 0415분혼자 → 짝 · 고쳐 쓰기
모호한 명세를 구현 가능한 명세로
목표AI가 마음대로 해석할 수 없는 ID + 규칙 + 상태 + 수용 기준 명세를 쓴다
## 메뉴 목록
- 메뉴가 보기 좋게 나온다
- 품절이면 적절히 표시한다
ID REQ-009
숫자 규칙 최대 · 최소 · 개수
상태 정상 / 품절 / 오류
수용 기준 Given … Then …
- 품절이면 적절히 표시한다
자동 검사
ID
숫자 규칙
상태 2개+
Given · Then
빈칸을 채우면 검사해요
체크하면서 스스로 확인해 보세요
취창업 연결모호한 요구를 명확한 요구로 바꾸는 일은 PM · 기획자가 매일 하는 핵심 업무입니다.
When to add a new MD
이런 신호가 보이면 MD를 추가합니다
같은 설명을 3번 반복REPEATED PROMPT“CSS 변수 써 줘”, “한국어로 써 줘”를 매번 입력한다→ .agents/rules/*.md
AI가 같은 실수 반복REPEATED MISTAKE품절 상품을 담게 하거나, 상태값 이름을 바꿔 쓴다→ 규칙에 금지·예시 추가
매번 같은 절차REPEATED PROCEDURE구현 → 테스트 → 로그 → 추적표 갱신을 손으로 시킨다→ .agents/skills/*/SKILL.md
새 화면·기능·정책NEW SCOPE쿠폰, 알림, 관리자 권한처럼 문서에 없는 범위가 생긴다→ service-planning/*.md + REQ ID
결정이 바뀜CHANGED DECISION“픽업 대기 → 완료 자동 전환”처럼 기존 명세와 달라진다→ DECISION_LOG + 원본 명세 수정
HANDS-ON 0510분짝 · 퀴즈
이 신호엔 어떤 MD를 추가할까?
목표개발 중 신호를 보면 어떤 MD를 추가할지 바로 판단한다
반복 설명같은 말을 3번→ 규칙
반복 실수AI가 또 틀림→ 금지 추가
반복 절차매번 같은 순서→ Skill
새 범위 · 결정 변경문서에 없음 · 바뀜→ 명세+REQ · DECISION_LOG
매번 “디자인 토큰 써 줘”라고 입력하고 있다
✓ 규칙 — 같은 설명 3번 반복 → .agents/rules/
AI가 또 품절 상품을 장바구니에 담게 만들었다
✓ 금지 추가 — 같은 실수 반복 → 규칙에 금지·예시
구현 후 매번 로그·추적표 갱신을 손으로 시킨다
✓ Skill — 같은 절차 반복 → SKILL.md
갑자기 쿠폰 기능이 필요해졌다
✓ 명세+REQ — 새 범위 → service-planning + REQ ID
픽업대기 → 완료를 자동으로 바꾸기로 했다
✓ DECISION_LOG — 결정 변경 → DEC 기록 + 원본 명세 수정
정답 0 / 5
체크하면서 스스로 확인해 보세요
취창업 연결반복을 찾아 자동화하는 습관은 생산성이 높은 개발자의 가장 큰 특징입니다.
How to add an MD · 5 steps
새 MD는 5단계를 거쳐야 AI의 기준이 됩니다
① 층 결정규칙·명세·기록·절차 중 어디? 기존 문서에 추가할지 새로 만들지
② 템플릿 + ID템플릿 복사 후 REQ-011, UI-C09 같은 고유 ID 부여
③ 지도에 등록AGENTS.md 문서 지도와 TRACEABILITY.md에 경로 추가
④ AI 교차 감사기존 문서와 용어·ID·상태값 모순과 누락을 검사
⑤ 승인 · 커밋사람이 검토·수정 후 docs: 커밋으로 확정
③을 빼먹으면 문서는 있어도 AI는 그 문서가 있는지 모릅니다. 등록까지가 추가입니다.
Let AI draft, you decide
MD 초안은 AI가, 결정은 사람이
1) 내가 먼저 5줄
목적: 쿠폰으로 첫 주문 할인
사용자: 첫 방문 고객
규칙: 1인 1회, 최소 주문 8,000원
제외: 포인트 적립, 중복 쿠폰
모르는 것: 품절 시 쿠폰 반환?
2) Antigravity에 구조화 요청
@AGENTS.md @service-policies.md 를 참고해
위 초안을 service-planning/coupon-spec.md로
템플릿(목적·REQ·상태·AC·TEST) 형식에 맞춰 작성해.
새 사실을 만들지 말고 [가정]/[질문]으로 표시하고,
기존 문서와 충돌하는 용어·상태값을 목록으로 알려 줘.
파일은 만들되 코드는 수정하지 마.
AI가 표시한 [가정]은 사람이 확인해 [결정]으로 바꾸거나 지웁니다. 확인되지 않은 가정이 남은 문서는 아직 계약이 아닙니다.
Antigravity build loop
구현은 계획 → 검토 → 실행 → 검증 루프로
/plan코드 수정 없이 탐색·질문 후 계획 아티팩트 작성바로 코딩 금지
계획 검토참조 문서 경로, 수정 파일, 범위를 확인하고 댓글로 수정사람의 승인 지점
실행 · 검증단계별 구현 후 수용 기준(AC)별로 동작 확인콘솔 에러 0
기록 · 커밋채택·수정·반려 판단을 로그로 남기고 작은 커밋롤백 가능한 단위
Build contract prompt
구현 요청은 범위를 잠그는 계약입니다
범위 없는 요청
장바구니 기능 만들어 주고
관리자 화면도 같이 해 줘.
디자인도 예쁘게.
여러 파일을 한 번에 갈아엎음
문서에 없는 기능이 추가됨
무엇이 바뀌었는지 리뷰 불가
문서 계약 요청
/plan
service-planning, service-analysis의 승인된 MD만
구현 근거로 사용해줘.
이번 범위는 REQ-004 (UI-C04) 하나다.
코드 작성 전에 관련 문서 경로, 수정할 파일,
불명확한 점을 먼저 보고해.
구현 후에는 변경 파일 목록, 실행 방법,
AC별 확인 결과를 요약해줘.
HANDS-ON 0620분혼자 · Antigravity
/plan 요청 만들고 계획 검토하기
목표범위를 잠근 /plan 요청을 쓰고, AI의 계획을 승인 전에 검토한다
1REQ 고르기이번 범위 하나
2문서 @멘션필요한 MD만
3/plan 실행코드 수정 없이 계획
4계획 검토5가지 체크 후 Proceed
주의계획을 읽지 않고 바로 Proceed를 누르면, 범위 밖 파일까지 바뀔 수 있습니다.
/plan 프롬프트
Implementation Plan 검토
0 / 5
체크하면서 스스로 확인해 보세요
취창업 연결“바로 만들기 전에 계획을 검토한다”는 습관은 실수 비용이 큰 실무 프로젝트에서 가장 신뢰받는 태도입니다.
Cycle 2 · 관리자 PC신규 주문 확인 → 상세 → 상태 변경(접수→조리중→픽업대기→완료) → 품절 관리 (1280px+)@admin/*.md
Cycle 3 · 예외 · 복구필수 옵션 미선택, 품절 차단, 빈 장바구니, 저장 실패 재시도@service-policies.md @test-data.md
Doc drift warning
코드만 고치면, 다음 AI는 옛 문서를 믿습니다
✓ 올바른 순서 — 문서 먼저, 코드는 마지막
① 기록차이와 이유를 DECISION_LOG에 DEC-### 로 남김
② 영향 분석관련 REQ · UI · DATA · API · TEST를 AI에게 찾게 함
③ 문서 수정service-planning 원본 명세를 먼저 수정
④ 승인학생·팀이 변경을 검토하고 승인
⑤ 코드 · 재검증그 다음에 코드 수정, 테스트 재실행
이 5단계를 doc-contract.md 규칙에 넣어 두면, 문서와 다른 구현이 필요할 때 AI가 스스로 멈추고 먼저 물어봅니다.
HANDS-ON 0710분짝 · 순서 맞히기
문서와 다르게 만들고 싶을 때, 올바른 순서는?
목표구현 중 변경이 필요할 때 문서 → 승인 → 코드 순서를 지킨다
상황REQ-012를 구현하다 보니, “픽업대기 → 완료”를 자동으로 바꾸는 게 더 좋아 보인다. 명세에는 관리자가 직접 바꾼다고 적혀 있다.
1카드 읽기5단계 카드
2짝과 상의무엇이 먼저?
3순서대로 누르기칸이 채워짐
4정답 확인코드는 언제?
① 카드를 순서대로 누르세요
② 내가 고른 순서
1…
2…
3…
4…
5…
0 / 5 선택함
체크하면서 스스로 확인해 보세요
취창업 연결변경 관리 절차를 지키는 개발자는 큰 조직 · 공공 프로젝트에서 특히 신뢰받습니다.
Skills · reusable procedures
반복되는 절차는 SKILL.md로 만들어 /호출합니다
.agents/skills/build-req/SKILL.md
---
name: build-req
description: 요구사항 ID 하나를 문서 계약대로 구현할 때 사용.
"REQ-xxx 구현", "/build-req" 요청에 적용.
---
1. TRACEABILITY.md에서 REQ의 UI·DATA·API·TEST 경로를 찾는다
2. 관련 MD만 읽고 불명확한 점을 먼저 질문한다
3. Implementation Plan을 작성하고 승인을 기다린다
4. 최소 범위로 구현하고 AC별로 확인한다
5. AI_WORK_LOG.md에 한 줄을 추가하고 추적표 상태를 갱신한다
Rules vs Skills
Rules: 항상 지킬 원칙 (짧게)
Skills: 특정 작업의 단계별 레시피 (필요할 때만 로드)
description이 구체적일수록 AI가 정확한 때에 사용
채팅에서 /build-req REQ-004로 직접 호출
예전의 Workflows(.agents/workflows)는 Skills로 통합되는 중입니다. 새로 만든다면 Skill로 작성하세요.
Log & verify
완료 선언 전에 기록과 증거를 남깁니다
AI_WORK_LOG.md (1요청 = 1줄)
| AI ID | REQ | 요청 | 결과 | 사람의 수정 | 판단 |
| AI-001 | REQ-004 | 합계 계산 | TEST-006 통과 | 음수 수량 방지 추가 | 수정 채택 |
| AI-002 | REQ-004 | 수량 버튼 UI | 색상 임의 변경 | 디자인 토큰으로 복구 | 반려 후 재요청 |
기능 완료 체크
AC가 모두 브라우저에서 재현된다
콘솔(F12) 에러 0건
360px 모바일 / 1280px PC 레이아웃 정상
명세의 필드명·상태값 = 코드 변수명
TRACEABILITY 상태를 ‘구현됨’으로 갱신
명확한 커밋 메시지: feat(REQ-004): ...
HANDS-ON 0810분혼자 · 기록
AI_WORK_LOG 한 줄 직접 쓰기
목표AI 작업마다 요청 · 결과 · 사람의 수정 · 판단을 한 줄로 남긴다
| AI ID | REQ | 요청 | 결과 | 사람의 수정 | 판단 |
| AI-001 | REQ-004 | 합계 계산 | TEST-006 통과 | 음수 수량 방지 추가 | 수정 채택 |
| AI-002 | REQ-004 | 수량 버튼 UI | 색상 임의 변경 | 디자인 토큰으로 복구 | 반려 후 재요청 |
1AI 요청 1건무엇을 시켰나
2결과 확인테스트 · 화면
3사람의 수정무엇을 고쳤나
4판단 기록채택 · 수정 · 반려
AI_WORK_LOG.md 한 줄
5칸을 채워 주세요
체크하면서 스스로 확인해 보세요
취창업 연결AI와 함께 일한 기록은 “AI를 잘 다루는 개발자”라는 증거로 포트폴리오와 면접에서 바로 쓸 수 있습니다.
Day 4 mission
오늘의 산출물
산출물 1 · 규칙 MD
AGENTS.md (6블록) + .agents/rules 2개 이상 (trigger 다르게)
산출물 2 · 추가 명세 MD
개발 중 발견한 신호로 MD 1개 이상 추가 + 지도·추적표 등록
산출물 3 · 동작하는 REQ
/plan → 검토 → 구현으로 수직 기능 1개 완주
산출물 4 · 기록
AI_WORK_LOG 3건+ (수정·반려 1건+) · TRACEABILITY 갱신
AI를 열기 전에 내 초안과 질문을 먼저 쓴다
실제 개인정보·결제정보·API 키를 MD와 코드에 넣지 않는다
외부 브랜드 로고·문구·이미지를 복제하지 않는다
AI가 만든 MD와 코드는 사람이 읽고 설명할 수 있어야 한다
Takeaway
프롬프트는 사라지고, MD는 남는다.
AI가 잘 일하게 만드는 사람은 더 많이 묻는 사람이 아니라, AI가 읽을 기준을 잘 설계하고 결과를 그 기준으로 판단하는 사람입니다.
설계하는 힘규칙·명세·기록·절차 MD를 층에 맞게 만든다
잠그는 힘요구사항 ID 하나씩 범위를 잠그고 계획을 검토한다
판단하는 책임문서 기준으로 채택·수정·반려하고 기록한다
1 / 31
LECTURE NOTE
Hands-on Lab
오늘의 실습 흐름
예제 프로젝트와 미션 가이드, 평가 루브릭은 문서 주도 서비스 개발 PBL 워크스페이스에서 확인하세요. 아래 템플릿은 그 예제 구조(service-planning · analysis · implementation · validation)에 맞춰져 있습니다.
STEP 01 · 30분
규칙 MD 세팅
루트에 AGENTS.md를 만들고 문서 지도를 채운 뒤, .agents/rules에 trigger가 다른 규칙 2개를 둡니다.
AGENTS.md · rules/
STEP 02 · 40분
명세 감사 & MD 추가
/doc-audit로 기존 명세의 모순·누락을 찾고, 신호에 따라 필요한 MD를 5단계 절차로 추가합니다.
REPORT_DOC_AUDIT · 새 MD
STEP 03 · 90분
REQ 하나 수직 구현
/plan으로 계획을 받고 댓글로 범위를 고친 뒤 Proceed. 브라우저에서 AC를 하나씩 확인합니다.
/build-req REQ-___
STEP 04 · 40분 · 핵심
기록 · 추적 · 회고
AI_WORK_LOG에 수정·반려 판단을 남기고 TRACEABILITY를 갱신합니다. 문서와 달라진 곳은 DECISION_LOG로.
AI-### · DEC-### · TRACE
프로젝트 MD 지도 — 무엇을, 언제 AI가 읽는가
예제 프로젝트 기준입니다. “자동”은 Antigravity가 스스로 읽는 위치, “수동”은 AGENTS.md 문서 지도나 @멘션으로 알려 줘야 읽는 위치입니다.
파일
층 · 역할
AI가 읽는 시점
언제 만들고 갱신하나
AGENTS.md
규칙 · 프로젝트 헌법과 문서 지도
자동 · 매 대화 항상
Day 4 시작 시 작성 · 새 MD를 추가할 때마다 지도 갱신
.agents/rules/doc-contract.md
규칙 · 문서 우선 원칙, 변경 절차
자동 · always_on
AI가 문서를 무시하는 실수를 할 때 금지·예시 추가
.agents/rules/frontend-style.md
규칙 · 디자인 토큰, 반응형, 접근성
자동 · glob (CSS·HTML 파일 작업 시)
디자인 컨셉 확정 후 · 색·간격 규칙이 바뀔 때
.agents/rules/safety.md
규칙 · 개인정보·결제·저작권 경계
자동 · model_decision
데이터·분석·결제 관련 기능을 시작하기 전
.agents/skills/build-req/SKILL.md
절차 · REQ 단위 구현 레시피
의도가 맞을 때 또는 /build-req
구현 요청 프롬프트를 두 번 이상 반복했을 때
.agents/skills/doc-audit/SKILL.md
절차 · 문서 교차 감사
의도가 맞을 때 또는 /doc-audit
새 MD를 추가하거나 명세를 수정한 직후
service-planning/**/*.md
명세 · 화면·흐름·정책·디자인·데이터
수동 · 문서 지도, @멘션, 스킬이 경로로 읽음
미션 2에서 작성 · 새 범위가 생기면 REQ ID와 함께 추가
service-analysis/*.md
명세 · 지표·이벤트·분석 API
수동
이벤트 수집이 필요한 REQ를 구현하기 전
TRACEABILITY.md
기록 · REQ→UI→DATA→API→TEST 사슬
수동 · build-req 스킬 1단계에서 읽음
MD 추가 시 행 추가 · REQ 구현·검증 후 상태 변경
DECISION_LOG.md
기록 · 결정과 변경 이유
수동 · 문서 지도
범위·정책이 바뀌거나 AI 제안을 반려했을 때
service-implementation/AI_WORK_LOG.md
기록 · AI 요청 1건 = 1줄
수동
AI 구현 요청이 끝날 때마다
MD 템플릿 키트 — 복사해서 바로 쓰기
각 블록의 복사 버튼으로 내용을 복사해 표시된 경로에 파일로 저장하세요. 팀 프로젝트에 맞게 [대괄호] 부분을 고칩니다.
규칙 · 루트
AGENTS.md
프로젝트 루트에 둡니다. frontmatter 없이 항상 적용됩니다.
# [서비스 이름] — AGENTS.md
## 1. 한 줄 정의
[고객]은 [모바일]에서 [샌드위치·음료를 주문]하고,
[관리자]는 [PC]에서 [주문 상태·품절]을 관리한다.
## 2. 문서 지도 (질문 → 읽을 문서)
- 범위·결정 → PROJECT_BRIEF.md, DECISION_LOG.md
- 고객 화면·흐름 → service-planning/customer-order/*.md
- 관리자 화면 → service-planning/admin/*.md
- 공통 정책·주문 상태값 → service-planning/common/service-policies.md
- 디자인 → service-planning/design-concept.md
- 지표·이벤트 → service-analysis/*.md
- 검증·테스트 데이터 → service-validation/*.md
- ID 연결 → TRACEABILITY.md
## 3. 기술 스택 · 실행
- HTML/CSS/Vanilla JS, 빌드 없음
- 실행: npx serve service-implementation
- 공통 데이터: service-implementation/shared/store.js
## 4. 작업 방식
- 한 번에 요구사항 ID 하나만 다룬다.
- 코드 수정 전에 관련 문서 경로·수정 파일·불명확한 점을 먼저 보고한다.
- 문서와 다른 구현이 필요하면 코드를 고치지 말고 문서 변경을 먼저 제안한다.
- 작업이 끝나면 AI_WORK_LOG.md에 한 줄을 남긴다.
## 5. 금지 사항
- 문서에 없는 기능·화면·필드를 추가하지 않는다.
- 실제 개인정보·결제정보·API 키를 저장하지 않는다.
- 외부 브랜드의 로고·문구·이미지를 복제하지 않는다.
## 6. 완료 정의
- 해당 REQ의 수용 기준(AC)이 모두 브라우저에서 확인됨
- 콘솔 에러 0건, 360px 모바일 / 1280px PC 정상
- TRACEABILITY.md 상태 갱신
규칙 · always_on
.agents/rules/doc-contract.md
문서 우선 원칙. 짧고 절대적인 규칙만 always_on으로 둡니다.
---
trigger: always_on
description: 문서 계약 우선 원칙과 명세 변경 절차
---
# 문서 계약 규칙
- 구현 근거는 service-planning, service-analysis의 승인된 MD뿐이다.
- 요청에 요구사항 ID가 없으면 먼저 어떤 REQ인지 물어본다.
- 명세에 없는 값은 추측하지 말고 [질문]으로 보고한다.
- 명세의 필드명·상태값을 코드에서 그대로 사용한다.
(예: received / preparing / ready / completed / canceled)
## 문서와 다른 구현이 필요할 때
1. 코드를 수정하지 말고 멈춘다.
2. 차이와 이유를 DECISION_LOG.md 초안(DEC-###)으로 제안한다.
3. 영향받는 REQ·UI·DATA·API·TEST 목록을 보여 준다.
4. 사람의 승인 후 문서 → 코드 순서로 수정한다.
규칙 · glob
.agents/rules/frontend-style.md
CSS·HTML 파일을 다룰 때만 자동 적용됩니다.
---
trigger: glob
globs: **/*.css, **/*.html
description: 디자인 토큰·반응형·접근성 규칙
---
# 프론트엔드 스타일 규칙
- 색·간격·글꼴은 design-concept.md의 CSS 변수만 사용한다.
새 색상 값을 직접 쓰지 않는다.
- 모바일 360px 우선, PC 관리자는 1280px 기준.
- 버튼은 최소 44px 높이, 엄지 영역에 주 동작 배치.
- 상태(품절·오류·필수)는 색 + 아이콘 + 문구로 함께 표시.
- 모든 입력에 label, 아이콘 버튼에 aria-label.
- 로딩·빈·오류·성공 상태를 빠뜨리지 않는다.
절차 · Skill
.agents/skills/build-req/SKILL.md
채팅에서 /build-req REQ-004로 호출합니다.
---
name: build-req
description: 요구사항 ID 하나를 문서 계약대로 구현할 때 사용한다. "REQ-xxx 구현", "기능 구현해 줘", "/build-req" 요청에 적용한다.
---
# 요구사항 단위 구현 절차
1. TRACEABILITY.md에서 대상 REQ의 UI·DATA·API·TEST ID와 문서 경로를 찾는다.
2. 그 문서들만 읽는다. 불명확한 점은 [질문] 목록으로 먼저 보고한다.
3. Implementation Plan을 작성한다.
- 참조 문서 경로 / 수정·생성 파일 / AC별 확인 방법
- 사람의 승인 전에는 파일을 수정하지 않는다.
4. 승인 후 최소 범위로 구현한다. 범위 밖 리팩터링 금지.
5. AC마다 브라우저에서 확인한 결과를 표로 요약한다.
6. service-implementation/AI_WORK_LOG.md에 한 줄을 추가한다.
7. TRACEABILITY.md의 해당 행 상태를 "구현됨"으로 바꾼다.
8. 커밋 메시지를 제안한다: feat(REQ-xxx): [요약]
절차 · Skill
.agents/skills/doc-audit/SKILL.md
새 MD를 추가하거나 명세를 고친 직후 /doc-audit로 실행합니다.
---
name: doc-audit
description: 기획·분석·검증 MD를 교차 검토해 모순과 누락을 찾을 때 사용한다. "문서 감사", "명세 점검", "/doc-audit" 요청에 적용한다.
---
# 문서 교차 감사 절차
새 요구사항을 추가하거나 문서를 수정하지 말고, 찾기만 한다.
1. AGENTS.md의 문서 지도에 있는 모든 MD를 읽는다.
2. 다음을 표로 보고한다.
- 문서 간 용어·ID·주문 상태값 불일치
- 화면 명세에는 있지만 DATA/API 정의가 없는 기능
- TRACEABILITY.md에 없는 REQ, 또는 TEST가 없는 REQ
- 측정할 수 없는 완료 기준 ("편리하다", "빠르다")
- 개인정보·결제·권한·저작권 위험과 사람이 결정할 질문
3. 결과를 service-validation/REPORT_DOC_AUDIT.md 초안으로 제안한다.
명세 · 새 MD
새 기능 명세 템플릿
새 범위가 생겼을 때 service-planning/ 아래에 추가합니다.
# [기능 이름] 명세 — REQ-0__
- 상태: 초안 / 검토 중 / 승인
- 작성: [이름] · 승인: [이름] · 관련 DEC: DEC-___
## 1. 목적
[누가] [어떤 상황에서] [무엇을 위해] 이 기능을 쓴다.
## 2. 범위
- 포함:
- 제외:
## 3. 화면 (UI-___)
| 요소 | 표시 정보 | 사용자 행동 | 다음 상태 |
|---|---|---|---|
## 4. 규칙 · 데이터 (DATA-___)
- [필드]: [타입], [허용 범위], [기본값]
## 5. 상태
- 정상 / 로딩 / 빈 상태 / 오류 / 복구
## 6. API · 이벤트
- API-___ : · EVT-___ :
## 7. 수용 기준
- AC-1 Given [조건] When [행동] Then [결과]
- AC-2
## 8. 검증
- TEST-___ (service-validation/...)
## 9. 열린 질문
- [질문]
기록
DECISION_LOG · AI_WORK_LOG · TRACEABILITY
세 파일의 머리말과 첫 행 예시입니다. 필요한 부분만 나눠 저장하세요.
# DECISION_LOG.md
| DEC ID | 날짜 | 결정 | 이유 · 근거 | 영향 ID | 승인 |
|---|---|---|---|---|---|
| DEC-001 | 2026-11-19 | 픽업 대기 30분 후 자동 완료 | 관리자 누락 방지 | REQ-007, TEST-012 | 팀 |
# service-implementation/AI_WORK_LOG.md
| AI ID | REQ | 요청 | 받은 제안 | 실행 결과 | 사람의 수정 | 판단 · 이유 |
|---|---|---|---|---|---|---|
| AI-001 | REQ-004 | 장바구니 합계 | 합산 함수 | TEST-006 통과 | 음수 수량 방지 | 수정 후 채택 |
# TRACEABILITY.md
| REQ | UI | DATA | API · EVT | TEST | 문서 | 상태 |
|---|---|---|---|---|---|---|
| REQ-004 | UI-C04 | DATA-cart | API-003, EVT-cart_added | TEST-006 | customer-order/order-flow.md | 구현됨 |
프롬프트
Antigravity 실전 프롬프트 모음
상황별로 그대로 붙여 넣어 쓰세요. @는 파일 멘션입니다.
[1] 프로젝트 첫 세팅
이 저장소의 폴더와 MD를 읽고 AGENTS.md 초안을 만들어 줘.
6개 블록(정의·문서 지도·스택·작업 방식·금지·완료 정의) 형식으로,
확실하지 않은 내용은 [질문]으로 표시해. 코드는 수정하지 마.
[2] 새 MD 추가
@AGENTS.md @service-policies.md 참고해서 아래 초안을
service-planning/[파일명].md로 '새 기능 명세 템플릿' 형식에 맞춰 작성해.
새 사실을 만들지 말고 [가정]/[질문]으로 표시하고,
AGENTS.md 문서 지도와 TRACEABILITY.md에 추가할 행도 제안해.
[3] 구현 계획
/plan REQ-___ 를 구현하려고 해. 승인된 MD만 근거로 쓰고,
참조 문서 경로·수정 파일·불명확한 점·AC별 확인 방법을 계획에 넣어 줘.
[4] 오류 분석
아래 콘솔 오류를 분석해 줘. 원인 후보를 먼저 설명하고,
수정은 REQ-___ 범위 안에서 최소로 제안해. [오류 전문 붙여넣기]
[5] 문서-코드 일치 검사
@TRACEABILITY.md 의 '구현됨' REQ마다 명세 필드명·상태값과
실제 코드 변수명이 같은지 표로 비교해. 수정은 하지 마.
[6] 회고
이번 사이클의 AI_WORK_LOG를 읽고, AI가 빠르게 해낸 것 / 놓친 것 /
사람이 고친 것 / 다음에 규칙 MD에 추가할 것을 정리해 줘.