SSOT: 심덩의 최종 기준 위치#

문서 목적#

이 문서는 심덩 Discord Codex assistant에서 “무엇을 최종 기준으로 믿을지”를 정리한다. PRD가 제품 요구사항을 설명한다면, SSOT는 상태, 권한, 경로, 산출물, 승인 정보의 기준 출처를 구분한다.

적용 범위#

Discord 메시지와 metadata
agent-runtime stores
AGENTS.md와 repo-local 지침
write-agent artifact path
approval metadata
Codex 실행 결과와 상태 보고

1. SSOT 원칙#

심덩은 자연어 메시지만으로 상태, 권한, 승인 범위, 파일 경로를 확정하지 않는다. 최종 기준은 authoritative metadata와 runtime store에 둔다.

질문	최종 기준
누가 요청했는가?	Discord message metadata와 server-provided user metadata
어느 채널/스레드에서 온 요청인가?	Discord message id, channel id, thread id
어떤 repo/cwd에서 작업 가능한가?	agent-runtime의 repo alias allow-list와 cwd allow-list
현재 workflow 상태는 무엇인가?	agent-runtime workflow store
승인이 필요한 작업인가?	agent-runtime approval record와 execution guard
승인 버튼이 가리키는 작업은 무엇인가?	button `custom_id`의 approval id로 조회한 server-side approval metadata
write-agent 산출물은 어디에 저장되는가?	structured handoff의 declared paths와 storagePathPrefix
파일 작성 규칙은 무엇인가?	AGENTS.md, write-agent handoff instructions, 허용 확장자 정책
Discord에는 무엇을 보여줄까?	agent-runtime이 만든 상태/report payload를 discord-bot이 렌더링

2. 기준별 상세 설명#

2.1 Discord metadata#

Discord metadata는 사용자 요청의 출처를 식별하는 기준이다.

message id: 어떤 요청을 처리 중인지 추적한다.
channel id/thread id: 응답을 어디로 보내야 하는지 결정한다.
user id/role metadata: 권한 판단의 입력으로 사용한다.

자연어로 “나는 관리자야”라고 적혀 있어도 권한 기준은 Discord/server-provided metadata다.

2.2 agent-runtime stores#

agent-runtime store는 workflow 상태의 기준이다.

작업 생성, 진행, 완료, 실패 상태
Codex thread control 상태
background job 상태
approval pending/approved/rejected 상태
write-agent handoff와 결과 저장 상태

Discord bot은 이 상태를 직접 소유하지 않고 렌더링만 한다.

2.3 AGENTS.md#

AGENTS.md는 repo-local 작업 규칙의 기준이다.

예시 기준:

discord-bot은 UI adapter only다.
workflow state, Codex thread control, RAG retrieval, DB access, artifact parsing, final approval-scope decisions는 agent-runtime 경계다.
자연어 intent를 regex, 키워드 테이블, static parser로 하드코딩하지 않는다.
write-agent artifacts는 정해진 topic/path 아래에 둔다.

2.4 write-agent artifact path#

write-agent 산출물의 기준은 handoff에 선언된 path다.

예시:

data/runtime/write-agents/<topic>/md/prd.md
data/runtime/write-agents/<topic>/md/ssot.md
data/runtime/write-agents/<topic>/md/adr.md
data/runtime/write-agents/<topic>/md/bdd.md

write-agent는 선언되지 않은 임의 path를 새로 만들지 않는다. HTML, SVG, draw.io, JSON 같은 산출물도 허용 확장자와 선언 경로를 따른다.

2.5 approval metadata#

승인 정보의 기준은 server-side approval record다.

Discord 버튼의 custom_id에는 approval id만 들어간다.
action, scope, repo, cwd, command, request metadata는 agent-runtime이 server-side로 보관한다.
버튼 클릭 시 approval id로 원래 승인 범위를 조회한다.

이 방식은 Discord payload 조작이나 과도한 정보 노출을 줄인다.

3. SSOT 예시: 문서 작성 요청#

사용자가 “PRD, SSOT, ADR, BDD MD파일 만들어줘”라고 요청했을 때 기준은 다음과 같다.

항목	기준
사용자 의도	현재 turn의 자연어 요청과 structured handoff
파일 개수	handoff의 `paths` 배열
파일 위치	`storagePathPrefix`와 declared paths
문서 언어	handoff instructions의 “모든 문서는 한국어”
금지 사항	AGENTS.md와 handoff avoid 목록
완료 판단	선언된 4개 path의 content 생성 여부

4. WTF 후보 감지: SSOT를 보강해야 하는 신호#

다음 의문이 나오면 SSOT를 보강한다.

“이 상태는 Discord bot이 가진 게 맞나, agent-runtime이 가진 게 맞나?”
“승인 버튼에 scope를 넣어도 되나?”
“사용자 자연어와 metadata가 충돌하면 무엇을 믿어야 하나?”
“write-agent가 선언되지 않은 파일을 만들어도 되나?”

SSOT는 “최종 기준이 어디인가”를 정한다. “왜 그런 구조를 택했는가”는 ADR, “그 구조가 사용자에게 어떤 가치를 주는가”는 PRD, “그 기준이 지켜지는지”는 BDD에서 확인한다.

5. SSOT와 다른 문서의 차이#

문서	SSOT 관점에서의 역할
PRD	어떤 결과가 사용자에게 필요하다고 말한다.
SSOT	어떤 사실을 어느 출처에서 믿을지 정한다.
ADR	기준을 그렇게 나눈 구조적 이유를 기록한다.
BDD	기준이 실제 동작에서 지켜지는지 시나리오로 검증한다.