ai-rules › handbook › AI Rules 시스템 개선 계획안

AI Rules 시스템 개선 계획안

``` Phase 1 (즉시) — rule 파일 텍스트 수정 (3개 파일) Phase 2 (단기) — 신규 core 파일 추가 (2개 파일) Phase 3 (중기) — 구조 개선 (Hooks 가이드 + Subagent 포맷 전환) Phase 4 (장기

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

작성일: 2026-04-01
분석 기반 문서: AI_RULES_IMPROVEMENT_ANALYSIS.md
브랜치: feature/260401-worklog-failure-learning
상태: 계획 수립 완료 — 사용자 승인 후 단계별 실행

전체 로드맵 요약

Phase 1 (즉시)  — rule 파일 텍스트 수정 (3개 파일)
Phase 2 (단기)  — 신규 core 파일 추가 (2개 파일)
Phase 3 (중기)  — 구조 개선 (Hooks 가이드 + Subagent 포맷 전환)
Phase 4 (장기)  — CLAUDE.md 슬리밍 + AGENTS.md 표준 대응

Phase 1 — 텍스트 수정 (즉시 실행 가능)

코드 변경 없음. 기존 파일 수정만. 작업 시간: ~30분

P1-1. core/05-responses.md — 스캔 금지 예외 조건 추가

현재

## 리포 스캔 금지
전체 저장소 스캔 금지 — CLAUDE.md / INTENT.md / docs index에서 참조된 파일만 읽기.

수정 후

## 리포 스캔 금지

전체 저장소 스캔 금지 — CLAUDE.md / INTENT.md / docs index에서 참조된 파일만 읽기.

**예외 조건 — 탐색 앵커 부재 시 (신규/초기 프로젝트)**:
아래 중 하나라도 해당하면 세션 시작 시 제한적 1회 탐색 허용:
- `docs/00_INDEX.md` 없음
- `INTENT.md` 없음
- `docs/` 디렉토리 자체 없음

탐색 허용 범위:
1. 프로젝트 루트 기준 `*.html` 파일
2. `docs/`, `ui-mockups/`, `mockups/`, `wireframes/`, `design/` 디렉토리 구조 1단계

탐색 후 발견된 자산을 사용자에게 보고하고, INTENT.md가 있으면 `context.docs`에 등록.
이후에는 일반 규칙 적용.

왜: 단일 조건보다 "탐색 앵커 부재" 개념이 신규/초기 프로젝트를 더 정확히 커버함.

P1-2. core/06-session.md — 세션 시작에 프로젝트 타입 판별 추가

현재

## 세션 시작

1. `~/.claude/ACTIVE_WORK.md` 확인
2. SESSION.md HANDOFF 블록 확인
3. WORKLOG/ 최신 파일 1개 확인
4. INTENT.md 확인
5. git status 확인

수정 후

## 세션 시작

### Step 0 — 탐색 앵커 확인 (신규 추가)

아래 중 하나라도 해당하면 **신규/초기 프로젝트**로 판별 → Bootstrap 절차 실행:

| 조건 | 판별 결과 |
|------|---------|
| `docs/00_INDEX.md` 없음 | 신규/초기 프로젝트 |
| `INTENT.md` 없음 | 신규/초기 프로젝트 |
| `docs/` 디렉토리 없음 | 신규/초기 프로젝트 |
| 모두 있음 | 성숙 프로젝트 → Step 1~5 바로 진행 |

**Bootstrap 절차** (신규 프로젝트 한정):
1. 아래 범위만 제한적 1회 탐색:
   - 프로젝트 루트 `*.html` 파일 (`node_modules`, `.git`, `dist`, `build`, `index.html` 제외)
   - `docs/`, `ui-mockups/`, `mockups/`, `wireframes/`, `design/` 디렉토리 구조
   - `docs/guide/`, `docs/design/` 존재 여부
2. 발견된 자산 목록을 사용자에게 먼저 보고
3. INTENT.md가 있으면 `context.docs`에 자산 경로 등록
4. HTML 목업이 있으면 `08-ui-first.md` 탐색 절차 실행
5. 이후 Step 1~5 정상 진행

### Step 1~5 (기존 유지)
1. `~/.claude/ACTIVE_WORK.md` 확인
2. SESSION.md HANDOFF 블록 확인
3. WORKLOG/ 최신 파일 1개 확인
4. INTENT.md 확인
5. git status 확인

왜: 신규 프로젝트에서 성숙 프로젝트 규칙을 그대로 적용하면 필수 자산을 발견하지 못함.

P1-3. core/04-workflow.md — AI 자율 실행 트리거 명시

현재: Plan Mode 필수/불필요 기준만 있고, 작업 유형별 자율 실행 기준 없음.

추가할 섹션

## AI 자율 실행 vs. 사람 승인 기준

**상위 원칙**: 아래 세 가지를 모두 만족하면 AI 단독 자율 실행 가능.
- 영향 범위 작음
- 의도 명확
- 검증 가능

### AI 단독 자율 실행 (승인 불필요)
- tsc --noEmit, lint, 테스트 실행
- 조사·분석·보고서 작성 (코드 변경 없음)
- 단순 버그 수정 — 위 상위 원칙 3개 충족 시 (예: 1파일, 10줄 이하)
- 문서 업데이트, 주석 추가
- 탐색 작업 → Task tool(Subagent)에 위임 (메인 컨텍스트 보호)

### 추가 승인 필요 (현재 명시 없던 항목)
- 새 파일 3개 이상 생성
- 기존 의존성 추가/제거 (package.json, requirements.txt 등)
- API 시그니처 변경 (함수명, 파라미터, 반환 타입)
- 에러 핸들링 패턴 변경
- 1문장으로 설명 불가능한 diff

### 사람이 직접 실행 (에이전트 실행 금지 — 기존 유지)
- DB 파괴적 변경 (07-db.md 참조)
- 보호 브랜치 push (01-git.md 참조)
- .env 파일 수정

### Context 소진 방지
대화 30턴 초과 또는 응답 느려짐 → SESSION.md 스냅샷 후 새 세션 요청.
많은 파일을 읽는 탐색 작업은 Task tool(Subagent)에 위임 — 결과만 메인으로 받기.

왜: 현재 규칙이 "금지" 위주이고 "AI가 자동으로 해야 하는 트리거"가 약해서 불필요한 승인 요청이 발생하거나 반대로 판단 없이 과도한 범위를 작업함.

Phase 2 — 신규 core 파일 추가 (단기)

신규 파일 2개 생성. Phase 1 완료 후 진행.

P2-1. core/09-hooks-guide.md — Advisory → Deterministic 전환 가이드

목적: CLAUDE.md 텍스트 규칙과 Hooks의 역할을 명확히 구분. 어떤 규칙을 hook으로 올려야 하는지 판단 기준 제공.

파일 구성 초안

# 09-hooks-guide — Hooks 활용 가이드

## Advisory vs. Deterministic

| 유형 | 구현 방식 | 보장 수준 |
|------|---------|---------|
| Advisory | CLAUDE.md 텍스트 | AI가 따르려 노력함 (컨텍스트 압박 시 무시 가능) |
| Deterministic | Hooks (.claude/settings.json) | 항상 실행됨 (AI 의지와 무관) |

## Hook 우선순위 분류

### must-hook
반드시 hook으로 이중화해야 하는 규칙:
- 보호 브랜치 커밋/푸시 차단
- DB 파괴 명령어 차단
- 민감 파일 수정 감시

### should-hook
hook이 있으면 실수를 크게 줄이는 규칙:
- 커밋 전 tsc 검증
- 파일 수정 후 lint/format

### text-only
판단과 예외가 많아 텍스트 규칙이 적합한 영역:
- 커밋 메시지 형식
- 코드 주석 스타일
- 응답 형식 규칙

## 프로젝트별 Hook 설정 위치

.claude/settings.json:
{
  "hooks": {
    "pre-tool-use": [...],
    "post-tool-use": [...]
  }
}

참고: 실제 hook 스크립트는 각 프로젝트 .claude/hooks/ 디렉토리에 구현. 이 파일은 "어떤 것을 hook으로 올려야 하는가"의 판단 기준만 제공.

P2-2. core/10-subagent-patterns.md — Subagent 활용 패턴

목적: 현재 텍스트로만 언급된 에이전트 팀을 실제 Claude Code Subagent 포맷으로 정의하는 가이드.

파일 구성 초안

# 10-subagent-patterns — Subagent 활용 패턴

## 왜 Subagent인가

메인 세션에서 탐색 작업을 수행하면 컨텍스트 윈도우를 소비.
Subagent는 독립 컨텍스트로 실행되어 메인 세션을 오염시키지 않음.

핵심 목적:
- 컨텍스트 보호
- 역할 분리
- 권한 제한

## Subagent 정의 포맷 (.claude/agents/)

파일: .claude/agents/{agent-name}.md
---
name: reviewer
description: PR 생성 전 코드 리뷰. 수정 없이 읽기와 분석만.
model: claude-opus-4-6        # 선택. 리뷰는 정밀도가 중요
tools: Read, Glob, Grep       # Edit 없음 — 리뷰어는 수정하지 않음
---
[리뷰어 지침...]

## 역할별 권한 기본 원칙

- `planner`: read-only
- `reviewer`: read-only, edit 금지
- `security`: shell 제한, 보안 중심 분석
- `builder`: 수정 가능, 검증 필수

## 핵심 패턴: 탐색은 Subagent, 구현은 메인

탐색 작업(파일 읽기, 검색, 분석)을 메인에서 직접 하지 않고
Task tool로 Subagent에 위임 → 결과만 메인으로 수신.

적합한 위임 작업:
- 프로젝트 구조 전체 분석
- 의존성 관계 조사
- 기존 패턴 코드베이스 검색
- 보안 취약점 스캔

## base agent → .claude/agents/ 전환 계획

현재 agents/ 디렉토리의 base 정의를
각 프로젝트 .claude/agents/ 포맷으로 sync하는 것은
adapters/claude-code adapter에서 처리.

Phase 3 — 구조 개선 (중기)

Phase 1, 2 완료 후. 프로젝트별 적용 범위 조율 필요.

P3-1. agents/ 포맷 → .claude/agents/ 공식 포맷 전환

현재: agents/base-*.md가 Claude Code 공식 subagent 포맷이 아님
목표: 역할별 권한표를 먼저 정의한 뒤, YAML frontmatter 추가로 실제 실행 가능한 subagent로 전환

사전 작업:
1. planner / builder / reviewer / security 권한표 작성
2. 각 agent의 입력 / 출력 / 금지사항 정의

변경 대상:
agents/base-builder.md    → name, description, model, tools frontmatter 추가
agents/base-planner.md    → 동일
agents/base-qa.md         → 동일
agents/base-reviewer.md   → model: claude-opus-4-6 (정밀도 중요)
agents/base-security.md   → model: claude-opus-4-6, tools 제한

adapters/claude-code adapter: 프로젝트별 .claude/agents/ 출력 시 frontmatter 포함하도록 수정.

P3-2. aitem-frontend.md 중복 제거

현재 중복 항목 (core/02-code.md에 이미 있음):

  • fetch/axios 컴포넌트 직접 사용 금지
  • dangerouslySetInnerHTML + DOMPurify
  • console.log/warn DEV 조건
  • 하드코딩 색상값 금지
  • 임의 간격값 금지

aitem-frontend.md에 남길 것 (AITEM 전용):

  • index.css CSS 변수 임의 변경 금지 → designer 에이전트 소환
  • DESIGN_TOKENS.md에 없는 토큰 직접 추가 금지 → designer 에이전트 소환
  • DO_NOT_CHANGE.md 폰트 규칙(#3~#5) 위반 금지
  • 커밋 전 셀프 체크리스트 (이것은 중복이지만 체크리스트 형식으로 유지 가치 있음)

Phase 4 — 장기 개선 (선택적)

필요성이 확인된 시점에 진행. 지금 당장 필수는 아님.

P4-1. CLAUDE.md 슬리밍 + Skills 분리

목표: 글로벌 CLAUDE.md 600줄+ → 150줄 이하

항상 로드 (CLAUDE.md 유지):
- 00-identity 핵심 (규칙 우선순위, 언어 규칙, 신뢰도 레이블)
- 01-git 핵심 (금지 명령어, 브랜치 규칙, 커밋 형식)
- 03-security 핵심 (Hard Ban 목록)
- 04-workflow 핵심 (모드, Plan Mode 필수 기준)

필요시 로드 (.claude/skills/ 분리):
- DB 마이그레이션 전체 절차 (07-db.md)
- 로컬 환경 세팅 체크리스트 (08-local-env.md)
- UI 목업 탐색 절차 (08-ui-first.md)
- 응답 형식 상세 (05-responses.md)

P4-2. AGENTS.md 표준 레이어 추가

우선 결정할 것:

  1. AGENTS.md를 장기 canonical source로 볼지
  2. CLAUDE.md를 Claude 특화 override로 축소할지

그 다음 구현:

  • adapters/ 에 agents-md.mjs 추가 → AGENTS.md 포맷 출력
  • 다른 AI 도구(Cursor, Windsurf, Codex)에서도 동일 rule 사용 가능

P4-3. MCP 통합 Extension 가이드

Linear/Jira MCP → INTENT.md 자동 생성
Figma MCP → UI 자산 자동 탐색
DB MCP → migration 안전성 자동 검증
이를 rule 시스템에서 어떻게 활용하는지 extension 가이드 추가.

실행 체크리스트

Phase 1 (즉시 — 오늘)

  • core/05-responses.md — 스캔 금지 예외 조건 추가
  • core/06-session.md — Step 0 프로젝트 타입 판별 추가
  • core/04-workflow.md — AI 자율 실행 트리거 섹션 추가
  • scripts/sync.mjs 실행 → CLAUDE.md 재생성
  • 변경 내용 커밋 → feature 브랜치 push → PR

Phase 2 (이번 주)

  • core/09-hooks-guide.md 신규 생성
  • core/10-subagent-patterns.md 신규 생성
  • sync → CLAUDE.md 재생성 → PR

Phase 3 (다음 주)

  • agents/base-*.md frontmatter 추가
  • adapters/claude-code.mjs subagent 출력 지원 수정
  • extensions/aitem-frontend.md 중복 항목 제거

Phase 4 (필요 시 결정)

  • CLAUDE.md 슬리밍 계획 확정
  • AGENTS.md adapter 구현
  • MCP extension 가이드 작성

판단 기준 요약

각 변경의 "왜 지금 해야 하는가"를 1줄로:

Phase 핵심 이유
P1 코드 변경 없이 즉시 실제 사고 재발 방지 가능
P2 "텍스트로만 존재하는 가드레일"의 한계를 구조적으로 해결
P3 중복 제거 + Claude Code 공식 기능 실제 활용
P4 업계 표준 대응 + 장기 확장성 (지금 당장 필수 아님)