【완벽 비교】4대 AI 에이전트 규칙 설계 가이드: Antigravity·Kiro·Claude Code·Codex (AGENTS.md 표준과 특화 확장)

📅 작성일: 2026/11/03, 수정일: 2026/11/07 ⏱️ 예상 읽기 시간 약 22분 (8,701자)

Google Antigravity, Kiro, Claude Code, OpenAI Codex를 아우르는 AI 에이전트 규칙 아키텍처 설계론. AGENTS.md 공통 표준, 150줄 토큰 예산, 지연 로딩, 결정론적 Hooks 방어벽을 해설합니다.

개요
1. 왜 AI 에이전트의 규칙 파일은 무너지는가? (3대 안티패턴)
2. 4대 에이전트 규칙 엔진 철저 비교: 공통 표준 vs 도구별 특화 기능
3. 모든 에이전트에 통하는 보편적 베스트 프랙티스 (Universal Foundation)
4. 【완전 경계 설계】 글로벌 vs 워크스페이스: 무엇을 어디에 정의할 것인가? (Scoping Architecture)
5. 에이전트별 ’특화 기능(Superpowers)’을 극대화하는 실전 테크닉
6. 【결정판】 무너지지 않는 「하이브리드 연합형 규칙 설계」 템플릿
1. 규칙 아키텍처 셀프 진단 체크리스트
7. 마무리
관련 글

개요

일상적인 소프트웨어 개발 업무에서 저는 여러 AI 코딩 에이전트(Google Antigravity, Anthropic Claude Code, Kiro, OpenAI Codex)를 동시에 조합해 사용하고 있습니다. 그런데 이 과정에서 제가 가장 깊이 고민하고 수많은 재작업과 아찔한 사고를 겪었던 지점은 바로 「에이전트 규칙 정의(프롬프트·지시서)의 붕괴와 도구 간 괴리」 였습니다.

처음에는 코딩 컨벤션과 금지 사항을 꼼꼼하게 정리한 문서를 만들어 AGENTS.md 나 CLAUDE.md 에 그대로 붙여넣기만 하면 어느 도구에서든 똑똑하게 동작할 줄 알았습니다. 하지만 여러 프로젝트를 동시에 운영하고 저장소 규모가 커지면서 현장에서는 다음과 같은 뼈아픈 문제들이 연달아 터졌습니다.

복사·붙여넣기 이중 관리로 인한 규칙 충돌(설정 드리프트) : AGENTS.md 와 CLAUDE.md 양쪽에 같은 규약을 적어두고 한쪽만 수정한 결과, 에이전트마다 지시를 다르게 해석해 PR을 올릴 때마다 포맷팅 전쟁이 벌어졌습니다.
규칙 비대화로 인한 컨텍스트 질식과 지시 무시 : “이것도 지키게 해야지, 저것도 주의시켜야지” 하며 규칙을 계속 덧붙이다 보니 1,000줄이 넘는 거대 모놀리스가 되었고, 세션 중반부터 가장 중요한 핵심 규칙을 그냥 지나쳐 버리는( Lost in the Middle 현상) 일이 빈번해졌습니다.
’자연어 부탁’이 부른 파괴적 사고 : “※절대로 main 브랜치에 직접 push 하지 마세요”라고 아무리 강조해서 적어두어도, 컨텍스트가 빡빡해지는 순간 에이전트가 태연하게 git push origin main 을 실행해 식은땀을 흘리게 만들었습니다.
도구마다 숨겨진 동작 차이 : Antigravity에서는 쾌적하게 작동하던 조건부 규칙이 다른 도구에서는 무시되고, Codex에서는 32 KiB 제한에 걸려 뒷부분이 경고 없이 잘려 나가며, Kiro의 동적 파일 참조 문법이 Claude Code에서는 그대로 해석되지 않는 문제가 발생했습니다.

