noye-phase-5-and-6.md

나만의 도비 만들기 #1 — Noye

최근에 나만의 도비 만들기 프로젝트를 시작했습니다.

기존에는 Obsidian과 AI 에이전트를 연결해 세컨드 브레인처럼 사용하고 있었습니다.

문서를 모아두고, 필요한 내용을 검색하고, AI에게 질문하고, 다시 새로운 지식으로 정리하는 방식이었습니다.

그러다 문득 생각했습니다.

“이 로직을 그냥 내가 쓰는 앱으로 만들면 되지 않을까?”

그래서 시작한 프로젝트가 Noye입니다.

이름에는 별로 거창한 사연이 없습니다.

처음에는 가제로 Note라고 적으려고 했는데, t 옆에 있는 y를 잘못 눌러 Noye가 됐습니다.

그런데 가만히 보니 한국어로 읽으면 노예였습니다.

나만의 파일을 읽고, 정리하고, 찾아주고, 문서까지 만들어주는 로컬 AI.

생각보다 프로젝트의 정체성과 너무 잘 맞았습니다.

그래서 오타를 고치지 않았습니다.

버그가 기능이 된 첫 사례입니다.

그렇게 Noye를 계속 만들다가 오늘 Phase 5, 문서 워크스페이스를 마무리했습니다.

그리고 바로 Phase 6, 신뢰성(Reliability) 작업에 들어갔습니다.

처음에는 간단해 보였습니다.

문서 기능 만들고, DB에 컬럼 몇 개 추가하고, 테스트 돌리면 끝.

물론 개발에서

“이거 몇 개만 하면 끝인데?”

라는 생각은 대체로 오래가지 않습니다.

이번에도 그랬습니다.

답변을 문서로 만들기

Noye의 채팅 답변 아래에 Create document 버튼을 추가했습니다.

버튼을 누르면 바로 저장하는 대신 먼저 묻습니다.

“이걸 무엇으로 만들까?”

같은 답변이라도 복습 노트가 될 수도 있고, 요약이 될 수도 있고, 단계별 가이드가 될 수도 있기 때문입니다.

사용자가 입력한 지시문을 바탕으로 초안을 생성하고, 그 결과를 다시 직접 편집하고 저장할 수 있게 만들었습니다.

AI의 답변을 읽고 끝내는 게 아니라 내가 다시 사용할 수 있는 결과물로 가져오는 것이 목표였습니다.

자동저장은 일부러 넣지 않았다

문서 편집기라면 자동저장을 떠올리기 쉽지만 이번에는 넣지 않았습니다.

로컬 모델이 만든 긴 초안을 편집하다 보면 문단을 통째로 지우고 다시 작성하는 일이 많습니다.

그때마다 자동저장이 실행되면,

“방금 지운 것도 저장된 건가?”

라는 새로운 불안감을 선물할 수 있습니다.

그래서 명시적인 Save 버튼을 유지하고, 저장하지 않은 상태로 페이지를 떠날 때만 beforeunload 경고를 띄우도록 했습니다.

단순하지만 지금 단계에서는 이쪽이 더 예측 가능했습니다.

PDF는 브라우저에게 맡겼다

PDF Export도 추가했습니다.

서버에서 PDF를 만들 수도 있지만 cairo나 pango 같은 시스템 의존성을 추가하고 싶지 않았습니다.

Noye는 내 기계에서 최대한 별다른 설정 없이 돌아가는 것을 목표로 하고 있기 때문입니다.

그래서 이미 훌륭한 PDF 생성기가 하나 있다는 사실을 이용했습니다.

브라우저입니다.

인쇄 CSS는 블랙리스트 대신 화이트리스트로 만들었습니다.

무엇을 숨길지 하나씩 지정하는 대신 data-print="document"가 붙은 문서 영역만 명시적으로 남깁니다.

새로운 버튼을 추가한 뒤 인쇄에서 숨기는 걸 깜빡해서 PDF 한쪽 구석에 Delete 버튼이 등장하는 미래를 피하기 위해서입니다.

Markdown도 “안전하겠지”라고 넘기지 않았습니다.

<script>와 <img onerror>를 직접 넣고 실제 DOM에 해당 요소가 생성되지 않는지 테스트했습니다.

문서에 적혀 있는 것과 내가 직접 확인한 것은 다르니까요.

그리고 이 생각은 곧 DB에서도 다시 등장했습니다.

CREATE TABLE IF NOT EXISTS를 믿었다

지금까지 Noye의 DB 변경은 대부분 새로운 테이블을 추가하는 일이었습니다.

그래서 이런 코드면 충분했습니다.

CREATE TABLE IF NOT EXISTS ...

Phase 6에서는 처음으로 기존 테이블에 컬럼을 추가해야 했습니다.

처음에는 기존 CREATE TABLE 정의에 컬럼을 추가하면 알아서 반영되지 않을까 생각했습니다.

직접 확인해봤습니다.

c.execute("CREATE TABLE IF NOT EXISTS files (id TEXT, name TEXT)")

c.execute("""
    CREATE TABLE IF NOT EXISTS files (
        id TEXT,
        name TEXT,
        embedding_model TEXT
    )
""")

columns = [row[1] for row in c.execute("PRAGMA table_info(files)")]
print(columns)

# ['id', 'name']

embedding_model은 없습니다.

SQLite도 아무 말이 없습니다.

그냥 아무 일도 일어나지 않습니다.

CREATE TABLE IF NOT EXISTS는

“기존 테이블이 선언과 다른데 제가 업데이트해드릴게요.”

가 아니라

“테이블 있네? 그럼 됐습니다.”

