한 줄 요약: MaxonT/aisync는 Claude Code·Codex·Cursor처럼 AI 코딩 에이전트를 둘 이상 동시에 돌리는 개발자를 위한 로컬 조정 허브입니다. 에이전트를 대신 돌려 주는 오케스트레이터가 아니에요. 에이전트들이 같이 쓰는 공유 계층입니다. 하는 일은 셋입니다. ① 규칙 블록 하나를 각 도구의 규칙 파일(CLAUDE.md·AGENTS.md)에 3-way로 동기화하고, ② “지금 이 파일은 내가 고친다”는 협조형 파일 클레임으로 충돌을 exit 3으로 알려 주고, ③ 모든 활동을 해시 체인 저널에 남겨 나중에 검증할 수 있게 합니다. 이 글은 v0.2.11(2026-11-16 23:06 KST 릴리스) 기준으로 구조와 설계 선택을 뜯어보고, 박스에서 직접 설치해 클레임 충돌·저널 변조·훅 주입까지 돌려 본 결과를 정리합니다.

1. 한눈에 보기
| 항목 | 내용 (2026-11-20 KST 확인) |
|---|---|
| 저장소 | github.com/MaxonT/aisync · 패키지 이름 aisync-cli, 명령은 aisync |
| 정체 | “Multi-Agent Context Management, Coordination & Observability”: 여러 코딩 에이전트가 함께 쓰는 로컬 허브 |
| 최신 릴리스 | v0.2.11 (2026-11-16 23:06 KST). 첫 공개 v0.1.0(2026-10-21) → v0.2.0(11-09, 규칙 인터페이스·레이어·MCP) → v0.2.5(11-12, gate·guard·wt 공개) → 11-16 하루에 0.2.6~0.2.11 |
| 언어·요구 사항 | Python 3.11+ 와 git, macOS 또는 Linux. 런타임 의존성 0개(표준 라이브러리만). MCP 서버만 옵션 extra aisync-cli[mcp] |
| 배포 채널 | PyPI(pipx install aisync-cli) · npm(@mingyang2026/aisync-cli, README 기준 0.2.9) · Homebrew 탭 maxont/tap · GHCR 컨테이너 · 설치 스크립트 |
| 라이선스 | MIT |
| 규모 | 스타 48 · 포크 6 · 열린 이슈 8. 패키지 ai_sync/ 25개 모듈 약 6,700줄, 테스트 파일 36개(테스트 458개) |
| 기여자 | 커밋 기준 MaxonT 82, claude 27, cursoragent 10 외 3명. 에이전트가 공동 작성한 커밋이 많아, 프로젝트 자체가 다중 에이전트 개발로 만들어지고 있음 |
| 통합 | 네이티브 훅: Claude Code·Codex·Cursor / 그 밖의 에이전트: MCP 서버·CLI·공유 지침 파일 |
2. 왜 지금 이 저장소인가
last30days 랭킹의 ‘AI agent repo’ 쿼리에서 잡힌 해커뉴스 글 “Show HN: Aisync, advisory file claims so two AI agents don’t edit one repo”(2026-11-10)가 출발점입니다. 반응은 4포인트로 작았어요. 그런데 같은 랭킹 상위에 “하버드 연구진: AI 코딩 에이전트가 병목을 코드 리뷰로 옮겼다”, “해커뉴스 댓글 663개에서 센 AI 코딩 에이전트 구성” 같은 글이 함께 올라와 있었습니다. 에이전트 하나를 잘 쓰는 단계는 지났고, 이제는 여러 에이전트가 한 코드베이스에서 서로 부딪히지 않게 하는 문제가 실무 과제가 됐다는 뜻이에요.
이 분야 도구들은 대부분 “에이전트를 띄우고 작업을 나눠 주는” 오케스트레이터입니다. aisync는 반대쪽 끝에 있어요. 어떤 에이전트를 어떻게 띄우든 상관하지 않고, 그 에이전트들이 같이 읽고 쓰는 공유 상태만 맡습니다. 스타 수는 작지만 설계 결정이 문서에 꼼꼼히 적혀 있고 테스트도 충실해서, 같은 문제를 직접 풀려는 팀이 참고하기 좋은 레퍼런스입니다.
3. 문제 정의: 에이전트 여럿이 부딪히는 네 지점
| 부딪히는 지점 | 현장에서 보이는 증상 | aisync의 대응 | 강제력 |
|---|---|---|---|
| 규칙 분산 | CLAUDE.md에 넣은 규칙이 Codex의 AGENTS.md에는 없음. 한쪽에서 고친 규칙이 다른 쪽에 반영되지 않음 | 규칙 블록 하나를 각 도구 파일에 3-way 동기화. 양쪽이 다 바뀌었으면 덮어쓰지 않고 충돌로 남김 | 동기화(자동) |
| 동시 편집 | 두 에이전트가 같은 파일을 동시에 고쳐 한쪽 변경이 날아가거나 머지 지옥 | aisync claim: 겹치면 exit 3. Claude Code 세션끼리는 옵트인 guard가 실제로 편집을 거부 |
claim은 협조형, guard는 강제 |
| 세션 중 변화 | 세션 시작 때 읽은 규칙·상황이 그 뒤로 갱신되지 않음 | 훅으로 “다른 도구가 그새 바꾼 것”(새 규칙·blocked·로그)만 주입. 새 소식이 없으면 출력도 없음 | 훅 지원 도구만 자동 |
| 사후 추적 | 누가 무엇을 왜 했는지 흩어진 채팅 기록뿐 | 해시 체인 저널 + 커밋 Agent: 트레일러 + status·report·board |
변조 탐지(한계 있음) |
4. 아키텍처: 허브 하나, 문 네 개

