요건으로부터 사양과 ADR까지 자동화하는 OKF 기반의 하이브리드 RAG

OKF-RAG v1을 만들었습니다.

요건을 전달하는 것만으로, 사양 docs 탐색, 영향 범위 조사, 불명확한 점 도출, 문서 업데이트 제안, ADR 기록까지 진행하는 CLI + Agent Skill입니다.

벡터 DB와 그래프 DB를 결합한 RAG를 통해, 문서군으로부터 관련 사양과 의존 관계를 추적합니다. AI가 구현(Implementation)으로 넘어가는 것은 사양 확인과 사용자 승인이 끝난 후입니다.

무엇을 해결하고 싶었는가

AI 코딩에서 두려운 점은, AI가 "그럴듯하게 보완해서" 구현해 버리는 것입니다.

요건 정의, 기본 설계, 상세 설계, API, DB, 테스트, 운용. 이런 문서들이 연결되어 있는 프로젝트에서는 하나의 변경이 곳곳으로 파급됩니다.

하지만 AI는 눈앞의 코드나 일부 docs만을 보고 멋대로 판단해 버릴 때가 있습니다. 악의는 없습니다. 아마 보이는 범위 내에서는 맞을 것입니다. 다만 그 범위가 좁을 뿐입니다.

그래서 AI에게 이러한 흐름을 밟게 하고 싶었습니다.

요건
-> 관련 docs 탐색
-> 현재 사양 읽기
...

OKF를 사양의 정본(Source of Truth)으로 만들기

OKF-RAG에서는 Open Knowledge Format을 사용합니다.

정본은 Markdown + YAML frontmatter입니다. SQLite나 embedding은 검색을 위한 캐시일 뿐, 사양 그 자체는 아닙니다.

검색 index가 망가져도, embedding provider가 다운되어도, docs가 남아 있다면 다시 만들 수 있습니다. 이런 형태로 만들고 싶었던 이유는 사양을 Git으로 관리되는 텍스트로서 남기고 싶었기 때문입니다.

frontmatter를 추적성(Traceability) 장부로 만들기

YAML frontmatter에는 태그뿐만 아니라 문서 간의 관계도 부여합니다.

예를 들어, 다음과 같은 관계입니다.

• 이 요건은 어떤 사양에 반영되어 있는가
• 이 API는 어떤 화면이나 DB와 관계가 있는가
• 이 테스트는 어떤 사양을 검증하고 있는가
• 이 사양 변경은 어떤 Decision Record에 기반하고 있는가

frontmatter를 경량 추적성 장부로 사용한다는 발상입니다.

폭포수(Waterfall) 모델에 가까운 문서군과는 궁합이 좋을 것입니다. 요건, 설계, 구현, 테스트, 운용이 처음부터 선으로 연결되어 있다는 전제이기 때문입니다.

State-Aware RAG로 다루기

OKF-RAG는 단발성으로 검색하여 답하는 RAG가 아닙니다.

AWS의 연구에서 소개된 State-Aware RAG의 개념을 참고하여, 검색과 평가의 중간 상태(Intermediate State)를 가집니다.

AI는 예를 들어 다음과 같은 상태를 확인합니다.

• 관련 docs를 찾았는가
• 근거가 되는 section을 읽었는가
• 영향 범위는 충분한가
• 불명확한 점이 남아 있는가
• 사용자 승인이 있는가
• Decision Record는 남겨졌는가
• audit의 blocking error는 0건인가

갖춰지지 않았다면 진행하지 않습니다.

ready_for_implementation 상태가 될 때까지는 구현하지 않습니다. 이 부분만큼은 상당히 강력하게 제약하고 있습니다.

CLI와 Agent Skill

OKF-RAG는 Go 언어의 단일 바이너리 CLI로 제작되었습니다.

자주 사용하는 것은 다음과 같습니다.

okf-rag search "결제 재시도 사양" --db okf.db
okf-rag ask "이 사양 변경의 영향 범위는?" --db okf.db --skill waterfall-impact-analysis
okf-rag update-docs "카드 결제 재시도 횟수를 3회에서 5회로 변경한다" --db okf.db --dry-run
...

AI 에이전트를 위해서는 JSON 출력과 schema / describe 기능도 있습니다.

okf-rag schema --output json
okf-rag describe search --output json
okf-rag describe update-docs --output json

