Google 반중력 감사를 자동화하는 방법: 자체 유지 관리 맞춤 기술 및 규칙 구축

📅 작성일: 2026/07/12, 수정일: 2026/07/12 ⏱️ 예상 읽기 시간 약 11분 (4,246자)

Google Antigravity와 같은 AI 어시스턴트를 사용자 정의하면 규칙과 기술을 관리하기에는 너무 많아질 수 있습니다.
이 문서에서는 AI 상담원이 자체 구성을 검토하고 자동으로 최적화할 수 있는 자체 유지 관리 사용자 지정 기술 (반중력 감사) 을 구축하는 방법에 대해 설명합니다.

개요
“구성 혼란” 문제
‘반중력 감사’ 설계
1. 주요 특징
2. 🔄 실행 프로세스 흐름
🔍 반중력 감사 로 스캔한 특정 감사 관점
1. 1. 정적 검증(프로그래밍 방식 검사)
2. 2. AI 정성적 검토 및 튜닝 제안(LLM 기반 점검)
🌐 Selenium을 통한 “외부 사양 및 규칙” 자동 동기화
1. 실행과정
📊 실제 감사 보고서 예시
🛠️ “자동 수정”의 메커니즘
🔄 일일 개발 및 워크플로 통합
🔗 GitHub 리포지토리
결론

Google 반중력 감사를 자동화하는 방법: 자체 유지 관리 맞춤 기술 및 규칙 구축

개요

AI 코딩 도우미(예: Google Antigravity 또는 Claude Code)를 사용하면 구성 파일과 사용자 지정 기술이 빠르게 축적되는 것을 확인할 수 있습니다.이로 인해 “구성 혼란”이 발생할 수 있습니다.이 기사에서는 깔끔한 이식 가능한 디자인 패턴과 함께 구성을 자동으로 스캔, 진단 및 최적화하는 ’반중력 감사’라는 자체 유지 관리 맞춤형 기술을 구축하는 방법을 소개합니다.

“구성 혼란” 문제

AI 코딩 도우미를 도입하면 프로젝트 로컬 및 사용자 전역 폴더 모두에서 동작 규칙(예: RULES.md, AGENTS.md) 및 사용자 정의 스크립트(예: SKILL.md)가 빠르게 구축되는 경우가 많습니다.

이러한 급속한 성장으로 인해 다음과 같은 몇 가지 관리 문제가 발생합니다.
1. 오래된 규칙 : 오래된 지침이 활성 상태로 유지되어 AI의 컨텍스트 창이 복잡해집니다.
2. 손상된 기술 : 누락된 스크립트 참조 또는 오래된 종속성으로 인해 실행이 중단됩니다.
3. 비동기화된 이중 언어 문서 : 한 언어의 문서 업데이트로 인해 다른 언어는 구식이 됩니다.

이러한 파일을 수동으로 검토하는 것은 지루한 작업입니다.우아한 해결책은 AI 구성 감사를 AI 도우미 자체에 위임 하는 것입니다.

‘반중력 감사’ 설계

‘반중력 감사’ 사용자 정의 기술은 대상 디렉터리를 검색하고, 구성 및 기술을 진단하고, 깨끗한 Markdown 진단 보고서를 생성하고, 사소한 문제를 자동 수정하려고 시도합니다.

주요 특징

이중 언어 작업 공간 감지 :
루트 파일(예: SKILL.md, README.md)을 검사하여 일본어 문자 비율을 감지합니다.이 비율에 따라 스킬은 감사 보고서를 일본어 또는 영어로 출력할지 여부를 동적으로 결정합니다.
스킬 무결성 검사 :
YAML 머리말에 필수 속성( 이름 , 설명 )이 포함되어 있는지 확인하고 데드 스크립트 참조에 플래그를 지정합니다.
규칙 중복 제거 :
글로벌 및 프로젝트 수준에서 중복 규칙을 검색하여 정리를 제안합니다.

🔄 실행 프로세스 흐름

다음 다이어그램은 감사 기술 트리거부터 환경 패치 적용까지의 작업 순서를 보여줍니다.

