[Claude Code] 배운 그 주에 바로 써먹었다 — Epic Story·병렬 워크플로우·가설 디버깅·컨텍스트 관리로 사내 대시보드 만든 일주일

[Claude Code] 배운 그 주에 바로 써먹었다 — Epic Story·병렬 워크플로우·가설 디버깅·컨텍스트 관리로 사내 대시보드 만든 일주일

📝 한줄 요약

스터디에서 배운 4가지(에픽 스토리 / 다이내믹 워크플로우 / 가설 기반 실패 테스트 / 컨텍스트 관리)를, 그 주에 바로 회사 사내 지식 대시보드 만드는 데 전부 적용해본 기록입니다.

바쁘시면 이것만 읽어도 돼요:

• 흩어진 회사 기록(여러 마크다운 파일)을 사내에서 믿고 쓸 수 있는 지식 대시보드로 만드는 게 목표였어요.

• PRD → 에픽 스토리 → 병렬 에이전트 구현 → 가설 QA까지, 배운 순서대로 한 줄에 엮어서 시켰더니 AI가 그대로 따라왔습니다.

• 한 주 동안 병렬 에이전트 워크플로우를 33번 돌렸어요. 한 번에 최대 45개가 동시에 일한 적도 있습니다.

• 가장 인상적이었던 건 AI가 자기가 세운 가설 3개를 데이터로 직접 기각하고, 실제 브라우저 실험으로 진짜 원인을 찾아낸 순간(309px 가로 넘침 버그).

• 컨텍스트가 한 주에 6번 터졌는데, "이어서 해줘"로 버티던 초반에서 → 핸드오프 문서를 미리 써두는 후반으로 일하는 방식이 바뀌었습니다.

• 솔직히 아쉬운 것도 있어요(배포는 아직 localhost). 그래도 "배운 걸 바로 실전에 적용"이라는 목표는 달성했습니다.

🎯 이런 분들께 도움돼요

• 스터디에서 에픽 스토리 / 워크플로우 / 가설 테스트 같은 개념을 들었는데 막상 어디다 쓰는지 감이 안 잡히는 분

• AI에게 "그냥 만들어줘" 말고 방법론까지 지정해서 시키는 법이 궁금한 분

• 비개발자인데 AI로 혼자서 회사 내부 도구를 만들어보고 싶은 분

😫 문제 상황 (Before)

제가 운영하는 농업 R&D 회사의 업무 기록이 여러 마크다운 파일에 흩어져 있었습니다. 설치 장소별 추이, 장비 수량과 커버리지, 측정값 로깅, 현장 관찰 기록, 장소별로 누구와 어떻게 연결됐는지, 기업·기관 업무 흐름… 다 어딘가에는 적혀 있는데, 읽기 힘들고 · 믿고 쓰기 어렵고 · 의사결정에 바로 못 쓰는 상태였어요.

"이 숫자 출처가 뭐지?", "이 장소 누구랑 연결됐더라?"를 매번 파일 뒤져서 확인해야 했습니다. 그래서 흩어진 기록을 그대로 둔 채, 읽기 좋고 신뢰할 수 있는 사내 지식 대시보드로 보여주자는 게 이번 주 과제가 됐습니다.

마침 스터디에서 에픽 스토리, 다이내믹 워크플로우, 가설 기반 실패 테스트, 컨텍스트 관리를 배운 직후였어요. "이걸 그냥 듣고 넘기지 말고, 이번 대시보드 만들 때 다 써보자"가 이 글의 시작입니다.

🛠️ 사용한 도구

• 도구: Claude Code (메인), Codex CLI (프론트엔드 외주용)

• 모델/모드: Claude Opus 4.8 · ultracode (다중 에이전트 오케스트레이션 모드)

• 스킬: /show-me-the-prd(기획서 생성), /workspace-standardizer(폴더 표준화), /kkirikkiri(에이전트 팀), /pumasi(Codex 병렬 외주), 그리고 "computer use"(실제 브라우저로 화면 직접 확인)

• 결과물: 사내 지식 대시보드 (Astro 정적 사이트, 9개 뷰·23개 페이지)

🔧 작업 과정

1️⃣ 기획부터 — "만들어줘" 대신 "기획서부터 써줘"

처음부터 코드를 시키지 않았습니다. 흩어진 기록 폴더를 가리키면서, 무엇을 보여줄 대시보드인지 먼저 정의하게 했어요.

