“문서가 구현을 결정한다”: AI에게 명세 문서부터 준 이유

2026-09-30-devlog-010-docs-decide-implementation

이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.

저희 작업 공간의 규칙 문서 맨 위에는 “문서가 구현을 결정한다”는 문장이 있습니다. 지난 편에서 예고한 대로 이번 편은 이 문장을 AI에게 왜, 어떻게 줬는지 적습니다. “이 문서대로 만들어 줘”라는 지시는 결과를 문서와 대조해 확인할 수 있다는 점이 “만들어 줘”와 다릅니다. 다만 저희 기록에는 문서가 구현을 뒤따라간 날도 있어서, 그것도 같이 적습니다.

세 줄 요약

  1. 서버·앱·웹 저장소가 여러 개라서, 모든 저장소가 기준으로 삼을 명세 문서 저장소를 따로 두고 “충돌하면 문서가 이긴다”고 정했습니다.
  2. 커뮤니티 기능을 붙인 9월 23일과 24일의 커밋 기록에서는 명세 커밋 뒤 1분에서 8분 안에 서버 구현 커밋이 이어진 경우가 세 번 있습니다.
  3. 문서가 구현보다 늦은 날도 있고, 문서 밖에서 이름이 어긋나 오류가 난 적도 있습니다. 규칙은 그래서 필요합니다.

 

왜 문서부터였나

떴다24는 서버 세 곳, 앱, 웹 서비스가 서로 요청을 주고받습니다. AI가 각 저장소에서 따로 작업하면 서버가 내려 주는 값과 앱이 기대하는 값이 어긋나기 쉽습니다. 그래서 명세를 한곳에 모았습니다. 명세 문서 저장소에는 API 명세(관리자·인증·공통), 데이터베이스 스키마 문서, 도메인 문서, 서비스 소개, 네이밍 같은 코드 규칙이 들어 있고, 7월 6일 첫 커밋 이후 9월 30일까지 커밋이 139개 쌓였습니다.

그리고 모든 저장소의 AI 규칙 문서(AGENTS.md)에 “작업 전에 이 문서들을 먼저 읽는다”는 목록을 넣었습니다. 작업 공간 규칙 문서에는 이렇게 적혀 있습니다(저장소 이름은 일반화해서 옮겼습니다).

  1. 모든 서비스는 명세 저장소의 명세(API, DB Schema, Domain, Auth)를 기준으로 구현한다. 명세와 구현이 충돌하면 문서를 우선한다.
  2. API 변경 순서: 명세 수정 → 각 서비스 구현. 반대 순서로 진행하지 않는다.
  3. 기존 구조/패턴을 임의로 변경하거나 추측으로 구현하지 않는다.
  4. 필요한 정보는 먼저 관련 파일과 문서에서 검색해 확인한다.

웹 저장소 규칙에는 “API 구현 전에 항상 API 문서를 확인한다”가 한 줄 더 있고, 도메인 문서(DOMAIN.md)에는 새 도메인이 필요하면 그 문서를 먼저 고치라는 문장이 있습니다. 공통점은 AI에게 추측하지 말고 문서에서 찾으라고 방향을 정해 준 것입니다.

 

커밋 시각으로 본 문서와 구현의 순서

말이 아니라 기록을 보겠습니다. 아래는 명세 저장소와 서버·앱 저장소의 커밋 시각을 나란히 놓은 것입니다.

날짜 명세 커밋 뒤따른 구현 커밋 간격
9월 23일 20:29 커뮤니티 스키마와 API 명세 추가 서버 커뮤니티 엔티티와 API 구현 (20:37) 8분
9월 23일 22:21 스토리 위치·해시태그 검색·댓글 알림 명세 서버 구현 (22:24) 3분
9월 24일 18:25 커뮤니티 조회 API를 비회원도 열람 가능하게 변경 서버 반영 (18:26) 1분

같은 날 앱 저장소는 더 일찍 움직였습니다. 22일과 23일 새벽부터 커뮤니티 화면을 짜는 커밋이 이어졌고, 서버 API에 연결한 커밋은 명세와 서버 구현 뒤인 23일 21:07에 나옵니다. 화면은 명세보다 앞섰지만 서버와 붙는 부분은 명세를 기다렸다는 뜻입니다.

 

