활용 가이드
의료기기 개발 문서의 빈 곳을 찾기 어려울 때. 코드 근거가 있는 요구사항·설계·SOUP 초안과 갭 리포트를 만듭니다. 담당자와 전문가가 누락·미확정 항목을 검토합니다.
의료기기 소프트웨어의 개발 문서를 준비한다면, 코드에서 확인할 내용과 담당자가 판단할 내용을 나눠 초안과 보완 목록을 만드세요.
이런 문제가 있다면
구현은 진행됐지만 요구사항·설계·외부 소프트웨어 목록을 따로 정리하려면 코드와 문서를 계속 대조해야 합니다. 문서 사이의 참조가 끊기거나 제품·안전 정보가 빠져 있어도, 무엇부터 보완할지 찾기 어렵습니다.
Specify로 해결하기
- GitHub 저장소와 필요한 문서 스킬을 연결하고, 코드에 없는 제품 정보를 입력합니다.
- Specify로 요구사항·아키텍처·SOUP 초안을 만들고 각 항목의 코드 근거와 문서 간 참조를 확인합니다.
- 갭 리포트로 누락과 미확정 항목을 모아 담당자가 보완합니다. 인증 제출 전 규제·안전 판단은 전문가가 검토합니다.
어떤 결과를 얻을 수 있나요?
| 지금 필요한 작업 | 만들 문서 | 검토할 결과 |
|---|---|---|
| 구현된 기능과 구조를 개발 문서로 정리 | 요구사항 명세서 · 아키텍처 설계서 | 요구사항 ID, 아키텍처 항목, 근거 파일 경로가 있는 초안 |
| 외부 소프트웨어 구성요소 정리 | SOUP 목록 | 의존성 식별 정보, 버전·사용 위치 근거와 추가 검토 항목 |
| 문서 세트의 빈 곳 찾기 | 문서 세트 갭 리포트 | 필수 절 누락, 미확정 값, [GAP], 끊긴 참조 ID를 정리한 리포트 |
먼저 알아둘 표기
| 표기 | 뜻 |
|---|---|
| REQ-… / ARCH-… | 요구사항과 아키텍처 항목 ID입니다. 문서 사이의 참조가 실제 항목과 내용에 맞는지 확인하세요. |
| [unconfirmed] | 초안에 제안됐지만 담당자가 아직 확정하지 않은 값입니다. 승인된 사실처럼 사용하지 않습니다. |
| [GAP] | 근거나 입력이 부족해 보완·확인이 필요한 부분입니다. 그 자체로 규정 준수 여부를 판정하지는 않습니다. |
| SOUP | 출처·개발 정보가 충분하지 않은 소프트웨어 항목을 검토할 때 쓰는 표기입니다. 버전과 사용 위치만 확인했다고 안전 영향까지 판단된 것은 아닙니다. |
이 예제에서 사용하는 프로젝트
MedRelay Demo는 합성 기기 패킷의 입력 검증, 순서 검사, 메모리 보관, CSV 내보내기를 구현한 작은 문서화 예제입니다. 화면은 이 코드를 연결해 실제 앱에서 실행한 결과입니다. 실제 환자 데이터나 고객 프로젝트는 사용하지 않습니다.
예제 코드 내려받기 후 자신의 GitHub 저장소에 올려 같은 흐름을 따라 할 수 있습니다. 실제 의료기기나 인증 완료 사례가 아니며, 안전 등급·위험 수용 기준 등은 미확정 상태로 남겨 둔 예제입니다.
생성 결과는 제출 전 규제·품질 전문가의 검토가 필요한 초안입니다. 코드에서 확인한 구현 사실이 승인된 요구사항이나 시험 수행 증거를 대신하지는 않습니다. 대상 국가, 제품의 의도된 사용, 안전 등급, 적용 표준과 판은 담당자가 확인하세요.
시작하기 전에
- 문서화할 GitHub 저장소와 브랜치를 연결합니다. 처음에는 검토 범위가 명확한 저장소로 시작하세요.
- 문서 프로젝트를 만들 수 있는 편집 권한과 이용 플랜을 확인합니다. 최신 이용 조건은 요금제에서 확인하세요.
- 제품 목적·사용자·사용 환경·코드 범위처럼 코드만으로 확정할 수 없는 정보를 준비합니다.
- 표준 문서 라이브러리의 이용 가능 여부를 확인합니다. 표준 검색을 사용할 수 없거나 조항을 찾지 못하면 그 부분은 근거 부족으로 남겨 검토해야 합니다.
설정 → AI 에이전트 → 플러그인에서 medical-device-docs를 찾아 포함된 스킬을 확인하고 설치합니다. 이 팩에는 인증 프로필 수집, 개발 문서 작성, 갭 검토를 위한 스킬 10종이 있습니다.
사례 1. 요구사항·설계 문서 초안 만들기
제품 정보를 먼저 검토하기
먼저 프로젝트 만들기에서 저장소와 브랜치를 선택하고, 문서 종류로 인증 프로필 인테이크를 선택해 생성합니다. certification-profile-intake는 저장소를 읽고 인증 프로필의 제안 값을 만듭니다. 제품명, 의도된 사용, 시스템 경계 등에는 코드 근거 또는 미확인 사유가 붙습니다.
생성된 프로필의 [unconfirmed]는 아직 사람이 확정하지 않았다는 뜻입니다. 담당자가 검토한 항목만 [confirmed]로 바꾸고, 안전 등급이나 위험 수용 기준이 정해지지 않았다면 미확정 상태로 둡니다. 이후 문서에서는 확정된 프로필 값만 사실로 사용합니다.
문서 종류와 범위 선택하기
같은 프로젝트에 문서 추가
사이드바 프로젝트 목록에서 해당 프로젝트의 문서 추가 버튼을 누릅니다. 연결했던 저장소와 브랜치를 그대로 사용합니다. 이전 진행 상황이 열리면 닫기를 눌러 문서 선택으로 돌아갑니다.
요구사항과 아키텍처 선택
문서 단계에서 이전 선택을 해제하고 SW 요구사항 명세서 (IEC 62304)와 SW 아키텍처 설계서 (IEC 62304)를 선택합니다. 이 예제에서는 사례 2의 SOUP 목록 (IEC 62304)도 함께 선택했습니다. 실행 지침 보기에서 작성 범위를 확인하세요.
검토한 인증 프로필 연결
선택한 문서 설정에서 각 문서를 펼쳐 인증 프로필 노드 ID에 같은 프로필을 지정합니다. 프로필 문서를 열었을 때 주소의 마지막 부분인
node-…가 노드 ID입니다. 연결이나 확정 값이 없으면 관련 내용을 임의로 채우지 않고 미확정 항목으로 남깁니다.선택한 문서 확인 후 생성
문서 종류와 입력값을 확인하고 문서 3종 만들기를 누릅니다. 요구사항과 SOUP 문서가 먼저 시작되고, 아키텍처는 같은 배치의 요구사항 문서 실행이 끝나면 시작됩니다. 생성 후 문서를 열어 결과를 확인합니다.
결과에서 확인할 것
요구사항 문서의 REQ-001 같은 ID와 아키텍처 문서의 ARCH-001 같은 ID를 따라가며, 설명이 실제 구현과 맞는지 검토합니다. 근거 파일 경로는 해당 내용을 다시 확인하는 출발점입니다.
| 확인 항목 | 담당자가 할 일 |
|---|---|
| 기능·인터페이스 설명 | 실제 코드와 비교하고, 누락된 요구나 구현과 요구의 차이를 기록 |
| 요구사항과 설계의 연결 | 참조 ID가 실제로 존재하며 내용도 서로 맞는지 확인 |
| 표준 인용 | 적용 표준·판과 인용한 조항이 검토 범위에 맞는지 확인 |
[GAP]과 미확정 값 | 제품 책임자·개발·규제·품질 담당자 중 보완할 주체를 정하기 |
| 검증 관련 내용 | 계획과 실제 수행 결과를 구분하고, 시험 기록은 별도 근거로 확인 |
사례 2. SOUP 검토 자료 정리하기
외부 라이브러리와 소프트웨어 구성요소를 정리해야 한다면 SOUP 목록 스킬 sw-soup-list를 사용합니다. 저장소의 의존성 매니페스트와 lock 파일을 근거로 식별 정보를 정리하는 초안입니다.
문서에 적힌 이름·정확한 버전·라이선스·사용 위치를 원본 파일과 대조하세요. 라이선스가 확인되지 않거나 공개 이상 목록 평가 자료가 없다면, 확인되지 않았다는 사실을 남기는 것이 맞습니다.
의존성 목록만으로 SOUP 검토가 끝나지는 않습니다. 직접·전이 의존성의 포함 범위, 각 구성요소의 SOUP 해당 여부, 알려진 이상 평가와 제품 안전에 미치는 영향은 담당자가 검토해야 합니다. 수행하지 않은 취약점 점검이나 위험 평가 결과를 완료된 사실로 기록하지 마세요.
사례 3. 문서 세트의 누락 항목 찾기
검토할 문서가 모두 완료되면 같은 프로젝트에서 문서 추가를 엽니다. 이전 문서 선택을 해제하고 SW 문서 세트 갭 리포트만 선택한 뒤, 같은 인증 프로필 노드 ID를 지정하고 문서 1종 만들기를 누릅니다. pack-gap-review는 다른 문서를 읽어 리포트를 작성하며, 점검 대상 문서 자체를 수정하지 않습니다.
이 실행에서는 REQ-011의 미매핑, REQ-020의 부분 매핑, SOUP 항목의 ARCH 연결이 검토 대상으로 표시됐습니다. 요구사항·아키텍처·SOUP와 인증 프로필을 실제로 읽어 점검했고, 제목 탐색에서 확인되지 않은 나머지 문서는 없다고 단정하지 않고 미판정으로 남겼습니다.
| 리포트에서 찾을 내용 | 다음 행동 |
|---|---|
| 필수 절 누락·빈 본문 | 해당 문서의 누락 부분을 작성하고 근거 보완 |
| 표준 조항 참조 누락 | 적용 범위와 검색 결과를 확인해 인용 또는 근거 부족 사유 보완 |
| 끊긴 요구사항·설계 참조 ID | 실제 항목과 연결하거나 폐기 이력 확인 |
| 미확정 정보를 확정 사실로 서술 | 인증 프로필과 대조해 수정하고 담당자 검토 |
남아 있는 [GAP] | 필요한 입력·증거·판단을 확보한 뒤 다시 검토 |
이 리포트는 문서 팩의 체크리스트에 따른 보완 작업 목록으로 사용하세요. 누락 항목이 없다는 표시만으로 규제 요구사항을 모두 충족하거나 제출 준비가 완료됐다는 뜻은 아닙니다.
코드가 바뀐 뒤에는
의료기기 문서 팩의 개발 문서 8종과 갭 리포트는 전체 재작성 방식입니다. 저장소 변경을 자동으로 반영을 켜면 선택한 브랜치의 변경에 따라 기존 관리 문서를 갱신합니다. 영향받은 부분만 고치는 증분 갱신과 달리 문서 전체를 다시 작성하는 방식이므로, 결과와 사람이 보완한 내용을 함께 검토하세요. 이 예제의 최초 생성에서는 자동 갱신을 꺼 두었습니다.
재생성 전후에는 확정된 제품 정보, 기존 항목 ID, 사람이 보완한 근거와 검토 기록이 일관되게 유지되는지 확인하세요. 인증 프로필 인테이크는 별도의 증분 갱신 방식이며, 기존 확정 값을 임의로 바꾸지 않고 재검토할 내용을 남깁니다.
내 프로젝트로 시작하기
처음부터 모든 문서를 만들기보다, 저장소 하나 → 인증 프로필 검토 → 요구사항·아키텍처 초안 → 갭 검토 순서로 시작하세요. 첫 검토에서 필요한 자료와 담당자를 확인한 뒤 SOUP·위험관리·사용적합성 문서로 범위를 넓힐 수 있습니다.