본격! AX 3편 — 실제로 AI로 기준문서 만들기

지난 2편에서 프롬프트를 드린다고 이야기 드렸는데요,

막상 쓰려고 보니 그냥 파일 하나 드리는 건 반쪽짜리가 될 것 같더라고요. 프롬프트는 어떤 구조 위에서 쓰느냐에 따라 결과가 완전히 달라지거든요. "이 프롬프트가 왜 이렇게 생겼는지"를 먼저 보여드려야, 가져가셨을 때 본인 상황에 맞게 바꿔 쓰실 수 있겠더라고요.

그래서 이번 편은 순서를 좀 바꿨어요. 제가 실제로 어떻게 시작했는지 정리한 실무 가이드 문서는 마지막에 공유드리고, 그 전에 어떤 구조로 정바카라서를 설계했는지, Claude Code가 그 정바카라서를 어떻게 읽는지, 어떤 외부 도구들을 연결했는지부터 먼저 보여드리려 합니다.

먼저 구조부터: 도메인을 나누는 방법

2편에서 "구조가 먼저였다"는 얘기를 했는데, 실제로 어떤 구조인지는 말씀 못 드렸어요.

정바카라서를 만들기 전에 먼저 해야 하는 게 도메인을 나누는 일이에요. 도메인이 정리되지 않으면 정바카라서가 또 어딘가에 섞인 문서 더미가 되거든요.

이 부분은 AI랑 상의해서 잡는 걸 추천해요. 방법은 단순합니다. 서비스가 어떤 구성으로 되어 있는지, 어떤 기능이 있는지, 사용자가 어떤 흐름으로 쓰는지를 최대한 자세하게 설명하는 거예요. 그러면 AI가 어떤 기준으로 도메인을 나눌 수 있는지 제안해줍니다. 거기서 "이건 맞고 이건 아닌 것 같아"를 반복하면서 우리 서비스에 맞는 구조를 잡아가는 거예요.

중요한 건 처음부터 완벽하게 나누려 하지 않아도 된다는 거예요. 우선 큰 덩어리로 나눠두고, 문서를 만들면서 필요하면 쪼개거나 합치면 됩니다.

나누고 나면 다음 문제가 생겼어요. 정바카라서 안에 뭘 담을지였어요.

규칙을 모아두는 파일, 화면 동작을 정리하는 파일, 전체 서비스에서 공통으로 쓰이는 패턴을 정리하는 파일 — 이 세 가지가 섞이면 나중에 AI한테 던졌을 때 어떤 기준으로 읽어야 할지가 애매해지더라고요. 그래서 문서 유형도 나눴습니다.

정바카라 문서 (policy.md): "~해야 한다", "~하면 안 된다" 규칙. 예: "비로그인 사용자는 댓글 작성 불가"

UX 스펙 (ux-spec.md): 화면에서 어떻게 동작하는지 구현 기준. 예: "댓글 입력창 클릭 시 로그인 유도 팝업 노출"

공통 UX 정의 (common-ux.md): 전체 서비스에서 동일하게 쓰이는 패턴. 예: "날짜 표기는 방금 전 / N분 전 / N시간 전 / MM.DD 순서로"

이렇게 나뉘니까 "이건 정바카라이야, 구현 기준이야?" 같은 판단을 Claude가 스스로 하게 됐어요. 제가 매번 설명 안 해도 됐고요.

재료는 기존에 쌓여 있던 TC(테스트케이스) 엑셀에서 꺼냈어요. QA팀이 만들어둔 테스트 시나리오들인데, "기대 결과" 항목에 사실상 서비스 규칙이 다 들어 있거든요. "로그인하지 않은 사용자가 이 버튼을 누르면 로그인 화면으로 이동한다" — 이런 식으로요. 새로 만드는 게 아니라 이미 있는 것에서 꺼내는 과정이었습니다. TC가 없는 팀이라면 기존 기획 문서나 PRD에서 꺼내도 돼요. 형식보다는 "서비스 규칙이 글로 정리된 것"이 있으면 됩니다.