(회사 기록 폴더)를 기반으로 우리 회사 내부 대시보드를 만들려고해. 설치 장소별
추이 확인, 설치 장비 수, 장비 커버리지, 설치 후 측정값 로깅, 설치 후 현장 관찰
추이, 각 장소별 어떤 사람과 커넥션을 했는지 정리해

여기서 /show-me-the-prd로 PRD(제품 요구사항 문서) 를 먼저 뽑았습니다. 단순 메모가 아니라 진짜 기획서였어요 — 데이터 소스(읽기 전용 마크다운), 9개 뷰, 사용자(운영자), 제약(모든 수치는 출처 인용 / 인과 단정 금지 / 개인정보 마스킹)까지. 그리고 PRD가 01_PRD.md, 02_DATA_MODEL.md, 03_PHASES.md(단계 분리), 04_PROJECT_SPEC.md 파일로 디스크에 남았습니다.

💡 느낀 점: "만들어줘"라고 던지면 AI가 멋대로 가정하고 시작합니다. PRD를 먼저 파일로 남기게 하니, 이후 모든 작업이 그 문서를 기준으로 정렬됐어요. 기획서가 흔들림 방지 장치 역할을 했습니다.

2️⃣ 병렬로 굴리기 — 에이전트 하나가 아니라 팀으로

대시보드를 다 만든 다음, 화면이 영 마음에 안 들었습니다. "페이지마다 사람 붙여서 동시에 봐줬으면" 싶었어요. 그래서 그렇게 시켰습니다.

http://localhost:4321 의 모든 페이지를 매우 상세히 분석하고 (정본 내용)과 맞지 않는
내용은 모두 개선해줘. 페이지별로 에이전트를 붙여서 병렬로 확인하고 개선해

그러면 한 페이지에 한 에이전트씩 동시에 달라붙어서 각자 확인하고 고칩니다. 이게 다이내믹 워크플로우예요. 한 주 동안 이런 병렬 실행을 33번 돌렸는데, 한 번에 최대 45개 에이전트가 동시에 일한 적도 있었습니다. 보통은 "감사하는 에이전트 + 그 결과를 검증하는 에이전트"를 짝으로 붙여서, 한쪽이 찾은 문제를 다른 쪽이 "이거 진짜 문제 맞아?"로 걸러내게 했어요. (실제로 협력사 이름을 한 글자 틀리게 적은 오타 같은 걸 이 방식이 잡아냈습니다.)

💡 느낀 점: 한 명한테 "전부 다 봐줘" 하면 대충 봅니다. 일을 쪼개서 각자에게 한 조각씩 주니까 훨씬 꼼꼼해져요. PM이 된 기분이었습니다.

3️⃣ 4가지를 한 줄에 — 방법론을 통째로 지정한 프롬프트

이 주의 핵심 순간입니다. 프론트엔드 개선을 시키면서, 배운 걸 한 문장에 다 욱여넣어 봤어요. 결과물뿐 아니라 일하는 방법을 지정한 거죠.

프론트엔드는 /pumasi 를 사용해서 codex에게 시켜봐. 진행할때 Dynamic Workflow를
사용하고, 진행하기 전에 epic story로 작성하고 이에 대해 어떤 결과를 내야하는지
테스트를 (정의)하고, QA 진행시 문제가 있을 때 반드시 3가지 가설을 통해 QA 후
실패 테스트 후 해당 결과까지 이루어지도록 해

이 한 줄에 (1) 병렬 외주(Codex) (2) 다이내믹 워크플로우 (3) 에픽 스토리 (4) 가설 기반 실패 테스트가 다 들어있습니다. AI는 시킨 대로:

• 먼저 에픽 스토리를 파일로 작성했어요(EPIC_redesign_2026-06.md). "As(사내 사용자) / I want(모든 수치·관계가 정본과 일치하기를) / so that(믿고 의사결정에 쓸 수 있다)" 형식에, 인수기준(예: Lighthouse 접근성 90점 이상)과 테스트 항목까지 붙은 진짜 에픽이었습니다.

• 프론트엔드 구현은 Codex에게 외주(/pumasi)로 넘겼습니다. 단, 외주 주기 전에 되돌릴 수 있게 체크포인트(커밋) 부터 찍어두더라고요.

• 그리고 QA에서 문제가 나오면 무조건 가설 3개부터 세우게 했습니다.

💡 느낀 점: AI에게 결과만 요구하지 말고 "어떤 방식으로 일해라" 까지 적어주면 결과물의 신뢰도가 확 올라갑니다. 이 한 문장이 이번 주 전체에서 가장 잘 쓴 프롬프트였어요.

