기술팀에 합류한 신입 개발자가 가장 먼저 부딪히는 벽은 코드가 아니라 내부 도구다. 어떤 환경 설정 순서가 맞는지, 어떤 CLI 명령어를 어느 순서로 실행해야 하는지, 그 맥락을 전달하는 문서가 없으면 온보딩은 시니어 개발자의 시간을 반복적으로 소모한다. 이 글은 행동 로그와 스크린샷 캡처를 출발점으로, Upstage Document Parse와 Solar Pro 3를 거쳐 Markdown 파일까지 내보내는 설명서 프로토타입 빌드 과정을 단계별로 정리한다.
개발 환경 설정 및 도구 설명 가이드의 병목을 어떻게 해결할까?
신입 개발자 온보딩 가이드의 병목은 대부분 같은 지점에서 생긴다. 가이드가 없거나, 있어도 실제 화면과 달라서 신뢰를 잃은 경우다. 환경 설정 단계는 도구 버전이 바뀔 때마다 내용이 틀어지는데, 그 갱신 비용을 아무도 지지 않으려 하면 문서는 방치된다.
병목의 구조를 간단하게 분류하면 다음과 같다.
| 병목 유형 | 원인 | 기존 대응 방식의 한계 |
|---|---|---|
| 화면 불일치 | UI 변경 후 스크린샷 미갱신 | 수동 캡처 반복, 유지 비용 높음 |
| 맥락 누락 | 클릭 이유가 문서에 없음 | 구두 전달에 의존 |
| 버전 드리프트 | 도구 업데이트 미반영 | 신입이 오류로 발견 |
| 문서 작성 지연 | 시니어 개발자의 우선순위 낮음 | 온보딩 완료 후 소급 작성 |
이 병목을 줄이려면 실제 작업 흐름을 직접 캡처해서 문서로 변환하는 루프가 필요하다. 별도의 글쓰기 작업 없이, 실제로 도구를 사용하는 행위 자체가 초안 생성의 재료가 되는 구조다.
행동 로그와 스크린샷 기록으로 개발 가이드 초안을 어떻게 작성할까?
Manual Maker 확장을 Chrome에 설치하고 녹화를 시작한다. 이후 내부 도구를 평소처럼 조작하면 된다. 확장은 클릭 직전 시점의 스크린샷을 캡처하고, 각 행동에 대한 로그(클릭 대상 요소, 입력 값, 페이지 URL, 타임스탬프)를 IndexedDB에 먼저 저장한다. 스크린샷은 로컬에 머물며 서버로 전송되지 않는다.
녹화 시 주의할 점이 있다. 비밀번호 입력 필드와 주민번호 형태의 값은 자동으로 마스킹 처리된다. 내부 API 키를 직접 화면에 입력하는 단계가 있다면 해당 필드가 블러 처리됐는지 녹화 후 반드시 확인한다.
녹화를 마치고 Ctrl+Shift+M(Mac: Cmd+Shift+M)을 누르면 행동 로그와 스크린샷 시퀀스를 묶어 Document Parse 파이프라인으로 넘기는 요청이 생성된다. 이 시점에 행동 로그만 전송되고, 스크린샷 바이너리 자체는 로컬에서 처리된다.
Upstage Document Parse로 복잡한 개발 도구 UI를 어떻게 인식할까?
Upstage Document Parse는 스크린샷 이미지에서 UI 구조를 추출하는 데 특화된 모델이다. 일반 OCR과 달리 버튼, 드롭다운, 입력 필드, 탭 구조를 레이아웃 단위로 인식한다. 개발 도구 화면처럼 텍스트 밀도가 높고 UI 요소가 겹치는 경우에도 요소별 바운딩 박스와 레이블을 JSON 형태로 반환한다.
Manual Maker는 이 출력을 행동 로그와 결합한다. 예를 들어, 행동 로그에 "버튼 클릭, id=deploy-btn"이 기록되어 있고, Document Parse가 해당 화면에서 "Deploy" 레이블의 버튼 위치를 식별했다면, 두 정보를 합쳐 "Deploy 버튼을 클릭한다"는 단계를 생성한다. 행동 로그만으로는 맥락이 빈약하고, 스크린샷만으로는 어떤 순서로 조작했는지 알 수 없는 문제를 이 결합이 보완한다.
Document Parse API 호출은 생성 단계에서 한 번 이루어진다. 이후 편집 화면에서 수동으로 내용을 수정해도 API를 재호출하지 않는다.
DOM 맥락 분석과 수동 수정 보호 기능으로 가이드 신뢰도를 어떻게 높일까?
스크린샷 기반 인식만으로는 한계가 있다. 같은 화면이라도 권한에 따라 표시되는 버튼이 다를 수 있고, 동적으로 렌더링되는 컴포넌트는 캡처 타이밍에 따라 상태가 달라진다. Manual Maker는 녹화 중 DOM 스냅샷을 병행 수집해서 aria-label, data-testid, 요소의 텍스트 콘텐츠 같은 속성을 행동 로그에 추가한다. Document Parse 출력과 DOM 데이터를 함께 Solar Pro 3 모델에 전달하면 "이 버튼의 실제 레이블은 무엇인가"를 더 정확하게 판단할 수 있다.
Solar Pro 3는 생성한 각 단계에 대해 자기검증 루프를 돌린다. 행동 로그에서 추론한 단계 설명이 DOM 맥락 및 Document Parse 결과와 일치하는지를 모델이 스스로 채점하고, 신뢰도가 낮은 단계에 플래그를 붙인다. 편집 화면에서 플래그가 붙은 단계는 강조 표시되어 수동 검토를 유도한다.
수동 수정 보호 기능은 이 루프 이후에 작동한다. 사용자가 특정 단계를 직접 편집하면 해당 단계는 이후 재생성 요청에서 덮어쓰지 않는다. 수정 내용이 의도치 않게 초기화되는 상황을 막는 단순한 잠금이다.
Markdown 파일로 내보내어 사내 위키에 가이드를 등록하는 방법
편집이 끝난 초안은 Markdown, Word, PDF, ZIP 네 가지 형식으로 내보낼 수 있다. 사내 위키(Confluence, Notion, GitHub Wiki 등)에 직접 붙여 넣거나 파일로 업로드할 때 Markdown 형식이 가장 적합하다.
내보낸 Markdown 파일의 구조는 다음과 같다.
- H1: 가이드 제목 (녹화 시작 시 입력한 이름)
- H2: 각 주요 단계 (Document Parse가 페이지 전환을 기준으로 자동 구분)
- 번호 목록: 세부 클릭 및 입력 단계
- 이미지 참조: 로컬 스크린샷 경로 또는 Base64 인라인 이미지
- 플래그 주석: 자기검증에서 신뢰도가 낮은 단계에 추가
ZIP 내보내기를 선택하면 Markdown 파일과 스크린샷 이미지가 폴더 구조로 묶인다. GitHub 레포지토리의 docs/ 디렉터리에 ZIP을 풀어 커밋하면 PR 리뷰 흐름 안에서 가이드 갱신도 관리할 수 있다.
가이드를 사내 위키에 등록할 때 권장하는 메타데이터는 아래와 같다.
| 항목 | 권장 값 예시 |
|---|---|
| 문서 버전 | v1.0 (초안), v1.1 (수동 검토 완료) |
| 대상 독자 | 신입 개발자, 온보딩 1주차 |
| 마지막 검증 날짜 | 문서 등록일 기재 |
| 관련 도구 버전 | 캡처 당시 도구 버전 명시 |
| 다음 갱신 주기 | 분기 1회 또는 도구 업데이트 시 |
온보딩 설명서 자동화 전체 워크플로는 이 가이드에서 더 자세히 확인할 수 있다.
자주 묻는 질문
녹화 중 실수로 잘못된 클릭을 했을 때 어떻게 처리하나?
편집 화면에서 개별 단계를 삭제하거나 순서를 바꿀 수 있다. 녹화 자체를 재시작할 필요는 없다. 잘못된 단계만 지우고 나머지를 유지하면 초안 품질에 영향이 없다.
스크린샷이 외부 서버로 전송되는지 확인하는 방법은?
브라우저 개발자 도구의 네트워크 탭에서 녹화 종료 후 발생하는 요청을 확인할 수 있다. Manual Maker는 행동 로그 JSON만 API 엔드포인트로 전송하고, 스크린샷 바이너리는 전송 페이로드에 포함되지 않는다.
Document Parse가 인식하지 못하는 UI 요소가 있을 때 어떻게 보완할까?
DOM 맥락 데이터가 보완재로 작동한다. DOM에서 aria-label이나 data-testid가 잘 정의된 요소라면 Document Parse 인식 실패 시에도 Solar Pro 3가 DOM 데이터로 단계 설명을 생성할 수 있다. 두 소스 모두 불충분하면 해당 단계에 플래그가 붙고 수동 입력을 요구한다.
무료 플랜과 Pro 플랜의 차이는?
무료 플랜은 매뉴얼 10페이지까지 생성할 수 있다. 신입 개발자 온보딩 가이드 한 세트를 프로토타입으로 만들기에 충분한 분량이다. 10페이지를 초과하는 가이드나 팀 전체 설명서 세트가 필요하다면 Pro 플랜이 필요하다. Pro는 일회성 결제 평생 라이선스 구조로, 구독 방식이 아니다.
가이드 내용이 오래되어 갱신이 필요할 때 기존 파일을 재사용할 수 있나?
기존 Markdown 파일을 Manual Maker에 가져와서 특정 단계만 재녹화하는 기능은 현재 지원하지 않는다. 변경된 워크플로 구간만 새로 녹화해서 별도 초안을 만든 뒤, 기존 파일의 해당 섹션을 수동으로 교체하는 방식이 현재 가장 간단한 갱신 경로다.
신입 개발자 온보딩 가이드 프로토타입의 핵심은 문서 작성을 별도 작업으로 분리하지 않는 것이다. 행동 로그와 스크린샷 캡처로 시작해 Upstage Document Parse와 Solar Pro 3의 자기검증 루프를 거치면, 빈 페이지 대신 검토 가능한 초안이 생긴다. 무료 플랜 10페이지로 팀의 핵심 도구 설정 가이드를 먼저 만들어보고, 규모가 커지면 일회성 Pro 라이선스로 전환하면 된다.
더 보기: https://chromewebstore.google.com/detail/fgkbklaijebjeadmgbmopmdndkfllaoa?utm_source=item-share-cb
Top comments (0)