이 글에서는 이러한 현장의 시행착오 끝에 정립한 「4대 AI 에이전트(Antigravity / Kiro / Claude Code / Codex) 규칙 아키텍처 완전 설계론」 을 공유합니다.

모든 도구에서 통용되는 공통 오픈 표준(Universal Foundation) 과 각 도구의 고유 강점을 끌어내는 특화 확장(Specialized Superpowers) 의 경계를 명확히 가르고, 실무에서 무너지지 않는 하이브리드 연합형 규칙 아키텍처(Federated Rules Architecture) 설계도를 공개합니다.

1. 왜 AI 에이전트의 규칙 파일은 무너지는가? (3대 안티패턴)

실무에서 AI 에이전트를 매일 깊숙이 활용하는 엔지니어라면 거의 예외 없이 밟게 되는 3가지 함정이 있습니다.

안티패턴 1: 거대 모놀리스의 컨텍스트 세금 (The Monolithic Context Tax)

“테스트 코드는 반드시 작성할 것”, “커밋 메시지 규칙”, “특정 라이브러리의 구버전 사용 금지”, “클라우드 IAM 최소 권한 원칙…” 등 프로젝트의 모든 규칙을 단일 루트 AGENTS.md 파일에 전부 밀어 넣는 패턴입니다.

에이전트는 매 턴 도구를 호출할 때마다 이 문서 전체를 프롬프트 창에 주입합니다. 규칙이 1,000줄(수천~1만 토큰 이상)에 달하면 매 실행마다 막대한 토큰 비용이 새어 나갈 뿐만 아니라, LLM의 어텐션 메커니즘이 포화 상태에 빠져 정작 가장 중요한 지시를 놓칠 확률이 기하급수적으로 치솟습니다 .

안티패턴 2: 이중 유지보수로 인한 설정 드리프트 (Duplication Drift)

“Claude Code에는 CLAUDE.md 가 필요하고 다른 도구에는 AGENTS.md 가 필요하니까”라며 두 파일에 똑같은 내용을 복사해 관리하는 패턴입니다.
기능이 추가되거나 아키텍처 규칙이 바뀔 때 한쪽 파일만 업데이트하고 다른 쪽을 잊어버리면, 에이전트 A는 최신 규칙으로 코드를 짜고 에이전트 B는 옛날 규칙으로 기존 코드를 덮어쓰며 망가뜨리는 지옥이 시작됩니다.

안티패턴 3: 자연어 ’부탁병’에 의존한 보안 (Plea-Based Security)

“main 브랜치 직접 push 금지”, “시크릿 키 커밋 금지” 같은 절대적인 보안·안전 통제를 Markdown의 정중한 자연어 문장만으로 강제하려는 패턴입니다.
LLM은 확률적 모델이기 때문에 아무리 강한 어조로 적어도 복잡한 다단계 추론 중이나 컨텍스트 압박 상황에서는 프롬프트 지시를 우회할 수 있습니다. 절대 어겨서는 안 되는 규칙은 문장으로 부탁하는 것이 아니라, 훅(Hook)이나 권한 정책·샌드박스로 물리적으로 차단하는 것이 철칙입니다.

2. 4대 에이전트 규칙 엔진 철저 비교: 공통 표준 vs 도구별 특화 기능

현재 주류인 4대 코딩 에이전트가 규칙을 로드하고 처리하는 메커니즘을 최신 사양 기준으로 정리했습니다.

