# 보고서 생성 아키텍처

## 디렉토리 구조
```text
docs/
├── PRD.md             # 사용자가 입력하는 보고서 브리프
├── ARCHITECTURE.md    # 보고서 생성 흐름과 산출물 구조
├── ADR.md             # 리서치/작성 의사결정
├── UI_GUIDE.md        # 보고서 문체와 형식 가이드
├── RESEARCH_LOG.md    # 웹 검색 결과, 출처, 검증 메모
├── REPORT_DRAFT.md    # 현재 보고서 초안
└── FEEDBACK.md        # 사용자 피드백과 반영 이력

phases/
├── index.json
└── {phase}/
    ├── index.json
    ├── step0.md
    ├── step1.md
    └── stepN.md
```

## 에이전트 역할 패턴
- Research Lead: 브리프를 읽고 리서치 질문, 검색 범위, 단계 계획을 정의한다.
- Domain Researcher: 특정 키워드, 산업, 지역, 기간을 맡아 웹 검색하고 근거를 축적한다.
- Source Reviewer: 출처 신뢰도, 최신성, 상충 자료, 과장된 해석을 점검한다.
- Outline Writer: 리서치 로그를 바탕으로 보고서 구조와 핵심 메시지를 설계한다.
- Report Editor: 초안을 작성하고 문체, 흐름, 근거 연결, 피드백 반영을 정리한다.

하나의 Codex 세션이 여러 역할을 수행할 수 있다. 사용자가 명시적으로 subagent 사용을 요청한 경우에만 병렬 subagent를 구성한다.

## 데이터 흐름
```text
사용자 입력
  -> docs/PRD.md
  -> phase plan 생성
  -> 웹 검색 및 출처 검증
  -> docs/RESEARCH_LOG.md 축적
  -> 개요와 논점 정리
  -> docs/REPORT_DRAFT.md 초안 작성
  -> 사용자 피드백 요청
  -> docs/FEEDBACK.md 기록
  -> 추가 검색/수정 반복
```

## 산출물 불변식
- `docs/PRD.md`는 사용자 의도와 범위의 단일 진실 공급원이다.
- `docs/RESEARCH_LOG.md`는 모든 핵심 사실과 출처의 단일 진실 공급원이다.
- `docs/REPORT_DRAFT.md`에는 검증된 근거와 명시된 한계만 반영한다.
- `docs/FEEDBACK.md`에는 피드백 원문, 해석, 반영 여부, 미반영 이유를 기록한다.
- `phases/{phase}/index.json`은 단계 실행 상태의 단일 진실 공급원이다.

## 리서치 기록 단위
각 출처는 아래 필드를 포함해야 한다.

```text
- 주장/논점:
- 출처 제목:
- 발행기관:
- URL:
- 발행일:
- 접근일:
- 핵심 내용:
- 신뢰도 메모:
- 보고서 반영 위치:
```

## 상태 관리
- 보고서 상태는 별도 애플리케이션 상태가 아니라 문서 파일의 변경 이력으로 관리한다.
- 단계 상태는 `phases/{phase}/index.json`의 `pending`, `completed`, `error`, `blocked`로 관리한다.
- 사용자의 추가 판단이 필요한 경우 Codex는 추측하지 말고 해당 step을 `blocked`로 표시하고 `blocked_reason`을 기록한다.