file-save-protocol

파일 저장 프로토콜

Overview

이 스킬은 분석 에이전트가 결과를 파일로 저장할 때 따라야 하는 규칙을 정의합니다.

핵심 목표: 분석 결과의 영속성 보장 및 환각 방지

---

1. 파일 저장 필수 규칙 (CRITICAL)

환각 방지의 핵심: 분석 결과를 반드시 파일로 저장해야 합니다. 프롬프트로만 반환하면 데이터 손실 및 환각 발생 위험이 있습니다.

왜 파일 저장이 필수인가?

문제	설명
컨텍스트 손실	긴 대화에서 이전 분석 결과가 잘릴 수 있음
재현 불가	파일 없이는 분석 결과를 재검증할 수 없음
환각 위험	저장 없이 "저장됨"이라고 응답하면 환각
워크플로우 중단	다음 에이전트가 입력 파일을 찾지 못함

필수 사항 (MUST)

• 모든 분석 결과는 Write 도구로 파일 저장
• 저장 경로는 coordinator가 제공하는 output_path 사용
• 저장 성공 여부 확인 후 응답
• 저장 실패 시 명시적 FAIL 응답

금지 사항 (NEVER)

• 파일 저장 없이 분석 결과 "완료" 응답
• 저장 실패를 무시하고 진행
• output_path 무시하고 임의 경로 사용

---

1.5 Markdown 저장 규칙 (MANDATORY)

JSON 저장은 항상 필수이며, 사람이 읽기 위한 Markdown 요약도 반드시 저장합니다.

필수 규칙

• JSON과 MD 모두 저장 (둘 중 하나라도 누락 시 FAIL)
• MD는 JSON 내용을 요약/정리만 수행 (새 수치/새 출처 추가 금지)
• 파일명은 번호 접두어 고정:
  • {output_path}/{NN}-{base}.md (base = JSON 파일명에서 .json 제거)
  • 예: 00-index-data.md

---

2. 저장 프로세스

Step-by-Step

Step 1: 분석 완료 후 JSON 객체 생성

Step 2: Write 도구로 파일 저장
        Write(
          file_path="{output_path}/{filename}.json",
          content=JSON.stringify(analysis_result, null, 2)
        )

Step 3: 저장 성공 확인
        └─ 성공: 정상 응답 반환
        └─ 실패: FAIL 응답 반환 (환각 데이터 생성 금지)

저장 경로 컨벤션

coordinator가 제공하는 output_path를 사용합니다:

portfolios/{session_folder}/{filename}

예시:
portfolios/2026-01-14-aggressive-abc123/
├── index-data.json             # index-fetcher 출력
├── rate-analysis.json          # rate-analyst 출력
├── sector-analysis.json        # sector-analyst 출력
├── risk-analysis.json          # risk-analyst 출력
├── leadership-analysis.json    # leadership-analyst 출력
├── material-summary.md         # material-organizer 출력 (옵셔널)
├── macro-outlook.json          # macro-synthesizer 출력
├── 00-macro-outlook.md         # macro-synthesizer 출력
├── 01-fund-analysis.md         # fund-portfolio 출력
├── 02-compliance-report.md     # compliance-checker 출력
├── 03-output-verification.md   # output-critic 출력
└── 04-portfolio-summary.md     # portfolio-orchestrator 출력

에이전트별 출력 파일

에이전트	출력 파일	필수
index-fetcher	index-data.json	O
rate-analyst	rate-analysis.json	O
sector-analyst	sector-analysis.json	O
risk-analyst	risk-analysis.json	O
leadership-analyst	leadership-analysis.json	O
material-organizer	material-summary.md	X (옵셔널)
macro-synthesizer	macro-outlook.json, 00-macro-outlook.md	O
fund-portfolio	01-fund-analysis.md	O
compliance-checker	02-compliance-report.md	O
output-critic	03-output-verification.md	O
portfolio-orchestrator	04-portfolio-summary.md	O

---

3. 저장 실패 시 응답

저장이 실패하면 절대 "저장됨"으로 응답하지 않습니다:

{
  "status": "FAIL",
  "error": "FILE_SAVE_FAILED",
  "detail": "{filename} 저장 실패",
  "attempted_path": "{output_path}/{filename}",
  "action": "재시도 필요"
}

