如何在 osFoundry 筆記中重現樂觀鎖,避免 Claude 編輯覆蓋人類修改
osFoundry 노트에서 Claude의 편집이 사람의 편집을 덮어쓰지 않게 하는 낙관적 락 다시 만들어 보기
作者以 SQLite 重建 osFoundry 筆記工具的寫入流程,測試樂觀鎖能否避免 Claude 與人類編輯互相覆寫。在每位編輯者各寫 100 次、共 5 組測試中,無版本檢查令 1,000 行預期修改中有 300 行遺失;衝突後重新讀取並重套修改則沒有遺失,只更新版本再重送舊內容仍遺失 304 行。
Claude 채팅이 osFoundry 노트를 고칠 때 쓰는 tool은 공개 MCP 엔드포인트에 이렇게 정의돼 있다. 2026-11-06에 인증 없이 tools/list를 찔러서 받았고, 이 글에 필요한 필드만 남겼다.
{"name": "edit_note_tab",
"description": "Use an exact tab ID and version from read_note_tab. Use replace_text for Note/Markdown, slide_add or slides_add_outline for Slides, sheet_set_range for Sheet, or replace_tab_data for supported content tabs. File and Source attachments cannot be edited through this tool. A repeated idempotency key returns the first result.",
"inputSchema": {
"required": ["note_id", "tab_id", "expected_version", "idempotency_key", "operation"],
"properties": {
"operation": {"enum": ["replace_text", "replace_tab_data", "slide_add",
"slides_add_outline", "sheet_set_range"]},
"sheet_id": {"type": "string"}, "start_row": {"type": "integer"},
"start_col": {"type": "integer"}, "values": {"type": "array", "items": {"type": "array"}}}},
"annotations": {"readOnlyHint": false, "destructiveHint": true},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
필수 필드 다섯 개 중 두 개는 편집 내용이랑 상관이 없다. expected_version은 쓰기를 compare-and-swap으로 만든다. 에이전트가 읽었던 버전 그대로일 때만 쓴다. idempotency_key는 재전송을 무해하게 만든다. 노트에 쓰는 다른 tool인 create_note_tab, add_note_source도 이 두 개를 똑같이 필수로 받는다. 읽기 쪽인 list_note_tabs, read_note_tab, read_sheet_range(최대 100×100셀), list_note_attachments는 전부 osfoundry:read에 readOnlyHint: true다.
이 계약이 실제로 뭘 지켜 주는지 직접 다시 만들어서 재 봤다. 버전 체크는 절반일 뿐이다. 나머지 절반은 거절당한 다음에 에이전트가 뭘 하느냐다.
오래된 쓰기를 왜 병합하지 않고 거절할까
replace_text는 탭의 텍스트를 통째로 보낸다. Claude가 버전 7을 읽고, 사람이 버전 8을 저장했고, 그다음 Claude가 텍스트를 보냈다고 해 보자. 서버 손에는 전문 두 개만 있고 공통 조상은 이미 없다. Claude가 사람이 새로 쓴 문단을 지우려던 건지, 그냥 못 본 건지 구분할 방법이 없다. 나중에 쓴 쪽이 이기게(last-writer-wins) 두면 조용히 틀린 쪽을 고른다. 추측하지 않는 응답은 거절뿐이다.
이게 낙관적 락(optimistic locking)이다. 모델이 20초 동안 생각하는 사이에 아무도 락을 잡고 있지 않는다. 쓰기는 자기가 어느 버전을 기준으로 했는지 밝히고, 서버는 그게 아직 최신일 때만 바꾼다.
UPDATE notes SET version = :new WHERE id = :note AND version = :expected; -- 0 rows → conflict
osFoundry 데스크톱 앱은 사람 쪽에서도 똑같이 한다. apps/web/src/screens/notes/context/NotesContext.tsx의 노트 저장은 PATCH /notes/:id이고, expected_updated_at(에디터가 마지막으로 본 서버 리비전)을 같이 보낸다. Connected 쓰기가 한 번 들어온 뒤에는 connected-note-save-guard.ts가 localStorage에 들고 있는 expected_version도 붙는다. 새로고침해도 사라지지 않게 하려는 거다. 저장이 실패하면 에디터는 사람이 쓴 내용을 로컬 초안으로 남기고 동기화 오류를 띄운다. 결국 양쪽 편집자가 둘 다 조건부로 쓰는 구조다.
거절당하면 에이전트는 뭘 해야 할까
그럴듯한 반응은 두 가지인데, 제대로 되는 건 하나뿐이다.
- 탭을 다시 읽고, 하려던 변경을 새 내용 위에 다시 적용하고, 새 버전으로 쓴다
- 버전만 다시 읽고 같은 페이로드를 다시 보낸다
2번은 체크를 통과하는데도 사람의 편집을 덮어쓴다. 페이로드가 옛 텍스트로 만들어졌기 때문이다. 체크는 그걸 못 본다. 버전이 증명하는 건 "최신 번호를 봤다"는 것뿐이고, "그 내용을 썼다"는 게 아니다.
다시 만든 환경
여기서는 Claude 바이너리를 띄우지 않았다. notes_store.py가 list_note_tabs, read_note_tab, read_sheet_range, edit_note_tab(replace_text, sheet_set_range), create_note_tab을 sqlite(WAL 모드) 위에 구현한다. tool 이름과 인자 이름은 실서버와 같게 맞췄다. 쓰기는 전부 BEGIN IMMEDIATE 안에서 멱등 키 테이블 조회, 버전 비교, 적용, 버전 증가, 결과 저장까지 한 트랜잭션으로 처리한다.
race.py는 각자 커넥션을 가진 스레드 두 개를 띄운다. 스크립트대로 움직이는 "Claude"와 역시 스크립트대로 움직이는 사람이다. 둘 다 "읽기 → 생각 → 쓰기"를 100번 한다. 생각하는 시간은 줄여 놨다. Claude는 20~80ms, 사람은 5~40ms다. 실제 모델처럼 읽고 나서 쓰기까지의 창은 에이전트 쪽이 더 길다. 쓰기마다 고유한 한 줄(claude-17, human-42)을 붙이니까, 끝나고 빠진 줄을 세면 그게 갱신 손실(lost update) 개수다. Python 3.9.6, Apple M1, 시드 1~5.
sqlite 배관을 뺀 쓰기 경로는 이렇다.
def _guarded(self, note_id, tab_id, expected_version, idempotency_key, apply):
db.execute("BEGIN IMMEDIATE")
hit = db.execute("SELECT result FROM idem WHERE key=?", (idempotency_key,)).fetchone()
if hit:
return {**json.loads(hit[0]), "replayed": True}
current = tab_version if self.check == "tab" else note_version
if self.check != "none" and expected_version != current:
return {"error": "version_conflict", "current_version": current}
result = apply(db) # replace_text / sheet_set_range / new tab
# bump version, store (key, result), COMMIT
에이전트 쪽 루프와 정책 스위치.
r = s.edit_note_tab("note-1", tab, tab_now["version"], uuid.uuid4().hex, **payload)
while "error" in r:
fresh = s.read_note_tab("note-1", tab)
if policy == "reapply":
payload["text"] = fresh["data"] + "\n" + line # redo the change on what's there now
tab_now = fresh # refresh_version keeps the old text
r = s.edit_note_tab(...)
충돌 뒤의 시도에는 새 멱등 키를 줬다. 키는 "어떤 기준 위의 의도된 쓰기 하나"를 가리킨다. 거절당하고 다시 적용한 쓰기는 다른 쓰기다.
체크가 없으면 얼마나 날아갈까
5번 돌렸고, 한 번에 편집자마다 100건이다. 표의 각 행마다 의도한 줄은 총 1,000개다.
| 쓰기 보호 | 충돌 시 에이전트 | 날아간 줄 | Claude / 사람 | 충돌 Claude / 사람 | 최대 시도 |
|---|---|---|---|---|---|
| 없음 | — | 300 | 125 / 175 | 0 / 0 | 1 |
| 노트 버전 | 다시 읽고 다시 적용 | 0 | 0 / 0 | 219 / 133 | 2 |
| 노트 버전 | 버전만 다시 읽고 옛 텍스트 재전송 | 304 | 117 / 187 | 213 / 136 | 3 |
체크가 없으면 전체 편집의 30%가 사라졌고, Claude보다 사람이 더 많이 잃었다. 에이전트는 생각하는 시간이 길어서 더 오래된 읽기를 기준으로 쓰고, 그래서 덮어쓰는 쪽이 되기 쉽다. 체크를 걸고 다시 적용하면 하나도 안 날아간다. Claude 쓰기의 41~48%가 두 번째 시도를 했고, 세 번째는 없었다. 평균 시도 횟수는 Claude 1.41~1.48, 사람 1.24~1.30. 어느 모드든 실행 시간은 9.6~10.5초로, 거의 생각하는 시간이 정한다.
기억할 건 세 번째 행이다. 서버는 충돌을 300건 넘게 돌려줬는데 지킨 건 하나도 없다. 버전 체크가 강제할 수 있는 건 "다시 읽기"까지고, "읽은 걸 쓰기"는 강제 못 한다.
체크에 비용이 들까
bench.py로 200자짜리 replace_text의 edit_note_tab을 연속 2,000번 호출하고, 모드마다 3번 쟀다. 쓰기 1회 중앙값은 체크 없음 61.9~63.1µs, 노트 버전 57.0~58.8µs, 탭 버전 55.1~61.1µs. 비교는 어차피 열려 있는 트랜잭션 안에서 인덱스를 한 번 읽는 게 전부라서, 차이가 실행마다의 노이즈에 묻힌다. p99(0.42~1.33ms)는 sqlite fsync 흔들림이고 모드와 상관없다.
버전은 왜 노트 단위고, 그 대가는 뭘까
osFoundry의 tool 설명은 버전 하나를 노트 전체에 묶는다. create_note_tab은 "list_note_tabs의 버전을 써라"라고 하는데, 이건 노트 단위 목록이다. 데스크톱 앱에서 Connected 편집을 적용하는 경로(connected-note-application.ts)에서도 expected_version은 노트의 updated_at과 비교된다. 그러니까 사람이 시트 탭을 만지면, Claude의 텍스트 탭 쓰기가 비교당하는 버전도 같이 움직인다.
다시 만든 환경에서는 이걸 셀 수 있다. race.py tabs로 Claude는 텍스트 탭, 사람은 시트 탭 셀을 쓴다. 3번, 각 100건.
| 버전 단위 | Claude 충돌 | 사람 충돌 | 날아간 줄 |
|---|---|---|---|
| 노트 | 300건 중 130 (43%) | 300건 중 87 (29%) | 0 |
| 탭 | 0 | 0 | 0 |
이 217건은 전부 가짜 충돌이다. 둘은 같은 탭을 한 번도 안 건드렸다. 치른 건 다시 읽기 한 번씩뿐이다. 노트 단위 버전에는 탭 단위로는 못 얻는 게 있다. 쓰기가 노트 전체를 기준으로 검사되니까, 시트를 읽고 Brief를 쓰는 에이전트가 그사이 바뀐 시트 값을 바탕으로 Brief를 쓸 일이 없다. 탭 단위로 바꾸면 가짜 충돌은 없어지지만, 바로 그 탭 간 보장도 같이 없어진다. 한 탭을 읽고 다른 탭에 쓰는 에이전트라면 거친 버전이 더 안전한 기본값이다.
밀리초 타임스탬프는 버전 체크에 무슨 짓을 할까
타임스탬프를 버전으로 쓰려면 저장 두 번이 같은 문자열을 만들지 않아야 한다. race.py fast로 생각 시간을 0으로 두고, 편집자마다 2,000건, 5번. 밀리초로 자른 버전과, 마이크로초에 16진 6자리 접미사를 붙인 버전을 비교했다.
| 버전 형식 | 날아간 줄 (20,000개 중) | 손실이 난 실행 |
|---|---|---|
| 밀리초 | 136 (0.68%) | 5번 중 5번 |
| 마이크로초 + 접미사 | 0 | 5번 중 0번 |
같은 밀리초 안에 쓰기 두 개가 커밋되면 두 번째가 첫 번째와 같은 버전을 받는다. 첫 번째 전에 읽은 편집자는 두 번째에 대한 체크를 그냥 통과한다. osFoundry는 노트 버전을 PostgreSQL 타임스탬프 정밀도 그대로 들고 있다. 직접 만든다면 카운터를 쓰거나, 타임스탬프에 순서를 정하는 값을 붙이자.
탭 생성에는 왜 따로 키가 필요할까
create_note_tab은 아무것도 대체하지 않으니까 버전 체크만으로는 중복을 못 막는다. 재전송된 호출은 새 버전 위의 새 탭이 될 뿐이다. race.py create로 시트 탭 50개를 만들면서 응답의 30%를 버려, 호스트가 타임아웃 뒤에 하듯 재시도하게 했다.
| 보낸 횟수 | 생긴 탭 | 중복 | |
|---|---|---|---|
| 키 없음, 3번 | 71 / 61 / 63 | 71 / 61 / 63 | 21 / 11 / 13 |
| 재시도에 같은 키 | 71 / 61 / 63 | 50 / 50 / 50 | 0 |
키가 있으면 재시도에 첫 결과가 탭 ID까지 그대로 돌아온다. 에이전트의 다음 edit_note_tab은 실제로 있는 탭으로 간다. osFoundry tool 설명의 "A repeated idempotency key returns the first tab"이 이 얘기다.
직접 붙일 때 정해 둘 것
- 모든 쓰기 tool에서
expected_version을 스키마 필수로 둔다. 선택 항목으로 둔 체크는 모델이 서두르는 첫 순간에 빠진다. - 충돌은 모델이 다음 수를 둘 수 있는 평범한 tool 결과로 돌려주고, 뭘 해야 하는지(다시 읽고 변경을 다시 적용)를 tool 설명에 적는다. "버전만 갱신하지 말고 다시 적용하라"는 규칙을 둘 곳은 거기밖에 없다.
- 버전 단위를 의식해서 고른다. 문서 단위는 가짜 충돌이 생기지만 탭을 넘나드는 읽기를 지켜 준다. 탭 단위는 가짜 충돌이 없는 대신 그 보호도 없다.
- 버전은 충돌하지 않게 만든다. 카운터, 아니면 최대 정밀도 타임스탬프에 순서용 값을 붙인 것. 밀리초로 반올림한 타임스탬프는 쓰지 않는다.
- 생성과 추가에는 "한 기준 위의 한 의도"를 나타내는 멱등 키를 붙이고, 키와 결과는 쓰기와 같은 트랜잭션에서 저장한다.
- 사람 쪽 에디터도 지킨다. 에이전트만 충돌 체크해 봐야, 오래된 브라우저 탭이 에이전트의 변경을 덮어쓸 수 있다.
밑에 깔린 프로토콜의 짧은 설명은 osFoundry의 MCP 용어 설명에 있다. 노트의 이전 상태를 남기고 되돌리는 방식은 노트 버전 페이지에 정리돼 있다.
來源:DEV Community · dev.to