평가 축	Google Antigravity	Kiro (CLI / IDE)	Anthropic Claude Code	OpenAI Codex
주요 규칙 파일	`~/.gemini/config/rules/*.md` `<repo>/AGENTS.md`	`~/.kiro/steering/.md` `.kiro/steering/.md` `AGENTS.md`	`CLAUDE.md` `~/.claude/rules/*.md` `AGENTS.md` (폴백)	`~/.codex/AGENTS.md` `<repo>/AGENTS.md` `AGENTS.override.md`
오픈 표준 `AGENTS.md` 지원	네이티브 지원 (상시 로드)	네이티브 지원 (상시 로드)	폴백 지원 ( `CLAUDE.md` 부재 시)	네이티브 지원 (상위부터 순차 병합)
파일 읽기 상한	모델 컨텍스트 창 의존	프로젝트 의존	컨텍스트 창 의존	기본 32 KiB ( `config.toml` 에서 조정 가능)
조건부 / 동적 로드 기구	YAML Frontmatter ( `glob` , `model_decision` , `manual` )	Steering 설정 (Always, Conditional, Manual)	디렉터리 계층 기반	`AGENTS.override.md` (상위 탐색 차단)
외부 파일 동적 라이브 참조	에이전트 스킬 경유 참조	`#[[file:...]]` 문법 (줄 범위 및 폴더 지원)	`@path/to/file` 참조 문법	인라인 텍스트 기술만 지원
강제 차단 / 실행 가드레일	PreToolUse / PostToolUse 훅	Permission 정책 (allow/ask/deny)	PreToolUse 훅 ( `settings.json` )	`config.toml` 샌드박스 정책

3. 모든 에이전트에 통하는 보편적 베스트 프랙티스 (Universal Foundation)

어떤 에이전트를 쓰더라도 절대 흔들리지 않는 3가지 아키텍처 대원칙이 있습니다.

① 3계층 캐스케이드 (UNIX 계층 모델 계승)

리눅스의 /etc/ → ~/.config/ → ./ 구조와 마찬가지로, 에이전트 규칙도 아래 3계층으로 나누고 「로컬(하위) 설정이 항상 글로벌(상위) 설정을 오버라이드한다」 는 원칙을 철저히 적용합니다.

Global ( ~/.config/ , ~/.gemini/config/rules/ , ~/.claude/rules/ ) : 조직이나 개인의 불변 행동 규범(커밋 작성자 속성, 최소 보안 원칙, 기본 응답 언어).
Workspace Root ( ./AGENTS.md ) : 저장소 전체의 아키텍처 제약, 필수 빌드·테스트 명령어, 디렉터리 구조 규약.
Subdirectory ( ./src/api/AGENTS.md ) : 특정 패키지나 마이크로서비스 고유의 프레임워크 규칙.

② 컨텍스트 예산 (150~200줄의 황금률)

상시 로드되는 루트 AGENTS.md 의 분량은 150~200줄 이내 로 엄격히 제한합니다.
모든 문장에 대해 다음 리트머스 테스트(Litmus Test)를 적용해 보십시오.
> 「이 줄을 지웠을 때, 에이전트가 치명적이거나 되돌릴 수 없는 실수를 저지르는가?」

린터(Linter), 포매터(Formatter), 타입 체커가 자동으로 잡아낼 수 있는 코드 스타일 규칙이나 프레임워크의 흔한 기본 사용법은 과감히 삭제합니다. 에이전트가 코드만 보고 추론할 수 없는 ’프로젝트 고유의 예외 사항’과 ’정확한 빌드·검증 명령어’만 남깁니다.

③ ’규약(Rule)’과 ’절차(Skill)’의 완전 분리

규칙 파일 안에 장황한 배포 매뉴얼이나 다단계 마이그레이션 절차를 적어 넣어서는 안 됩니다.
- Rule ( AGENTS.md ) : 항상 지켜야 할 불변의 판단 기준, 경계선, 금지 사항만 정의합니다.
- Skill ( SKILL.md ) / Runbook : 구체적인 작업 절차, 스크립트, 트러블슈팅 명령어는 별도 스킬로 분리해 필요한 순간에만 온디맨드로 로드하게 만듭니다.

4. 【완전 경계 설계】 글로벌 vs 워크스페이스: 무엇을 어디에 정의할 것인가? (Scoping Architecture)

3계층 캐스케이드 원칙을 이해하더라도, 실무 엔지니어가 그다음으로 가장 많이 막히는 지점은 「구체적으로 어떤 규칙을 글로벌에 두고, 어떤 규칙을 저장소 안에 두어야 하는가」 라는 스코핑(Scoping) 경계 설계입니다.

