아틀라스는 처음에 대화 기록을 모아 찾는 저장소로 시작했다. 그러다 한 단계를 더 나아가기로 했다. 워크스페이스마다 파일로 흩어져 있던 메모리 문서와, 훅이 세션을 막고 안내하는 규칙의 정본을 아틀라스로 옮긴 것이다. 검색 대상이던 저장소가 이제 세션들이 읽고 쓰는 기준이 됐다. 그 결정의 이유와, 몇 주 운영해 본 결과를 적는다.
Table of contents
Open Table of contents
배경 — 같은 규칙의 판이 머신마다 달랐다
전에는 메모리와 규칙이 각 워크스페이스의 Markdown 파일이었고, 파일은 git 으로 머신 사이를 오가므로 한 머신에서 고친 규칙이 다른 머신에 닿기까지 pull 이 끼어 있었다. 그 사이에는 같은 규칙의 다른 판을 머신마다 읽었다. 메모리도 마찬가지라서 한 세션이 남긴 함정 기록을 다른 워크스페이스의 세션은 볼 수 없었다.
판단 — 정본을 어디에 둘 것인가
정본을 둘 자리의 선택지는 두 가지였다.
- 정본은 파일로 두고, 아틀라스는 그 파일을 읽어 검색만 한다
- 정본을 아틀라스 문서로 옮기고, 파일은 읽기 사본으로만 남긴다
2번을 고른 이유는 여러 머신의 세션이 같은 순간에 같은 판을 읽어야 하기 때문이다. 정본을 MariaDB 의 문서 표에 두면 Claude Code 훅이 UserPromptSubmit·PreToolUse·Stop 같은 이벤트마다 HTTP 서비스의 /atlas/rules 로 규칙을 그 자리에서 받아 오고, 세션은 MCP 도구 get_doc·put_doc 으로 문서를 읽고 쓴다. 문서를 고치면 판 번호가 오르고 이전 판은 이력 표에 남는다. 반면 1번은 pull 주기를 짧게 해 판이 갈라지는 시간을 줄일 수는 있어도 없앨 수는 없다.
규칙은 특히 조심해서 다뤘다. 세션이 규칙 문서를 직접 고치지 못하게 하고, 고치려면 put_doc 이 후보(P-번호)를 만들고, 사람이 decide_proposal 로 승인해야 규칙이 되게 했다. 후보를 올릴 때는 그 규칙이 걸려야 할 호출에 걸리고 다른 호출은 통과하는지를 훅 엔진으로 시험한 결과를 함께 붙인다. 대가는 규칙 하나를 고치는 데 승인 한 번이 더 든다는 점이다. 그래도 세션이 스스로 규칙을 느슨하게 고쳐 막힌 일을 통과시키는 길을 막으려면 그 한 번이 필요했다.
결과 — 옮긴 범위와 지금의 규모
전환은 워크스페이스와 머신의 쌍 단위로 했다. 다섯 워크스페이스에서 12쌍을 옮겼고, 각 워크스페이스에 전환 안내 문서를 두었다. 워크스페이스 안내 파일인 CLAUDE.md 의 메모리 링크는 문서를 get_doc 으로 여는 안내로 바꿨다.
11월 초 기준으로 아틀라스에 저장된 조각은 출처별로 이렇다.
| 출처 | 조각 수 |
|---|---|
| 대화 턴 | 146,838 |
| 워크스페이스 메모리 | 2,237 |
| 머신 문서 | 1,285 |
| 규칙 | 429 |
| 자동 메모리 | 291 |
| 가이드 | 166 |
최근 7일 동안 프롬프트 1,377개에 조각 9,014개가 세션에 보였다. 규칙은 훅이 아틀라스의 규칙 판 번호와 함께 받아 오므로, 승인된 새 판이 따로 배포하는 절차 없이 각 머신의 훅에 걸린다. 이번 주에만 블로그 집필 규칙과 병합 시각 규칙 같은 후보 여러 개가 사람 승인을 거쳐 새 판으로 반영됐다.
저장소가 스스로 나아지는지 보는 신호도 붙였다. 보여 준 기록을 세션이 실제로 따라 썼는지, 보여 준 뒤 그 문서를 열었는지, 사람이 지적하기 직전에 필요했던 문서가 무엇이었는지를 매일 집계해 조정 기록 문서로 남긴다. 다만 판정 기준을 시험할 자료를 다시 만들기 전까지는 자동 조정을 하지 않고, 사람이 기록을 보고 정한다.
영향 범위 — 옮기며 생긴 대가
옮기는 과정에서 생긴 문제도 그대로 적는다.
- 잘못 잡힌 워크스페이스. 발견 로직이 메모리 폴더가 있는 폴더를 모두 워크스페이스로 보는 바람에, 프로젝트 저장소 네 곳(8쌍)이 워크스페이스로 잡혔다. 같은 날 되돌려 문서 34개를 원래 워크스페이스 범위로 옮겼고, 남은 옛 키 조각은 승인을 받아 지우기로 했다
- 동결 사본. 파일은 읽기 사본으로 얼려 두었는데, 몇몇 도구와 규칙이 여전히 그 사본 경로를 읽고 있었다. 정본을 고쳐도 사본을 읽는 쪽은 옛 판을 본다. 이번 주에 그 규칙을 아틀라스 문서를 열게 고치는 후보를 올려 승인받았고, 사본을 읽던 형식 검사 도구는 실행할 때마다 아틀라스에서 내보낸 판을 읽게 바꿨다
- 장애 때의 경로. 정본이 DB 에 있으므로 DB 에 닿지 않으면 규칙을 받지 못한다. 그래서 머신 문서는 각 머신의 홈 폴더에 읽기 사본을 따로 두어, 아틀라스의 MariaDB 나 HTTP 서비스가 끊겼을 때 그 사본을 읽게 했다
정리
- 여러 머신의 세션이 같은 순간 같은 판을 읽어야 하면 정본을 파일이 아니라 한 저장소에 둔다
- 규칙은 세션이 직접 고치지 못하게 하고, 후보와 엔진 시험과 사람 승인을 거치게 한다
- 정본을 옮기면 옛 경로를 읽는 도구를 끝까지 찾는다. 사본을 읽는 도구가 하나라도 남으면 정본이 둘이 된다
- 장애 때 읽을 사본은 따로 정해 둔다. 정본을 한곳에 모은 대가는 그렇게 줄일 수 있다