본격! AX 2편: 문맥을 찾고 팀을 위한 도구 만들기

"제품의 의도와 목표와 방향이 지속적으로 잘 정리되는 공간을 마련하는것" 자체가 아마 대부분의 PM들에게도 이런 작업들이 하나의 숙원사업 이라고 생각하셨을 것 같아요, 저 역시도 AI가 내말을 잘 알아듣고 서비스를 분석할 수 있다면 이것부터 해보고 싶다가 가장 컸거든요.

"이거 제대로 정리되면 돈주고 사서라도 쓰고싶다"라는 생각은 있었는데, 시간도 없었고 무엇보다 AI를 어떻게 써야 할지를 몰랐거든요. 그러다 Claude Code를 제대로 쓰게 되면서 이번엔 할 수 있겠다 싶었습니다. 근데 막상 시작하려니 아무리 잘 분석해 주더라도 내가 어떻게 잘 주느냐에 따라서도 너무나 다른 결과값들을 남겼습니다.

1편에서 말씀드린 것처럼 — AI한테 제대로 된 결과를 받으려면 정바카라서가 먼저였어요. 아무도 안 보는 문서지만, AI에게는 기준이 되는 재료거든요. 오늘은 어떤 문제를 겪었는지 그리고 어떻게 하나씩 풀어나갔는지, 그리고 풀어나가면서 들었던 생각들을 공유드리려 합니다.

가장 처음 한 일: 팀이 일하는 문맥 파악과 재료 찾기

1편에서도 이야기 드렸듯, 초기에는 어느정도 서비스에 대한 구성 형태 방향 정의에 대한 부분들이 잘 되어 있었을 겁니다; 어떤 제품을 만들것인지 그리고 어떤 방향을 지향하는지. 왜냐면 사람들의 동의 없이는 제품의 시작을 할 순 없고 그만큼 무엇이 가장 중요한지에 대한 부분과 실제 만들때 어떤것들이 주안점이 되어야하는지가 정의되지 않으면 시작조차 하기 힘들기 때문이죠. 그리고 나서가 항상의 문제입니다. "전에 있었던거 기준으로"로 가게 되면, 이전에 있던 코드베이스 기준의 형태로 하나씩 쌓이기 때문에 이전에 만든 배경과 지식을 아는 사람들은 적용에 대해서 이해도 빠르고 수행도 빠르지만, 해당 부분을 처음보는 사람들이나 구성을 처음 확인하고 개발을 해야하는 엔지니어들은 처음을 파악하기 힘들죠. 그렇게 시간이 가면 갈수록 처음은 뭐고 지금은 어떻게 되어 있고 문서랑 이거랑은 다르고 이런 부분에서부터 갈등은 시작됩니다. 제가 일했던 곳들에서도 그 부분들은 다르지 않았습니다. 그래서 지금까지 모여있는 정보들이 어디에 있는지 그리고 어떤식으로 의사소통을 해서 정보를 모으고 제품을 만들어 나갔는지에 대한 확인이 필요했어요.

그래서 어떤 재료에서부터 시작할지 고민했어요

처음엔 뭐가 있는지 파악하는 것부터 시작했어요. 정바카라서를 정리하려면 지금 어떤 게 있는지 먼저 봐야 하니까요.

Confluence를 열어봤습니다. 있긴 있었어요. 새로운 피처가 나올 때마다 하나씩 쌓인 PRD들이 30~40개 정도. 근데 라이트한 PRD들이 뒤에 계속 쌓이다 보니, 앞에 있는 게 현재 코드에 적용된 건지 아닌지조차 모르는 것들이 더 많았습니다. 서비스가 5~6년째 돌고 있었는데, 저는 초기부터 이 팀에 있었던 것도 아니었거든요. 처음부터 다 찾고 정리할 엄두가 나지 않았어요.

아마 대부분의 스타트업이 이렇게 되어 있을 거라 생각합니다. 만드는 건 빠른데, 정리는 항상 나중으로 밀리는 거요. 그래서 우선은 내가 정보로 확인할 수 있는 것들은 무엇들이 있는지부터 파악하고 정리했습니다.

위에 이야기 했던 컨플 페이지들

QA 분들이 테스트를 위해 진행했었던 전수 테스트 케이스들이나 신규 피처가 나올때 만들어주신 TC들

프로젝트를 진행하며, Task 매니지먼트에 달려있는 이슈들

컨플 페이지에 있는 서비스를 만들기 위해 리서치한 내용 등