4️⃣ 하이라이트 — AI가 자기 가설을 스스로 기각한 순간

모바일(320px) 화면에서 한 페이지가 가로로 309px나 삐져나가는 버그가 있었어요. "반드시 3가설"이라고 시켜놨으니, AI가 원인 후보 3개를 세웠습니다.

• 가설 1: 표를 감싼 박스에 너비 제한 설정이 빠졌다

• 가설 2: 바깥 레이아웃(그리드)에 너비 제한이 빠졌다

• 가설 3: 표가 아니라 다른 넓은 요소가 범인이다

그런데 실제 브라우저에서 하나씩 재보니 — 세 가설이 전부 "이미 충족돼 있음" 이었어요. 보통이면 여기서 아무거나 갖다 붙이고 끝낼 텐데, AI가 이렇게 말했습니다.

"내가 세운 3가설은 전부 이미 충족돼 있어 기각. 한 단계 위에서 잡아야 합니다."

그러고는 화면에서 직접 실험을 했어요. 표를 숨겨보니 넘침이 0이 되고, 흔히 쓰는 해결책(overflow:clip)은 이 브라우저에선 안 먹혔고, 결국 contain:paint라는 속성 하나로 309px → 0px으로 잡았습니다. 고친 뒤에는 같은 화면을 다시 띄워서 "정말 0이 됐나" 실패 테스트를 재현해 확인까지 했고요.

💡 느낀 점: "그럴듯한 답"과 "진짜 원인"은 다릅니다. 세운 가설을 데이터로 기각할 줄 아는 것 — 이게 가설 기반 디버깅의 핵심이라는 걸 이 장면에서 제대로 봤어요. 사람이 디버깅할 때도 똑같이 해야 하는 거였습니다.

5️⃣ 컨텍스트 관리 — "이어서 해줘"에서 "핸드오프 문서"로

작업이 길어지니 대화 컨텍스트가 자꾸 가득 찼습니다. 한 주에 6번이나 한계에 부딪혔어요. 처음엔 그냥 이렇게 버텼습니다.

어디까지 진행했어?

Continue from where you left off. (이어서 해줘)

그런데 이게 반복되니까 비효율적이더라고요. 그래서 후반(SSOT 운영 시스템 작업)엔 방식을 바꿨습니다. 새 세션이 바로 이어받을 수 있게 핸드오프 문서를 미리 써두고, 새 대화를 그 문서로 시작했어요.

새 AI비서/Claude/Codex 세션이 바로 이어받을 수 있도록 핸드오프 문서를 만들었습니다.
이 문서에 담은 내용: 4대 핵심 문서와 우선순위 / 사용자 최종 목표 / 그동안의 결정
요약 / 다음 AI가 반드시 할 것과 하지 말아야 할 것

이 문서엔 "결정이 충돌하면 무엇을 우선한다"는 규칙까지 넣었습니다. 또 하나 배운 건 주입하는 문서는 작아야 한다는 것. 매 세션 자동으로 읽히는 파일이 너무 크면 토큰만 낭비하고 정작 핵심이 묻히거든요.

"자동 주입 파일이 너무 크면 토큰을 낭비한다 … 핵심만!"

이렇게 하니, 핸드오프로 시작한 세션은 컨텍스트가 한 번도 안 터졌습니다. 컨텍스트가 터지길 기다리는 게 아니라, 터지기 전에 상태를 문서로 빼두는 것 — 반응형에서 선제형으로 바뀐 셈이에요.

✅ 결과 (After)

Before vs After

결과물

• 사내 지식 대시보드가 로컬에서 동작. 빌드 검사 0 에러, 23페이지, 접근성 Lighthouse 94~95점.

• 한 주간 병렬 워크플로우 33회 실행, 에픽 스토리·QA 로그·PRD 문서가 전부 파일로 남음.

🙆 짚어둘 점: 외부 배포는 이번 범위에서 일부러 뺐습니다 — 사내 검증을 먼저 끝내는 게 우선이라 로컬에서 돌려보는 단계까지로 범위를 잡았어요(외부 공개는 계획상 다음 단계). 그리고 "병렬"은 Claude 쪽 에이전트가 한 거고, Codex 외주는 한 번에 1개씩 썼습니다. 화려한 자랑보단 기록에 가까운 결과지만, "배운 걸 바로 적용"이라는 목표는 충분히 달성했습니다.

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 결과가 아니라 방법을 지정하기. "만들어줘"가 아니라 "PRD부터 → 에픽 스토리 → 병렬로 → 문제 생기면 가설 3개"처럼 일하는 절차를 적어주면 결과물이 달라집니다.

