Agentic-AI-Template/Document/docs/ARCHITECTURE.md

보고서 생성 아키텍처

디렉토리 구조

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를 구성한다.

데이터 흐름

사용자 입력
  -> 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은 단계 실행 상태의 단일 진실 공급원이다.

리서치 기록 단위

각 출처는 아래 필드를 포함해야 한다.

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

상태 관리

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