저 역시 초창기에는 “매번 적기 번거로우니까”라는 이유로 특정 프로젝트 설정을 글로벌 영역에 적어두었다가 다른 고객사 저장소에서 엉뚱한 프로필로 명령이 실행될 뻔한 아찔한 경험을 했고, 반대로 개인 Mac의 로컬 경로를 저장소에 커밋해 팀원의 환경을 깨뜨린 적도 여러 번 있었습니다.

현재 제가 모든 실무 워크플로우에서 엄격하게 적용하고 있는 ’글로벌’과 ’워크스페이스’의 책임 경계 매트릭스는 다음과 같습니다.

책임 경계 매트릭스 (어디에 무엇을 작성할 것인가)

카테고리	글로벌 영역 ( `~/.config/` , `~/.gemini/...` )	워크스페이스 영역 ( `./AGENTS.md` , `./.agents/...` )
아이덴티티 & 속성	오퍼레이터 속성 및 페르소나 ・Git 커밋 작성자 이름(Kanji Shinohara) 및 이메일 ・AI 이름을 내세우지 않는 규약(‘AI 어시스턴트’ 등 표기 금지) ・기본 대화 언어(한국어 정중체, 일본어 `です/ます` , 영어 코드 주석 기준)	프로젝트 담당 팀 및 도메인 맥락 ・사내 프로덕트 호칭 및 프로젝트 명명 규칙 ・담당 리뷰어 및 이해관계자 지정
엔지니어링 원칙	보편적 개발 사상 및 가드레일 ・TDD 원칙(Red-Green-Refactor, 커버리지 80% 이상) ・불변성(Immutability, 원본 변이 금지 및 복사본 반환) ・플랜 퍼스트(구현 전 설계 방향 합의) ・함수 길이 상한(50줄 미만 권장)	구현 스택 & 아키텍처 규약 ・디렉터리 구성 규칙( `features/` , `components/` ) ・상태 관리 및 API 클라이언트 설계(React Query, Zustand) ・디자인 시스템 및 토큰 규약
호스트 머신 & OS 안전 관리	호스트 환경 보호의 절대 방벽 ・로컬 GUI 조작 금지(마우스 이동 및 창 포커스 탈취 차단) ・5자리 포트 번호 충돌 방지(30000~49999 배타적 관리) ・임시 스크립트·캐시 위치 제한(반드시 `/tmp` 사용, 루트 오염 금지) ・백그라운드 데몬 프로세스 기동·종료 원칙	빌드·테스트·개발 실행 명령어 ・정확한 빌드/테스트 명령어( `npm run build` , `pytest` ) ・로컬 개발 서버 기동 명령어( `npm run dev` ) ・정적 분석 및 타입 체크( `tsc --noEmit` , `ruff check` )
보안 & 컴플라이언스	전사 공통 기밀·인증 방어 ・시크릿 정보(API 키, 프라이빗 토큰) 하드코딩 및 커밋 금지 ・자격 증명 스캔 및 외부 유출 차단 ・네트워크 샌드박스 경계 준수	산업 규제 및 도메인 고유 법규 ・금융 규제 준수(무인가 투자 자문·매수 유도·목표 주가 제시 절대 금지) ・광고 표기 의무( `SPONSORED` / 광고 고지 라벨) ・개인정보보호법·GDPR·HIPAA 등 도메인별 컴플라이언스 요건
Git & 릴리스 전략	공통 Git 프로토콜 ・Conventional Commits 형식( `feat:` , `fix:` ) ・HTTPS 연결 강제(SSH 인증 오류 방지) ・병렬 브랜치 작업 시 `git worktree` 격리 원칙	저장소 고유 브랜치 & 배포 파이프라인 ・브랜치 모델( `develop` 통합 → `main` 운영) ・배포 타깃(Firebase Hosting, Cloudflare Pages, Cloud Run 등) ・GCP 프로젝트 ID, AWS 프로필명
컨텍스트 운용	세션 예산 및 서브에이전트 위임 정책 ・대규모 코드 탐색 및 반복 빌드 시도는 서브에이전트로 격리 ・컨텍스트 고갈 방지를 위한 컴팩션·세션 리셋 기준	인라인 참조 및 동적 프로젝트 컨텍스트 ・핵심 스키마 및 타입 정의 파일 경로 참조( `#[[file:...]]` 등) ・주요 아키텍처 설계서 및 README 위치