어떻게 시작하는지, 어떤 프롬프트로 AI랑 상의하는지는 마지막에 안내드리는 노션에서 예시로 정리해뒀어요.

Claude Code에게 "일하는 방법"을 알려주는 파일

정바카라서는 서비스 규칙을 담는 문서예요. 그런데 정바카라서를 만들었다고 Claude Code가 알아서 잘 쓰는 건 아니에요. 어떤 순서로, 어떤 기준으로 정바카라서를 다룰지를 따로 알려줘야 했습니다.

그게 SKILL.md예요.

프롬프트라고 하기엔 좀 다른 성격이에요. 정바카라 문서 작업을 요청했을 때 Claude Code가 따라야 하는 작업 기준서에 가깝습니다. "문서 유형을 먼저 판단하라", "파일 경로는 이 트리 안에서 결정하라" — 이런 것들을 정의해뒀어요.

그중에서도 제일 신경 쓴 건 근거 표기였어요. 처음엔 확인 안 된 내용을 전부 [확인 필요]로 뭉뚱그렸는데, 그러다 보니 "아직 안 정한 것"과 "찾아봤는데 실제로 없는 것"이 똑같은 표기가 되는 문제가 생기더라고요. 근데 이게 개발자 입장에서는 완전히 다른 얘기예요 — 하나는 누군가 결정을 내려야 하는 거고, 하나는 그냥 없는 게 맞다는 확인이거든요. 그래서 네 단계로 나눴어요. 근거 출처까지 병기하는 [확인됨], 찾아봤지만 정바카라상 원래 없는 [확인됨: 없음], 못 찾은 [확인 필요], 소스끼리 말이 다른 [모순]. 표기 하나 나눴을 뿐인데 문서 신뢰도에 대한 얘기가 확실히 줄었어요.

세부 규칙에서도 비슷한 문제가 있었어요 — 어떤 값이 서버에 저장되는 건지, 클라이언트가 화면에서 매번 계산해서 보여주는 건지를 구분 안 하고 적으면 문제가 생기더라고요. 예를 들어 "정확도 92%" 같은 수치가 서버가 판정해서 내려주는 값처럼 적혀 있는데, 실제로는 클라이언트가 그때그때 계산하는 파생값인 경우가 있거든요. 이걸 구분 안 하면 정바카라서의 핵심 주장 자체가 실제와 다르게 전달돼요. 화면에 보이는 이름과 코드·DB에 있는 실제 값 이름이 다른 경우도 마찬가지고요 — 리네임 이력 때문에 둘이 갈라진 걸 하나로 퉁쳐서 적으면, 나중에 개발자가 그 이름으로 코드를 검색해도 안 나와요. 그래서 이런 것도 SKILL.md에 규칙으로 박아뒀습니다.

그중에서 가장 중요하게 생각한 건 Step 0이에요. 정바카라 문서 작업 전에 Linear에서 관련 맥락을 먼저 확인하도록 했거든요. 이 기능 관련 이슈가 있는지, 연결된 PRD가 있는지, 현재 개발 상태가 어떤지를 먼저 잡고 들어가는 거예요.

이게 중요한 이유가 있어요. 정바카라서는 현재 서비스 상태를 반영해야 하는데, 이미 바뀐 내용이 정바카라서에 그대로 남아 있으면 오히려 혼란이 생기거든요. Linear에서 맥락을 먼저 잡으면 "이미 배포된 건데 정바카라서가 업데이트 안 됐네요" 같은 걸 Claude Code가 먼저 짚어줍니다.

MCP를 연결한 이유

2편에서 정바카라서가 "살아있는 문서"여야 한다고 했지만, 이게 말은 쉬운데, 현실에서는 잘 안 됩니다.

