33
“기능은 고쳤는데, 문서도 같이 바뀌었나요?”
개발팀에서 한 번쯤 나올 법한 질문입니다. 코드는 저장소에 있고, 요구사항은 다른 문서에 있고, 시험 기록은 또 따로 있습니다. 작은 변경 하나를 설명하려고 여러 파일을 오가다 보면, 어디까지 확인했는지부터 헷갈리기 쉽습니다.
인증·인허가를 준비하는 팀이라면 이 질문이 더 무겁게 느껴질 수 있습니다. 지금 문서가 어떤 코드와 자료를 바탕으로 작성됐는지, 아직 확인하지 못한 부분은 무엇인지 설명해야 하기 때문입니다.
저는 개발자 문서 자동화 도구 Specify를 만들고 있습니다. 이번 글에서는 Specify 공개 문서의 의료기기 소프트웨어 활용사례를 바탕으로, 인증 준비 과정에서 문서 자동화를 어디에 써볼 수 있는지 소개합니다.
1. 빈 문서부터 쓰기 전에, 이미 있는 자료부터
문서를 처음 열었을 때 가장 막막한 건 첫 문장보다 재료를 모으는 일일 수 있습니다. 어떤 기능이 구현돼 있는지, 어느 파일에서 확인할 수 있는지, 기존 설명과 달라진 곳은 어디인지 살펴봐야 하니까요.
Specify의 활용사례는 GitHub 저장소와 제품 정보를 연결하는 데서 시작합니다. 먼저 제품의 용도와 범위 등을 정리한 ‘인증 프로필’을 준비하고, 이를 바탕으로 요구사항 명세서와 아키텍처 설계 문서의 초안을 만듭니다.
코드에서 읽을 수 있는 구현 내용은 관련 파일 경로와 함께 확인합니다. 반면 대상 시장, 의도한 사용 목적, 안전 등급처럼 사람이 결정해야 하는 정보는 담당자가 확인해야 합니다. 확인되지 않은 값을 그럴듯하게 채우지 않고 남겨두는 것이 이 과정의 중요한 부분입니다.
자료에서 초안을 만들고, 변경 근거와 미확인 내용을 검토하는 흐름. 실제 제품 화면이 아닌 개념도입니다.
2. MedRelay Demo로 문서를 만들어보면
공개 예제인 MedRelay Demo로 문서를 만드는 과정을 살펴보겠습니다. 장치에서 보낸 합성 데이터의 형식과 순서를 확인하고, 메모리에 저장한 뒤 CSV로 내보내는 작은 프로젝트입니다.
먼저 Specify에 예제 저장소를 연결하고, 제품 정보를 정리해 요구사항 명세서와 아키텍처 설계 문서의 초안을 만듭니다. 코드에 있는 기능을 문서로 옮기고, 각 기능이 어떻게 구성돼 있는지 함께 정리하는 과정입니다.
요구사항 초안에는 항목별 ID와 구현 근거 파일, 검증 후보가 함께 담깁니다. 데이터 형식을 검사하는 요구사항부터 하나 골라보세요. 연결된 코드 파일을 열어 입력을 어떻게 검사하는지 살펴보고, 문서의 설명과 맞는지 확인할 수 있습니다.
이어서 설계 문서에서 같은 기능을 찾아봅니다. 해당 요구사항이 어떤 구성요소로 이어지는지, 연결된 ID가 맞는지 따라가며 두 문서를 함께 검토하면 됩니다.
검증 후보는 다음에 무엇을 시험할지 정하는 출발점으로 활용할 수 있습니다. 여기에 실제 시험을 진행한 기록과 결과를 더해가면, 코드에서 시작한 초안을 팀이 검토하고 보완할 수 있는 문서로 구체화할 수 있습니다.
공개 예제 MedRelay Demo의 코드와 문서를 함께 살펴보는 검토 흐름입니다.
3. 문서 여러 개를 쓴 다음에는, 서로 맞는지 보기
요구사항 문서와 설계 문서가 각각 잘 읽혀도 둘 사이의 연결이 빠져 있을 수 있습니다. 요구사항에서 가리키는 설계 항목이 실제로 존재하는지, 같은 기능을 서로 다르게 설명하지 않는지도 살펴봐야 합니다.
Specify의 공개 활용사례에서는 요구사항·아키텍처 초안, 외부 소프트웨어 구성요소를 정리하는 SOUP 목록, 문서 묶음의 누락 검토 보고서를 순서대로 보여줍니다. 이 보고서로 빈 항목, 확인되지 않은 정보, 끊어진 항목 ID 참조 등을 모아 담당자가 보완할 일을 찾습니다.
공개 데모의 누락 검토에서는 설계와 연결되지 않았거나 일부만 연결된 요구사항, SOUP 항목의 설계 참조 등이 검토 대상으로 나왔습니다. 보고서를 읽고 “무엇이 더 필요한가, 누가 확인해야 하나”를 정리하는 데 활용할 수 있습니다.
의료기기 문서팩은 총 10개 스킬로 구성돼 있습니다. 개발 계획·요구사항·설계·안전 분류·SOUP·위험관리·사용적합성·사이버보안 관련 문서 8종에, 인증 프로필 수집과 누락 검토를 더한 구성입니다.
4. 자동화 설정을 켜기 전에 확인할 것
코드 변경 뒤 문서를 갱신할 때는 기존 문서에 사람이 보완한 내용도 중요합니다.
현재 공개 안내에 따르면 의료기기 문서팩의 개발 문서 8종과 누락 검토 보고서는 문서 전체를 다시 작성하는 방식을 사용합니다. 자동 업데이트를 켰다면, 재생성 전후에 확정된 제품 정보와 기존 항목 ID, 사람이 추가한 근거, 검토 기록이 일관되게 유지되는지 확인해야 합니다.
규격 검색의 이용 조건도 살펴보세요. 규격 라이브러리는 라이선스 확인을 거쳐 단계적으로 제공됩니다. 사용할 수 없는 워크스페이스에서는 팀 자료를 바탕으로 작성하며 규격 인용을 붙이지 않습니다. 규격 원문은 적법하게 확보한 해당 판본으로 확인해야 합니다.
생성 문서는 제출 전 규제·품질 전문가의 검토가 필요한 초안입니다. 초안 작성이나 누락 검토만으로 인증 취득, 규정 준수, 제출 준비 완료를 판단할 수는 없습니다.
5. 첫 시도는 변경 한 건이면 충분합니다
도입을 검토한다면 최근 변경 하나와 관련 문서 몇 개부터 골라보세요. 아래 질문에 답할 수 있는지 확인하는 것만으로도 팀에 맞는 활용 범위를 가늠할 수 있습니다.
- 이번 초안은 어느 코드 버전과 자료를 바탕으로 했나?
- 바뀐 설명의 근거를 원문에서 다시 확인할 수 있나?
- 미확인 정보와 실제로 확인한 사실이 구분돼 있나?
- 남은 질문을 누가 검토하고 보완할지 정했나?
문서 자동화를 평가할 때는 완성된 페이지 수만큼이나 검토하기 쉬운지도 중요합니다. 다음 사람이 근거를 따라가고, 남은 질문을 찾고, 필요한 결정을 이어갈 수 있어야 하니까요.
코드와 문서를 함께 관리하는 방법을 찾고 있다면, 공개 활용사례부터 살펴보세요.
