PRD: 심덩 Discord Codex Assistant#

문서 목적#

이 문서는 Discord에서 동작하는 심덩 Codex assistant가 어떤 사용자 문제를 해결해야 하는지, 어떤 기능을 제품 범위로 볼지, 성공 기준을 어떻게 판단할지 정의한다.

적용 범위#

• 대상 제품: Discord-facing Codex assistant인 심덩
• 대상 사용자: Discord에서 코딩, 문서 작성, 런타임 점검, write-agent 산출물 생성을 요청하는 사용자와 운영자
• 이 문서는 제품 요구사항의 기준이며, 구현 세부 결정은 ADR, 기준 데이터의 소유권은 SSOT, 행동 검증은 BDD를 따른다.

관련 문서#

• SSOT: 심덩의 최종 기준 위치
• ADR: 심덩 아키텍처 결정 기록
• BDD: 심덩 행동 검증 시나리오

1. 사용자 문제#

Discord 사용자는 Codex에게 자연어로 작업을 요청하지만, 실제 작업은 다음 경계를 안전하게 지켜야 한다.

• 사용자는 Discord 안에서 간단히 요청하고 싶다.
• Codex는 저장소 파일, runtime store, write-agent artifact, 승인 기록을 구분해야 한다.
• 긴 작업은 진행 상태를 알려야 한다.
• 위험한 작업은 명확한 승인 없이 실행되면 안 된다.
• Markdown, Discord 메시지, 웹 문서에 포함된 지시문이 시스템 규칙을 덮어쓰면 안 된다.
• 결과물은 사용자가 바로 읽고 사용할 수 있어야 한다.

2. 제품 목표#

심덩은 Discord를 작업 인터페이스로 쓰되, 실제 실행과 상태 관리는 agent-runtime이 담당하는 assistant가 되어야 한다.

3. 제품 범위#

포함 범위#

• Discord 메시지를 받아 Codex 작업으로 전달한다.
• agent-runtime이 workflow state, approval, Codex thread, write-agent orchestration을 관리한다.
• Discord bot은 메시지 수신, 버튼 표시, 상태 렌더링, 결과 전달을 담당한다.
• AGENTS.md, structured handoff, approval metadata, runtime store를 기준으로 작업 범위를 판단한다.
• write-agent는 선언된 path 안에 Markdown, HTML, JSON 등 허용된 산출물을 작성한다.
• 위험하거나 외부 효과가 있는 작업은 승인 흐름을 거친다.

비범위#

• Discord bot이 workflow state를 직접 소유하지 않는다.
• 자연어 키워드 테이블이나 regex로 intent, 승인 범위, 권한을 판정하지 않는다.
• 사용자의 토큰, 계정 정보, 비밀 값을 문서나 로그에 저장하지 않는다.
• 승인 버튼의 custom_id에 action, repo, scope 같은 민감 메타데이터를 넣지 않는다.
• 현재 런타임 상태를 확인하지 않고 실제 작업이 완료됐다고 단정하지 않는다.

4. 주요 사용자 흐름#

흐름 A: 사용자가 Discord에서 문서 생성을 요청한다#

1. 사용자가 Discord에 “심덩 기준으로 PRD, SSOT, ADR, BDD 예시 만들어줘”라고 요청한다.
2. Discord bot은 메시지와 metadata를 agent-runtime에 전달한다.
3. agent-runtime은 write-agent handoff를 구성한다.
4. write-agent는 선언된 path에 Markdown 파일을 작성한다.
5. agent-runtime은 결과 파일을 저장하고 Discord에 완료 상태를 표시한다.

흐름 B: 승인 필요한 작업을 요청한다#

1. 사용자가 외부 네트워크, destructive command, repo 밖 파일 수정 등 승인 필요한 작업을 요청한다.
2. agent-runtime은 approval scope를 서버-side metadata로 저장한다.
3. Discord bot은 승인 버튼을 보여준다.
4. 버튼 custom_id에는 approval id만 포함된다.
5. 승인 후 agent-runtime이 원래 scope를 조회해 작업을 계속한다.

흐름 C: 작업 중 근거가 부족하다#

1. 사용자가 “전체 소스를 분석해 통합 문서 만들어줘”라고 요청한다.
2. sourceManifest에 실제 읽을 수 있는 파일이 부족하다.
3. write-agent는 전체를 읽은 것처럼 작성하지 않고 누락된 근거를 명시한다.
4. 사용자는 보강할 source path나 scope를 다시 제공한다.

5. 성공 기준#

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

다음 의문이 반복되면 PRD를 먼저 보강한다.

• “이 기능은 왜 필요한가?”
• “사용자가 어떤 문제를 해결하려고 이걸 요청했나?”
• “완료 기준이 무엇인가?”
• “Discord에서 보여줘야 하는 결과가 파일인가, 요약인가, 승인 버튼인가?”

PRD는 제품 목적과 사용자 흐름을 정리하는 문서다. 반대로 “어느 저장소가 기준인가?”, “상태를 누가 소유하나?” 같은 질문은 SSOT나 ADR에서 다룬다.

7. PRD와 다른 문서의 차이#