현장에서 빈발하는 「3대 경계 위반 안티패턴」

이 경계선이 흐려지면 에이전트는 순식간에 개발 현장에 미묘한 버그와 운영 사고를 일으킵니다.

위반 1: 글로벌 영역의 워크스페이스 설정 오염 (Global Leaking)

“매번 설정하기 귀찮으니까”라며 글로벌 규칙( ~/.gemini/config/rules/ 나 ~/.claude/rules/ )에 AWS_PROFILE=company-prod 나 특정 로컬 절대 경로( /Users/user01/workspace/client-a/... )를 박아 넣는 경우입니다.
나중에 개인 토이 프로젝트나 고객사 B의 저장소를 열었을 때, 에이전트가 무의식적으로 고객사 A의 프로필이나 인증 정보를 사용해 명령을 실행하려 들면서 권한 오류로 작업이 멈추거나, 최악의 경우 타사 인프라에 잘못 배포하는 대형 사고 로 이어집니다.

위반 2: 워크스페이스로의 로컬 개인정보·경로 유출 (Workspace Leaking)

저장소의 AGENTS.md 에 본인 Mac 고유의 절대 경로( file:///Users/kanji/... ), 개인 SSH 별칭, 로컬 전용 환경 설정을 적어 그대로 Git에 커밋해 버리는 경우입니다.
CI/CD 파이프라인(GitHub Actions)이나 Linux 컨테이너, 혹은 Windows PC를 쓰는 팀원이 git pull 을 받는 순간 존재하지 않는 경로 때문에 자동화 빌드가 즉시 깨지고, Git 히스토리에는 개인 머신의 내부 디렉터리 구조가 영구히 박제 되는 참사가 벌어집니다.

위반 3: 글로벌 과적재로 인한 ‘컨텍스트 질식’ (Global Bloating)

“언젠가 모든 프로젝트에 도움이 되겠지”라는 생각으로 Next.js, Python, Terraform, Docker, Go, Rust, Tailwind의 베스트 프랙티스를 전부 글로벌 규칙에 우겨 넣는 경우입니다.
에이전트는 단 한 줄짜리 셸 스크립트를 작성하는 가벼운 세션에서도 시작하자마자 10,000 토큰이 넘는 무관한 글로벌 규칙을 머릿속에 강제로 떠안게 됩니다. 그 결과 정작 사용자의 현재 지시를 해석할 컨텍스트 공간이 압박받고 어텐션이 분산되어 할루시네이션과 지시 불이행이 급증 합니다.

UNIX 철학에서 배우는 「배치 판정 체크리스트 (Litmus Test)」

규칙을 어디에 둘지 헷갈릴 때는 다음 두 가지 질문을 스스로에게 던져 보십시오.

「내일 전혀 무관한 새 프로젝트(다른 언어·다른 고객사)를 시작하더라도 이 규칙을 100% 똑같이 적용해야 하는가?」
- YES : 오퍼레이터 성명, TDD 원칙, GUI 조작 금지, 시크릿 유출 차단 등 → Global ( ~/.config/ )
- NO : 특정 프레임워크 규약, 빌드 명령어, 클라우드 프로필, 도메인 법규 등 → Workspace ( AGENTS.md )
「이 규칙이 적힌 파일을 마스킹 없이 그대로 Public GitHub에 전체 공개할 수 있는가?」
- YES : 프로젝트 아키텍처 패턴, 린트·빌드 절차, 코딩 컨벤션 → Workspace ( AGENTS.md )
- NO : 사내 비공개 인증 정보, 개인 머신 환경 설정, 특정 운영 계정 ID → Global 또는 환경 변수

💡 중간 계층의 최적해: Frontmatter를 활용한 ‘조건부 글로벌 규칙’

“여러 프로젝트에서 공통으로 쓰고 싶지만 Terraform을 만질 때 외에는 로드하고 싶지 않은 규칙”(예: 인프라 명명 규칙이나 Dockerfile 작성법)은 Antigravity의 trigger: glob: "**/*.tf" 나 Kiro의 조건부 Steering을 활용합니다. 파일 자체는 글로벌 영역에 두되, 매칭되는 파일이 실제로 열렸을 때만 컨텍스트에 지연 주입하는 설계 가 가장 세련된 Gen 3 운용법입니다.

5. 에이전트별 ’특화 기능(Superpowers)’을 극대화하는 실전 테크닉

보편적인 기반을 다졌다면, 이제 각 도구의 고유 기능을 적재적소에 결합해 레버리지를 극대화할 차례입니다.

1. Google Antigravity: YAML Frontmatter 기반 지연 로딩 (Lazy-Loading)

Antigravity의 가장 강력한 무기는 ~/.gemini/config/rules/*.md 에서 지원하는 세밀한 YAML Frontmatter 조건 지정 입니다.

---
trigger: glob
globs: "**/*.tf, **/*.tfvars, infra/**/*.yaml"
description: Terraform naming conventions and provider requirements
---
## 인프라 명명 규칙
- 리소스 이름에는 반드시 환경 프리픽스(prd, stg, dev)를 포함해야 합니다.

glob : 관련 파일을 열었을 때만 규칙을 주입하므로, 프론트엔드 UI 작업 중에 무거운 인프라나 마이그레이션 규칙으로 토큰을 낭비하는 일이 없습니다.
model_decision : 평소에는 가벼운 description 만 에이전트에 인지시켜 두고, 에이전트가 “이 작업에 해당 규칙이 필요하다”고 판단한 순간에만 본문 전체를 로드합니다.

2. Kiro: `#[[file:...]]` 라이브 참조와 Steering

Kiro는 Steering 문서 안에 실제 소스 코드 파일을 동적으로 임베딩하는 라이브 참조 문법을 지원합니다.

## API 에러 핸들링 규약
모든 에러 응답 페이로드는 아래 중앙 스키마 정의를 엄격히 준수해야 합니다:
#[[file:src/types/api_errors.ts]]

문서 안에 코드 조각을 복사해 붙여넣을 필요가 없으며, 실제 타입 정의 코드가 수정되면 에이전트의 Steering 컨텍스트도 자동으로 최신 상태를 유지합니다. 또한 /context show 명령어로 현재 세션에 어떤 규칙이 주입되어 있는지 실시간으로 확인하고 디버깅할 수 있습니다.

3. Anthropic Claude Code: ’심볼릭 링크의 함정’과 크로스 플랫폼 정석 해법 ( @AGENTS.md & Hooks 방벽)

Claude Code는 저장소 루트에 CLAUDE.md 가 존재하면 AGENTS.md 보다 우선해서 읽어들입니다.
이때 많은 macOS / Linux 엔지니어가 「 CLAUDE.md -> AGENTS.md 심볼릭 링크만 걸어두면 끝」 이라는 로컬 편법에 손을 대곤 하지만, 팀 개발이나 Windows 환경이 섞인 실무 현장에서는 치명적인 무음(Silent) 장애 를 일으킵니다.

⚠️ Windows 환경에서 발생하는 「9바이트 무음 규칙 증발 사고」

Windows(Git for Windows)는 기본 설정에서 심볼릭 링크가 비활성화( core.symlinks = false )되어 있습니다.
Windows 개발자가 심볼릭 링크가 포함된 저장소를 git clone 하면, CLAUDE.md 는 실제 링크가 아니라 단순히 "AGENTS.md" 라는 문자열 9바이트만 적힌 평문 텍스트 파일 로 생성됩니다.
그 결과 Claude Code는 아무런 경고도 띄우지 않은 채 이 9바이트짜리 껍데기를 전체 지시서로 읽어 들이며, 모든 안전 규칙과 아키텍처 가이드라인이 소리 소문 없이 통째로 증발한 상태로 동작 하는 최악의 사태에 빠집니다.

✅ OS에 구애받지 않는 결정판 접근법 (2가지 권장 해법)

정석: 네이티브 @AGENTS.md 인클루드 문법 활용 (권장)
CLAUDE.md 를 일반 텍스트 파일로 생성하고 첫 줄에 @AGENTS.md 임포트 지시자를 작성합니다.
```
@AGENTS.md

## Claude Code 전용 지시사항
- (Claude Code에서만 추가로 적용할 동작이나 서브에이전트 역할이 있다면 이곳에만 작성)
```
순수 텍스트 파일이므로 Windows, macOS, Linux, 컨테이너 CI 러너 어디서든 100% 결정론적으로 전개되며, Claude 전용 추가 지시도 깔끔하게 분리할 수 있습니다.
대안: 애초에 CLAUDE.md 를 두지 않기 (제로 설정 폴백 위임)
Claude Code는 저장소에 CLAUDE.md 가 아예 없으면 자동으로 AGENTS.md 를 찾아 폴백(Fallback) 로드하는 공식 사양 을 갖추고 있습니다. Claude 전용 프롬프트가 필요 없는 프로젝트라면 AGENTS.md 단 한 장만 유지하는 것이 가장 깔끔한 무보수 패턴입니다.

나아가 절대 깨져서는 안 되는 보안 경계는 프롬프트 문장으로 애원하지 않고 .claude/settings.json 의 결정론적 PreToolUse 훅으로 기계적으로 차단합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 scripts/secret_guard.py"
          }
        ]
      }
    ]
  }
}