을 우선 전반적으로 읽어보고, 이건 들어가야 하는 정보 이건 지금은 필요없는 정보 등으로 조금씩 나누고 시작했습니다.

예를들어 이슈들 같은 경우, 물론 코드베이스에 영향을 미쳤지만 의도와 방향에 관계 없는것들도 많았고 이미 넣어야 하는 정보가 산더미이기 때문에 포기하고 우선 정바카라과 관련된 컨플 페이지들과 TC를 위주로 정의했어요.

그 다음은 구조였습니다.

그래서 일단 던져봤어요. "이거 정리해줘."

결과물을 읽는데, 읽기가 어려웠어요. 같은 내용이 여기저기 문서에서 계속 반복되고, 어떤 건 UI 규칙 위주로, 어떤 건 데이터 정의 위주로 빠져나왔거든요. 하나의 정바카라서인데 뭘 목적으로 작성한 건지 알 수 없는 수준이었습니다. 도메인별로 공통된 기준이 뭔지 잡기가 너무 힘들었어요.

그때 보였습니다. AI 문제가 아니라 — 저한테도 정리가 안 된 것들을 던진 거였어요.

이게 어떤 서비스의 정바카라인지를 AI가 몰랐어요. 맥락이 없으니 그냥 내용을 요약하는 수준에 머문 거예요. 기능별로 쪼개진 걸 하나씩 던졌으니 AI는 각 문서를 독립적으로 처리했고요. 전체 그림이 안 잡히는 건 당연했습니다. 거기다 "어떤 기준으로 정리할 건지"도 없었으니 — AI가 스스로 기준을 만들어버렸어요. 제가 원하는 방향이 아니라.

그래서 방향을 바꿨습니다. AI한테 다시 던지기 전에 구조부터 잡았어요.

도메인을 나누는 건 생각보다 빠르게 됐습니다. PM을 12년 가까이 하다 보니, 서비스에서 데이터가 어떻게 흐르고 어떤 영역이 분리돼야 하는지 감이 있었거든요. 서비스 전반의 도메인 정의, UX·UI·라이팅 규칙, 공통 규칙(날짜·숫자 표기 방식 같은 것들) — 이렇게 세 덩어리로 나눴어요. 그리고 이게 맞는 구성인지 Claude에 물어봤습니다. 이미 서비스에 대해 오래 논의해온 맥락이 쌓여 있었으니까요. 큰 문제 없다는 확인을 받고 나서야 본격적으로 시작했어요.

이게 잡히고 나서야 AI가 제대로 된 결과를 냈습니다. AI한테 잘 정리된 교과서 한 챕터를 주는 것과, 내용이 섞인 프린트 열 장을 주는 것과는 결과가 달라요. 구조가 먼저였습니다.

다음 한 일: 어떻게 사용할 지 정의하고 최적의 방법 찾기

아무리 내용을 잘 구조화 하고 정리를 잘 해놨다고 하더라도, 어디에 저장해두고 어떤 방식으로 사용할 것인지가 없다면, 또다시 이전 정바카라서 처럼 어딘가에 고대유물처럼 다뤄지고 아무도 보지 않는 섬이 되어 버릴 가능성이 훨씬 높다고 생각했습니다. 그래서 그냥 정보를 아카이빙 한다 라는 형태가 아니라,

새로운 제품을 만들때 한번이라도 더 보고 지금의 구성과 이전의 히스토리를 더 잘 파악할 수 있도록

실제 제품과 동일한 정바카라을 가지고 있어서 정바카라을 보고 확인 하는게 내가 제품을 만드는데 도움이 되도록

개발, 기획, 디자인, 제품을 만드는 과정에서 하나의 원천으로서 활용할 수 있는 도구로 사용할 수 있는

도구가 될 수 있도록 하는것이 주요했습니다.

우선은 기존에 사용하던 것을 사용해 보려는 노력

어디에 담을지는 처음엔 당연히 Confluence였어요. 팀이 쓰는 공간이 거기니까. 새로운 것을 정착할때 새로운 도구를 사용해서 정의한다 라고 했을때, 인간은 새로운 도구에 은연중에 생기는 거부감이 있기 때문에 새로운 도구를 사용하는건 최대한 지양해 보려 했어요.