에이전트가 도구의 사용법을 스스로 읽을 수 있도록 하기 위함입니다. 인간을 위한 도움말(Help)만 있다면 대개 어딘가에서 잘못 읽기 때문입니다.

Decision Record와 Knowledge Principle

사양 변경 시 남기고 싶은 것은 「무엇을 결정했는가」만이 아닙니다.

• AI가 제안한 판단
• AI가 사용자에게 던진 질문
• 사용자의 답변
• AI가 질문하지 않고 설정한 전제
• 어떤 docs를 업데이트 대상으로 삼았는지

이러한 부분들을 종합하여 남기고 싶습니다.

OKF-RAG에서는 승인된 사양 판단을 Decision Record로서 남깁니다. ADR (Architecture Decision Record)과 유사하지만, AI 개발을 위해 조금 더 세밀한 기록을 가집니다.

반복적으로 승인된 판단은 Knowledge Principle로서 추상화할 수 있습니다. 단, AI가 멋대로 "이것은 암묵지입니다"라고 말하는 것은 허용하지 않습니다. 사용자가 승인한 Principle만을 차후의 전제로 사용할 수 있습니다.

벡터 검색과 그래프 탐색의 이중 구조

OKF-RAG의 검색은 벡터 검색(Vector Search)에만 치우쳐 있지 않습니다.

먼저, dense / sparse embedding을 통해 의미적으로 가까운 docs나 section을 찾아냅니다. 일본어의 경우, ruri-v3 dense + bge-m3 sparse의 hybrid retrieval (하이브리드 검색)을 상정하고 있습니다.

그 후, frontmatter의 trace

입구는 벡터 검색, 영향 범위 조사는 그래프 탐색. 이러한 이중 구조입니다.

단, embedding도 graph index도 캐시(Cache)입니다. 원본(Source of truth)은 OKF Markdown + YAML frontmatter입니다.

OKF-RAG에서는 provider가 유효한 상태와 degraded mode (성능 저하 모드)를 구분합니다.

• degraded=false: embedding provider를 사용할 수 있음
• degraded=true: provider-less 탐색 모드

degraded mode에서도 docs 탐색은 가능합니다. 하지만 이를 embedding 활성화 시의 검색 정밀도 평가로 취급해서는 안 됩니다.

이러한 경계가 없으면 AI가 검색 결과나 graph 전개를 과신하게 됩니다. 그 부분은 상당히 위험합니다.

실제 프로젝트에서 검증

실제 프로젝트의 docs 군으로 검증했습니다.

주문 상태 전이와 같은 query (질의)에서는 API 설계, 설계 규약, shared core, DB 설계 등 구현 전에 읽어야 할 문서로 추적할 수 있었습니다.

광고 모델 query에서도 광고 사업 설계나 광고 UX docs에 도달할 수 있었습니다.

ask나 update-docs가 최종 판단을 대행하는 것은 아닙니다. 역할은 탐색, 부족분 탐지, 정지의 보조입니다. 이 부분은 의도대로 동작합니다.

무엇이 좋은가

OKF-RAG가 있으면 AI에게 다음과 같은 동작을 강제할 수 있습니다.

사양을 읽지 않고 구현하지 말 것
근거 section을 확인할 것
영향을 받는 docs를 조사할 것
...

AI에게 "사양의 중력"을 부여하는 느낌입니다.

v1 출시

v1은 GitHub Releases를 통해 배포하고 있습니다.

• macOS Apple Silicon
• Linux x86_64
• Windows x86_64
• 표준 Skill pack

SQLite, embedding model, LLM provider는 바이너리에 포함되어 있지 않습니다. 환경에 따라 외부에서 연결합니다.

요약

OKF-RAG는 AI가 멋대로 구현을 진행하기 위한 도구가 아닙니다.

요건에서 사양으로 돌아가고, 관련 docs를 찾고, 영향 범위를 조사하며, 불명확한 점을 질문하고, 승인된 의사결정을 ADR로서 남기는 것. 이를 위한 CLI + Agent Skill입니다.

아직 완벽한 자동 사양 관리 도구는 아닙니다. 하지만 AI가 구현 전에 docs로 돌아가 근거를 읽고, 모호하면 멈추는 단계까지는 도달했습니다.

이제부터는 실제 프로젝트에서 사용하며 다듬어 나가겠습니다.

Discussion