ai-rules › handbook › AI Rules 시스템 개선 체크리스트

AI Rules 시스템 개선 체크리스트

### 그대로 반영

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

작성일: 2026-04-01
기준 문서:

1. 판단 요약

그대로 반영

  • Advisory vs. Deterministic를 핵심 격차로 유지
  • Bootstrap 절차 부재를 핵심 격차로 유지
  • Human-AI 하이브리드 게이트 불명확 문제를 유지
  • Context 소진 관리 부족 문제를 유지
  • Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 순서를 유지

보정 후 반영

  • P1-1의 예외 기준을 docs/00_INDEX.md 없음 단일 조건에서 탐색 앵커 부재 개념으로 확장
  • P1-2 Bootstrap의 탐색 범위를 docs/ 중심에서 프로젝트 루트 기준 제한적 1회 탐색으로 보정
  • P1-3 자율 실행 기준에서 1파일 10줄 이하를 절대 규칙이 아닌 대표 예시로 낮춤
  • P2-1 Hooks 문서에 must-hook / should-hook / text-only 우선순위 표 추가
  • P3-1 Subagent 전환에서 포맷 변환보다 권한 제한 설계를 먼저 명시
  • P4 AGENTS.md는 구현은 장기로 두되, canonical source 전략 결정은 앞당김

추가 설계 필요

  • Rule Test Suite 설계
  • Standard Promotion 체계 설계
  • Adoption Matrix 설계
  • Failure Ledger 강화
  • Context Budget Policy 명문화
  • Rule Benchmark 방식 정의

2. Phase 1 체크리스트

core/05-responses.md

  • "리포 전체 스캔 금지" 원칙 유지
  • 신규/초기 프로젝트 예외 조건 추가
  • 예외 조건을 docs/00_INDEX.md 없음만으로 제한하지 않음
  • 아래 중 하나라도 없으면 Bootstrap 예외 허용으로 정리
  • docs/00_INDEX.md
  • INTENT.md
  • 문서화된 자산 인덱스
  • 예외는 세션 시작 시 1회만 허용으로 제한
  • 스캔 후 발견 자산을 INTENT.md context.docs에 등록하도록 명시

core/06-session.md

  • 세션 시작 Step 0에 프로젝트 타입 판별 추가
  • 성숙 프로젝트 / 신규 프로젝트 구분 로직 추가
  • Bootstrap 절차를 별도 블록으로 명시
  • Bootstrap 탐색 대상에 아래 경로 포함
  • 루트 *.html
  • docs/**/*.html
  • ui-mockups/
  • mockups/
  • wireframes/
  • design/
  • docs/guide/
  • docs/design/
  • 발견 자산을 사용자에게 먼저 보고하도록 명시
  • Bootstrap 이후 기존 Step 1~5로 복귀하도록 명시

core/04-workflow.md

  • AI 자율 실행 vs 사람 승인 기준 섹션 추가
  • 자율 실행 기준을 영향 범위 작음 + 의도 명확 + 검증 가능 원칙으로 정의
  • 아래는 자율 실행 예시로 명시
  • 타입 체크 / lint / 테스트 실행
  • 조사 / 분석 / 보고서 작성
  • 단일 파일의 작은 수정
  • 문서 업데이트 / 주석 추가
  • 아래는 추가 승인 필요로 명시
  • 새 파일 3개 이상 생성
  • 의존성 추가 / 제거
  • API 시그니처 변경
  • 에러 핸들링 패턴 변경
  • 1문장으로 설명 불가능한 diff
  • 아래는 사람 직접 실행으로 유지
  • DB 파괴적 변경
  • 보호 브랜치 push
  • .env 수정
  • 많은 파일 탐색 시 Subagent 위임 규칙 추가

3. Phase 2 체크리스트

core/09-hooks-guide.md

  • Hooks와 텍스트 규칙의 역할 차이 설명
  • Advisory와 Deterministic 비교 표 추가
  • 아래 3분류를 포함
  • must-hook
  • should-hook
  • text-only
  • must-hook 예시에 아래 포함
  • 보호 브랜치 커밋/푸시 차단
  • DB 파괴 명령 차단
  • 민감 파일 수정 감시
  • should-hook 예시에 아래 포함
  • 파일 수정 후 lint/format
  • 커밋 전 타입 체크
  • text-only 예시에 아래 포함
  • 응답 형식
  • 코드 스타일 선호
  • 문서 서술 방식

