전체 내역
  • article
  • 7 min read
  • 조회수0

코드 주석부터 디자이너용 설명서, 테스트 케이스까지, 개발자가 쓰는 문서를 AI와 나눠 쓰기

문서는 누가 읽느냐에 따라 모양이 달라야 했습니다. 코드에 붙는 JSDoc, 디자이너가 읽는 화면 기능 설명서, 진행 표시 기능의 테스트 케이스 표를 AI와 만든 과정을 정리하고, AI 문서에서 가장 조심해야 했던 점을 적었습니다.

기획부터 검증까지, AI와 넓힌 프론트엔드 개발자의 일· 4 / 6펼치기
  1. 1. 기획서를 받기 전에 개발자가 먼저 그려 본 스토리보드, AI로 기능 초안 만들기
  2. 2. 피그마를 잘 모르는 개발자가 AI로 시안을 만들어 보며 알게 된 것
  3. 3. 이미지, 영상, 공유 이미지까지, 리소스를 AI로 만들 때 생성보다 코드가 더 많았던 이유
  4. 4. 코드 주석부터 디자이너용 설명서, 테스트 케이스까지, 개발자가 쓰는 문서를 AI와 나눠 쓰기
  5. 5. 요구사항, 시안, 테스트 케이스를 에이전트에게 넘겼더니 150줄이 나왔습니다
  6. 6. 테스트는 다 통과했는데 페이지가 통째로 깨졌습니다, AI로 만든 기능을 검증하며 찾은 것

이 블로그 저장소의 커밋 기록을 보면, 10월 7일 하루에 문서 커밋이 다섯 개 연달아 있습니다. 데이터 모듈, 상태 스토어, 컴포넌트, 페이지, 파이썬 스크립트에 JSDoc과 docstring을 붙인 커밋입니다. 다섯 커밋을 합치면 파일 58개에 624줄이 늘었습니다.

이 글에서는 개발자가 쓰는 문서를 AI와 나눠 쓴 경험을 정리합니다. 코드 옆에 붙는 문서, 다른 직군이 읽는 문서, 그리고 진행 표시 기능의 테스트 케이스 표까지 다룹니다. 사업 문서는 PM이 되고 나니 코드보다 문서를 더 많이 씁니다에, AI가 길을 잃지 않게 하는 프로젝트 문서 구조는 프로젝트 문서 6종에 따로 정리해 두었습니다.

문서도 전문 분야입니다. 요구사항 정의는 기획자가, 테스트 설계는 QA 엔지니어가 더 깊게 다룹니다. 여기서는 개발자가 자기 몫의 문서를 쓰고, 다른 직군에게 넘길 문서의 초안을 빨리 만드는 데 AI를 쓴 이야기만 합니다.

1. 코드 문서는 왜를 적게 했습니다

JSDoc을 붙일 때 정한 규칙은 하나였습니다. 코드를 읽으면 알 수 있는 건 쓰지 않고, 왜 그렇게 했는지를 쓰라는 것입니다. 실제로 남은 주석은 이런 모양입니다.

/**
 * 같은 브라우저 세션에서 글마다 한 번만 조회수를 올린다(`increment_view` RPC). 화면에는 아무것도 그리지 않는다.
 * 화면의 숫자는 ISR 캐시 값이라 늦게 반영돼도 된다. 새로고침으로 숫자를 올리는 걸 막는 정도의 가벼운 중복 방지이며,
 * 로그인 없이 호출되는 RPC라 악의적인 반복 호출까지 막지는 못한다.
 */
