본문은 AI의 정확성과 효율성을 높이는 도메인 지식의 중요성과 이를 구축하는 구체적인 방법을 제시합니다.
도메인 지식의 중요성
도메인 지식이 없을 경우 AI는 일반적인 관행을 적용하거나, 불필요한 추상화 계층을 추가하고, 시스템 고유의 요구사항을 놓치며, 제약 조건을 위반하는 솔루션을 제안할 수 있습니다. 그러나 도메인 지식이 문서화되면 AI는 다음과 같은 이점을 얻습니다.
-
특정 고객 유형과 비즈니스 목표에 맞는 제품 이해
-
핵심 차별점과 고객 유지 요인 파악
-
비즈니스 용어와 일치하는 변수명 사용
-
코드 품질 기준(예: 명료성 우선) 이해
-
데이터베이스 선택과 같은 아키텍처 결정의 배경 이해
-
다중 테넌트 격리와 같은 비협상적 요구사항 인지
-
반복하지 말아야 할 과거 실수 학습
-
실제로 추구하는 아키텍처 패턴 적용
지식 인프라 구축 방법
-
루트
CLAUDE.md파일 시작: 프로젝트의 최상위에CLAUDE.md파일을 생성하여 전체 프로젝트 개요, 핵심 아키텍처(예: Multi-tenant SaaS, Rails 8, Turbo/Stimulus, Solid Queue, Passwordless auth), 기술 스택, 그리고 다른CLAUDE.md파일의 위치를 명시합니다. 이는 AI가 코드베이스의 전반적인 컨텍스트를 빠르게 파악하는 데 도움을 줍니다. -
복잡한 시스템을 위한 심층 문서 추가:
@docs/payout-system.md와 같이 특정 복잡한 시스템(예: 결제 시스템)에 대한 별도의 상세 문서를 작성합니다. 이 문서에는 시스템의 흐름, 주요 설계 결정(예: 주간 배치 처리 이유, PayoutItem 조인 테이블 사용 이유), 문제 해결 가이드 등이 포함됩니다. 이러한 문서는CLAUDE.md파일, 프롬프트, 명령어 또는 에이전트 지침에서 참조할 수 있습니다. -
코드베이스 전체에 지식 분산: 각 주요 영역(예:
app/models,app/controllers,app/business_logic)에 자체CLAUDE.md파일을 배치하여 해당 영역에 특화된 지침을 제공합니다. 예를 들어,app/models/CLAUDE.md는 모델 상속(STI), 금액 처리, 공통 스코프, 모델 테스트 방법론 등 모델 관련 패턴과 베스트 프랙티스를 설명합니다. -
AIDEV-NOTE주석으로 흔적 남기기: 코드의 복잡하거나 비자명한 결정, 잠재적 문제점(gotchas)이 있는 부분에는AIDEV-NOTE주석을 추가합니다. 이는 특정 코드 섹션의 배경, 과거 문제 해결 이력, 관련 문서 경로, 테스트 커버리지 등을 명시하여 AI가 코드의 의도를 정확히 이해하도록 돕습니다.
도메인 지식의 복합 효과
도메인 지식은 AI의 프롬프트 의존도를 줄이고 결과의 정확성을 높입니다. “부분 환불 지원 추가”와 같은 간단한 요청에도 AI는 기존 아키텍처와 비즈니스 규칙에 맞춰 올바른 구현(예: 기존 명령 업데이트, 원장 기록, 비동기 작업 큐잉)을 수행할 수 있습니다. 지식이 누적될수록 각 작업은 더 쉬워지며, AI가 어려움을 겪을 때마다 누락된 컨텍스트를 문서화하면 지속적으로 개선됩니다.