"이 API 문서, 지금도 맞는 거예요?"
신입 개발자의 이 한마디에 팀 전체가 침묵했던 경험, 있으신가요?
— 노션에 마지막으로 손댄 게 3개월 전, 코드는 그새 12번 바뀌었습니다
회사마다 반드시 존재하는 유령이 있습니다. 바로 '아무도 믿지 않는 문서'입니다. 위키 어딘가에 있고, 노션 어딘가에 있고, 구글 독스 어딘가에도 있지만 — 정작 코드가 바뀌면 그 누구도 문서를 고치지 않습니다. 그렇게 문서는 서서히 '친절한 거짓말'이 되어갑니다.
이 문제를 해결하는 방법론이 바로 Docs-as-Code(코드로서의 문서)입니다. 그리고 오늘은 비전공자도 AI의 도움을 받아 '흩어진 문서를 코드 옆으로 옮기고, 코드가 바뀔 때마다 문서를 자동으로 갱신하는 동기화 봇'을 만들어, 개발팀·외주사·스타트업에 월 100만원의 유지보수 수익을 만드는 실전 과정을 5단계로 풀어드립니다.
Docs-as-Code는 "문서를 코드처럼 관리한다"는 뜻입니다. 문서를 코드와 같은 저장소(Git)에 두고, 코드 변경(PR)이 일어나면 관련 문서도 함께 리뷰·갱신되도록 강제하는 것이죠. 우리가 만들 봇은 이 흐름을 자동화합니다.
왜 문서는 반드시 썩는가
문서가 썩는 이유는 게으름이 아닙니다. '구조의 문제'입니다. 코드는 IDE에서 매일 만지는데, 문서는 브라우저를 새로 열고 → 노션에 로그인하고 → 해당 페이지를 찾아 → 수정해야 합니다. 이 물리적 거리가 문서를 죽입니다.
우리가 만들 봇의 전체 그림
거창해 보이지만, 봇의 역할은 단순합니다. ①흩어진 문서를 한 번 긁어 코드 옆으로 옮기고(이전) → ②코드가 바뀔 때마다 관련 문서를 자동으로 고쳐 올린다(동기화). 이 두 가지뿐입니다.
5단계 실전 가이드
1단계 — 흩어진 문서를 '수집'한다
첫 작업은 이전(migration)입니다. 노션, Confluence, 구글독스에 흩어진 문서를 API로 한 번에 긁어옵니다. 비전공자라면 여기서 AI가 강력한 무기가 됩니다. "노션 API로 특정 워크스페이스의 모든 페이지를 JSON으로 내려받는 파이썬 스크립트를 만들어줘"라고 요청하면 초안이 나옵니다.
처음부터 완벽하게 옮기려 하지 마세요. '자주 보는 문서 상위 20%'만 먼저 이전해도 고객은 효과를 체감합니다. 나머지는 계약 이후 천천히.
2단계 — AI로 '마크다운 변환' 후 코드 옆에 배치
수집한 문서를 마크다운(.md)으로 바꿔 코드 저장소의 /docs 폴더에 넣습니다. 핵심은 문서를 관련 코드 가까이 두는 것입니다. 예를 들어 결제 모듈 문서는 /src/payment/README.md에 두면, 개발자가 코드를 열 때 문서도 눈에 들어옵니다. AI에게 "이 노션 페이지를 GitHub 마크다운 형식으로 변환하고 이미지 링크도 상대경로로 바꿔줘"라고 시키면 됩니다.
3단계 — 코드 변경을 '감지'하는 자동화 설정
여기서부터가 봇의 심장입니다. GitHub Actions를 사용해, PR(코드 변경 요청)이 열릴 때마다 봇이 자동 실행되도록 합니다. "결제 관련 파일이 바뀌면 결제 문서 갱신이 필요하다"는 규칙을 걸어두는 것이죠. 이 설정 파일(YAML)도 AI가 대부분 작성해줍니다.
GitHub 위키는 코드와 분리된 별도 저장소라 PR 리뷰에 포함되지 않습니다. 즉 또 다른 '흩어진 문서'가 될 뿐이죠.
/docs 폴더 방식은 코드와 같은 PR에서 함께 리뷰되므로 동기화가 강제됩니다. 이것이 위키의 가장 강력한 대안입니다.
4단계 — AI가 '문서 초안을 자동 갱신'
봇이 변경된 코드를 감지하면, 그 diff(변경 내역)를 AI에게 전달합니다. "이 코드가 이렇게 바뀌었다. 관련 문서에서 고쳐야 할 부분을 수정한 새 버전을 제안해줘"라고요. AI는 함수 이름 변경, 파라미터 추가 같은 것을 문서에 반영한 초안을 만들어 PR에 코멘트로 답니다.
봇은 초안만 제안합니다. 최종 게시는 반드시 사람이 확인합니다. 이 'AI 제안 + 사람 승인' 구조가 신뢰의 핵심이며, 고객이 안심하고 돈을 내는 이유입니다.
5단계 — '리뷰 & 게시' 그리고 월 구독으로 전환
개발자는 코드 리뷰를 하면서 봇이 제안한 문서 수정안도 함께 확인하고 승인 버튼을 누릅니다. 문서는 코드와 같은 순간에 최신화됩니다. 이제 이 봇을 월 구독 서비스로 파는 겁니다.
왜 월 100만원이 정당한가
고객이 매달 100만원을 내는 이유는 봇의 코드값이 아닙니다. '문서가 항상 진실이라는 상태'를 유지해주기 때문입니다. 신규 입사자가 문서를 믿고 바로 일할 수 있고, 외주사는 "문서 안 맞는다"는 클레임에서 해방되며, 스타트업은 투자 실사(due diligence) 때 정돈된 문서를 바로 제출할 수 있습니다.
한 번 구축해두면 봇은 알아서 돌아갑니다. 여러분이 하는 일은 월 1~2시간의 모니터링과 규칙 조정뿐. 이것이 바로 '유지보수형 구독 수익'의 힘입니다.
① 문서는 코드에서 멀어지면 반드시 썩는다 → ② Docs-as-Code로 코드 옆에 붙인다 → ③ 봇이 변경을 감지해 AI가 초안을 갱신한다 → ④ 사람이 승인만 한다 → ⑤ 월 구독으로 판다.
혼자서는 막막하다면
여기까지 읽고 "방향은 알겠는데 API 연동이나 GitHub Actions 설정에서 막힐 것 같다"는 생각이 드셨다면, 정상입니다. 이 봇의 진짜 가치는 'AI에게 무엇을, 어떤 순서로 시킬 것인가'를 설계하는 능력에서 나옵니다.
TTJ 코딩클래스 정규반에서는 이렇게 비전공자가 AI를 활용해 실제로 돈이 되는 자동화 봇을 기획부터 배포, 그리고 월 구독으로 판매하는 영업 단계까지 프로젝트 중심으로 함께 만들어갑니다. 오늘 소개한 Docs-as-Code 동기화 봇도 그중 하나의 실전 커리큘럼입니다. 문서를 거짓말로 남겨둘지, 매달 100만원짜리 자산으로 바꿀지 — 선택은 지금 시작하는 당신에게 달려 있습니다.