sequenceDiagram autonumber actor Developer as Developer participant Audit as audit.py participant Selenium as Selenium (Headless) participant Spec as Spec Site (Web) participant Agent as AI Agent (LLM) participant Patch as apply_patch.py Developer->>Audit: Launch Skill (python3 scripts/audit.py) rect rgb(240, 248, 255) note right of Audit: Self-Update Phase Audit->>Selenium: Instruct Spec Scraping Selenium->>Spec: Fetch Live Guidelines (Antigravity 2.x) Spec-->>Selenium: Rendered Page DOM Selenium-->>Audit: Crawled Spec Data (Markdown/JSON) note right of Audit: Compare and self-update script if out-of-date end rect rgb(245, 245, 245) note right of Audit: Workspace Scan Phase Audit->>Audit: Scan target folder (.agents/) Audit->>Audit: Detect document language ratio end rect rgb(255, 245, 238) note right of Audit: Verification & Review Phase Audit->>Audit: Run static validations (YAML/JSON schema, Sidecar, MCP etc) Audit-->>Agent: Present static result and file list Agent->>Agent: Run LLM Qualitative Review (analyzing Hooks, Subagents, etc) Agent-->>Audit: Return Qualitative Tuning proposals end Audit-->>Developer: Output Audit Report (audit_report.md) Developer->>Developer: Review suggestions and approve patch Developer->>Patch: Run Patch Command (python3 apply_patch.py --patch [file]) Patch-->>Developer: Safely apply changes to target files

① 자체 업데이트 단계 :
최신 지침과의 동기화를 보장하기 위해 이 기술은 시작 시 공식 사양의 Selenium 기반 크롤링을 시작하고 불일치가 발생하면 자동으로 패치하고 다시 시작합니다.
II 작업 공간 스캔 단계 :
글로벌 및 프로젝트 수준 .agents/ 설정을 검색하고 일본어/영어 비율을 구문 분석하여 올바른 대상 언어로 출력 보고서 형식을 지정합니다.
3 검증 및 검토 단계 :
프로그래밍 방식 검사기(스키마 레이아웃, MCP 엔드포인트, 후크 구문, 사이드카 키)를 실행한 다음 AI 에이전트에 데이터를 전송하여 튜닝 체크리스트를 기반으로 정성적 최적화를 생성합니다.
넷째 신고 및 패치 적용 :
사용자 확인을 위해 Markdown 감사 보고서( audit_report.md )를 저장합니다.승인되면 apply_patch.py 를 사용하여 패치가 안전하게 적용됩니다.

🔍 `반중력 감사` 로 스캔한 특정 감사 관점

AI 개발 환경이 악화되는 것을 방지하기 위해 이 스킬은 LLM을 기반으로 하는 프로그래밍 방식의 “정적 검증”과 “AI 정성적 검토”를 결합한 검사를 수행합니다.

1. 정적 검증(프로그래밍 방식 검사)

audit.py 및 진단 하위 모듈을 사용하면 다음 항목이 자동으로 확인됩니다.

평가항목	세부정보 확인	목표 / 목적
스키마 적합성	`SKILL.md` 에 유효한 YAML 머리말과 적절한 JSON 구문/필수 속성이 포함되어 있는지 확인합니다.	시스템이 사용자 정의 기술을 올바르게 구문 분석하고 로드하는지 확인합니다.
규칙 설명 규칙	규칙 머리말( `rules/*.md` )의 `설명` 이 150자 이내인지 확인합니다.	UI 환경에서 깔끔한 목록 가독성을 유지합니다.
물리적 복제	전역( `~/.gemini/config/` ) 및 로컬( `.agents/` ) 위치에 물리적으로 복사된 중복 규칙 또는 기술 파일을 검색합니다.	구성 충돌을 방지하고 중복 파일을 정리합니다.
사이드카 활성화 ⚡	`sidecar.json` 이 존재하는 경우 `~/.gemini/config/config.json` 에서 `sidecars.<id>.enabled` 가 `false` 로 설정되어 있는지 확인합니다.	구성 키 누락으로 인해 백그라운드 데몬이 시작되지 않는 것을 방지합니다.
플러그인 배치 ⚡	플러그인이 지원되는 경로 `.agents/plugins/` 또는 `_agents/plugins/` 에 올바르게 배치되었는지 확인합니다.	런타임 플러그인 로딩 예외를 방지합니다.
MCP 스키마 확인 ⚡	`mcp_config.json` 의 원격 구성이 지원되지 않는 필드 대신 유효한 `serverUrl` 필드를 사용하는지 확인합니다.	외부 MCP 호스트와의 원격 연결 예외를 방지합니다.
Hook AgentStop 검증 ⚡	`hooks.json` 에 정의된 `AgentStop` 이벤트가 `decision` 필드가 포함된 JSON 출력을 반환하는지 확인합니다.	처리되지 않은 후크로 인해 실행 흐름이 갑자기 종료되는 것을 방지합니다.
두뇌 로그 이력 분석 ⚡	최근 세션 로그 및 오류 발생을 검색하여 반중력 구성 최적화(AUD-08~AUD-10)를 동적으로 진단합니다.	반복적인 컴파일/실행 예외 및 워크플로 마찰을 자동으로 해결합니다.