Warning

실전 주의사항 1: 훅이 스스로를 가두는 ’셀프 락아웃(Self-Lockout) 함정’을 피하라
PreToolUse 훅에서 시크릿(OpenAI/Anthropic API 키 등)을 검사할 때 단어 경계 없는 단순 정규표현식(예: sk-[A-Za-z0-9_-]+ )을 쓰면, 일반 Markdown 본문 속 risk-assessment-workflow... 같은 케밥 케이스 문자열까지 오탐지해 종료 코드 2를 반환합니다. 이 순간 Claude Code는 파일 읽기와 편집을 포함한 이후의 모든 도구 실행을 차단 하여 에이전트가 문제를 고치지도 못한 채 영구 락에 걸리는 사고가 발생합니다.
반드시 엄격한 단어 경계( \b )를 지정하고, 로컬 개발용 .env 나 테스트용 더미 파일은 안전하게 예외 처리하는 페일 오픈(Fail-Open) 설계를 적용하십시오.

Tip

실전 주의사항 2: 기존 규칙 덮어쓰기 사고를 막는 인스톨러 설계 ( install.py )
새 프로젝트나 팀원의 저장소에 표준 규칙 팩을 배포할 때 수동 cp 명령어를 쓰면 기존에 공들여 작성한 AGENTS.md 나 CLAUDE.md 를 경고 없이 덮어쓰는 사고가 자주 일어납니다. 기존 파일을 자동으로 .bak 으로 백업하고 병합을 안내하는 설치 스크립트( install.py )를 마련해 두는 것이 팀 도입의 베스트 프랙티스입니다.

