서론

소프트웨어 개발에 있어, 사양(Specification)과 코드의 괴리는 심각한 문제입니다. 사양이 업데이트되었음에도 구현이 이를 따르지 않거나, 반대로 어느 쪽이 올바른 상태인지 불분명해지는 경우가 적지 않습니다.

이러한 문제에 대해 기존의 해결 방법은 인간의 프로세스에 의존하는 것이었습니다. 코드 리뷰(Code Review)로 확인하거나, 테스트 문서(Test Document)를 작성하는 등... 하지만 이는 시간이 많이 걸리고 확실성이 부족합니다.

Drift는 이 과제에 기계적인 접근 방식으로 대응하는 오픈 소스(Open Source) 툴입니다. 사양과 코드의 대응 관계를 자동으로 검출·유지하며, 항상 동기화된 상태를 유지할 수 있습니다.

Drift란?

Drift는 사양과 코드의 대응 관계를 기계적(mechanical)으로 관리하는 툴입니다. 기존의 문서 검색(

// @spec: docs/auth.md#로그인 처리
async login(user: string, password: string): Promise<string> {
// ...구현...
...

상태 관리 (State Management): Fresh / Stale / Broken

3. 링크 상태는 항상 다음 세 가지 중 하나로 분류됩니다:

Fresh✅ — 사양과 코드 모두 마지막 승인 시점 이후로 변경되지 않음 -
Stale⚠️ — 둘 중 하나가 변경됨 -
Broken❌ — 코드 측이 삭제됨 (이름 변경(rename) 감지를 통해 복구 가능)

이름 변경 추적 (Rename Tracking)

4. 코드가 단순히 이름만 변경된 경우, 링크를 자동으로 추적할 수 있습니다. 해시(hash) 값이 변하지 않고 새로운 이름과 일치한다면, Drift가 자동으로 제안합니다.

✗ [3] BROKEN (symbol missing) login ↔ docs/auth.md#로그인 처리
↳ moved? source now matches 'authenticate' — drift relink 3

의미론적 검증 (Semantic Verification): LLM을 통한 검증

5. drift verify 명령어를 사용하여, Claude를 통해 Stale 상태인 링크가 실제로 모순되는지 판정할 수 있습니다.

npx drift verify --diff origin/main

이를 통해 단순한 코드 포맷팅 변경은 무시하면서, 실질적인 의미(semantic)의 변경을 감지할 수 있습니다.

사용법

설치

npm install -D driftdocs

초기화

npx drift init

백엔드(builtin 또는 codegraph), AI 에이전트, 전략을 선택합니다.

주요 명령어

실례: 부트스트랩 (Bootstrap)

기존 코드베이스에 Drift를 도입하는 경우:

npx drift suggest # 후보 나열
npx drift suggest --apply # 모든 후보 자동 생성
npx drift coverage # 진행 상황 측정

에디터 통합

VS Code 확장

Drift는 VS Code 확장을 제공하며, 각 링크된 심볼 위에 CodeLens가 표시됩니다. (아직 미완성이나 향후 대응 예정)

spec: ✓ fresh docs/auth.md#로그인 처리

Stale 링크에는 Approve 버튼이, Broken 링크(이름 변경 감지됨)에는 Relink 버튼이 표시됩니다.

Obsidian 플러그인

사양 작성자를 위해 Obsidian 플러그인이 제공됩니다. 각 섹션의 링크 상태가 배지로 표시되며, 클릭 한 번으로 승인 및 해제가 가능합니다. 또한 Publish 버튼으로 커밋(commit) 및 푸시(push)를 할 수 있습니다. (이 또한 OSS로 공개되어 있으나, 커뮤니티 플러그인으로는 아직 미출시 상태입니다. 향후 출시 예정입니다.)

PR 봇

GitHub Actions를 사용하여 PR(Pull Request)마다 링크 검증을 자동 실행할 수 있습니다. 변경된 파일과 관련된 링크만 검증하기 때문에 효율적입니다.

.github/workflows/drift-pr-bot.yml을 복사하는 것만으로 도입할 수 있습니다.

Drift의 독푸딩 (Dogfooding)

Drift 스스로가 Drift를 사용하고 있습니다. 리포지토리의 docs/design.md는 Drift의 디자인 결정 사항을 기록하고 있으며, 각 섹션은 @spec: 어노테이션 (annotation)을 통해 구현부와 연결되어 있습니다. CI (Continuous Integration)에서 링크 검증이 실행되며, Stale(오래된) 또는 Broken(깨진) 링크가 있으면 빌드(build)가 실패합니다.

이러한 자기 검증(self-verification)을 통해 이미 여러 버그가 탐지되었습니다:

• tree-sitter lexer의 파싱 트랩(parsing trap)으로 인한 버그
• 명시적인 앵커 오버라이드(anchor override)의 슬러그 하이재킹(slug hijacking)

이 문제들은 Drift의 링크 검증을 통해 조기에 발견되었습니다.

설계상의 특징

• 🔍 탐지는 해시 비교만 수행 — LLM은 필요한 경우에만 사용
• ⚡ O(edge-degree) 인덱스 검색 — 빠른 참조
• 🌳 Git으로 관리되는 마크다운 (Markdown) — Obsidian 호환, 공개는 명시적으로
• 📈 단계적인 링크 추가 — 강제적인 배치 처리(batch processing) 없음
• 🛡️ 엄격한 설정 검증 — 위험도가 높은 설정은 거부

요약

Drift는 사양(specification)과 코드의 동기화를 기계적으로 보장하는 도구입니다.

• 📚 AI 에이전트의 토큰(token) 절감
• ✅ 명확한 상태 관리
• 🚀 에디터 통합을 통한 개발 효율 향상
• 🤖 필요한 경우에만 LLM 활용

사양을 철저히 관리하고 싶거나, AI 도구와 결합하여 효율성을 높이고 싶은 프로젝트라면 꼭 Drift를 사용해 보세요.

GitHub: https://github.com/sho-ritz/drift

참고 자료

Discussion