// note
AI 코드 생성 규칙 — 편집 시점 훅과 맥락별 스킬로
- 앱 3개가 든 프론트엔드 모노레포. AI CLI로 코드를 생성하는 비중이 커짐
증상
- 팀 규칙이 문서로만 있어 사람·세션마다 준수가 갈림 — 리뷰에서 같은 지적이 반복됨
- 프롬프트에 규칙을 매번 덧붙여도 세션이 길어지면 지켜지지 않음
원인
- 절차 문서를 통으로 컨텍스트에 물리면 토큰만 먹고 정작 필요한 순간에 안 지켜짐
- 규칙이 강도 구분 없이 한 문서에 섞여 있어, 기계가 잡을 수 있는 것까지 사람 주의에 맡겨져 있었음
조치
- 규칙을 강도로 3층으로 나눔 — 상시 사실(네이밍·레이어 배치)은 문서 한 곳, 작업 절차는 스킬, 계층 방향·파일명·포맷·위험 경로는 검사기. 같은 규칙을 두 곳에 적지 않는 것이 조건 — 중복되면 한쪽이 낡아도 아무도 모름
- 훅을 편집 전·후 두 시점에 — 편집 직전에는 담당 아닌 영역 수정을 셸 우회까지 판정해 확인 요구, 편집 직후에는 복잡도를 키우는 패턴 추가를 사유 없이 차단하고 UI 문자열 하드코딩을 경고. 차단은 종료 코드로 하고, 메시지가 도구에 피드백으로 되돌아가 스스로 고치게 함
- 스킬은 작업 맥락이 맞을 때만 로드 — 새 모듈 배치·다국어 키·데이터 페칭·스토리 작성 4종으로 분리. 앱마다 복붙돼 있던 문서를 한 곳으로 합침
- 편집이 추가한 부분만 검사 — 파일 전체를 보면 레거시에 매번 걸려 경고가 상시 떠서 아무도 안 봄. 편집 전후 차이에서 추가분만 세고 주석은 제외해 오탐 방지
결과
- 규칙 위반이 리뷰가 아니라 생성 시점에 걸림 — 같은 지적을 반복하지 않게 됨
- 산출물을 5개 관점으로 자체 감사해 45건 반영. 제일 많이 나온 결함은 문서가 집행기라고 지목한 도구가 실제로는 연결돼 있지 않은 것 — 규칙을 적어두고 검사기를 안 붙이면 문서만 늘어남
- 도메인을 뺀 템플릿으로 분리해 다른 모노레포에도 붙일 수 있게 함
계층 방향을 실제로 막는 쪽 → FSD 레이어 경계를 린터로 강제