왜 우리는 문서부터 만들었나

WooSunLab의 개발은 코드가 아니라 문서에서 시작했습니다. 구현에 들어가기 전에 정본 문서 체계와 품질 게이트부터 세웠습니다. 밖에서 보면 느린 길처럼 보이지만, AI와 함께 소프트웨어를 만드는 팀에게는 이것이 가장 빠른 길이라고 믿습니다.

AI 시대의 개발, 병목은 타이핑이 아니다

AI는 코드를 빠르게 씁니다. 문제는 속도가 아니라 방향입니다. 무엇을 만들어야 하는지, 어디까지가 허용 범위인지, 무엇이 금지인지가 흐릿하면 AI는 그럴듯하지만 틀린 결과물을 빠르게 쌓아 올립니다. 빠른 손에게 필요한 것은 명확한 계약입니다.

코드보다 설계 문서를 먼저 쓰는 문화는 소프트웨어 업계에서 오래 검증된 방식이기도 합니다. 구글의 엔지니어링 문화를 다룬 Design Docs at Google이 설명하듯, 문서의 가치는 코드를 쓰기 전에 트레이드오프와 실패 지점을 가장 싼 비용으로 발견하게 해 준다는 데 있습니다. AI가 구현을 맡는 팀에서는 이 가치가 더 커집니다 — 문서가 곧 AI에게 건네는 작업 지시서이자 채점 기준이 되기 때문입니다.

그래서 우리는 구현 전에 문서로 계약을 만들었습니다. 제품이 지켜야 할 신뢰 원칙(승인 없는 자동 실행 0건, 모든 결과에 근거 기록), 공개해도 되는 정보와 안 되는 정보의 경계, 각 작업의 완료 조건(Definition of Done). 이 문서들이 모든 작업의 판단 기준, 즉 정본(Single Source of Truth)이 됩니다.

만드는 AI와 검수하는 AI를 분리한다

문서가 계약이라면, 게이트는 계약 이행을 확인하는 장치입니다. 우리는 구현하는 AI와 검수하는 AI의 역할을 분리했습니다. 같은 AI가 만들고 스스로 검사하면 자기 결과물에 관대해지기 쉽습니다. 그래서 구현 결과물은 독립적인 리뷰를 거치고, 체크리스트 기반 검증을 통과해야 완료로 처리됩니다. “통과했을 것”이라는 추정은 인정하지 않고, 실행 결과로만 판정합니다. 빌드가 실제로 통과했는가, 금지 목록 위반이 0건인가, 완료 조건을 전부 충족했는가 — 항목마다 답은 예/아니오뿐입니다.

이 방식은 우리 제품이 고객에게 약속하는 것과 정확히 같은 구조입니다. Flow가 만든 콘텐츠가 사실 검증과 법무 체크를 거치듯, 우리의 코드와 문서도 같은 종류의 게이트를 거칩니다. 고객에게 파는 원칙으로 우리 자신을 먼저 운영하는 것 — 이것이 우리가 생각하는 정직한 제품 개발입니다.

이 블로그도 그 산출물이다

지금 읽고 계신 이 글도 정본 문서(회사 브리프)에 근거해 작성되고, 금지 목록 검사를 거쳐 게시됐습니다. 근거 없는 실적 수치를 쓰지 않는 것, 확정되지 않은 일정을 확정처럼 말하지 않는 것, 데모에 “시뮬레이션”을 명시하는 것 — 전부 문서에 적힌 규칙이고, 게시 전에 검사되는 항목입니다. 앞으로 이 블로그에는 기능 소식과 함께 이런 개발 여정의 기록을 남기려 합니다. 과장 없이, 근거와 함께.

WooSunLab이 어떤 원칙으로 움직이는지는 회사 소개에서 더 보실 수 있습니다.

정본 문서가 답하는 세 가지 질문

문서	답하는 질문	우리의 예
원칙 문서	무엇을 절대 하지 않는가	승인 없는 자동 실행 0건, 근거 없는 수치 게시 금지
경계 문서	무엇을 공개하고 무엇을 숨기는가	사업자 정보는 최소 공개, 내부 코드명 게시 금지
완료 조건(DoD)	무엇이 “끝났다”는 뜻인가	빌드 통과 + 금지 위반 0건 + 배포 확인

작은 팀이라면 세 문서가 각각 한 장이어도 충분합니다. 중요한 것은 분량이 아니라, 판단이 필요할 때 돌아갈 곳이 정해져 있다는 사실입니다.

자주 묻는 질문

작은 가게·1인 팀도 문서부터 시작해야 하나요? 형식을 갖출 필요는 없습니다. “우리가 절대 안 하는 것”과 “끝났다의 기준” 두 목록만 메모로 적어 두어도, AI 도구에게 일을 시킬 때 지시서와 채점 기준이 생깁니다.

문서를 먼저 쓰면 개발이 늦어지지 않나요? 사람이 타이핑하던 시절의 직관입니다. 구현이 빨라진 지금의 병목은 방향이고, 문서는 방향을 고정하는 가장 싼 도구입니다 — 잘못 만든 뒤 버리는 비용보다 문서 한 장이 쌉니다.

---

참고 자료

• Design Docs at Google (Malte Ubl, Industrial Empathy) — 구현 전 설계 문서 문화의 가치