배포가 완료되고 나면 정바카라서 업데이트는 우선순위에서 밀리거든요. 기억이 흐려지고, 바뀐 내용이 반영 안 된 채로 시간이 지나요. 결국 문서가 또 섬이 돼요.

그래서 자동화 흐름이 필요했어요. 프로젝트가 완료됐을 때 — Jira든 Linear든 Confluence든 — 거기 정의된 내용을 읽어서 정바카라서에 반영하는 과정을 사람이 직접 타이핑하는 게 아니라 Claude Code가 해주도록 하는 거예요. MCP는 그걸 가능하게 해주는 연결 방식이에요.

Atlassian은 Confluence와 연결했어요. 회의록이나 기획 문서에서 완료된 내용을 읽어와야 하는 경우에 씁니다. Linear는 이슈와 프로젝트를 연결했어요. 배포가 완료된 이슈에서 어떤 기능이 바뀌었는지 확인하고, 연관된 정바카라 파일 중 업데이트가 필요한 부분을 찾아줍니다.

이 흐름이 제대로 작동하면 — 배포 후 "정바카라서 어디 고쳐야 해?"를 Claude Code에 물어봤을 때 Linear 이슈를 읽고, 영향받는 도메인을 찾고, 수정 내용을 제안해줘요. 코드베이스 전체 연결은 아직 안 됐지만, 이 방향으로 가는 게 목표입니다.

연결 자체는 어렵지 않았어요. 실제 설정 방법은 노션에서 정리해드릴게요.

정바카라서가 기준점이 된 이후

솔직히 처음엔 효과가 바로 느껴지진 않았어요. 정바카라서를 만들었다고 Claude Code가 갑자기 다른 결과를 내는 건 아니거든요.

달라진 건 조금 다른 곳에 있었어요. "이 기능 정바카라이 어떻게 정의돼 있어?"라고 물으면 정바카라서를 읽고 맥락을 잡아줬고, "배포했는데 정바카라서에서 바꿔야 할 부분이 어딘가?"라고 물으면 업데이트 포인트를 찾아줬어요. 정바카라서가 Claude Code의 단일 기준점이 된 거예요.

그보다 더 달라진 건 팀 안에서였어요. "이 기능 어떻게 돼 있어?" 했을 때 각자 기억에서 꺼내는 게 아니라 정바카라서를 열어서 확인하는 흐름이 생겼습니다. 속도보다 맥락의 일관성이 달라졌습니다.

아직 해결 못 한 부분도 있어요. 정바카라서가 서비스 규칙을 담는다면, 실제 코드나 데이터베이스에 어떤 데이터가 어떤 구조로 남아있는지도 함께 연결되면 훨씬 강력해지거든요. 이건 코드베이스 접근 권한 문제로 아직 풀리지 않은 상태예요. 팀 안에서 해결해야 할 과제로 남아있습니다.

어떻게 시작했는지 궁금하신 분들께

이 구조를 직접 적용해보고 싶으신 분들이 계실 것 같아서, 제가 어떻게 시작했는지 정리한 실무 가이드 문서를 노션으로 준비했어요.

자료 수집 단계에서 해야 할 일

도메인 구성을 위한 프롬프트 예시

SKILL.md 만드는 프롬프트

Git에 연결하고 활용하는 방법

본인 서비스에서도 도입해 보고 싶으신 분은 댓글로 남겨주시면, 노션 링크도 같이 보내드릴게요.

다만 하나만 다시 말씀드리면 — 이건 저희 서비스 구조에서 최적화한 방식이에요. 도메인 구성도, 문서 유형 분류도, 팀마다 달라야 해요. 그대로 복사하지 마시고, 본인 서비스에 맞게 다시 설계해보시는 걸 권해드려요. 또는, 지금 팀에서 사용하고 계신 AI에게 글을 보여주시고, 우리팀에 적용할 수 있는 방법이 있을지도 분석헤보세요!