에 가까웠습니다.

더 위험한 건 조용히 실패한다는 것이었습니다.

기존 DB를 가진 사용자는 정상적으로 프로그램을 실행하다가 코드가 처음 embedding_model을 조회하는 순간에야 문제를 발견합니다.

결국 제대로 된 schema migration이 필요해졌습니다.

with connection:이면 트랜잭션인 줄 알았다

처음 만든 마이그레이션 러너는 이랬습니다.

with connection:
    for step in MIGRATIONS[version:]:
        step(connection)

    connection.execute(
        f"PRAGMA user_version = {LATEST}"
    )

Python에서 자주 보던 형태였고, docstring에도 자신 있게 적었습니다.

모든 마이그레이션은 하나의 트랜잭션에서 실행된다.

그러다 문득 궁금해졌습니다.

정말 그런가?

그래서 일부러 중간에 실패하는 마이그레이션을 넣고 측정했습니다.

with connection:
컬럼 롤백 False | 버전 롤백 False

명시적 BEGIN:
컬럼 롤백 True  | 버전 롤백 True

제가 원했던 것은 두 번째였습니다.

with connection:은 블록에 진입한다고 무조건 새로운 트랜잭션을 시작해주는 장치가 아니었습니다.

그래서 마이그레이션 전체를 명시적인 BEGIN으로 감싸고, 중간 단계가 실패하면 스키마 변경과 버전 변경이 함께 롤백되도록 수정했습니다.

이게 중요한 이유는 간단합니다.

마이그레이션이 절반만 적용됐는데 버전만 올라가버리면 다음 실행에서

“이미 했네.”

하고 나머지를 건너뛸 수 있습니다.

DB 입장에서는 안 했는데 했다고 주장하는 셈입니다.

꽤 자신감 있는 거짓말입니다.

그리고 조금 민망한 점도 있었습니다.

저는 이 동작을 확인하기 전에 이미 docstring에 “하나의 트랜잭션”이라고 적어놨습니다.

코드보다 자신감이 먼저 배포될 뻔했습니다.

user_version도 모든 것을 알고 있지는 않았다

SQLite의 PRAGMA user_version을 이용하면 DB의 스키마 버전을 기록할 수 있습니다.

문제는 마이그레이션 시스템이 생기기 전에 만들어진 Noye DB였습니다.

기존 DB도

user_version = 0

새로운 DB도 처음에는

user_version = 0

입니다.

숫자는 같은데 실제 스키마는 다릅니다.

그래서 지금 단계에서는 user_version만 믿을 수 없었습니다.

각 마이그레이션을 여러 번 실행해도 같은 결과가 나오도록 만들고, PRAGMA table_info(...)를 이용해 실제 스키마도 확인하도록 했습니다.

Alembic도 고려했지만 아직은 사용하지 않았습니다.

현재 Noye는 단일 사용자 로컬 SQLite 앱이고 마이그레이션도 몇 개의 ALTER TABLE 수준이라 작은 자체 러너로 충분하다고 판단했습니다.

물론 스키마가 복잡해지면 이 결정도 바뀔 수 있습니다.

그때는 미래의 제가 이 글을 읽으며 Alembic을 설치하고 있을지도 모릅니다.

코드 말고도 낡는 것들

Phase 6을 시작하면서 코드 외에도 오래된 것들을 몇 개 발견했습니다.

계획서에는 이미 구현된 기능들이 미완료로 남아 있었고,

README에는 여전히

The backend currently provides a minimal FastAPI health endpoint

라고 적혀 있었습니다.

확인해보니 백엔드에는 이미 21개의 라우트가 있었습니다.

minimal health endpoint라고 하기에는 꽤 건강하게 자라 있었습니다.

테스트도 마찬가지였습니다.

“특정 버튼이 없다”를 확인해야 하는 테스트가 “버튼이 하나도 없다”를 검사하고 있었고, 새로운 버튼을 추가하자 깨졌습니다.

예전에는 우연히 같은 의미였지만 이제는 아니었습니다.

코드만 유지보수가 필요한 게 아니었습니다.

TODO도, README도, 테스트가 품고 있는 가정도 같이 낡습니다.

이번 작업에서 남은 것

프론트엔드 테스트는

96 → 115

백엔드 테스트는

420 → 431

이 됐습니다.

Phase 5는 마무리했고 Phase 6은 계획된 7개 브랜치 중 첫 번째까지 진행했습니다.

다음 작업은 로깅입니다.

원래는 조금 뒤에 있던 작업이었지만 앞으로 당겼습니다.

어차피 이후에도 문제가 생길 거라면,

적어도 로그가 있는 상태에서 문제가 생기는 편이 낫습니다.

이번 작업에서 가장 많이 한 일은 코드를 추가하는 것보다 당연하다고 생각했던 것들을 하나씩 확인하는 일이었습니다.

CREATE TABLE IF NOT EXISTS가 기존 스키마를 알아서 맞춰줄 거라는 생각.

with connection:이면 하나의 트랜잭션일 거라는 생각.

계획서와 README가 현재 상태를 정확하게 설명하고 있을 거라는 생각.

하나씩 확인해보니 꼭 그렇지는 않았습니다.

결국 이번에 가장 많이 배운 건 꽤 단순했습니다.

추측하지 말고 직접 확인하기.

코드도,

테스트도,

문서도,

그리고 제가 자신 있게 적어놓은 docstring도

현실과 다를 수 있습니다.

Phase 6의 다음은 로깅입니다.

이번에는 적어도,

다음 가정이 틀렸을 때 조금 더 빨리 알 수 있을 것 같습니다.

← cd ../posts