1. SaMD와 FDA 510(k) 문서화의 과제
의료 목적으로 사용되는 독립형 소프트웨어인 SaMD는 FDA의 510(k) 제출 과정을 통해 안전성과 유효성을 입증해야 합니다. 이 과정에서 가장 큰 병목 현상은 의사 결정 이력과 기술적 세부 사항을 추적하는 문서화 작업입니다.
- 추적성 요구: 고수준 아키텍처부터 개별 클래스, 사용자 경로, 외부 인터페이스까지 모든 요소가 문서화되어야 합니다. 단순한 인증 시스템이라도 관련 클래스, 보안 제어, 사용자 경로를 모두 명시해야 합니다.
- 유지보수의 어려움: 수동으로 작성된 문서는 코드가 변경됨과 동시에 구식이 되기 쉬워, 실제 제품과 문서 간의 불일치가 발생하고 이는 규제 준수 리스크로 이어집니다.
2. Claude Code skills의 작동 원리
Claude Code skills는 특정 작업을 수행하기 위한 전문적인 지침 세트를 프로젝트 내의 skill.md 파일에 저장하여 관리하는 방식입니다.
- 구조화된 지침: YAML 프런트매터를 사용하여 기술의 이름과 설명을 정의합니다. 여기서 ‘설명(Description)’ 섹션은 Claude가 해당 기술을 언제 호출할지 결정하는 핵심 기준이 됩니다.
- 컨텍스트 효율성: 기술이 실제로 호출되기 전까지는 세부 지침이 컨텍스트 창에 포함되지 않아, 대규모 프로젝트에서도 효율적인 리소스 관리가 가능합니다.
3. Rails 프로젝트 적용 사례 및 기술적 구현
본 실험에서는 Rails 프로젝트를 대상으로 SDS(Software Design Specifications) 문서를 생성하는 기술을 구축했습니다. 비록 해당 앱이 실제 SaMD는 아니었지만, 규제 준수 문서를 생성하는 테스트베드로 활용되었습니다.
- 문서 생성 범위: 인증 구성 요소, 모듈 간 상호작용, 세션 관리, 데이터 모델링 및 보안 조치 등을 포함한 상세 사양을 생성했습니다. 특히 510(k) 표준 형식을 따르며 버전 식별자 및 위험 분류를 포함했습니다.
- MCP(Model Context Protocol) 연동: Linear MCP 서버를 연동하여 프로젝트 관리 도구인 Linear의 티켓 정보를 직접 참조했습니다. 이를 통해 특정 코드 모듈과 관련된 이슈 ID, 제목, 상태를 문서에 포함시켜 강력한 추적성(Traceability)을 확보했습니다.
4. 한계점 및 인간의 역할
AI를 활용한 자동화는 강력하지만 완벽하지는 않으며, 다음과 같은 주의사항이 필요합니다.
- 정확성 이슈: 실험 중 Claude는 Rails의
has_secure_password를 사용함에도 불구하고 관습적으로Devise젬을 사용한다고 문서에 기술하는 오류를 범했습니다. 또한 실제 티켓 대신 자리표시자 ID를 생성하기도 했습니다. - 검토 프로세스: AI가 생성한 문서는 ‘강력한 초안’으로 간주해야 합니다. Claude에게 스스로의 문서를 검토하게 하여 누락된 정보나 불일치를 찾아내도록 유도할 수 있지만, 최종적으로는 도메인 전문가의 검증이 필수적입니다.