2. 기획서·에픽을 파일로 남기게 하기. 대화 속 말은 휘발되지만 파일은 다음 세션도 기준으로 삼습니다.

3. 일을 쪼개서 병렬로. 한 명에게 "다 봐줘"보다 페이지/주제별로 에이전트를 나눠 붙이면 훨씬 꼼꼼합니다.

4. 컨텍스트가 터지기 전에 핸드오프 문서를 써두기. "이어서 해줘"를 반복하는 것보다 훨씬 깔끔합니다.

이렇게 하면 안 돼요

1. 첫 가설에 바로 안주하기. AI도 사람도 "그럴듯한 답"을 진짜 원인으로 착각합니다. 세운 가설을 데이터로 기각할 수 있어야 진짜 디버깅이에요.

2. 자동 주입 문서를 크게 만들기. 매 세션 읽히는 파일이 비대하면 토큰만 먹고 핵심이 묻힙니다. 핵심만, 짧게.

3. 방법론 이름만 외치기. "에픽 스토리 써줘"라고만 하면 형식만 흉내 냅니다. 인수기준·테스트까지 요구해야 진짜가 나와요.

🌍 다른 업무에 적용한다면?

• 흩어진 자료 정리가 필요한 누구나: 원본은 그대로 두고, "읽기 좋은 뷰"만 따로 만드는 패턴은 사내 위키·리포트·고객 자료에 그대로 적용됩니다.

• 검토/감사 업무: 항목별로 에이전트를 병렬로 붙여 "찾는 에이전트 + 검증하는 에이전트" 짝으로 돌리면 사람이 일일이 보는 병목이 줄어듭니다.

• 긴 작업의 인수인계: 핸드오프 문서 패턴은 팀원 간 업무 인계, 휴가 전 정리에도 똑같이 쓸 수 있어요.

🚀 앞으로의 계획

• 사내 검증이 끝나면 계획대로 외부 배포(접근 권한 걸어서 사내 공개) 단계로 넘어가기.

• 이번에 손으로 시킨 "에픽 → 병렬 → 가설 QA" 절차를 반복 가능한 규칙(룰) 으로 굳혀서 매번 타이핑 안 해도 되게 하기. (실제로 후반 작업에선 "작업 전 에픽 스토리, 문제 시 실패 가설 3~5개 + 재테스트"를 표준 규칙으로 적어두기 시작했어요.)

📋 재사용 가능한 프롬프트

프롬프트 1: 방법론까지 지정해서 시키기 (이번 주 핵심)

[개선할 대상]을 개선해줘. 진행하기 전에 에픽 스토리로 작성하고(As/I want/so that + 인수기준 + 테스트 항목), 작업은 페이지/주제별로 에이전트를 나눠 병렬로 진행하고, QA 중 문제가 생기면 반드시 원인 가설 3개를 세워서 하나씩 실패 테스트로 검증한 뒤 진짜 원인까지 찾아 고치고, 고친 뒤 같은 문제를 다시 재현해 해결됐는지 확인해줘.

[개선할 대상]을 본인 상황에 맞게 바꾸세요.

프롬프트 2: 가설 기반 실패 테스트

지금 [증상]이 발생해. 바로 고치지 말고,

1. 서로 다른 계층(데이터 / 화면 스타일 / 동작·빌드 / 환경)에서 원인 가설 3개를 세워줘.

2. 각 가설을 실제로 재현·측정해서 검증해줘.

3. 세운 가설이 전부 틀리면 솔직히 기각하고 다시 세워.

4. 진짜 원인을 찾으면 고치고, 같은 증상을 다시 재현해서 0이 됐는지 확인해줘.

[증상]을 본인 상황에 맞게 바꾸세요.

프롬프트 3: 컨텍스트 핸드오프 문서 만들기

다음 세션(또는 다른 AI)이 바로 이어받을 수 있게 핸드오프 문서를 만들어줘. 담을 내용: 최종 목표 / 지금까지의 핵심 결정 요약 / 기준이 되는 핵심 문서 목록 / 다음 작업자가 반드시 할 것과 하지 말 것 / 결정이 충돌할 때 무엇을 우선할지. 단, 매 세션 자동으로 읽힐 거니까 핵심만 짧게(핵심당 몇 줄) 써줘. 길면 토큰 낭비야.