4. OpenAI Codex: `AGENTS.override.md` 를 통한 깔끔한 컨텍스트 차단

대규모 모노레포에서 상위 디렉터리의 방대한 규약을 특정 서브 패키지나 격리 영역에서 완전히 끊어내고 싶을 때 Codex의 AGENTS.override.md 가 큰 위력을 발휘합니다. 이 파일을 배치한 디렉터리 하위에서는 상위 AGENTS.md 탐색이 즉시 중단되어, 군더더기 없는 깨끗한 컨텍스트로 작업을 수행할 수 있습니다.

또한 Codex의 기본 문서 읽기 상한이 32 KiB 라는 점도 반드시 기억해야 합니다. 거대한 규칙 파일을 두면 파일 끝부분이 아무 경고 없이 잘려 나가므로, config.toml 의 project_doc_max_bytes 를 조정하거나 규칙 자체를 슬림하게 유지해야 합니다.

6. 【결정판】 무너지지 않는 「하이브리드 연합형 규칙 설계」 템플릿

4가지 에이전트 모두가 하나의 저장소에서 충돌 없이 조화롭게 동작하도록 제가 실무에서 사용하는 표준 디렉터리 구조입니다.

my-project/
├── AGENTS.md                  # [SSOT] 전 에이전트 공통 핵심 규칙 (200줄 미만)
├── CLAUDE.md                  # Claude 전용 (@AGENTS.md 인클루드로 Windows 호환 100% 보장)
├── .kiro/
│   └── steering/              # Kiro 전용 파일 매칭 조건부 규칙 & #[[file:...]]
├── .gemini/ (또는 global)
│   └── rules/                 # Antigravity 전용 glob / model_decision 조건부 규칙
├── .codex/
│   └── config.toml            # Codex 바이트 상한 및 샌드박스 정책 정의
└── .agents/
    └── hooks.json             # 사고를 물리적으로 차단하는 PreToolUse / PostToolUse 가드레일

