파일이 늘어나는 날은 진전하고 있다는 기분이 든다. 늘어나지 않는 날은 멈춰 있는 기분이 든다. 나는 오랫동안 후자를 싫어했다. 하지만 Version 1.0에 가까워질수록, 멈춰 보였던 시간——리뷰(Review), 문서화(Documentation), 용어 통일——의 가치가 반전되었다. 구현(Implementation)보다 리뷰(Review)가 프로젝트를 앞으로 나아가게 했다고, 지금이라면 말할 수 있다.

이것은 "코드를 쓰지 않으니까 어쩔 수 없다"는 이야기가 아니다. 코드를 쓸 줄 아는 사람일수록 리뷰를 가볍게 여기기 쉽다. 가볍게 처리한 리뷰는 빠른 부채를 낳는다. 비엔지니어(Non-engineer) 프로젝트에서는 부채의 이자가 그대로 아침의 부담이 된다.

Connector가 늘어나고, Dashboard가 늘어나고, Human Approval 이야기가 나온다. 늘어난 것들은 각각 타당한 이유를 가지고 있었다. 하지만 전체로서 설명할 수 있는지는 별개의 문제였다. 설명할 수 없는 상태에서 Version을 올리면, Version은 라벨(Label)이 된다. 라벨은 안심을 위한 대용품일 뿐이다.

Vol.04에서 사양(Specification)의 오너(Owner)는 인간이라고 썼다. 오너십(Ownership)은 문서에 남지 않으면 사라진다. 사라진 사양은 구현의 속도에 의해 덮어씌워진다. 덮어씌워진 것은 깨달았을 때 되돌려야 한다. 되돌리는 작업은 신기능 개발의 두 배의 시간을 잡아먹는다.

그래서 "한 단계 더 구현을 멈추고 정리하는" 주가 왔다. 코드를 늘리지 않는 Architecture Review. 수수한 Step이지만, 이후의 RC(Release Candidate)로 직결된다.

테마는, Documentation First와 Architecture Review가 구현 속도보다 효과적이었던 이유다.

Documentation First는 예쁜 문장을 먼저 쓰는 것이 아니다. 결정한 것, 결정하지 않은 것, 변경한 이유를 구현과 같은 타이밍에 남기는 것이다. ADR(Architecture Decision Record)은 그 짧은 형식이다. CHANGELOG는 외부에서 보이는 이력이다. architecture review는 흩어진 설계를 하나의 지도로 되돌리는 작업이다.

Step34.6의 Architecture Review에서는 Python도 SQLite도 Streamlit도 만지지 않았다. 만지지 않으면 진전하고 있지 않다고 느껴진다. 그렇게 느껴지지만, 성과물은 많았다. glossary.md를 통해 용어를 통일했다. Kagoshimaniax OS, Connector, SQLite Connector, Interactive MCP Connector, Human Approval——같은 언어로 말할 수 있게 되면, AI와의 대화가 짧아진다.

development-history.md로 Phase를 정리했다. Step 1의 MCP 통합 구상은 방향 전환이 아니라 성숙(Maturation)으로서 기록했다. 성숙으로서 기록할 수 있으면 과거의 자신을 탓하지 않아도 된다. 자신을 탓하지 않으면 다음 판단이 빨라진다.

ADR-0001부터 ADR-0006까지. SQLite, Connector, MCP, Interactive MCP, Human Approval, Local First. 하나하나가 짧다. 짧기에 읽을 수 있다. 읽을 수 있기에 리뷰에서 "이것은 이미 결정되었다"라고 말할 수 있다. 그렇게 말할 수 있으면 동일한 논의의 재연이 줄어든다.

constitution.md와 philosophy.md도 두었다. North Star는 "매일 아침 10분 이내에 운영 방침을 결정"하는 것이다. 화려한 기능보다 수수한 지표가 프로젝트를 붙들어 주었다. 구속은 자유의 적이 아니라, 망설임의 적이다.

실패담: 나는 몇 번이고 "문서는 나중에 해도 된다"라고 말했다. 나중에 쓰려고 하면 쓸 수 없다. 구현의 세부 사항은 잊어버린다. 잊어버린 세부 사항은 추측으로 채워진다. 추측은 버그보다 무섭다. 버그는 고칠 수 있다. 추측은 방침이 된다.

또 다른 실패는 리뷰를 서로를 비난하는 것으로 만드는 것이다. 리뷰는 옳고 그름을 가리는 재판이 아니다. 설명 가능성(Explainability)의 점검이다. 점검에서 "모르겠다"가 나오면 승패의 문제가 아니라 문서화 태스크(Task)가 된다. 태스크로 넘어가면 앞으로 나아갈 수 있다.

세 번째는 CHANGELOG 업데이트를 잊는 것이다. 업데이트를 잊으면 과거의 내가 타인이 된다. 타인의 판단을 신뢰할 수 없으면 또 같은 곳에서 멈춘다. 멈출 때마다 구현은 진행되고 있는데 마음은 지친다.

Documentation First가 효과를 발휘한 장면은 Human Approval에 관한 논의였다. 조작 목록표는 구현 전에 읽었다. 읽고 나서 Green을 선택했다. 선택한 후에 구현했다. 순서가 반대라면 만든 후에 "이것은 위험하다"라고 깨닫게 된다. 깨달음은 늦다.

