AI Rules 시스템 개선 분석 보고서

### 트리거가 된 실제 사건

guide 2026-04-01 docs/guide/AI_RULES_IMPROVEMENT_ANALYSIS.md

작성일: 2026-04-01
분석 기반: AITEM 프로젝트 실제 사고 사례 + Anthropic 공식 문서 + 업계 리서치
관련 계획: AI_RULES_IMPROVEMENT_PLAN.md

1. 분석 배경

트리거가 된 실제 사건

AITEM 프로젝트에서 신규 기능 구현 시 AI 에이전트가 docs/ui-mockups/에 존재하는 HTML 목업 파일을 발견하지 못하고 임의 디자인으로 UI를 구현. 원인 분석 결과 단순 탐색 실수가 아닌 세 가지 구조적 결함이 동시에 작용한 것으로 확인됨.

결함	설명
INTENT.md가 AI의 유일한 시야	`context.docs`에 없으면 AI가 존재 자체를 모름
신규 프로젝트 Bootstrap 규칙 부재	성숙 프로젝트와 초기 프로젝트를 동일 규칙으로 처리
"스캔 금지" 규칙이 탐색을 막음	`docs/00_INDEX.md`가 없으면 맹목적 준수가 오히려 해가 됨

리서치 범위

Anthropic 공식 문서 (Claude Code Best Practices, Agentic Coding Trends Report 2026)
Linux Foundation AGENTS.md 표준화 동향 (2025년 12월)
33,596개 실제 AI PR 분석 데이터 (Vivek Babu, Jan 2026)
InfoQ AI Context File 연구 (March 2026)
Anthropic Engineering: Effective Harnesses for Long-Running Agents

2. 현재 시스템 강점 (유지할 것)

항목	파일	평가	근거
Plan Mode 규칙	`04-workflow.md`	✅ 업계 최선	Anthropic 공식 4단계 패턴(Explore→Plan→Implement→Commit)과 정확히 일치
SESSION.md HANDOFF 패턴	`06-session.md`	✅ 우수	Anthropic "두 단계 초기화 패턴"(Initializer→Coding Agent)과 동일 구조
WORKLOG 시스템	`04-workflow.md`	✅ 우수	멀티에이전트 핸드오프 맥락 보존의 실증적 효과 확인
git stash drop/clear 금지	`04-workflow.md`	✅ 선제적	문서화된 에이전트 실패 패턴을 이미 방어 중
답변 신뢰도 레이블	`00-identity.md`	✅ 독창적	타 rule 시스템에 없는 차별점
에이전트 모드 3단계	`04-workflow.md`	✅ 실용적	manual/auto/auto-push 스펙트럼이 업계 자율 제어 요구와 정확히 매칭
08-ui-first.md	`08-ui-first.md`	✅ 이미 작성됨	HTML 목업 탐색 절차, auto-fail 기준 포함

3. 구조적 격차 분석

격차 A — Advisory vs. Deterministic 문제 ★★★ (최우선)

현황
현재 rule 시스템 전체가 CLAUDE.md 텍스트(advisory) 형태로만 존재.

리서치 발견
Anthropic 공식 문서:

"Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens."

현재 규칙 중 절대 위반 불가 항목들이 advisory로만 존재:

"보호 브랜치 직접 커밋 금지"
"git push --force 금지"
"migrate reset 차단"

결론: 텍스트 규칙은 AI가 컨텍스트 압박 상황에서 무시할 수 있음. 핵심 가드레일은 Hooks로 이중화 필요.

격차 B — CLAUDE.md 비대화 리스크 ★★★

현황
글로벌 CLAUDE.md가 600줄+. Extension이 profile을 통해 전부 병합되어 더 늘어남.

리서치 발견
InfoQ 연구:

"중요한 규칙이 노이즈에 묻힌다. 200줄 이하 유지 권장."
기준: "Would removing this cause Claude to make mistakes?"

현재 구조 문제
항상 로드되어야 하는 것(보안/git 핵심)과 필요시만 로드할 것(DB 마이그레이션 절차, 환경 세팅, UI 탐색)이 혼재.

결론: Skills 시스템(.claude/skills/)으로 도메인 지식을 분리하면 on-demand 로드 가능. CLAUDE.md는 150줄 이하 핵심 규칙만 유지.

격차 C — 신규 프로젝트 진입 절차 부재 ★★★

현황
06-session.md 세션 시작 절차가 성숙 프로젝트(docs/00_INDEX.md 존재) 기준으로만 작성됨.

실제 사건 연결
docs/00_INDEX.md가 없는 신규 프로젝트에서 05-responses.md의 "전체 스캔 금지" 규칙이 자산 탐색 자체를 차단 → UI 목업 미발견.

결론: 세션 시작 시 프로젝트 성숙도 판별 + Bootstrap 절차 추가 필요. 규칙 간 충돌을 예외 조건으로 명시.

격차 D — Subagent 정의가 텍스트로만 존재 ★★

현황
planner/builder/qa/reviewer/security가 04-workflow.md 텍스트 안에만 언급됨.