중심은 ~/.ai-sync/(환경 변수 AISYNC_HOME으로 위치 변경 가능)에 있는 로컬 git 저장소입니다. 서버도, 데몬 프로토콜도, 데이터베이스도 없어요. 상태는 전부 평문 파일이고, 동시성은 state/.lock에 거는 fcntl.flock 배타 잠금 하나로 처리합니다. 에이전트 셋이 같은 순간에 aisync log를 불러도 저널 체인이 갈라지지 않는 이유가 이 잠금이에요. 반대로 말하면 같은 파일시스템을 공유하는 한 대의 머신이 기본 전제입니다. 여러 머신 사이는 remote 설정으로 허브를 git push하는 방식으로만 이어집니다.
| 허브 파일 | 역할 | 설계 포인트 |
|---|---|---|
preferences.md |
공유 규칙의 ‘진실’. 규칙마다 R-### 고정 ID |
교체된 규칙은 rules-archive.md로 이동. 아무것도 지우지 않음 |
journal.jsonl |
append-only 이벤트 로그(dev_log·decision·blocked·unblocked·rule_change·note·commit·claim·release) | 각 줄이 이전 줄 id를 품는 해시 체인. 쓸 때마다 fsync |
config.toml |
roster(소식을 기대하는 도구), scan_dirs(감시 저장소), target(규칙 블록을 받을 파일), shelf(주제별 키워드) | 타이밍 기본값: 디바운스 30초, 최대 대기 120초, 안전망 600초, 실패 5회 연속이면 일시정지 |
agents.md / progress.md |
렌더된 공유 페이지와 진행 현황 | progress_file로 진행 표를 분리하면 공유 페이지가 바이트 단위로 그대로 유지돼 프롬프트 캐시가 깨지지 않음 |
state/claims.json |
TTL이 붙은 파일 클레임(기본 120분) | 만료된 클레임은 읽을 때 걸러짐. 별도 청소 작업이 없음 |
state/*.json·jsonl |
health·runs(사이클 로그)·hooks(훅 호출 통계)·cursors(세션별 ‘어디까지 읽었나’) | aisync status가 이 파일들을 모아 보여 줌 |
동기화 사이클(aisync sync 1회, 또는 aisync watch의 이벤트 기반 루프)은 harvest → rules → distribute → render → flush 다섯 단계입니다. 감시 중인 저장소의 새 커밋을 Agent: 트레일러로 귀속해 저널로 옮기고, 규칙 소스를 모으고, 규칙 블록을 각 도구 파일에 3-way로 뿌리고, 진행 페이지를 그리고, 허브를 커밋합니다. 단계마다 실패가 격리돼 있어서 한 단계가 실패해도 나머지는 계속 돕니다. 모든 git 호출에는 타임아웃과 지수 백오프 재시도가 붙어 있어요.
5. 저장소 구조: 어디부터 읽으면 되나
| 모듈 | 줄 수 | 무엇을 하나 |
|---|---|---|
core.py |
974 | 설정 로드, 잠금, 해시 체인 저널(append_event·verify_chain), 규칙 블록 3-way 분배, harvest·flush·run_cycle·status |
cli.py |
975 | argparse 기반 서브커맨드 30여 개. 외부 CLI 프레임워크를 쓰지 않음 |
hooks.py |
581 | 도구별 훅 진입점(aisync hook <tool>), 뉴스 주입, 2단계 설치(diff 먼저 보여 주고 승인), 전역 git 훅 |
collab.py |
488 | 공유 규칙 추가, 클레임·릴리스, 진행 렌더, report 힌트 |
guard.py |
390 | Claude Code 세션당 저장소 하나 리스(PreToolUse·SessionEnd 훅), headless 인수 |
enforcement.py · rulespec.py · ruleids.py |
328 · 202 · 162 | When/Do/Not 규칙 형식, ID 부여, “이 규칙을 무엇이 지키나”(테스트 파일·판단·계획) 등록부 |
board.py · demo.py |
285 · 285 | 허브를 정적 HTML 한 장으로 렌더 / 합성 데이터로 임시 허브 생성 |
gate.py · landq.py · worktree.py |
265 · 182 · 168 | push 시점 테스트 게이트, 저장소별 랜딩 큐(flock), 세션 전용 worktree 생성·랜딩 |
tidy.py · rulecheck.py · layers.py |
179 · 153 · 113 | 규칙 정리 제안, 규칙 정리 뒤 사라진 사실(경로·숫자·명령) 검사, 레이어 접기 |
mcp_server.py |
134 | MCP 도구 8개: rules·rule_add·log·claim·release·news·status·tidy |
모듈마다 docstring 첫머리에 What / Why / How가 적혀 있고, Why에는 날짜와 실제 사건이 들어 있습니다. guard.py의 Why는 “2026-10-23 Claude Code 세션 둘이 같은 티켓을 서로 모른 채 처리해 같은 답장을 두 번 올릴 뻔했다”예요. 기능이 하나같이 작성자 자신의 운영 사고에서 나왔다는 게 코드에서 보입니다. 장점이자 한계이기도 합니다. 일반화된 제품이라기보다 한 사람의 실전 워크플로를 공개한 도구에 가까워요.
6. 해시 체인 저널: 무엇을 증명하고 무엇은 못 하나

저널의 이벤트 id는 SHA-256(prev + "\n" + 정렬된 JSON 본문)의 앞 16자리 16진수(64비트)입니다. 각 이벤트가 바로 앞 이벤트의 id를 prev로 품기 때문에, 중간 줄을 고치거나 지우면 사슬이 끊깁니다. git 커밋 해시와 같은 발상이고, README도 git에서 빌렸다고 밝히고 있어요. 박스에서 저널을 직접 건드려 봤습니다.
| 변조 시나리오 (박스 실측) | aisync verify 출력 |
종료 코드 | 해석 |
|---|---|---|---|
| 3번째 줄 요약문 한 단어 수정 | line 3: id mismatch (event edited by hand) |
1 | 본문 변조 탐지 |
| 4번째 줄(중간) 삭제 | line 4: prev link broken (event lost, reordered or forked) |
1 | 유실·순서 변경 탐지 |
| 마지막 줄 삭제 | journal chain intact |
0 | 미탐지. README와 이슈 #23에 알려진 한계로 명시 |
실무에서 읽어야 할 포인트는 셋입니다. 첫째, 키가 없는 해시 체인이라 허브에 쓰기 권한이 있는 쪽이 체인 전체를 다시 계산하면 위조를 막을 수 없습니다. 위협 모델은 “실수나 어설픈 손 편집 탐지”이지 “악의적인 에이전트 방어”가 아니에요. 둘째, 꼬리 잘림은 허브 자체를 git에 커밋(flush)하고 가능하면 remote로 밀어 두는 것으로 보완하라는 게 공식 권고입니다. 셋째, 저널은 에이전트가 스스로 보고한 내용입니다. README도 “주장한 행동이 실제로 일어났다는 증명은 아니다”라고 선을 긋습니다. 행동 증거가 필요하면 커밋 트레일러와 harvest로 수집되는 git 이력을 같이 봐야 합니다.
7. 클레임 · guard · lease · worktree: 충돌을 다루는 네 단계
aisync에서 가장 실무적인 부분입니다. 충돌을 다루는 장치가 강도별로 네 가지 있어요.
| 장치 | 방식 | 막는가? | 키 | 기본값 |
|---|---|---|---|---|
claim / release |
“이 project의 이 파일들을 지금 내가 고친다” 선언. 같은 파일이거나 디렉터리 접두사가 겹치면 OVERLAP·exit 3 | 아니요(협조형). 에이전트가 exit 3을 존중해야 함 | 에이전트 이름 + project + 경로 | 켜짐, TTL 120분(--ttl) |
guard |
Claude Code PreToolUse 훅. 다른 세션이 리스를 쥔 저장소에서는 편집·쓰기 명령을 거부 | 예. 훅이 도구 호출을 거부 | 건드린 경로의 git 루트(worktree는 별도 키) | 꺼짐(guard_hook = true로 옵트인) |
lease |
guard가 쓰는 저장소별 리스 조회·수동 해제 | guard의 일부 | 저장소 키 | 마지막 편집 후 만료, SessionEnd에 해제 |
wt start / wt land |
잠긴 저장소 대신 세션 전용 worktree(<repo>-wt/<id8>)에서 작업 후 랜딩 |
충돌 자체를 피함 | 세션 ID | 명시적으로 호출할 때만. land는 --yes 없이는 dry run |
설계에서 눈여겨볼 디테일이 몇 가지 있습니다. 클레임이 겹쳐도 뒤에 온 쪽의 클레임은 기록됩니다. 박스 실행에서도 “Your claim is noted, so claude-code can see you are waiting”이라고 나왔어요. 거절이 아니라 대기열 표시에 가깝습니다. 파일을 생략하거나 .을 주면 저장소 전체 클레임이 되고, 경로는 파일시스템을 보지 않고 posixpath.normpath로만 정규화합니다(v0.2.11 이후 커밋 #38). 그리고 같은 에이전트 이름끼리는 겹침으로 치지 않습니다. 그래서 Claude Code 창 두 개는 둘 다 “claude-code”라 서로의 클레임을 보지 못하는데, guard가 바로 이 구멍을 메우려고 따로 만들어졌다고 docstring에 적혀 있어요.
wt land는 꽤 강한 의견이 담긴 기능입니다. 브랜치를 GitHub의 main 위로 rebase하고 main에 먼저 push한 뒤 로컬 main을 fast-forward합니다. 저장소에 check.sh가 있으면 그 사이에 ./check.sh --fast를 통과해야 하고, 전 과정이 저장소별 랜딩 큐(flock) 안에서 돕니다. PR 리뷰를 거쳐 머지하는 팀 워크플로와는 맞지 않으니, 1인 + 에이전트 여럿인 환경에 맞춘 기능으로 보는 게 정확합니다.
8. 규칙을 API처럼: When/Do/Not · 레이어 · tidy · enforce
v0.2.0의 핵심 변화는 “규칙 파일은 계속 커지고, 세션마다 그 비용을 내고, 아무도 읽지 않는다”는 문제의식에서 나왔습니다. 그래서 규칙을 인터페이스처럼 다룹니다.
| 기능 | 동작 | 실무 의미 |
|---|---|---|
| When / Do / Not | 규칙 한 줄 = [R-087] When: <트리거>. Do: <행동>. Not: <금지>. rule_spec = true면 다른 형식은 거부 |
규칙이 검사 가능한 단위가 됨. 이유(why)는 규칙이 아니라 저널로 |
레이어 (layer = "core") |
core_topics만 전문으로 싣고 나머지 주제는 한 줄로 접음. 프롬프트·도구 호출이 [shelf] 키워드에 닿으면 세션당 한 번 주입 |
작성자 허브 실측: 항상 로드되는 규칙 20,673 → 7,876 토큰(1회 측정, 벤치마크 아님이라고 README가 명시) |
tidy |
중복 후보, 30일간 인용되지 않은 규칙, core 예산 초과를 제안만 함. 직접 고치지 않음 | “청소부가 아니라 서기”. 자동 정리로 규칙이 사라지는 사고를 막는 쪽을 택함 |
rulecheck |
규칙 정리 전후로 경로·숫자·명령·ID 같은 hard fact가 하나라도 빠졌는지 검사 | LLM에게 규칙을 요약시켰을 때 사실이 조용히 빠지는 문제 대응 |
rule enforce / enforcement |
규칙마다 무엇이 지키는지 기록: 테스트 파일, 판단 전용(이유 필수), 또는 크기별 기한(S 7일·M 30일·L 90일)이 있는 계획 | “규칙만 있고 검사는 없는” 상태를 목록으로 드러냄. 기한 연장은 --reason과 함께 기록에 남음 |
progress_file |
자주 바뀌는 진행 표를 공유 페이지 밖으로 분리 | 시스템 프롬프트 접두부를 고정해 프롬프트 캐시 적중 유지 |
9. 도구별 통합: 훅이 하는 일과 못 하는 일

| 도구 | 설치되는 훅·파일 | 규칙 전달 | 세션 중 뉴스 |
|---|---|---|---|
| Claude Code | ~/.claude/settings.json에 SessionStart·UserPromptSubmit·PostToolUse(타임아웃 5초) |
~/.claude/CLAUDE.md에 규칙 블록 |
hookSpecificOutput.additionalContext로 주입 |
| Codex | ~/.codex/hooks.json에 같은 세 이벤트 |
~/.codex/AGENTS.md에 규칙 블록 |
Claude Code와 같은 응답 형식 재사용 |
| Cursor | ~/.cursor/hooks.json에 sessionStart·postToolUse |
User Rules가 앱 내부라 파일 동기화 불가 → sessionStart에서 규칙·진행 주입 | postToolUse의 additional_context |
| MCP 지원 에이전트 | aisync mcp(stdio) |
rules 도구 호출 시 |
에이전트가 news 도구를 직접 불러야 함 |
| 셸 실행 가능한 에이전트 | 없음 | 지침 파일 또는 aisync rule list |
aisync news를 직접 실행해야 함 |
| git (전역) | 전역 core.hooksPath → 허브의 githooks/(체이닝 스텁 16개). commit-msg가 Agent: <tool> 트레일러 추가 |
– | harvest가 트레일러로 커밋을 에이전트별로 귀속 |
훅 호출은 전부 fail-open입니다. 항상 exit 0이고, 오류가 나도 도구를 막지 않아요. 새 소식이 없으면 아무것도 출력하지 않으니 조용한 허브는 토큰을 쓰지 않습니다. 박스에서 훅을 20번 불러 보니 중앙값 75ms였어요(Python venv, 이벤트 10개 남짓한 작은 허브 기준). 매 프롬프트와 매 도구 호출 뒤마다 프로세스가 하나씩 뜨는 구조라, 도구 호출이 많은 세션에서는 이 비용이 쌓인다는 점도 계산에 넣어야 합니다.
10. 설치와 첫 실행
# 체험만: 임시 폴더에 합성 데이터 허브를 만들고 끝(내 허브는 건드리지 않음)
uvx --from aisync-cli aisync demo
# 설치 (택1)
pipx install aisync-cli # 또는 uv tool install aisync-cli
brew install maxont/tap/aisync
docker run --rm ghcr.io/maxont/aisync --version
# 허브 만들기 → 훅 연결(diff를 먼저 보여 주고 물어봄) → 동기화 루프
aisync init
aisync install-hooks --dry-run # 무엇이 바뀌는지 먼저 확인
aisync install-hooks
aisync watch & # 또는 필요할 때 aisync sync
# 세션 중 에이전트가 하는 일
aisync claim -a codex -p api -f app/payments/ -m "SDK upgrade" # 3 = 다른 에이전트가 잡고 있음
aisync log -a codex -p api -k decision -m "SDK 5.0, retries kept"
aisync rule add -a codex --when "changing an API" --do "add a contract test"
aisync release -a codex -p api

README가 권하는 다른 설치 방법은 “AI에게 설치 페이지를 읽히는 것”입니다. 설치 페이지가 dry run부터 하고 변경 전에 묻도록 쓰여 있어요. 다만 curl ... | bash 경로든 AI 경로든, 전역 git 설정과 세 도구의 설정 파일을 건드리는 도구라는 점은 같습니다. 처음에는 반드시 --dry-run으로 diff를 읽어 보세요.
11. 박스 스모크 테스트: 설치부터 변조 탐지까지

2026-11-20 KST, x86_64 Linux 박스에서 Python 3.13.5 venv에 aisync-cli==0.2.11을 설치하고 AISYNC_HOME을 작업 폴더로 격리해 돌렸습니다. install-hooks는 가짜 HOME에서 --dry-run으로만 실행해 실제 설정은 하나도 바꾸지 않았어요.
| 확인 항목 | 명령 | 결과 |
|---|---|---|
| 설치·버전 | pip install aisync-cli==0.2.11 → aisync --version |
aisync 0.2.11, 추가로 설치되는 의존성 없음 |
| 허브 생성 | aisync init |
target 2개(~/.claude/CLAUDE.md, ~/.codex/AGENTS.md), 기본 규칙 R-001~R-003, 첫 사이클 ok |
| 클레임 충돌 | claude-code가 app/api/refunds.py 클레임 → codex가 같은 파일 클레임 |
OVERLAP: claude-code is working on ..., exit 3. release 뒤 재시도 exit 0 |
| 뉴스 | codex log -k blocked·rule add → claude-code news |
첫 호출은 커서만 설정, 두 번째 호출에 새 규칙 R-004와 blocked 이벤트가 표시됨 |
| 훅 출력 | echo '{...UserPromptSubmit...}' | aisync hook claude-code |
새 소식이 있으면 hookSpecificOutput.additionalContext JSON, 없으면 빈 출력·exit 0 |
| 저널 검증 | 본문 수정 / 중간 줄 삭제 / 마지막 줄 삭제 | 탐지(exit 1) / 탐지(exit 1) / 미탐지(문서에 적힌 한계와 일치) |
| 훅 설치 미리보기 | aisync install-hooks --dry-run |
변경 6건: Claude Code·Codex·Cursor 훅, 규칙 블록 2곳, 전역 core.hooksPath. 아무것도 쓰지 않음 |
| 규칙 정리 | aisync tidy |
방금 rule add로 만든 R-004까지 “형식 불일치”로 중복 비교에서 제외. main 브랜치(커밋 #43)로 다시 돌리면 R-004는 비교 대상에 들어감 |
| 문서-릴리스 차이 | aisync news --last 3 |
0.2.11 PyPI판은 “unrecognized arguments”. README에 적힌 이 옵션은 릴리스 뒤 main에 들어간 기능(#40). main 설치본에서는 동작 |
| 단위 테스트 | python -m unittest discover -s tests |
458개 중 456 통과·1 스킵·1 실패. 실패 1건은 pytest 미설치 때문이었고, pytest 설치 뒤 해당 파일 3개 테스트 통과 |
| 데모 | aisync demo |
합성 저널 67개 이벤트, 클레임 3개, blocked 1개, 규칙 충돌 1개가 있는 임시 허브를 /tmp에 생성 |
정리하면, 핵심 경로(클레임·저널·뉴스·훅)는 문서대로 동작했습니다. 다만 하루에 여섯 번 릴리스할 만큼 빠르게 바뀌는 프로젝트라 README가 최신 릴리스보다 앞서 있는 경우가 실제로 있었어요. 도입할 때는 버전을 고정하고, 쓰려는 옵션을 aisync help <명령>으로 확인하는 게 안전합니다.
12. 비슷한 접근과 비교
| 접근 | 푸는 문제 | 세션 중 갱신 | 동시 편집 처리 | 감사 기록 | 적합한 상황 |
|---|---|---|---|---|---|
| AGENTS.md / CLAUDE.md만 | 저장소의 고정 지침 | 없음(세션 시작 때 읽음) | 없음 | 파일의 git 이력뿐 | 에이전트 1개, 규칙 변화가 적을 때 |
| 도구별 훅 직접 작성 | 원하는 무엇이든 | 가능 | 직접 구현 | 직접 구현 | 도구 1~2개, 요구가 아주 구체적일 때 |
git worktree 수동 분리 |
작업 디렉터리 격리 | 해당 없음 | 물리적으로 분리, 충돌은 머지 때 | git 이력 | 작업이 명확히 나뉠 때 |
| worktree 기반 세션 관리자·칸반형 오케스트레이터 | 에이전트를 띄우고 작업을 나눠 줌 | 도구마다 다름 | 보통 worktree로 격리 | 도구마다 다름 | 작업 분배까지 맡기고 싶을 때 |
| aisync | 여러 에이전트의 공유 규칙·현재 상황·이력 | 훅으로 변경분만 주입 | 협조형 클레임(exit 3) + 옵트인 guard·worktree | 해시 체인 저널 + Agent: 트레일러 |
이미 쓰는 에이전트들을 그대로 두고 조정 계층만 더할 때 |
요점은 aisync가 오케스트레이터와 경쟁하기보다 그 아래층에 깔리는 위치라는 점입니다. 작업 분배는 사람이나 다른 도구가 하고, aisync는 “누가 무엇을 잡고 있고, 그새 무엇이 바뀌었나”만 공유합니다. AGENTS.md와의 관계도 README가 분명히 정리합니다. 고정 지침은 AGENTS.md에 그대로 두고, 작업 중에 바뀌는 맥락만 aisync가 맡으라는 거예요.
13. 도입 전 평가 체크리스트
| 질문 | 확인 방법 | 판단 기준 |
|---|---|---|
| 에이전트들이 exit 3을 존중하나? | 에이전트 지침에 “claim 먼저, exit 3이면 멈춤”을 넣고 일부러 충돌시켜 보기 | 무시하는 에이전트가 있으면 claim은 무의미. Claude Code라면 guard 검토 |
전역 core.hooksPath를 바꿔도 되나? |
install-hooks --dry-run의 git 항목 확인 |
husky 등 저장소별 core.hooksPath를 쓰는 저장소는 로컬 설정이 우선이라 트레일러 훅이 안 탈 수 있음 |
| 훅 지연이 허용 범위인가? | aisync status의 hook 통계(호출 수·평균 ms) |
도구 호출마다 프로세스 1개. 대형 저장소·느린 디스크에서 따로 측정 |
| 저널에 민감 정보가 남지 않나? | aisync tail, board.html 검토 |
요약·파일명이 평문 저장. board 생성 시에도 “공유 전에 읽어 보라”는 경고가 뜸 |
| 허브 백업과 꼬리 잘림 대비 | remote 설정, flush 주기 확인 |
마지막 줄 삭제 미탐지를 git 이력으로 보완 |
| 버전 고정 | pipx install aisync-cli==0.2.11 등 |
릴리스 주기가 매우 빠름. README와 설치본의 기능 차이 확인 |
| 여러 머신에서 쓰나? | 잠금·클레임 저장 위치 확인 | flock은 로컬 전용. 머신 간에는 git push된 허브로만 공유되므로 실시간 클레임은 기대하기 어려움 |
14. 한계와 주의할 점
- 강제력의 경계: 클레임은 OS 잠금이 아닙니다. 에이전트가 프로토콜을 따르지 않으면 아무것도 막지 못하고, 실제로 거부하는 guard는 Claude Code 전용이며 기본값은 꺼져 있습니다.
- 저널의 위협 모델: 키 없는 해시 체인이고 꼬리 잘림을 탐지하지 못합니다. id가 64비트로 잘려 있다는 점도 알아 두세요. 실수 탐지용이지 적대적 환경의 감사 로그는 아닙니다.
- 전역 부작용:
install-hooks는 세 도구의 사용자 설정 파일과 전역 gitcore.hooksPath를 바꿉니다. diff를 보여 주고 묻는 2단계 방식이긴 하지만, 회사 표준 git 훅이나 다른 훅 관리자와 같이 쓰려면 미리 확인해야 합니다. - 문서와 릴리스의 차이: 박스에서 README의
news --last N이 0.2.11에 없었고,tidy가 자기 형식의 규칙을 비교에서 빼는 문제는 main에서만 고쳐져 있었습니다. - 한 사람의 워크플로 냄새:
wt land가 GitHub main으로 바로 push하고, landq의 대기 메시지가 중국어로 하드코딩돼 있는 등 작성자 환경에 맞춘 부분이 남아 있습니다. 옵트인 기능은 팀 프로세스와 맞는지 먼저 따져 보세요. - 성숙도: 공개 한 달, 스타 48개, 기여는 사실상 메인테이너 한 명과 그가 쓰는 에이전트들입니다. 버스 팩터를 생각하면, 핵심 업무에 들이기보다 설계를 빌려 오는 레퍼런스로 먼저 보는 게 맞습니다.
- 숫자 읽기: README의 “20,673 → 7,876 토큰”과 “저널 이벤트 6,700개 이상”은 작성자 허브 한 곳의 1회 측정입니다. README 스스로 벤치마크가 아니라고 밝혀 두었어요.
15. 결론
aisync는 “에이전트를 더 똑똑하게”가 아니라 “에이전트 여럿을 서로 보이게” 만드는 도구입니다. 평문 파일 + git + flock + 해시 체인이라는 지루할 만큼 단순한 재료로 공유 규칙, 협조형 클레임, 세션 중 뉴스, 검증 가능한 이력을 묶었고, 각 장치가 무엇을 보장하고 무엇을 보장하지 않는지 문서와 코드에 정직하게 적어 두었어요. 박스에서도 핵심 동작은 문서 그대로였습니다. 다만 충돌 방지는 결국 에이전트의 협조에 달려 있고, 릴리스 속도가 문서를 앞지르기도 합니다. Claude Code·Codex·Cursor를 한 저장소에 같이 풀어 놓고 쓰는 팀이라면 aisync demo와 install-hooks --dry-run부터 돌려 보세요. 그것만으로도 우리 워크플로에서 무엇이 빠져 있었는지 꽤 선명하게 보일 겁니다.