Sanctum 서비스 컨텍스트 팩 설계 향상 보고서

보고서 목적

이 보고서는 Sanctum에서 service-scoped LLM worker를 운영하기 위한 AGENTS.md와 llm-context/ 패키지 설계를 구체화한다. 원본 문서는 contracts/만으로는 worker 실행 문맥이 부족하며, 각 서비스에 작업 규칙, 명령, 테스트, 계약 매핑, e2e 역할, dependency stub, handoff 문서가 필요하다고 결론냈다.

핵심 결론

Sanctum의 권장 모델은 서비스별 context pack, canonical contracts, runtime-enforced worker boundary의 결합이다.

AGENTS.md: worker role, write/read/propose-only boundary, 금지 작업, handoff rule, test obligation.
llm-context/service.md: 서비스 책임, 비책임, 주요 entry point, dependency, 먼저 읽을 파일.
llm-context/commands.md: 검증된 build/test/lint/run 명령과 handoff-required validation.
llm-context/test-scope.md: local required, conditional, contract-sensitive, e2e handoff test 구분.
llm-context/e2e-role.md: end-to-end flow에서 이 서비스가 맡는 역할과 실패 전파.
llm-context/contracts.md: canonical contracts/로 가는 pointer와 usage map. 계약 내용 복제 금지.
llm-context/dependency-stubs.md: sibling service 직접 수정 없이 local test를 가능하게 하는 stub 정책.
llm-context/handoff.md: root/e2e agent, contract owner, sibling service worker로 넘기는 절차.

원본 문서의 주요 내용

원본 문서는 wallet-api, kms-api, hd-manager, rust-mpc/mpc-manager-rs, rust-mpc/party-node-rs 각각에 같은 skeleton을 적용하되 내용은 service-specific해야 한다고 제안했다. 기본 경계는 해당 서비스 구현, 로컬 테스트, 해당 서비스 llm-context/는 write, root/service AGENTS.md, canonical contracts/, 직접 의존 서비스 공개 context pack은 read, contracts/, 다른 서비스 구현, root e2e 흐름, 배포/운영 설정은 propose-only다. Contract change, cross-service behavior change, e2e flow impact, security-sensitive change는 handoff 대상이다.

Graphify는 context pack 생성과 갱신 후보를 찾는 데 유용하지만 write authorization이나 SSOT 역할을 맡으면 안 된다. RAG는 과거 결정과 canonical docs를 찾는 데 쓸 수 있지만 최신 계약 사실의 원본은 아니다.

Sanctum 적용 해석

wallet-api context pack은 API entry point와 wallet flow 조정을 중심으로 작성한다. kms-api, hd-manager, MPC layer를 dependency로 기록하되 해당 서비스 구현 변경은 propose-only로 둔다. local stubs는 handler/unit test에 사용할 수 있지만 signing, key lifecycle, MPC protocol 호환성의 최종 증거가 될 수 없다.

kms-api context pack은 security-sensitive responsibility를 명시해야 한다. secret 값은 기록하지 않고, sensitive log 금지, key operation contract, signing boundary, wallet consumer impact를 다룬다. kms-api worker가 wallet-api behavior를 임의로 바꾸지 않도록 handoff rule을 강하게 둔다.

hd-manager context pack은 derivation responsibility, wallet/account hierarchy, KMS/MPC interaction, deterministic fixture policy를 다룬다. derivation semantics가 바뀌면 contract proposal과 root/e2e validation이 필요하다.

mpc-manager-rs context pack은 MPC session orchestration, party coordination, manager-party protocol boundary, integration test 역할을 다룬다. party-node-rs protocol 변경은 직접 수정이 아니라 handoff 또는 명시적 paired scope가 필요하다.

root/e2e context pack은 service worker의 권한을 대체하지 않고 통합 판단을 담당한다. 모든 service context와 contracts/를 읽고, cross-service flow, e2e test matrix, handoff closure를 관리한다.

운영 판단

서비스 context pack은 문서일 뿐 실제 권한 집행 장치가 아니다. 따라서 설계는 runtime enforcement와 결합되어야 한다. Worker 시작 시 root/service AGENTS.md와 작업 유형에 맞는 llm-context/*를 읽고, Graphify나 RAG로 후보를 찾더라도 canonical file을 직접 읽어야 한다. 변경 파일은 service write allowlist 안에 있어야 하며, 종료 전 diff guard가 out-of-scope 변경을 차단해야 한다. contract/e2e/security-sensitive 영향은 handoff artifact로 남긴다.

Codex App workspace separation은 개인 탐색과 리뷰의 risk reduction 수단이다. hard write boundary는 sparse worktree, container/read-only mount, discord-codex-bot runtime write allowlist, diff guard로 구현해야 한다.

리스크와 가드레일

contracts.md 복제 위험: pointer와 usage map만 허용한다.
AGENTS.md 과신 위험: 문서 지시만으로 권한이 집행되지 않는다.
Dependency stub 오해: stub 통과는 integration readiness가 아니다.
Service worker scope invasion: write allowlist와 diff guard를 적용한다.
Graphify drift: Graphify는 후보 탐색으로 제한한다.
RAG stale retrieval: source disclosure와 canonical direct read가 필요하다.
명령어 부정확성: commands.md에 검증되지 않은 명령을 확정처럼 넣지 않는다.

실행 체크리스트

각 서비스 루트에 AGENTS.md를 둔다.
각 서비스에 llm-context/service.md, commands.md, test-scope.md, e2e-role.md, contracts.md, dependency-stubs.md를 만든다.
운영 안정성을 위해 handoff.md와 known-risks.md를 추가한다.
contracts.md는 canonical path, usage point, owner, permission, validation만 포함한다.
dependency-stubs.md에 stub으로 충분하지 않은 영역을 명시한다.
test-scope.md에 local required와 e2e handoff trigger를 분리한다.
root/e2e agent 문서에 service handoff 수신, contract impact, e2e validation 책임을 둔다.
runtime write allowlist와 diff guard를 문서 규칙과 맞춘다.