AI 워터폴 개발: 컨텍스트 제로(Context Zero)인 AI를 숙련자로 만드는 메커니즘

서론

Claude Code를 사용하기 시작하자마자 바로 깨달았다. 세션을 열 때마다 AI는 아무것도 모르는 상태에서 시작한다.

지난주에 이야기한 사양 변경도, ADR(Architecture Decision Record)로 결정한 설계 방침도, 해당 구현이 의존하고 있는 요구사항도 전부 없다. 매번 처음부터 다시 설명해야 한다. 그런데도 "영향 범위가 누락되었다"라거나 "다른 사양과 모순된다"라는 문제가 발생한다.

AI와의 개발에 워터폴(Waterfall)적인 추적성(Traceability) 메커니즘을 도입하여 이 문제를 해결하려고 시도한 이야기를 쓰고자 한다.

AI는 "온보딩만 받은 신입 사원"

매일 아침, 기억이 리셋된 신입 사원이 출근한다. 프로젝트의 배경도, 과거의 의사결정도 아무것도 가지고 있지 않다. 손에 쥐고 있는 것은 그날 전달받은 1~2장의 문서뿐이다.

다단계 하청의 말단 구현자에 가깝다. 눈앞의 태스크는 수행하지만, 옆의 업무 흐름(Workflow)과 DB를 공유하고 있다는 사실은 깨닫지 못한다. 사양의 모순도 전달받은 자료의 밖에 있다.

"컨텍스트 엔지니어링 (Context Engineering)"을 통해 문서를 전달하면 해결될 것이라 생각했지만, 그것만으로는 부족했다. AI에게는 "무엇과 무엇이 연결되어 있는가"를 스스로 추적할 수 있는 메커니즘이 필요하다.

문서에 관계성을 부여하기

워터폴 개발의 "워터폴" 부분은 필요 없다. 원하는 것은 오직 추적성(Traceability)뿐이다.

이 기능은 어떤 요구사항(Requirement)에서 왔는가
이 사양(Specification)은 어떤 의사결정에 기반하고 있는가
이 코드가 바뀌면 어떤 테스트(Test)가 영향을 받는가

이를 AI가 스스로 추적할 수 있는 상태로 만드는 것, 그것만이 내가 하고 싶은 일이었다.

문서 체계: 이론값으로부터 설계하기

"일단 문서를 늘리자"가 아니라, 어떤 기능이 동작하기 위해 몇 건의 문서가 필요한지를 먼저 계산했다.

레이어	역할	최소 건수	이유
ADR (Why)	설계 판단의 근거	2건	1건이면 비교 및 소급이 성립하지 않음
...

너무 적으면 그래프 검색(Graph Search)이 자명한 결과만을 반환한다. 너무 많으면 준비 비용이 올라가 아무도 지속하지 않는다. 처음에는 더 적은 수로 시도해 보며 "이것만으로는 영향이 횡단적으로 파악되지 않네"라고 깨달은 뒤에 늘려 나갔다. 이 숫자는 그러한 시행착오의 결과다.

GraphDB

노드(Node)와 에지(Edge)로 표현한다. 문서를 노드로 등록하고, 참조 관계를 에지로 연결한다.

// ADR → REQ → SPEC → TestCase 의 3-hop 추적성
MATCH (adr:ADR)-[:MOTIVATES]->(req:Requirement)
-[:DEFINED_BY]->(spec:Specification)
...

이벤트 예약 시스템 샘플로 테스트해 보니 38개의 노드와 44개의 에지가 생성되었다. 에지는 6종류이다: MOTIVATES (ADR→REQ), DEFINED_BY (REQ→SPEC), COVERED_BY (SPEC→BF), VERIFIED_BY (TC→SPEC), IMPLEMENTED_BY (src→SPEC), VALIDATES (src→TC).

Neo4j Browser で見たトレーサビリティグラフ（38ノード・44エッジ）

본문은 넣지 않는다. "무엇과 무엇이 연결되어 있는가"만을 가진 지도로 사용한다.

GraphRAG: 2단계 검색으로 컨텍스트를 최소화하기

일반적인 RAG는 "의미적으로 유사한 텍스트를 찾는" 것에 불과하여 그래프의 관계를 추적할 수 없다.

GraphRAG 2段階検索フロー: pgvector近傍検索 → Neo4jグラフ展開 → コンテキスト生成

