Sanctum LLM 문서 폴더 구조 향상 보고서

보고서 목적

이 보고서는 Sanctum 저장소에 LLM 작업자가 읽고 실행할 수 있는 문서 구조를 어떻게 배치할지 결정하기 위한 실무 설계 문서다. 원본 문서는 Notion, contracts/, service context, flow context, runtime context, validation context, Derived Knowledge, Graphify support structure를 분리하는 폴더 구조를 제안했다. 이 보고서는 도입 순서와 운영 판단 중심으로 재정리한다.

핵심 결론

Sanctum의 LLM 문서 구조는 사람용 위키 복사가 아니라 worker execution system이어야 한다. 설명하기 좋은 문서보다 작업자가 안전하게 읽고, 수정하고, 검증하고, 넘길 수 있는 문서가 우선이다.

AGENTS.md: worker 규칙, write/read/propose-only boundary, handoff gate.
contracts/: 서비스 간 계약의 canonical SSOT.
llm-docs/services/: 서비스별 실행 문맥.
llm-docs/flows/: cross-service request flow와 e2e 역할.
llm-docs/contracts/: 계약 운영 매뉴얼. 계약 원문 복제가 아니라 ownership/change process/map.
llm-docs/runtime/: worker model, workspace boundary, write allowlist, diff guard, sandbox.
llm-docs/operations/: deployment, runbook, observability, secrets policy.
llm-docs/decisions/: ADR과 stale condition.
llm-docs/validation/: test matrix, graph drift, RAG source disclosure, completion gates.
llm-docs/derived/: 검증 상태가 있는 분석 결론.
llm-docs/graphify/: Graphify refresh, root/cwd graph, merge, context pack generation policy.

원본 문서의 주요 내용

원본 문서는 wallet-api, kms-api, hd-manager, rust-mpc/mpc-manager-rs, rust-mpc/party-node-rs, contracts, root/e2e agent를 기준으로 LLM-facing 문서 체계를 설계했다. contracts/는 contract SSOT지만 service worker 실행 문맥으로 충분하지 않으며, 각 서비스에는 service-local AGENTS.md와 llm-context/가 필요하다. llm-context/contracts.md는 계약 내용을 복제하지 않고 canonical contract로 매핑해야 한다.

Flow 문서는 서비스별 문서와 다르게 end-to-end 요청 흐름을 다룬다. Runtime 문서는 Codex App workspace separation이 hard boundary가 아니라는 보정을 포함해야 한다. Graphify는 root graph로 시작하고, noisy할 때 cwd-specific graph와 merged graph로 확장한다. Derived Knowledge는 SSOT가 아니며 confidence, validation state, stale condition을 포함해야 한다.

Sanctum 적용 해석

wallet-api에는 API entry point, wallet lifecycle 책임, kms-api/hd-manager/MPC dependency, local test와 e2e handoff 기준이 필요하다. wallet-api worker는 자기 구현과 테스트를 수정하되 contracts/, sibling service, Rust MPC 변경은 기본 propose-only로 둔다.

kms-api에는 key operation, signing boundary, secret handling, sensitive logging 금지, contract compatibility 문맥이 필요하다. secret 값이나 private credential은 문서에 포함하지 않는다.

hd-manager에는 derivation responsibility, wallet/key lifecycle, upstream/downstream contract touchpoint, deterministic test fixture 기준이 필요하다. Rust MPC manager와 party node에는 session lifecycle, protocol compatibility, integration test 역할과 network/session behavior가 필요하다.

root/e2e agent는 service map, contract map, integration commands, e2e flow, worker handoff 문서를 가진 cross-service 판단과 검증 담당자로 제한해야 한다.

운영 판단

문서 구조는 한 번에 전부 만들기보다 최소 실행 집합부터 도입해야 한다. 초기 필수 파일은 root AGENTS.md, 각 service AGENTS.md, 각 service llm-context/service.md, commands.md, test-scope.md, e2e-role.md, contracts.md, dependency-stubs.md, root llm-context/e2e-flows.md, worker-handoff.md다.

그 다음 확장 단계에서 llm-docs/flows/, llm-docs/contracts/, llm-docs/runtime/, llm-docs/validation/, llm-docs/derived/, llm-docs/graphify/를 채운다. 특히 commands.md에는 검증되지 않은 명령을 확정처럼 쓰면 안 되며, 실제 실행 후 갱신해야 한다.

리스크와 가드레일

문서 과잉 위험: 최소 실행 집합부터 시작한다.
SSOT 혼선: 각 계층의 역할과 SSOT 여부를 llm-docs/index.md에 명시한다.
계약 복제: service contracts.md에는 schema를 복사하지 않는다.
Graphify drift: rename/delete/move, branch switch, merge/rebase, ignore 변경 후 refresh 조건을 문서화한다.
RAG stale retrieval: source path, index version 또는 timestamp, validation state가 필요하다.
Workspace boundary 착각: Codex App workspace separation은 hard enforcement가 아니다.
Runtime 미집행: 문서상 경계만으로는 부족하므로 runtime write allowlist와 diff guard를 도입한다.

실행 체크리스트

llm-docs/index.md에 계층별 역할과 SSOT 여부를 명시한다.
서비스별 AGENTS.md skeleton을 만든다.
서비스별 llm-context/ 최소 6종 문서를 만든다.
contracts.md를 pointer 문서로 작성하고 schema 복제를 금지한다.
root/e2e agent용 e2e-flows.md, service-map.md, contract-map.md, worker-handoff.md를 만든다.
Runtime 문서에 Codex App workspace limit correction을 명시한다.
Validation 문서에 graph drift check, RAG source disclosure, worker completion gates를 추가한다.
Graphify 초기 운영은 root graph로 시작하고 노이즈가 과도할 때 service graph/merged graph로 확장한다.