apply

name: apply description: Apply ROI-prioritized actions from an ai-ready:audit run. Read <target>/.ai-ready/audit.json + audit-report.md, then for each top-N action either run a mechanical script (CLAUDE.md scaffolds, ANTIPATTERNS seed, INDEX.md, ARCHITECTURE.md Mermaid diagrams, freshness Stop hook install, naming/testing extraction) or apply a judgment-based change via Claude (anti-pattern entries, ADRs, "DO NOT" sections, "When to use" guides). Use this skill after the user has run ai-ready:audit and now wants to actually execute the recommended improvements rather than just read the report — invoke it whenever they say "apply the audit", "audit 적용", "ROI 액션 실행", "우선순위 액션 적용", "AI 준비도 개선 실행", "audit fix", or refer to running through the action list, even casually.

AI-Ready Apply — ROI 액션 자동 실행기

ai-ready:audit 결과(audit.json + audit-report.md)를 읽어 ROI 상위 액션들을 차례로 적용하는 오케스트레이터입니다.

입력 가정

• 대상 디렉토리에 .ai-ready/audit.json 이 이미 존재 (ai-ready:audit 선행 실행)
• 절대 경로로 받은 <target> (사용자가 지정)

레이아웃 감지 (단일 vs 멀티 모듈)

audit.json 의 single_module_mode (bool) + package_catalog (path|null) 를 먼저 확인한다.

매핑 테이블의 일부 룰은 룰 이름 자체가 모드에 따라 다르다. apply 는 rule.name 의 정확한 문자열로 매핑하므로 audit.json 에 들어온 이름을 그대로 키로 사용하면 된다.

적용 흐름

1. 목록화: audit.json 의 actions 배열을 ROI 내림차순으로 읽고, 각 항목을 아래 매핑 테이블로 분류한다.
2. 사용자에게 계획 제시: top-N (기본 5) 액션의 적용 방법 (mechanical / judgment / skip) 을 표로 보여주고 진행 여부 확인.
3. 순서대로 실행:
   • mechanical → Bash 로 스크립트 호출, 결과 stdout 캡처, evidence 보고
   • judgment → Claude 가 대상 파일을 읽고 초안을 작성, 사용자에게 보여주고 승인받은 뒤 적용
   • skip → 이유와 함께 건너뛰기
4. 재평가: 모두 끝나면 ai-ready:audit 의 scripts/audit.py 를 다시 돌려 점수 변화를 보고.

규칙 → 스크립트 매핑 테이블

각 audit 규칙 이름(rule.name)에 대응되는 처리 방법:

실행 가이드

대상 절대경로 <T> 를 받은 뒤:

1. <T>/.ai-ready/audit.json 이 없으면 먼저 ai-ready:audit 를 안내하고 종료.

2. audit.json 의 actions 를 읽고 위 매핑으로 (rule, kind, command) 튜플 리스트 만들기.

3. 사용자에게 계획 표 출력:

   다음 액션을 적용합니다 (ROI 순):
   1. [mechanical] 인덱스 / MOC 파일 — gen_index.py 실행
   2. [mechanical] 모듈 의존성 맵 — gen_arch_diagram.py 실행
   3. [judgment]   '사용 시점' 가이드 — Claude 가 초안 작성
   4. [skip]       빌드 매니페스트 — 이미 커버됨
   5. [mechanical] freshness Stop hook — install_hook.py 실행
   

4. mechanical 중 문서를 전체 생성/덮어쓰는 액션(gen_index.py / gen_arch_diagram.py / extract_section.py / inject_module_map.py)은 일괄 실행하지 말고 문서별 confirm 루프로 — grill-me 식으로 한 번에 하나씩:

   • 기존 파일이 있으면 Read 로 현재 내용 확보
   • 스크립트를 --dry-run(지원 시) 또는 --out 을 <T>/.ai-ready/proposed/ 임시 경로로 돌려 새 제안 생성 (실제 대상 직접 덮어쓰기 금지)
   • 기존 vs 제안 diff 를 사용자에게 보여주고 추가/수정 항목을 확인 → 승인분만 실제 파일에 반영
   • 스크립트가 중단(사람 인수 추정) 으로 거부(exit 3)하면, 그 문서는 사람이 관리 중이라는 신호다. --force 를 무심코 붙이지 말고, 사용자에게 알리고 어떻게 할지 물을 것
   • 부수효과 없는 멱등 작업(install_hook.py 등)은 announce 후 바로 실행 가능

5. judgment 항목들은 한 번에 하나씩:

   • 관련 파일 읽기 (Read)
   • 초안 작성 (메시지로 보여주기)
   • 사용자 승인 대기 → 적용 (Write/Edit)

6. 모든 적용이 끝나면:

   python3 $CLAUDE_PLUGIN_ROOT/skills/audit/scripts/audit.py --target <T> --out <T>/.ai-ready
   

   재실행해 변화한 점수와 카테고리별 변화를 표로 보고.

안전 원칙

• 사람 인수 문서 보호 (v0.4.0+): gen_index / gen_arch_diagram / extract_section / inject_module_map 은 출력 대상에 ai-ready 자동 생성 시그니처가 없으면(= 사람이 직접 손봤다는 신호) 중단 + exit 3 으로 덮어쓰기를 거부 한다 (managed_doc 가드). 이 거부는 정상 동작이다. --force 로 우회하기 전에 반드시 diff 를 확인하고 사용자 승인을 받을 것. 특히 NAMING.md / TESTING.md / ARCHITECTURE.md 처럼 사람이 산문으로 다듬은 문서가 대상이 되기 쉽다.
• 모든 생성은 diff confirm 후 반영: 문서 전체를 덮어쓰는 액션은 임시 출력 → diff → 사용자 승인분만 반영 (위 실행 가이드 4번). 무조건 덮어쓰지 않는다 — 어떤 ai-ready 문서든 사람이 손댔을 수 있다는 전제.
• 항상 dry-run 우선: inject_module_map.py 와 같이 기존 파일을 수정하는 스크립트는 가능한 경우 --dry-run 으로 미리 보여준 뒤 사용자 승인 → 실제 실행.
• judgment 항목은 항상 사용자 승인: AI 가 임의로 컨벤션을 결정하지 않도록.
• 백업 권장: 사용자가 git commit 하지 않은 변경이 있으면 적용 전에 안내.
• 상위 N 만 적용: 기본 5개. 사용자가 더 많이 원하면 명시적으로 요청.
• 점수 변화 보고: 적용 후 점수가 오르지 않거나 떨어지면 솔직하게 보고하고 원인 분석 (false negative 인지, 적용이 잘못됐는지).

하지 말 것

• audit.json 없이 추측으로 액션 실행
• 한 번에 여러 judgment 항목을 묶어서 처리 (사용자가 검토 못 함)
• 사용자 동의 없이 git commit / push / 외부 시스템 호출
• 적용 결과를 보지 않고 다음 액션으로 넘어가기 (실패해도 계속 가다가 누적 오류)
• 가드의 중단(사람 인수 추정) (exit 3) 을 사용자 승인 없이 --force 로 우회
• 기존 문서를 diff 확인 없이 통째로 덮어쓰기 (사람 편집 손실 위험)