로컬의 384차원 일본어 대응 모델(paraphrase-multilingual-MiniLM-L12-v2)을 사용하고 있으므로 OpenAI API는 필요하지 않다.

result = graphrag_search("취소 정책과 관련된 테스트 케이스")
# → SPEC-004(취소), TC-BOOK-008~010이 반환됨

문서가 늘어나도 AI에게 전달하는 것은 관련 있는 몇 건으로 충분하다. 전부 읽게 하는 것보다 필요한 부분만 깊게 파고든다.

Claude Code Skills: AI의 행동을 패턴화하기

`/impact-report`

코딩 전: 구현을 시작하기 전에 AI가 영향 범위를 자기 평가한다.

## 변경 영향 보고서
### 변경 요구사항
[AI가 이해한 변경 내용]
...

갑자기 코드를 쓰게 하지 않는다. 코드 리뷰(Code Review) 전에 이해 리뷰(Understanding Review)를 수행한다.

`/spec-check`

사양 확인: 요구사항과 사양의 정합성을 확인하여 모순되거나 정의되지 않은 부분을 찾아낸다. 구현 전에 여기서 멈출 수 있다.

`/trace-test`

구현 후: 테스트 케이스를 사양 ID와 함께 생성한다. 나중에 "이 테스트가 무엇을 위한 것인가"를 추적할 수 있다.

def test_cancel_within_24h():
"""
TC-BOOK-004: 개최 24시간 전 이후의 취소
...

/cross-review

/waterfall-pr

PR 리뷰 전: 요구사항(Requirement)·영향(Impact)·테스트(Test)·코드(Code)·회귀(Regression)의 5개 축으로 체크리스트를 만들고, PR 본문도 생성한다.

GitHub Actions: 자동화를 통해 메커니즘을 강제하기

doc-lint.yml

문서 린트 (Document Lint) (sample-project/docs/)

문서에 변경이 있으면 CI(지속적 통합)가 실행된다. 파일 이름의 명명 규칙, 필수 섹션의 존재, 교차 참조(Cross-reference)의 실재 여부를 확인한다. 깨진 참조가 있으면 실패한다.

pr-impact.yml

PR 영향 범위 코멘트 (PR을 제출하면 봇이 자동으로 코멘트를 남긴다.)

## 추적성 영향 보고서 (Traceability Impact Report)
### 변경된 파일
- REQ-002-booking.md
...

문서를 변경할 때마다, 그 변경이 무엇에 영향을 미치는지 자동으로 출력된다.

기존 프로젝트에 도입하기

문서가 없는 프로젝트에 도입하는 경우, 먼저 /reverse-doc을 사용하여 코드로부터 문서를 역생성하여 출발점을 만든다.

/reverse-doc
# 생성되는 파일
docs/business-flows.md # ⚠ 코드로부터 역생성
...

생성물은 모두 "⚠ 코드로부터 역생성" 태그가 붙으며, 사람이 정확성을 확인한 후에 사용한다. 그 후 Neo4j와 pgvector에 인덱스를 투입하면 GraphRAG가 작동한다.

아키텍처 전체도

Claude Code Skills
↓ /impact-report / /spec-check / /trace-test / /waterfall-pr
MCP Server (traceability)
...

로컬 환경은 Docker (Neo4j + PostgreSQL/pgvector)로 완결된다. 외부 API는 필요하지 않다.

마치며

컨텍스트를 전달하는 것만으로는 부족하다는 것을 깨달은 것은 한동안 사용한 후였다.

문서를 전달하면 AI는 읽는다. 하지만 "이 DB 컬럼을 바꾸면 무엇이 망가지는가"는 문서를 읽어도 알 수 없다. 그것은 문서들 사이의 관계를 추적해야만 알 수 있는 내용이다.

워터폴(Waterfall)의 경직성은 필요 없다. 추적성(Traceability)만을 가져온다. 그것이 이번에 시도한 것이며, 현재까지는 잘 작동하고 있다. 다만, 처음부터 문서를 정비하는 습관이 없는 팀에 도입하는 것은 아마 어려울 것이다. 그 부분은 아직 해결되지 않았다.

슬라이드는 여기에서 확인하세요: https://tomohiro-owada.github.io/ai-doc-driven-dev/