실패 유형별 대응

실패 유형	코드	대응
경로 없음	PATH_NOT_FOUND	coordinator에 경로 확인 요청
권한 오류	PERMISSION_DENIED	경로 권한 확인
디스크 공간	DISK_FULL	공간 확보 후 재시도
알 수 없음	UNKNOWN_ERROR	에러 메시지 포함하여 보고

---

4. Write 도구 사용법

기본 사용법

Write(
  file_path="portfolios/{session_folder}/rate-analysis.json",
  content="{\"fed_outlook\": {...}, \"bok_outlook\": {...}}"
)

JSON 포맷팅

# 들여쓰기 2칸으로 포맷팅
JSON.stringify(analysis_result, null, 2)

파일 확장자 규칙

데이터 유형	확장자
구조화된 데이터	.json
마크다운 보고서	.md
원시 텍스트	.txt

---

5. 저장 확인 체크리스트 (MANDATORY)

저장 전 확인

• output_path가 coordinator로부터 전달되었는가?
• 저장할 데이터가 완전한가 (모든 필수 필드 포함)?
• JSON 형식이 올바른가?

저장 후 확인

• Write 도구가 에러 없이 완료되었는가?
• 저장 경로를 응답에 포함했는가?
• 저장 실패 시 FAIL 응답을 반환했는가?

절대 금지

• 파일 저장 실패 시 "저장된 것처럼" 응답하지 않았는가?
• 저장 없이 분석 "완료"로 응답하지 않았는가?

---

6. 응답 템플릿

성공 시 응답

{
  "status": "SUCCESS",
  "output_file": "{output_path}/{filename}.json",
  "summary": {
    // 분석 결과 요약
  }
}

실패 시 응답

{
  "status": "FAIL",
  "error": "FILE_SAVE_FAILED",
  "detail": "rate-analysis.json 저장 실패",
  "attempted_path": "portfolios/2026-01-14-aggressive-abc123/rate-analysis.json",
  "action": "재시도 필요"
}

---

---

7. 세션 재개 시 파일 검증 (v1.1 신규)

목적: 세션 재개 시 필수 JSON 파일 존재 여부 확인 참조: portfolio-orchestrator 스킬의 세션 재개 검증 섹션

세션 재개 시 coordinator가 수행하는 검증

[Step -0.5: 세션 재개 검증]
     │
     ▼
Glob("portfolios/{session_folder}/*.json")
     │
     ├── 필수 파일 목록:
     │   ├── index-data.json
     │   ├── rate-analysis.json
     │   ├── sector-analysis.json
     │   ├── risk-analysis.json
     │   └── leadership-analysis.json
     │
     ├─ 모든 파일 존재 → 다음 Step 진행
     │
     └─ 파일 누락 → 해당 에이전트 재호출

에이전트 책임

각 에이전트는 반드시 파일 저장을 완료해야 합니다:

조건	에이전트 행동
Write 성공	정상 응답 반환 (output_file 경로 포함)
Write 실패	FAIL 반환 (환각 데이터 생성 금지)
output_path 미전달	FAIL 반환 (경로 확인 요청)

금지 사항 (coordinator 포함)

❌ 파일 저장 없이 "완료" 응답
❌ 이전 세션 결과 "텍스트 요약"으로 대체
❌ JSON 파일 없이 markdown만 작성
❌ 파일 검증 없이 다음 Step 진행

---

메타 정보

version: "1.1"
created: "2026-01-14"
updated: "2026-02-01"
purpose: "파일 저장 프로토콜 통합 - 코드 중복 제거"
changes:
  - "v1.1: 세션 재개 시 파일 검증 섹션 추가 (Step -0.5 연동)"
  - "v1.0: 초기 버전 - 파일 저장 필수 규칙 정의"
consumers:
  - index-fetcher
  - rate-analyst
  - sector-analyst
  - risk-analyst
  - leadership-analyst
  - macro-synthesizer
  - compliance-checker
  - fund-portfolio
  - output-critic
  - material-organizer
extracted_from:
  - "파일 저장 필수 섹션 (rate-analyst v4.2)"
  - "저장 프로세스 섹션"
  - "저장 실패 시 응답 형식"
dependencies:
  - Write
  - Glob (coordinator 검증용)