export function ViewCounter({ slug }: { slug: string }) {

마지막 문장이 마음에 듭니다. 이 코드가 무엇을 막지 못하는지 적어 두었기 때문입니다. AI에게 문서를 맡기면 장점만 늘어놓기 쉬운데, 한계를 적게 하니 다음에 이 코드를 고칠 사람에게 쓸모 있는 문서가 됐습니다.

이 주석은 사람만 읽는 게 아닙니다. 다음 세션의 에이전트도 이걸 읽고 코드를 고칩니다. React 19 시리즈 3편을 쓸 때도, 에디터가 form을 null로 시작하는 이유를 주석과 코드에서 찾을 수 있었습니다.

2. 디자이너가 읽는 문서는 형식부터 달랐습니다

회사에서는 반대 방향의 문서도 만들어 봤습니다. 공공 관제 시스템 사업에서 Figma 와이어프레임 24개 화면을, 디자이너가 시안 작업 전에 읽을 기능 설명서로 옮기는 일이었습니다. Figma MCP로 프레임의 텍스트 라벨과 스크린샷을 읽게 하고, 그걸 바탕으로 초안을 받았습니다.

이 문서를 계획하면서 가장 먼저 정한 건 독자였습니다. 개발자가 익숙한 기능 정의 표는 기능 ID, 입력, 출력, 예외를 칸마다 채우는 형식인데, 디자이너에게 필요한 건 그게 아니었습니다. "이 영역이 무슨 기능이고, 왜 여기 있고, 어떤 상태가 생기는가"였습니다. 그래서 문서 구조를 이렇게 잡았습니다.

  • 용어집: 디자이너가 모를 수 있는 단어를 한두 문장으로 풀고, 어느 화면에 나오는지 적기
  • 사건 하나가 흘러가는 이야기: 이벤트 발생부터 종결까지 화면 순서대로 서술하기
  • 화면별 설명: 모든 화면을 같은 형식으로, 영역마다 무엇인가, 어떻게 동작하나, 상태와 변형, 디자인 시 유의점

가장 중요했던 규칙은 "디자인 시 유의"에 와이어프레임에 근거가 있는 내용만 쓰게 한 것입니다. 근거 없이 추측한 내용은 "(추정)"이라고 표시하게 했습니다. AI는 그럴듯한 문장을 잘 만들기 때문에, 근거가 있는 문장과 없는 문장이 섞이면 읽는 사람은 구분할 수 없습니다.

3. 진행 표시 기능은 테스트 케이스 표로 정리했습니다

이번 시연에서는 1편의 요구사항과 스토리보드를 주고, 테스트 케이스와 화면 정의를 엑셀 파일로 받았습니다. 테스트 케이스 시트의 일부입니다.

ID 화면 조건 동작 기대 결과 자동화
TC-01 시리즈 상세 읽은 기록 없음 페이지 열기 진행 0 / 4, 이어 읽기 배지 없음 e2e
TC-02 글 상세 시리즈 글 본문 끝 전까지만 보기 읽음으로 기록되지 않음 e2e
TC-03 글 상세 시리즈 글 본문 끝까지 스크롤 브라우저 저장소에 기록 e2e
TC-04 시리즈 상세 1편만 읽음 페이지 다시 열기 진행 1 / 4, 2편에 이어 읽기 e2e
TC-07 시리즈 상세 모바일 390px 2편 읽은 상태 가로 스크롤 없음 수동
TC-08 공통 저장소 차단 브라우저 페이지 열기 진행 표시만 빠지고 페이지는 정상 미확인

표에 "자동화" 칸을 둔 이유는, 6편에서 이 표를 그대로 e2e 테스트로 옮기기 위해서입니다. 문서와 테스트가 따로 놀지 않게 하려는 장치입니다.

TC-01의 "이어 읽기 배지 없음"은 처음 받은 초안과 다릅니다. 1편 스토리보드에는 기록이 없으면 1편에 "이어 읽기"를 붙인다고 적었는데, 구현하다 보니 아직 읽기 시작하지도 않은 사람에게 "이어" 읽으라는 말이 어색했습니다. 그래서 요구사항을 바꾸고 표도 고쳤습니다. 이렇게 바뀐 결정을 문서에 다시 반영하는 일은 AI가 빨랐지만, 바꾸자고 정하는 건 제 몫이었습니다.

4. 문서가 맞는지 확인하는 사람이 필요했습니다

AI 문서에서 가장 조심한 건 그럴듯함이었습니다. TC-08이 좋은 예입니다. 요구사항에는 "저장소를 쓸 수 없는 브라우저에서는 진행 표시를 숨긴다"라고 적었고, 테스트 케이스도 그대로 만들어졌습니다. 문서만 보면 아무 문제가 없습니다. 하지만 실제 코드가 그렇게 동작하는지는 아무도 확인하지 않았고, 표에는 "미확인"으로 남았습니다. 이 항목이 어떻게 됐는지는 6편에서 다룹니다.

테스트를 설계하는 전문가라면 이 표를 보고 빠진 경우를 더 찾아낼 겁니다. 여러 탭을 동시에 열었을 때나, 시리즈에서 글이 삭제됐을 때 같은 경우요. AI가 만든 표는 요구사항에 적힌 범위를 벗어나지 않았습니다. 요구사항 밖을 의심하는 건 여전히 사람의 일이었습니다.

마치며

문서를 AI와 나눠 쓰면서 가장 많이 바뀐 건 쓰는 속도보다 쓰는 범위였습니다. 미뤄 두던 코드 주석을 하루에 붙였고, 디자이너용 설명서처럼 예전에는 엄두를 내지 못했던 문서도 초안을 만들 수 있었습니다.

대신 근거가 있는 문장과 추측한 문장을 구분하는 규칙이 꼭 필요했습니다. 다음 글에서는 이렇게 쌓인 요구사항, 시안, 테스트 케이스를 에이전트에게 넘겨 실제로 구현한 과정을 정리합니다.

Comments (0)