core/10-subagent-patterns.md

  • Subagent의 목적을 컨텍스트 보호 + 역할 분리로 정의
  • 탐색은 Subagent, 구현은 메인 세션 원칙 추가
  • 역할별 권한 제한 예시 포함
  • planner: read-only
  • reviewer: read-only, edit 금지
  • security: 제한된 shell / 보안 중심
  • builder: 수정 가능, 검증 필수
  • 병렬 실행 가능한 작업 예시 추가
  • 탐색/검증/리뷰를 메인 세션과 분리하는 이유 설명

4. Phase 3 체크리스트

agents/ -> .claude/agents/

  • 포맷 전환 전에 역할별 권한표 작성
  • 각 에이전트의 목적/입력/금지사항 정리
  • YAML frontmatter 필드 표준 정의
  • name
  • description
  • tools
  • model
  • permission mode 또는 동등 제약
  • reviewer는 수정 도구 제거
  • planner는 읽기 전용 유지
  • security는 민감 작업 기준 강화
  • adapter가 프로젝트별 agent 파일을 실제로 생성하도록 설계

중복 제거

  • extensions/aitem-frontend.md와 core 중복 항목 재검토
  • 공통 규칙은 core로 승격
  • AITEM 고유 제약만 extension에 남김
  • 체크리스트 형식으로 유지할 가치가 있는 항목만 남김

5. Phase 4 체크리스트

CLAUDE.md 슬리밍

  • 항상 로드와 필요시 로드를 분리
  • 글로벌 CLAUDE.md 목표 길이 정의
  • 핵심 규칙만 남긴다는 기준을 문장으로 명시
  • 기준 질문 포함:
  • "이 문장이 없으면 AI가 반복적으로 실수하는가?"
  • DB / 로컬 환경 / UI 탐색 / 응답 상세는 Skills 후보로 분류

AGENTS.md 전략

  • AGENTS.md를 장기 canonical source로 볼지 결정
  • CLAUDE.md는 Claude 특화 override 전략 검토
  • adapter 계층에서 공통/도구별 차이를 어떻게 표현할지 설계
  • 다중 도구 호환 시 drift 방지 방안 정리

MCP 확장

  • MCP를 core가 아닌 extension/guide 레벨에서 시작
  • Figma / Jira / Linear / DB MCP 활용 시나리오 정리
  • MCP 도입 시 컨텍스트 비용과 도구 수 상한도 함께 명시

6. 국내/해외 이상으로 가기 위한 추가 항목

운영 체계

  • STANDARD_PROMOTION.md 초안 작성
  • 승격 단계 정의:
  • candidate
  • validated
  • recommended
  • mandatory
  • 프로젝트별 채택 상태를 기록하는 ADOPTION_MATRIX.md 초안 작성

검증 체계

  • RULE_TEST_SCENARIOS.md 초안 작성
  • 최소 시나리오 포함
  • 신규 프로젝트 + 목업 존재
  • 성숙 프로젝트 + docs index 존재
  • DB 위험 명령 포함
  • 다파일 탐색 필요 작업
  • 의존성 추가 요청

측정 체계

  • 규칙 변경 전/후 재작업 횟수 측정 방식 정의
  • 규칙 변경 전/후 토큰 사용량 비교 방식 정의
  • 규칙 변경 전/후 승인 요청 횟수 비교 방식 정의
  • 실패 패턴 재발률을 추적하는 ledger 항목 정의

컨텍스트 관리

  • Context Budget Policy 문서 초안 작성
  • 많은 파일 탐색 시 Subagent 위임 임계치 정의
  • MCP 서버/도구 수 상한 가이드 정의
  • 긴 규칙 파일의 최대 길이 기준 정의

7. 추천 실행 순서

  • 이 체크리스트 기준으로 Phase 1 먼저 반영
  • Phase 1 반영 후 실제 sync 결과 검토
  • 이후 Phase 2 문서 2개 추가
  • 그 다음 승격 체계 + 테스트 시나리오 문서 추가
  • 마지막으로 agents 포맷 전환, AGENTS.md, MCP 확장 진행

8. 최종 판단

  • 현재 분석 문서의 문제 정의는 유지
  • 현재 계획 문서의 Phase 순서는 유지
  • 다만 Bootstrap, 자율 실행 기준, Hooks 우선순위, Subagent 권한 설계는 보정 후 반영
  • 장기적으로는 규칙 작성보다 실행 강제 + 채택 관리 + 효과 측정까지 가야 국내/해외 공개 사례를 넘어설 수 있음