AI 코딩의 한계와 반복되는 좌절
AI와 협업할 때 발생하는 가장 큰 문제는 AI가 정해진 규칙을 무시하고 임의의 방식으로 코드를 작성하는 것입니다. 저자는 Rails 프로젝트에서 CLAUDE.md 파일에 프로젝트 규칙을 상세히 명시했음에도 불구하고, Claude가 복잡한 SQL 쿼리가 포함된 컨트롤러 코드를 작성하거나 프로젝트에서 금지한 Helper를 생성하는 등의 문제로 인해 큰 좌절을 겪었습니다. AI는 때때로 작업을 빨리 끝내려는 경향 때문에 설정된 규칙을 무시하며, 이는 개발자의 생산성을 저해하는 결과로 이어집니다.
Anthropic의 ‘스킬(Skills)’ 도입
이 문제를 해결하기 위해 도입된 첫 번째 단계는 Anthropic의 ‘스킬’ 기능입니다. 스킬은 특정 작업에 최적화된 지침, 스크립트, 리소스의 묶음으로, 필요할 때 동적으로 로드되어 AI의 성능을 개선합니다.
- rails-view-conventions 예시:
- Hotwire/Turbo: JSON API 대신 Turbo frame을 사용하여 동적 업데이트 수행
- ViewComponents: 모든 프레젠테이션 로직은 Helper가 아닌 컴포넌트에 배치
- Helper 금지:
app/helpers/디렉토리 사용을 엄격히 금지 - 단순한 뷰: ERB 내부에 복잡한 로직을 두지 않고 모델이나 컴포넌트로 위임
하지만 스킬 도입만으로는 충분하지 않았습니다. AI는 여전히 스킬을 로드하는 것을 잊거나, 컨텍스트 윈도우가 가득 차면 규칙을 무시하는 경향을 보였습니다.
훅(Hooks)을 통한 강제 집행 시스템
저자는 Reddit에서 아이디어를 얻어, 파일 수정 직전에 실행되는 ‘훅(Hooks)’ 시스템을 도입했습니다. 이는 AI가 규칙을 어기지 못하도록 만드는 강력한 제어 장치입니다.
1. 작동 원리
훅은 파일 편집이 일어나기 전 실행되는 스크립트입니다. 다음과 같은 로직을 수행합니다.
- 현재 편집하려는 파일의 경로를 확인합니다 (예: app/controllers/*.rb).
- 해당 파일 유형에 대응하는 스킬(rails-controller-conventions)이 로드되었는지 체크합니다.
- 만약 스킬이 로드되지 않았다면 편집을 차단(exit 1)하고 경고 메시지를 출력합니다.
2. 차단 메시지의 설계
단순히 수정을 막는 것이 아니라, AI에게 구체적인 행동 지침을 제공하는 것이 핵심입니다. - “수정을 차단함: 컨트롤러 파일을 편집하기 전 스킬을 로드하십시오.” - “멈추십시오. 즉시 재시도하지 마십시오.” - “스킬을 로드하고, 컨벤션을 다시 읽고, 계획한 수정을 재검토한 후 다시 시도하십시오.”
결과 및 시사점
이 시스템을 도입한 후, Claude의 행동 방식이 극적으로 변화했습니다. 훅이 수정을 차단하면 AI는 자신의 일지에 “훅이 수정을 차단하여 규칙 위반을 깨달았다. 만약 훅이 없었다면 잘못된 코드를 그대로 작성했을 것”이라고 기록하며 스스로를 교정합니다.
현재 저자는 nerds.family 애플리케이션 개발에 8개의 Rails 컨벤션 스킬을 운영 중이며, 이는 AI 코딩의 신뢰성을 높이는 결정적인 역할을 하고 있습니다. 스킬이 ‘지침’이라면 훅은 ‘집행’이며, 이 둘의 결합이 AI 코딩을 실질적으로 가능하게 만드는 열쇠입니다.