2. AI 정성적 검토 및 튜닝 제안(LLM 기반 점검)

정적 검사를 실행한 후 AI 에이전트는 구성 파일을 검토하여 구조적 개선을 제안합니다.

평가항목	세부정보 확인	목표 / 목적
후크 변환	Linter 마이그레이션, 서식 지정 또는 테스트 스크립트가 활성 기술 단계 대신 ‘hooks.json’ 이벤트로 실행되도록 제안합니다.	중요한 어설션을 자동화하고 수동 실행 감독을 방지합니다.
글로벌/로컬 배치	재사용 가능한 일반 지침을 전역 설정으로 이동하고 프로젝트별 컨텍스트를 프로젝트 로컬 경로로 이동할 것을 제안합니다.	컨텍스트 창 사용을 최적화하고 규칙 재사용을 개선합니다.
사이드카 마이그레이션	시스템 데몬으로 실행하기 위해 백그라운드 리스너나 반복 크론 작업을 `sidecar.json` 구조로 래핑하는 것을 제안합니다.	활성 대화 실행에서 차단 작업을 오프로드합니다.
하위 에이전트 위임	’invoke_subagent’를 사용하여 무거운 작업(예: 대규모 코드베이스 스캔 또는 E2E 테스트)을 하위 에이전트로 오프로드하도록 제안합니다.	상위 컨텍스트 창 제한(65,536개 토큰)을 우회하고 비동기 작업을 실행합니다.
플러그인 패키징	패키징 관련 기술, 규칙, MCP 설정 및 후크를 하나의 네임스페이스로 구분된 플러그인으로 권장합니다.	맞춤형 기능 관리를 단순화하고 설정을 깔끔하게 배포합니다.
최소 권한 권한	특정 명령 접두사 또는 디렉터리에 대한 와일드카드( `*` ) 실행 권한 범위를 좁힐 것을 제안합니다.	샌드박스 무결성을 유지하고 위험한 명령 실행을 방지합니다.
논리적 통합	“현재 상태 -> 미래 상태” 비교 테이블을 사용하여 병합하여 서로 다른 파일 이름으로 유사한 지침을 공유하는 규칙을 해결합니다.	중복 지침을 제거하고 규칙 토큰 공간을 작게 유지합니다.
안전장치 후크	`--no-verify` 를 사용하여 커밋하거나 설정 구성을 수정하려는 에이전트를 차단하는 후크를 권장합니다.	실수로 검증 표준을 우회하는 것을 방지합니다.
메모리 일관성	진행 파일( `task.md` )과 상태 캐시 JSON 간의 일관성을 검증합니다.	에이전트의 진행률 표시기를 동기화 상태로 유지합니다.
후크 비용 평가	감사는 응답 지연과 불필요한 토큰 청구를 방지하기 위해 시간 초과 및 수량을 연결합니다.	느린 왕복을 방지하여 개발자 경험(DX)을 최적화합니다.
규칙/스킬 추천	프로젝트의 고유 기술 스택 또는 API(예: Vertex AI)와 일치하는 커스텀 규칙/기술을 제안합니다.	기술 스택별 함정을 방지하고 구현 속도를 높입니다.

🌐 Selenium을 통한 “외부 사양 및 규칙” 자동 동기화

규칙 감사의 또 다른 중요한 요소는 “규칙 세트 최신성 관리” 입니다.
AWS 및 GCP와 같은 클라우드 서비스의 공식 사양과 AI 도구 문서(예: Antigravity 자체)는 자주 업데이트됩니다.로컬에 저장된 규칙( RULES.md )이 정적으로 유지되는 경우 AI 도우미는 오래된 구성과 더 이상 사용되지 않는 명령 호출을 계속 생성합니다.

이 문제를 해결하기 위해 ’반중력 감사’는 Selenium(헤드리스 Chrome)을 사용하여 공식 사양 사이트의 자동 웹 크롤링 및 스크래핑 을 지원하여 최신 지침을 가져옵니다.

실행과정

동적 문서 가져오기 : Selenium은 헤드리스 Chrome 인스턴스를 제어하여 표준화된 API가 없는 공개 참조 사이트나 릴리스 노트를 탐색하고 HTML 테이블/문서를 Markdown 또는 JSON으로 변환합니다.
차이 감지 : 크롤링된 실시간 사양과 로컬 규칙(예: port_allocation.md 포트 테이블 또는 명령 매개변수)을 구문 분석하고 비교합니다.
자동 규칙 패치 : 감사 보고서에서 더 이상 사용되지 않는 명령이나 업데이트된 엔드포인트를 사용자에게 경고하여 자동으로 업데이트할 수 있는 필드에 대한 패치 파일을 생성합니다.