그렇지 않은 날도 있었습니다

모든 커밋이 문서가 먼저였던 것은 아닙니다. 7월 23일 일감 작업은 오전 08:38에 스키마 설계 문서가 먼저 올라갔지만, 11:55에는 API 계약 문서와 서버 구현이 같은 분에 기록됐습니다. 이튿날 오후 4시 무렵에도 서버, 명세, 앱 커밋이 15:59와 16:00에 몰려 있습니다. 어느 쪽이 먼저였는지 기록으로는 가릴 수 없는 경우입니다.

9월 8일 밤에는 명세 저장소에 “채용 테이블 정의를 변경된 실제 스키마로 동기화”라는 커밋(23:58)이 있고, 이어서 9일 새벽에 채용 상태 코드와 고용 타입 코드 문서를 구현에 맞게 고친 커밋이 세 개 나옵니다. 커밋 제목이 “실제 구현과 맞게 갱신”이라고 하니 구현이 먼저 바뀌고 문서가 따라간 흔적입니다. “문서가 결정한다”는 규칙은 순서가 항상 지켜진다는 뜻이 아니라, 둘이 어긋났을 때 어느 쪽을 기준으로 맞출지 정해 둔 규칙에 가깝습니다.

 

문서 밖에서 어긋나면 이렇게 됩니다

AI가 작업 중 틀려서 바로잡은 일 가운데 다시 틀리면 안 되는 것은 피드백 기록으로 남깁니다. 그중 하나가 상태 값의 철자입니다. 서버에서 취소 상태 이름의 철자를 미국식(CANCELED, L 하나)으로 통일했는데, 앱에서 같은 값을 받는 쪽은 옛 철자로 남아 있었습니다. 서로 다른 저장소, 다른 언어여서 컴파일 단계에서는 잡히지 않았고, 취소된 항목이 든 목록 응답을 받는 순간 앱이 값을 읽지 못했습니다. 앱 쪽 이름을 고쳐 해결했고, 플랫폼 표기는 CANCELED로 확정했습니다.

 

따라 해 보기: 내 프로젝트의 규칙 문서 만들기

저장소가 둘 이상이거나 AI에게 자주 작업을 시킨다면 아래 네 가지를 규칙 문서에 적어 볼 만합니다.

  1. 기준 문서 목록: 작업 전에 읽을 문서를 저장소 규칙 문서 맨 위에 나열합니다. AI는 목록에 적힌 것부터 읽습니다.
  2. 충돌 규칙: “명세와 구현이 다르면 어느 쪽이 맞는지”를 한 줄로 적습니다. 저희는 문서 쪽이라고 정했습니다.
  3. 변경 순서: 인터페이스를 바꿀 때는 문서를 먼저 고치고, 그다음 구현하라고 적습니다. 문서를 나중에 고쳤다면 커밋 제목에 그 사실이 드러나게 합니다.
  4. 이름·값 규칙: 상태 값 이름처럼 저장소 사이에서 반드시 같아야 하는 것은 한곳에 정의합니다. 저희는 코드 값 이름 규칙 문서를 따로 두었습니다.

시켜 보고 확인하는 것도 중요합니다. 작업 뒤에는 AI에게 “어떤 문서의 어느 부분을 근거로 이렇게 했는지”를 물어보고, 문서와 코드가 어긋난 곳이 나오면 규칙 문서에 한 줄 추가합니다.

 

마무리와 다음 편

문서 먼저 원칙이 노리는 것은 속도보다 틀렸을 때 어디가 틀렸는지 찾기 쉽게 만드는 것입니다. 문서에 없는 값이 코드에 있으면 그것이 어긋난 곳입니다.

다음 편에서는 서로 다른 AI 도구인 Claude Code와 Codex를 함께 쓰면서 저장소 규칙 문서와 알림 채널로 역할을 나눈 방법을 적겠습니다.

떴다24 홈페이지 · Google Play에서 받기

← 이전 글
다음 글 →