프로젝트 리뷰(Project Review, Step39)에서는 Must와 Nice, Known Limitations(알려진 한계)에 대한 이야기도 정리했다. 정리하지 않은 채 RC(Release Candidate)로 넘어가면, RC는 그저 "일단 내놓은 버전"이 되어버린다. RC는 동결(Freeze)의 선언이어야 한다. 동결을 선언하려면 무엇을 포함하고 무엇을 포함하지 않는지를 문서로 설명할 수 있어야 한다.

Analytics 페이지가 늘어나던 시기에도 구현은 빨랐다. GA4, Search Console, Clarity, Metricool——그래프와 표가 나열되면 성취감이 든다. 하지만 페이지 수만 늘어날 뿐, 용어가 통일되어 있지 않으면 "어떤 숫자를 믿어야 할지" 알 수 없다. 리뷰 주간에 glossary.md를 다시 읽었을 때, 내가 만든 화면의 설명이 타인의 문장처럼 느껴졌다. 타인의 문장처럼 느껴지는 이유는 결정의 이력(History)이 내 머릿속에 없기 때문이다. 이력을 외부로 꺼내면 머리가 가벼워진다.

README.md를 다시 쓰는 작업도 구현이 전혀 없는 날에 수행했다. 표나 링크를 정리하는 것처럼 보일 수도 있다. 하지만 README는 프로젝트의 얼굴이다. 얼굴이 두 개라면 둘 다 거짓말처럼 보인다. Architecture Review에서 브랜드(Kagoshimaniax OS)와 범용 아키텍처(AI Local Business Platform)를 분리한 것도 같은 이유였다. 분리하면 무엇이 이 사이트를 위한 것인지, 무엇을 미래의 모델(Type)로서 남길 것인지 이야기할 수 있다.

CHANGELOG에 Step을 추가하는 습관은 처음에는 번거로웠다. 번거로운 작업일수록 나중에 효과를 발휘한다. 그 효과는 Qiita 원고를 쓰는 바로 지금 이 순간 나타난다. 당시의 감정을 로그와 CHANGELOG가 떠올려 준다. 떠올릴 수 있기에 체험담으로서 쓸 수 있다. 쓸 수 있기에 기술 해설이 아닌 연재물로서의 가치가 생긴다.

리뷰는 지연이 아니라 압축이라고 생각한다. 한 번의 정리로 몇 주간 이어질 동일한 논의를 생략할 수 있다. 생략은 시간의 절약이 아니라 주의력(Attention)의 절약이다. 주의력은 비엔지니어(Non-engineer)에게 가장 부족한 자원이다.

또한, 리뷰는 완벽을 목표로 하지 않는다. 용어가 100% 통일될 때까지 기다리면 영원히 내보낼 수 없다. 통일된 부분까지만을 Version으로 끊는다. 끊어내는 용기 또한 리뷰의 성과다. Version 1.0.0-rc1은 그 끊어내는 방식 중 하나가 된다.

AI는 리뷰에 적합했다. 반대 의견, 누락, 용어의 불일치——질문하면 답을 해준다. 답을 해주지만, 채택하는 것은 인간이다. 채택한 것을 ADR(Architecture Decision Record)에 남긴다. 남겨두면 다음 AI 세션도 동일한 지도 위에서 시작할 수 있다.

리뷰 주간은 팀에게 "휴식"이 아니었다. 호흡을 가다듬는 주간이다. 흩어진 판단을 한 번에 끌어올려 내뱉는다. 내뱉은 것이 문서가 된다. 문서는 다음 구현의 연료가 된다. 연료가 없는 구현은 단거리 달리기처럼 보일 수는 있어도 마라톤에는 적합하지 않다. 지역 미디어 운영 OS는 마라톤이다.

비엔지니어가 리뷰를 주전장으로 삼을 수 있었던 이유는, 코드 차이(Code Diff)를 읽지 않더라도 결정과 이유가 담긴 문장이라면 검토(Peer Review)할 수 있기 때문이다. 검토할 수 있는 영역을 넓히면 프로젝트의 주도권이 자연스럽게 돌아온다. 돌아온 주도권은 Human Approval(인간 승인) 사상과도 연결된다.

Step 로그를 다시 읽는 습관은 리뷰 주간 이후에도 계속했다. 계속하다 보면 당시의 "나아가고 있다는 느낌"이 재현된다. 재현되면 동일한 함정을 알아챌 수 있다. 함정은 성공 경험 바로 옆에 있다. 함정이 존재하기에 기록은 축배를 든 직후에 써야 한다. 나중에 쓰면 미화된다. 미화는 체험담의 적이다.

• 파일이 늘어나는 날과 설명할 수 있는 날은 같지 않다
• Documentation First는 결정과 이유를 구현과 동시에 남기는 것이다
• ADR과 CHANGELOG는 동일한 논의의 재연을 줄인다
• Architecture Review는 코드를 늘리지 않고도 앞으로 나아갈 수 있게 한다
• 용어 통일은 AI와의 대화 비용을 낮춘다
• 리뷰는 재판이 아니라 설명 가능성(Explainability)의 점검이다

다음에는 정리의 끝에 놓아둔 구분점——Version 1.0.0-rc1까지의 여정——을 쓸 것이다. 더하지 않기로 한 결단과 141개 테스트에 관한 이야기다.

Step48의 동결, Must 체크리스트, Known Limitations——RC의 의미를 작성합니다.