코드는 바뀌었는데 인증 문서는 그대로라면? 개발팀의 문서 자동화 방법

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