Claude Code 실제 기능
.claude/agents/ 디렉토리에 YAML frontmatter 포함 Markdown으로 정의하면:

독립 컨텍스트 윈도우로 실행 (메인 컨텍스트 오염 방지)
도구 접근 제한 (reviewer는 Edit 도구 없음 / security에 Opus 모델 지정)
병렬 실행 가능

결론: agents/ 디렉토리의 base agent 정의를 .claude/agents/ 공식 포맷으로 전환하면 실제 실행 가능한 subagent가 됨.

격차 E — Human-AI 하이브리드 게이트 불균형 ★★

현황
G1~G4 게이트가 있지만 "언제 AI가 자율 진행하고, 언제 사람이 개입하는지" 기준이 작업 유형별로 불명확.

리서치 발견 (33,596개 PR 분석)

"Excellent janitors, but unreliable engineers"
에이전트는 반복적·증분적 작업에 탁월, 의도와 판단이 필요한 구조적 작업에서 실패.
병합 성공률의 최대 예측 변수: 파일 수 적음 + 라인 수 적음

현재 규칙이 놓친 하이브리드 패턴

구분	조건	현재 규칙 상태
AI 단독 자율 실행	tsc/lint/테스트, 문서 업데이트, 1파일 10줄↓ 버그 수정	명시 없음
사람 승인 추가 필요	새 파일 3개↑ 생성, 의존성 추가/제거, API 시그니처 변경	명시 없음
사람이 직접 실행	DB 파괴적 변경, 보호 브랜치 push	✅ 이미 있음

현재 규칙은 "금지" 위주 — "AI가 자동으로 해야 하는 트리거"가 약함.

격차 F — Context 소진 관리 부족 ★★

현황
"30턴 초과 시 새 세션 요청"만 존재.

리서치 발견
Context 70% → 정밀도 저하, 85% → 할루시네이션 증가.

결론: 조사 작업을 Subagent로 위임해서 메인 컨텍스트를 보호하는 패턴을 rule로 명시해야 함.

"많은 파일을 읽는 탐색은 Task tool(Subagent)에 위임 — 결과만 메인으로 받기"

4. AI 기술 방향성 관점 추가 고려사항

AGENTS.md 표준화 물결

2025년 12월 Linux Foundation 표준화. Anthropic·Google·Microsoft·AWS·Block 창립 멤버. 현재 60,000+ 프로젝트 채택.

현재 ai-rules의 adapters/ 구조가 이미 multi-tool 지향이므로, AGENTS.md를 공통 베이스로 하고 CLAUDE.md가 Claude 특화 오버라이드하는 계층 구조 고려 가치 있음.

MCP (Model Context Protocol) 통합 가능성

현재 rule 시스템에 MCP 관련 내용 전무. Claude Code에서 MCP 서버를 통해:

Linear/Jira 이슈 직접 조회 → INTENT.md 자동 생성 가능
Figma/디자인 파일 직접 읽기 → UI 자산 탐색 자동화
DB 스키마 직접 조회 → migration 안전성 자동 검증

성숙한 프로젝트에 MCP 서버가 있다면 rule에서 활용 방법 정의 필요.

Writer/Reviewer 독립 세션 패턴

Anthropic 공식 권장 패턴. 현재 planner → builder → reviewer 시퀀스는 같은 세션 안에서 이루어짐. 신선한 컨텍스트의 독립 리뷰어가 실증적으로 더 효과적. 중장기 방향으로 고려.

5. 핵심 인사이트 요약

#	인사이트	출처
1	Hooks > Advisory Rules: 필수 가드레일은 반드시 hooks로 이중화해야 deterministic 보장	Anthropic 공식 문서
2	CLAUDE.md 길이는 품질과 반비례: 200줄 이하, "이게 없으면 Claude가 실수하나?" 기준	InfoQ 연구
3	LLM 자동생성 context 파일 금지: 성공률 3% 하락 + 비용 20% 증가	InfoQ 연구
4	Scope Discipline이 신뢰의 핵심: 파일 수↓ + 라인 수↓가 병합 성공률 최대 예측 변수	33K PR 분석
5	Multi-agent 전환이 context 문제의 해법: 탐색은 subagent, 구현은 메인 세션	Anthropic Engineering
6	규칙 시스템의 현재 비율: 금지 80% + 절차 20% → 목표: 금지 40% + 자율 트리거 40% + 검증 체크리스트 20%	이번 분석

6. 개선 후 기대 효과

문제	현재	개선 후
AI가 규칙을 무시함	Advisory 텍스트만	Hooks 이중화로 deterministic 보장
신규 프로젝트 자산 누락	Bootstrap 절차 없음	세션 시작 시 프로젝트 타입 자동 판별
자율 실행 범위 불명확	"금지"만 있음	자율 실행 트리거 + 승인 임계치 명시
CLAUDE.md 비대화	모든 것 항상 로드	Skills로 on-demand 분리
조사 중 컨텍스트 소진	위임 패턴 없음	Subagent 위임 규칙 명시