이 메커니즘은 사람의 개입 없이 로컬 규칙 컨텍스트가 최신 산업 사양과 동기화된 상태를 유지하도록 보장합니다.

📊 실제 감사 보고서 예시

다음은 반중력 감사 를 실행할 때 생성된 실제 Markdown 보고서 출력의 예입니다.시각적 경고( ❌ 오류 , ⚠️ 경고 )와 GitHub 스타일 경고를 사용하여 문제를 쉽게 식별할 수 있습니다.

# 🛡️ Antigravity Environment Audit Report

> [!NOTE]
> Scan completed at: 2026-07-12 19:40:00 (JST)
> Detected primary language: English (en)

## 📈 Diagnostic Summary

| Category | Checks Run | Issues Found | Auto-fix Status |
| :--- | :---: | :---: | :---: |
| Global Rules (AGENTS.md) | 12 | 1 | 🛠️ Auto-fixed |
| Project Rules (RULES.md) | 8 | 0 | ✅ No issues |
| Custom Skills (skills/) | 15 | 2 | ⚠️ Action Required |

---

## 🚨 Diagnostic Alert Details

### 1. Duplicate Rule in Global Settings
- **File**: `~/.gemini/config/AGENTS.md`
- **Status**: `⚠️ Warning`
- **Details**: The rule forbidding "Chrome automation" duplicates a project-level definition in `.agents/RULES.md`.
- **Action**: Automatically removed the duplicate rule section from the global configuration to optimize context. (**Auto-fix completed**)

### 2. Missing YAML Frontmatter Field in Custom Skill
- **File**: `skills/aws-deploy/SKILL.md`
- **Status**: `❌ Error`
- **Details**: Missing the mandatory `description` field required by the skill loader.
- **Action**: Please open `skills/aws-deploy/SKILL.md` manually and add a suitable description to its frontmatter block.

### 3. Broken Executable Reference in Custom Skill
- **File**: `skills/house-keeping/SKILL.md`
- **Status**: `❌ Error`
- **Details**: The helper script `scripts/cleanup.sh` referenced in `SKILL.md` is missing or lacks executable permissions.
- **Action**: Check if the file exists and verify if `chmod +x` has been run.

🛠️ “자동 수정”의 메커니즘

단순히 문제를 보고하는 것 외에도 반중력 감사 는 특정 구성을 안전하게 해결할 수 있습니다.

자동 채우기 YAML 서문 :
SKILL.md 에 YAML 머리말이 없는 경우 AI 모델은 스킬 콘텐츠를 구문 분석하고 이름과 설명을 동적으로 추론한 다음 파일 상단에 머리말 블록을 자동으로 삽입합니다.
중복 규칙 병합 :
전역 및 로컬에 동일한 규칙이 존재하는 경우 우선 순위가 낮은 전역 규칙을 주석 처리하거나 정리하여 토큰 소비를 최소한으로 유지하는 데 도움이 됩니다.

🔄 일일 개발 및 워크플로 통합

이 감사 워크플로를 일일 개발 주기에 통합하는 것이 좋습니다.

주간 또는 월간 정기 검토(권장) :
규칙 컨텍스트와 기술이 지속적으로 증가하므로 주간 또는 월간 유지 관리일 을 예약하여 감사 스크립트를 실행하세요.이를 통해 로컬 커밋 속도(DX)를 늦추지 않고도 환경 상태 점검 및 정리 작업이 가능합니다.
CI/CD 파이프라인 통합 :
풀 요청 생성 또는 병합 시 CI/CD 환경(예: GitHub Actions)에서 자동으로 감사 스크립트를 실행하여 로컬 커밋 속도를 늦추지 않고 규칙과 기술의 형식이 올바른지 확인합니다.
수동 주문형 지침 :
AI 에이전트와 세션을 시작할 때 간단한 프롬프트를 사용하여 스캔을 요청하세요.
> “자동 감사 기술을 실행하여 현재 사용자 정의 기술 및 규칙을 스캔합니다. 중복된 규칙이나 형식 오류를 자동으로 해결합니다.”

🔗 GitHub 리포지토리

자동 감사 기술에 대한 구성 템플릿과 이 블로그의 소스 코드는 다음 GitHub 리포지토리에서 사용할 수 있습니다.

👉 kanji-shinohara/web-gcp-us-firebase-moderniser-repo

결론

AI 코딩 에이전트의 효율성을 극대화하려면 개발 환경을 체계적이고 최적화된 상태로 유지해야 합니다.자체 유지 관리 작업을 사용자 지정 기술에 위임하면 개발자가 활성 코딩에 집중할 수 있습니다.