규칙 아키텍처 셀프 진단 체크리스트

루트 AGENTS.md 의 분량이 200줄 이하로 유지되고 있는가?
글로벌(오퍼레이터 속성·호스트 머신 보호)과 워크스페이스(빌드·기술 스택)의 책임이 엄격히 분리되어 있는가?
포매터나 린터가 자동으로 잡을 수 있는 코드 스타일 규칙을 장황한 문장으로 적어두지 않았는가?
CLAUDE.md 를 복사·이중 관리하지 않고 @AGENTS.md 인클루드 또는 네이티브 폴백으로 OS 심볼릭 링크 함정을 피했는가?
절대 해서는 안 될 파괴적 조작을 자연어 부탁이 아닌 결정론적 훅과 권한 정책으로 막고 있는가?
긴 운영 매뉴얼과 스크립트는 온디맨드 SKILL.md 나 docs/ 로 분리했는가?

7. 마무리

AI 코딩 에이전트의 규칙 관리는 이제 프롬프트 입력창에 주의사항 몇 줄을 덧붙이던 수준을 완전히 넘어섰습니다.

글로벌과 워크스페이스의 스코프 경계를 엄격히 분리한다 (인증 정보 및 로컬 경로 유출 원천 차단)
기반 규칙은 벤더 중립적인 AGENTS.md 단일 정본(SSOT)으로 집약한다
토큰 예산(150~200줄 이내)을 철저히 지켜 컨텍스트 포화를 막는다
Antigravity의 Frontmatter, Kiro의 라이브 참조, Claude Code의 훅, Codex의 오버라이드 등 도구별 특화 무기를 적재적소에 결합한다
반드시 지켜야 할 안전 제약은 문장이 아니라 결정론적 훅으로 물리적으로 멈춰 세운다

이 다섯 가지 기둥만 단단히 세워 두어도 에이전트의 어이없는 재작업과 지시 무시가 극적으로 줄어들며, 여러 에이전트를 매끄럽게 오케스트레이션하는 예측 가능하고 빠른 자율 개발 환경을 구축할 수 있습니다. 오늘 바로 여러분의 저장소에 있는 규칙 파일부터 점검해 보시기 바랍니다.