근데 실제로 해보니 번거로웠어요. Claude Code에서 작업한 내용을 Confluence에 붙여넣고, Confluence에서 수정하면 다시 Claude Code에 복붙하고. 왔다갔다가 반복됐습니다. 그래서 Atlas를 MCP로 연결해봤어요. Atlassian에서 나온 AI 도구인데, Claude Code에서 Confluence를 직접 읽고 쓸 수 있게 해줍니다. 연결 자체는 금방 됐어요. 이전에도 여러 MCP를 만들어봤던 터라 어렵지 않았거든요.

근데 막상 써보니 기대했던 만큼이 아니었어요. Confluence의 진짜 강점은 매크로를 잘 활용할 때 나오거든요. 표, 코드 스니펫, 페이지 간 리다이렉션 — 이런 것들이 제대로 돼야 문서가 살아있는데, MCP로 연결해서는 그게 잘 안 됐습니다. 마크다운이 그대로 노출되거나, 매크로가 깨지거나. 보기 불편한 수준이었어요.

그때 생각을 좀 바꿨어요. 어디에 저장할 건가가 아니라 — 이 정바카라서를 앞으로 어떻게 함께 쓸 건가로.

이후 새로운 도구의 사용: Git을 사용한 형태와 이유

Confluence는 그대로 씁니다. 회의록, 업무 방식 정의, 성과 정리 — 이 용도로는 여전히 잘 맞거든요. 다만 정바카라만 Git으로 옮겼어요.

이유는 하나였습니다. 실제 코드베이스와 교차검증을 하고 싶었거든요. 정바카라서에 이렇게 정의되어 있는데, 코드에는 어떻게 구현됐나 — 이 확인이 같은 공간에서 되면 달라지거든요. 마크다운 파일로 관리하면 Claude Code가 직접 읽고, 변경된 부분을 바로 보여주고, 틀린 내용은 바로 고칠 수 있었어요. Confluence에서는 이 흐름이 잘 안 됐는데, Git에서는 그냥 됐습니다. 다만, 아쉽게도 코드베이스 전체를 연결하는 건 아직 못 했습니다. 개발팀 쪽에서 보안 이슈로 반대가 있었거든요. 그래서 PM·PD 그룹으로 접근 설정을 해두고, 새 기획을 시작할 때 참조하거나 배포가 완료되면 바뀐 내용을 업데이트하는 방식으로 운영했어요.

정바카라서가 Git에 들어가는 순간부터, 이게 Claude Code의 단일 기준점이 됐어요. "이 부분 전반적으로 어떻게 정의되어 있어?" 하고 물으면, Claude Code가 정바카라서를 읽고 맥락을 잡아줍니다. "이 서비스 배포됐는데, 정바카라서에서 바꿔야 할 부분이 어딘가?" 하고 물으면, 업데이트 포인트를 찾아줬고요.

눈에 보이는 효율도 있었지만, 더 중요한 건 조금 다른 데 있었습니다. 서비스에 대해 묻고 확인하는 과정이 쌓이면서 — 도메인을 이해하는 눈이 생겨났어요. 정바카라서 하나가 팀 전체의 컨텍스트를 공유하는 기준점이 되는 것. 그게 진짜 변화였습니다.

솔직히 말씀드리면,

저도 처음엔 좋은 프롬프트 하나 찾아서 그대로 쓰면 되지 않을까 했어요. "세상이 이렇게 좋아졌는데 어딘가에 잘하는 사람들이 정리한 스킬이 있고, 그걸 그대로 적용하면 결과가 나오겠지" 하는 기대가 훨씬 컸거든요.

근데 막상 해보니 그게 아니었어요. 프롬프트를 어디서 받아오거나, 있는 도구를 더 때려박는다고 결과가 좋아지지 않았습니다. 제가 일하는 환경이 어떻게 구성되어 있는지, 어떤 방식으로 정보가 흐르는지, 무엇이 걸림돌이었는지 — 그걸 직접 찾아나가고, 같이 구성해보는 과정 자체가 전환이었어요. 최적화된 답을 가져오는 게 아니라, 내 환경에서 최적화할 수 있는 방향을 찾아나가는 것. 그게 저한테는 AX 전환의 진짜 시작이었습니다.

다음 편에서는 실제로 어떤 프롬프트를 썼는지 공유할게요. 다만 하나만 미리 말씀드리면 — 이게 모든 팀에 맞는 답은 아닙니다. 서비스 구조도 다르고, 팀이 일하는 방식도 다르니까요. 본인이 생각하는 구조가 저와 다르다면, 이건 그냥 하나의 예시입니다. 참고만 해주세요.