Specify — 코드와 문서가 함께 바뀌도록

기능 하나를 고친 뒤, 반나절이 더 들었습니다

의료기기 소프트웨어 스타트업에서 개발과 인증 준비를 함께 경험했습니다. 인증에 필요한 문서 구조를 잡고, 개발표준에 맞춰 문서를 작성하고 관리하는 일에 반년 넘게 참여했습니다.

가장 오래 걸린 일은 문서의 첫 문장을 쓰는 것이 아니었습니다. 개발이 진행되는 동안 바뀐 코드와 여러 문서의 내용을 계속 맞추는 일이었습니다.

기능 하나를 바꾸면 관련 문서를 찾아야 했습니다. 그 문서의 어느 부분이 달라졌는지 확인하고, 다른 문서에도 같은 설명이 남아 있는지 대조했습니다. 다른 사람이 쓴 문서는 어디에 있는지부터 찾아야 할 때도 있었습니다.

이렇게 기능 변경 한 건의 문서를 정리하는 데 약 4시간이 들었습니다. 코드 수정이 끝나도 문서 작업은 별도로 다시 시작됐습니다.

수정할 문서를 찾는 일이 반복됐습니다

문서를 잘 작성해두어도 다음 변경이 생기면 다시 확인해야 했습니다. 문서의 위치와 작성 맥락을 아는 사람에게 관리가 의존했고, 담당자가 바뀌면 같은 탐색을 처음부터 반복했습니다.

주변 소규모 팀의 개발자들과 이야기했을 때도 문서를 작성할 시간을 내기 어렵다는 말을 들었습니다. 필요한 순간에만 갱신하거나, 문서를 충분히 남기지 못한 채 개발을 이어가는 경우도 있었습니다.

제게 해결하고 싶은 문제가 분명해졌습니다. 코드가 바뀔 때마다 관련 문서를 찾고, 수정할 위치를 확인하고, 내용을 다시 맞추는 반복 작업이었습니다.

코드 변경을 문서 작업의 시작점으로

이 경험을 바탕으로 Specify를 직접 개발했습니다. GitHub의 코드 변경과 팀의 개발문서를 연결해, 변경 후에 남는 문서 관리 작업을 줄이는 제품입니다.

사용 흐름은 다음과 같습니다.

1. 저장소와 자료를 연결합니다. GitHub 저장소와 기존 개발문서, 제품 정보를 준비합니다.
2. 변경 내용을 읽습니다. 코드가 푸시되면 무엇이 바뀌었는지 분석합니다.
3. 영향받는 문서를 찾습니다. 관련 문서와 수정할 구간을 찾아 기존 맥락에 맞는 수정안을 만듭니다.
4. 확인하고 반영합니다. 변경 근거와 수정안을 검토할 수 있고, 자동 반영 여부는 프로젝트 설정에 따라 선택합니다.

기존 자료는 RAG로 검색해 문서 작성과 수정에 필요한 맥락으로 사용합니다. API 문서, 내부 위키, 온보딩 안내, 릴리스 노트처럼 같은 코드 변경의 영향을 받는 문서를 함께 다루도록 구성했습니다.

변경 한 건으로 보면 더 분명합니다

예를 들어 웹훅의 재시도 횟수를 3회에서 5회로 바꾼다고 해보겠습니다. 코드만 수정하면 작업이 끝난 것처럼 보이지만, 연동 가이드에 여전히 ‘3회 재시도’라고 적혀 있다면 다음 사람은 이전 정책을 기준으로 개발하게 됩니다.

이때 필요한 일은 재시도 정책을 설명하는 문서를 찾고, 바뀐 코드와 대조한 뒤 설명을 맞추는 것입니다. Specify는 이 과정을 코드 변경에서 이어가도록 만들고 있습니다.

아래는 재시도 정책을 적은 데모 문서를 실제 서비스에서 열어본 화면입니다. 문서 편집과 상태·공유 기능을 보여주는 예시이며, 자동 갱신 결과를 캡처한 화면은 아닙니다.

인증을 준비하는 팀뿐 아니라 제품을 계속 업데이트하는 팀에서도 문서는 코드와 함께 바뀝니다. 제가 겪었던 문서 탐색과 대조 작업을, 다음 변경 때마다 처음부터 반복하지 않아도 되는 환경을 만들고 싶습니다.

Specify 사용해 보기 · 제품 문서